Design System

design-system.md   → "O botão primário deve ter destaque máximo e feedback visual imediato"
tokens.json        → color.primary: #1A56DB, spacing.md: 16px

Nome do projeto:
Versão do documento:
Status: [rascunho | revisando | aprovado]
Documentos base: Docs/pages.md, Docs/flow.md, Prototype/, Docs/project.md
Data de criação:
Última atualização:

Clareza         — [o que significa clareza neste produto]
Consistência    — [como a consistência é mantida entre telas]
Legibilidade    — [regras de legibilidade para o contexto]
Eficiência      — [como a interface reduz esforço do usuário]
Acessibilidade  — [comprometimento e escopo da acessibilidade]

Direção visual:     [minimalista | sóbria | técnica | premium | operacional | amigável]
Personalidade:      [descreve]
Sensação desejada:
  - [sensação 1]
  - [sensação 2]
O que evitar:
  - excesso visual
  - ambiguidade
  - contraste ruim
  - interações inesperadas

Estrutura base:  [header + conteúdo + ações | sidebar + principal | dashboard modular]
Composição:
  - [regra 1]
  - [regra 2]
Espaçamento:     [lógica — valores ficam em Docs/tokens.json]
Alinhamento:     [descreva]
Responsividade:
  - [breakpoints e comportamento]
Grid / containers: [lógica estrutural]

título de página    — destaque máximo, uma ocorrência por tela
título de seção     — organização de blocos
subtítulo           — complemento de seção
corpo principal     — leitura contínua
corpo secundário    — informação de apoio
legenda             — dados auxiliares menores
rótulo              — formulários e listas
ajuda               — instrução contextual
feedback            — validação e estados
ação                — labels de botões e links

primária         — ação principal, identidade do produto
secundária       — ação de apoio ou alternativa
neutra           — textos, bordas, superfícies e ícones
sucesso          — confirmação, conclusão, estado positivo
aviso            — atenção, estado intermediário
erro             — falha, validação negativa, bloqueio
informação       — contexto adicional, tooltip
destaque         — ênfase controlada
superfície       — fundo de card, modal, container
borda            — separação e delimitação
texto            — hierarquia de leitura
estado desabilitado — elemento não interativo

default    — estado inicial sem interação
hover      — cursor sobre o elemento
active     — elemento pressionado
focus      — elemento selecionado por teclado
disabled   — não interativo
loading    — aguardando resposta
success    — operação concluída
error      — falha de operação
empty      — sem conteúdo para exibir
selected   — item ativo ou marcado
pressed    — botão ou controle ativado
readonly   — exibição sem edição
invalid    — entrada com erro de validação

Princípios:
  - previsibilidade — o usuário sabe o que vai acontecer
  - tempo de resposta claro — loading sempre visível em operação assíncrona
  - baixo esforço cognitivo — hierarquia clara de ação
  - feedback imediato — toda ação tem resposta visual
 
Padrões obrigatórios:
  - formulários com validação por campo (não só no submit)
  - botões com hierarquia bem definida (primário, secundário, ghost)
  - confirmação em ações destrutivas ou irreversíveis
  - navegação consistente entre telas do mesmo módulo
 
A evitar:
  - ação sem feedback (botão que não responde)
  - ação destrutiva sem confirmação
  - labels ambíguos ("OK", "Confirmar" sem contexto)
  - estados invisíveis (sem loading, sem erro)

botão           input           textarea
select          checkbox        radio
switch          badge           card
modal           drawer          tooltip
alert           toast           tabela
tabs            pagination      breadcrumb
avatar          skeleton        spinner
empty state

#### Componente: [Nome]
 
Objetivo: [para que serve]
 
Variações previstas:
- [variação 1]
- [variação 2]
 
Tamanhos previstos:
- pequeno | médio | grande
 
Estados obrigatórios:
- default | hover | active | focus | disabled | loading
 
Regras de uso:
- [regra 1]
- [regra 2]
 
Restrições:
- [o que não fazer com este componente]
 
Acessibilidade:
- [aria, foco, contraste mínimo, navegação por teclado]

#### Componente: Button
 
Objetivo: disparar ação do usuário
 
Variações: primário, secundário, ghost, link, destrutivo
Tamanhos:  pequeno, médio, grande
 
Estados obrigatórios:
- default, hover, active, focus, disabled, loading
 
Regras:
- Máximo 1 botão primário por superfície de ação
- Botão destrutivo nunca deve ser a ação padrão
- Label deve ser verbo + objeto ("Salvar alterações", não "OK")
 
Restrições:
- Não usar button para navegação quando o elemento correto é link/anchor
- Não empilhar botões primários sem hierarquia clara
 
Acessibilidade:
- role="button" ou <button> nativo
- foco visível com outline definido
- state disabled com aria-disabled="true"

página de listagem   — título, filtros, ações, tabela/lista, paginação, estados
página de detalhe    — header, seções, ações contextuais, estados
formulário simples   — título, campos, validação, ações, feedback
formulário multi-etapas — progress, passo atual, navegação, validação por etapa
dashboard            — métricas, gráficos, alertas, ações rápidas
tela de autenticação — foco único, sem distrações, feedback de erro inline
tela vazia           — ilustração, título e orientação de próxima ação
tela de erro         — código de erro, mensagem, ação de recuperação
tela de confirmação  — ação destacada, contexto claro, opção de cancelamento

design-system.md define → papel, regra, semântica, comportamento
tokens.json define       → valor, escala, alias, categoria para código
 
Regra: toda semântica documentada aqui deve ter correspondência em tokens.json

Docs/pages.md   → design-system orienta componentes e estados de cada tela
Docs/flow.md    → design-system define padrão de feedback para estados de navegação
Prototype/      → design-system reflete e registra padrões validados na prototipagem
Docs/tokens.json→ design-system é a fonte semântica que tokens estruturam como valores
Docs/tasks.md   → tasks de UI/UX devem referenciar regras deste documento

Obrigatório:
  - respeitar hierarquia de ação (1 primário por superfície)
  - implementar todos os estados listados por componente
  - manter contraste WCAG AA
  - não criar variação de componente sem registrar aqui
 
Pode variar com segurança:
  - ordem de apresentação de campos opcionais
  - animações de transição (desde que dentro das diretrizes)
 
Exige atualização deste documento:
  - novo padrão visual recorrente em mais de 1 tela
  - nova variação de componente aprovada
  - mudança de regra semântica de cor ou tipografia

Direção visual resumida:          [preencher]
Princípios que não podem ser quebrados:
  - [princípio 1]
  - [princípio 2]
Componentes mais críticos:        [preencher]
Estados que devem existir com consistência: [preencher]
O que ainda está indefinido:      [ponto 1]

Status: [pendente | aprovado | revisando]
Aprovado por:
Data de aprovação:
Observações finais:

## Direção visual
[linguagem visual do projeto]
 
## Princípios
- clareza
- consistência
- legibilidade
- acessibilidade
 
## Regras gerais de layout
- [regra 1]
- [regra 2]
 
## Tipografia — regras de uso
- [regra 1]
 
## Cores — semânticas
- primária, secundária, neutra
- sucesso, aviso, erro, informação
Regras: [preencher]
 
## Estados consistentes
default, hover, active, focus, disabled, loading, success, error, empty, invalid
 
## Componentes principais
 
### Button
Variações: primário, secundário, ghost
Estados: default, hover, active, disabled, loading
Regras: [preencher]
 
### Input
Estados: default, focus, invalid, disabled
Regras: [preencher]
 
### Modal
Quando usar: [caso]
Quando não usar: [caso]
 
## Padrões de página
listagem, detalhe, formulário, dashboard, autenticação, erro, vazio
 
## Acessibilidade
- contraste adequado
- foco visível
- labels claros
- feedback não dependente só de cor
 
## Relação com tokens.json
Este documento: regras, semânticas, comportamento
tokens.json: valores, escalas, aliases
 
## Síntese para Dev e AI
- Aplicar componentes e estados conforme regras deste documento
- Sincronizar com tokens.json e Prototype/
- Em conflito entre rapidez e consistência: priorizar acessibilidade e previsibilidade

Atue como UIAgent.
Objetivo: criar Docs/design-system.md com base em Docs/pages.md e Docs/flow.md
 
Carregue contexto base:
- GUIDE.md
- Skills/ui-ux.md
- Templates/Full/design-system.md
- Docs/pages.md
- Docs/flow.md
 
Preencha as 17 seções do template Full.
Seção 3: defina os princípios com descrição aplicada ao projeto.
Seção 7: mapeie todos os papéis semânticos de cor.
Seção 8: liste os 13 estados obrigatórios com feedbacks esperados.
Seção 10: registre contrato de cada componente identificado nas páginas.
Seção 11: defina padrões para cada tipo de página presente em Docs/pages.md.
Seção 12: especifique regras de acessibilidade aplicadas ao contexto.
Marque [indefinido] onde houver decisão pendente de prototipagem.

Docs/design-system.md (aprovado)
    ↓
Docs/tokens.json     — valores estruturados derivados das semânticas definidas aqui
Prototype/           — implementações visuais validadas contra estas regras
Docs/tasks.md        — tasks de UI referenciam componentes e estados deste documento