Convenções

CódigoCopy Anchor Link

• Um arquivo por componente em packages/ui/src/<família>/<kebab>.tsx, com index.ts da família (sem "use client"), <kebab>.examples.tsx, <kebab>.test.tsx e <kebab>.figma.tsx.
• Autocontido: só imports relativos, _lib/* e @base-ui/react, class-variance-authority, clsx, tailwind-merge, motion, lucide-react, react. Nada de @/, next/*, next-intl ou store. É isso que deixa o docs importar o componente sem cópia.
• API = propriedades do Figma: variant, size, tone em camelCase; State não é prop (hover, foco e pressionado são interação; disabled, loading, invalid, selected são props). Ícones são leadingIcon / trailingIcon (um elemento lucide).
• Polimorfismo pelo render do base-ui. Sem asChild, sem Radix.
• Estados forçados: use ds-hover:, ds-focus:, ds-pressed: em vez de hover:, focus-visible:, active:. Eles também disparam com data-ds-state, o que permite mostrar todos os estados lado a lado.
• Proibido: hex/rgb literais, opacity-50 pra desabilitado, cor de texto sem token semântico.

Marca e acessibilidadeCopy Anchor Link

• Roxo é ação primária e identidade; amarelo é atenção; lilás é superfície calma; vermelho só pra falha que para a proteção ou confirmação destrutiva.
• Foco visível: anel de 2 px na cor color/focus-ring, com 2 px de folga.
• Alvo ≥ 44 px nos tamanhos de celular. Status nunca só por cor.
• Copy de exemplo em pt-BR, sem vocabulário de vigilância.

ResponsivoCopy Anchor Link

• Duas larguras de referência: celular 390 e desktop 1440. A rota /__ds do platform renderiza cada matriz nas duas, em iframes, porque media query precisa de viewport de verdade.
• Tamanhos de toque: no celular, controles usam os tamanhos 44 e 48 (alvo ≥ 44 px). 32–40 e a escada densa xs–lg são pra desktop e backoffice.
• Espaçamento: px-gutter (16 px) é a margem lateral no celular; gap-section separa seções (64 px no desktop, 48 px no celular, pelo spacing/12 do Figma).
• Raio dos painéis: rounded-panel-phone (28 px) e rounded-panel (40 px).

Como um componente ganha página aquiCopy Anchor Link

Sozinho. Cada matriz registrada no examples.ts da família vira uma página em Componentes, na pasta da família, com a descrição tirada do doc comment do componente, um playground (Fumadocs Story), todas as células da matriz e a tabela de props tirada dos tipos. A lane só precisa:

1. registrar a matriz no examples.ts (já faz parte do trabalho, por causa do /__ds);
2. escrever o doc comment do componente e das props, em inglês.

Notas de uso opcionais vão em apps/docs/content/ds-notes/<família>/<componente>.mdx. Detalhes no README.md de apps/docs.