Organização de componentes de interface no Veritas, em todo front-end (Vite, Next.js, React Native e templates Django). Use ao criar um componente novo, decidir onde ele mora, quebrar uma tela em partes, ou quando um componente parecer grande ou repetido demais.
El texto de las convenciones está escrito en portugués y se muestra aquí tal como está en el repositorio.
Atomic Design — organização de componentes
Projeto que já existe? Estas convenções valem para código novo e para remodelação. Em sistema legado, de cliente ou de outra equipe, a arquitetura do projeto manda: antes da primeira mudança, siga
veritas:projeto-existente.Dado pessoal? Código que toca CPF, contato, saúde, dado financeiro ou credencial, e todo log, exportação ou integração, segue também a
veritas:lgpd, em qualquer modo.
Vale para todo front-end da casa: Vite, Next.js e React Native.
Templates Django (renderizados no servidor): os níveis e as regras são os
mesmos, mas as pastas, a forma de chamar e o CSS mudam. Leia
django.md.
A pergunta que a pasta responde
Todo componente responde a uma pergunta: de que ele depende? É isso, e não o tamanho dele, que decide onde mora.
src/components/
atoms/ # não depende de nenhum outro componente nosso
molecules/ # compõe atoms
organisms/ # compõe molecules e atoms; pode ter estado e buscar dados
templates/ # o esqueleto da tela, sem dado real
src/pages/ # template + dado; é o que a rota renderiza
Os níveis
Atom — a menor peça útil. Botão, input, label, ícone, avatar. Não importa
outro componente nosso. Não sabe de domínio: um atom não se chama
BotaoSalvarCliente, se chama Botao.
Molecule — um punhado de atoms com um propósito só. Campo de busca (label + input + botão), item de lista, card simples. Ainda não busca dado.
Organism — um pedaço da interface que se sustenta sozinho. Cabeçalho, formulário de cadastro, tabela com paginação. Pode ter estado próprio e chamar serviço.
Template — a tela sem conteúdo. Define o arranjo — onde fica o cabeçalho, onde entra a lista — com props no lugar dos dados.
Page — o template preenchido. Busca o dado, trata carregamento e erro, e entrega para o template. É a única camada que conhece rota.
Tokens — abaixo dos atoms. Cor, tamanho de texto, espaço, raio e sombra,
definidos uma vez (@theme, :root, objeto theme no RN, base.html no
Django). Não são componente: são o que os atoms consomem. Como montar:
veritas:cores e veritas:tipografia-e-espacamento.
Regras (violação = erro)
Componente consome token, nunca valor cru. Hex,
rgb(),pxsolto, classe de cor do framework (bg-blue-600) ou valor arbitrário (p-[13px]) dentro de atom, molecule ou organism é erro: o valor vira token primeiro. Antes de entregar a tela:veritas:revisao-de-design.A dependência aponta sempre para baixo. Atom nunca importa molecule, molecule nunca importa organism. Se precisou, o componente está no nível errado.
Atom não conhece domínio. Nada de
CardClienteematoms/. Se o nome precisa de um substantivo do negócio, é molecule ou acima.Busca de dado só em organism ou page. Atom e molecule recebem por prop — é o que os mantém testáveis e reutilizáveis.
Template não tem dado real. Se você precisou de um
useEffectno template, aquilo é uma page.Componente responde ao próprio espaço, não à janela. O que muda de forma conforme a largura do lugar onde está usa container query (
veritas:responsividade).Não crie o nível por antecipação. Componente usado numa tela só começa dentro da própria page; sobe para
organisms/quando a segunda tela precisar dele. Pasta cheia de componente com um uso só é custo sem retorno.
Onde isso costuma dar errado
O organism que virou página. Se um organism busca dado, controla rota e
decide layout, ele é uma page com nome errado. Sintoma: props demais e
useEffect encadeado.
O atom que cresceu. Um Botao com quinze variantes por prop booleana já não
é um atom, é três componentes disfarçados. Sintoma: if sobre prop dentro do
render. Se vercel-composition-patterns estiver instalada, carregue para
desmontar: ela decide a técnica, esta skill decide em que nível cada parte
mora. As outras skills de fora: skills-de-fora.md.
Molecule que só existe para embrulhar um atom. Se ela não acrescenta comportamento nem composição, apague e use o atom direto.
React Native
Os mesmos cinco níveis. O que muda é só o vocabulário da camada de baixo: atoms
são View, Text, TouchableOpacity em vez de elementos HTML. A regra de
dependência é idêntica.
Origem
Banco de skills do Veritas, skill atomic-design. Método
original de Brad Frost; os nomes de pasta e as regras acima são a aplicação
escolhida pela casa.
Correções vão por PR no repositório, não editando a cópia local.