Especificação Components.build
Diretrizes abrangentes para construir componentes de UI modernos, componíveis e acessíveis. Contém 16 categorias de regras cobrindo desde princípios fundamentais até distribuição, coautorado por Hayden Bleasel e shadcn.
Quando Aplicar
Consulte estas diretrizes quando:
- Criando novos componentes React ou bibliotecas de componentes
- Projetando APIs de componentes e interfaces de props
- Implementando recursos de acessibilidade (teclado, ARIA, gerenciamento de foco)
- Construindo arquiteturas de componentes componíveis
- Estilizando componentes com Tailwind CSS e CVA
- Publicando componentes em registros ou npm
Categorias de Regras por Prioridade
| Prioridade | Categoria | Foco | Prefixo |
|---|---|---|---|
| 1 | Visão Geral | Escopo e objetivos da especificação | overview |
| 2 | Princípios | Filosofia central de design | principles |
| 3 | Definições | Terminologia comum | definitions |
| 4 | Composição | Decompondo componentes complexos | composition |
| 5 | Acessibilidade | Teclado, leitores de tela, ARIA | accessibility |
| 6 | Estado | Padrões controlado/não controlado | state |
| 7 | Tipos | Props e interfaces TypeScript | types |
| 8 | Polimorfismo | Troca de elemento com prop as | polymorphism |
| 9 | As-Child | Padrão de composição Radix Slot | as-child |
| 10 | Atributos de Dados | data-state e data-slot | data-attributes |
| 11 | Estilização | Tailwind CSS, utilitário cn, CVA | styling |
| 12 | Design Tokens | Variáveis CSS e temas | design-tokens |
| 13 | Documentação | Documentação de componentes | documentation |
| 14 | Registro | Registros de componentes | registry |
| 15 | NPM | Publicação no npm | npm |
| 16 | Marketplaces | Mercados de componentes | marketplaces |
Referência Rápida
1. Visão Geral
overview- Escopo, objetivos e filosofia da especificação
2. Princípios
principles- Composibilidade, acessibilidade, customização, transparência
3. Definições
definitions- Terminologia comum (primitivo, composto, headless, etc.)
4. Composição
composition-root- Componente raiz com Context para estado compartilhadocomposition-item- Componentes wrapper de itemcomposition-trigger- Componentes de gatilho interativoscomposition-content- Componentes de exibição de conteúdocomposition-export- Padrão de exportação por namespace
5. Acessibilidade
accessibility-semantic-html- Use elementos HTML apropriadosaccessibility-keyboard- Suporte completo de navegação por tecladoaccessibility-aria- Roles, estados e propriedades ARIA corretosaccessibility-focus- Gerenciamento e restauração de focoaccessibility-live-regions- Anúncios para leitores de telaaccessibility-contrast- Requisitos de contraste de cor
6. Estado
state-uncontrolled- Gerenciamento de estado internostate-controlled- Delegação de estado externostate-controllable- Suporte a ambos os padrões com useControllableState
7. Tipos
types-extend-html- Estenda atributos HTML nativostypes-export- Exporte tipos de props para consumidorestypes-single-element- Um componente envolve um elemento
8. Polimorfismo
polymorphism-as-prop- Altere o tipo do elemento renderizadopolymorphism-typescript- Componentes polimórficos com segurança de tipopolymorphism-defaults- Padrões semânticos de elementos
9. As-Child
as-child-slot- Radix Slot para mesclagem de propsas-child-composition- Componha com componentes filhos
10. Atributos de Dados
data-attributes-state- Usedata-statepara estilizar estadosdata-attributes-slot- Usedata-slotpara segmentar subcomponentes
11. Estilização
styling-cn-utility- Combine clsx e tailwind-mergestyling-order- Base → Variantes → Condicionais → Sobrescrições do usuáriostyling-cva- Class Variance Authority para variantesstyling-css-variables- Valores dinâmicos com variáveis CSS
12. Design Tokens
design-tokens-css-variables- Defina tokens como variáveis CSSdesign-tokens-theming- Suporte a modos claro/escuro e temas
13. Documentação
documentation-props- Documente todas as props com JSDocdocumentation-examples- Forneça exemplos de uso
14. Registro
registry-structure- Estrutura de arquivo do registroregistry-schema- Esquema de metadados do componente
15. NPM
npm-package-json- Configuração do pacotenpm-exports- Exportações do módulo
16. Marketplaces
marketplaces-distribution- Estratégias de distribuição de componentes
Como Usar
Leia arquivos de regra individuais para explicações detalhadas e exemplos de código:
rules/composition/SKILL.md
rules/accessibility/SKILL.md
rules/styling/SKILL.md
Cada arquivo de regra contém:
- Breve explicação de por que é importante
- Exemplo de código incorreto com explicação
- Exemplo de código correto com explicação
- Melhores práticas e armadilhas comuns
Documento Completo Compilado
Para o guia completo com todas as regras expandidas: AGENTS.md
Princípios Chave
- Composição sobre Configuração - Divida componentes em subcomponentes componíveis
- Acessibilidade por Padrão - Não é um pensamento posterior, mas um requisito
- Empacotamento de Elemento Único - Cada componente envolve um elemento HTML
- Estenda Atributos HTML - Sempre estenda props de elementos nativos
- Exporte Tipos - Torne os tipos de props disponíveis para consumidores
- Suporte Ambos os Padrões de Estado - Controlado e não controlado
- Mesclagem Inteligente de Classes - Use o utilitário
cn()com tailwind-merge
Autores
Co-autorado por:
- Hayden Bleasel (@haydenbleasel)
- shadcn (@shadcn)
Adaptado como um skill de IA por:
- Jordan Gilliam (@nolansym)
Baseado na especificação components.build.