Convenções de código · Docs

Algumas convenções mantêm um projeto Nimbly fácil de entender, para o desenvolvedor que o escreveu, o designer que o estiliza e quem vier depois.

Onde fica cada coisa

O quê	Onde
Markup	Templates: `ext/tpl/` para partes reutilizáveis, `ext/uri/` para rotas
Lógica e preparação de dados	Bibliotecas em `ext/lib/`
O formato dos seus dados	Definições de recursos em `ext/data/<resource>/.meta`
Estilos	`ext/theme.css` e classes do Tailwind nos templates
Cores e temas	`ext/tailwind.theme.js`
Uma funcionalidade empacotada	`ext/modules/<name>/`

Os templates continuam sem lógica e as bibliotecas não contêm HTML. Assim, um designer pode mudar qualquer parte da interface sem ler PHP, e um desenvolvedor pode mudar uma regra sem mexer no markup.

Nomes

Templates: primeiro o tipo, depois o assunto. Os cartões ficam juntos, as seções também, e as páginas também:

Tipo	Usado para	Exemplo
`page-`	O conteúdo de uma página	`page-about`, `page-contact`
`section-`	Uma seção dentro de uma página	`section-home-hero`
`card-`	Um item repetido	`card-project`, `card-team-member`
`form-`	Um formulário	`form-newsletter`
`icon-`	Um ícone inline	`icon-arrow-right`
`btn-`	Um botão ou estilo de botão	`btn-preview`

Escreva card-project, não project-card.

PHP: snake_case em todo lugar. Funções, variáveis, parâmetros e nomes de arquivo: prepare_projects_sc(), $project_count, ext/lib/prepare-projects.php. O arquivo da biblioteca usa hífens porque também é o nome do shortcode, [#prepare-projects#].

Recursos e campos: minúsculas, plural para o recurso. projects, team-members; campos como title, title_slug, published, sort_order.

Componentes

Um componente é um template reutilizável com tudo de que precisa dentro da própria pasta:

ext/tpl/photo-collage/index.tpl     the markup
ext/tpl/photo-collage/style.css     its own CSS, imported from ext/theme.css

Autossuficiente. A página só chama [#photo-collage#]; o componente não depende da página ao redor.
Definido por quem chama. O que varia a cada uso é definido antes da chamada: [#set collage_columns=3 overwrite#], depois [#photo-collage#].
Portátil. Um bom componente funciona quando copiado para outro projeto.

A maioria das partes da interface são componentes. Transforme-o em módulo só quando ele também trouxer dados ou rotas próprios.

Estilo

Use as cores do tema (primary, secondary e os tokens próprios do projeto) em vez de cores fixas da paleta, para que um redesign seja uma mudança num único lugar.
Quando uma lista longa de classes se repete em vários elementos, dê a ela um pequeno template próprio e reutilize-o. Poucas classes ficam inline.
Coloque entre aspas as listas de classes guardadas numa variável, [#set card-style="rounded-2xl bg-white"#], para que o build as encontre.

Estilo de código

Use sempre chaves em if, else, for e while, também em volta de uma única linha, em PHP e JavaScript.
Corrija a causa, não o sintoma: quando falta um dado num template, corrija onde o dado é carregado; quando um layout quebra, corrija o layout em vez de esconder o overflow.
Mantenha tudo tão pequeno quanto a necessidade atual permite. Nada de campos, configurações ou abstrações "para depois".

Commits

Use Conventional Commits: um tipo, um escopo opcional e uma linha clara.

feat(projects): filter the overview by sector
fix(header): logo and menu no longer overlap on phones
style(cards): align the card titles

Se mais contexto ajudar, acrescente-o depois de uma linha em branco. A primeira linha se sustenta sozinha.