Especialista Design System no Specsfy: documentação técnica

Quando usar

Esta skill governa o documento DESIGNSYSTEM.MD do projeto consumidor. Ela define linguagem visual, shell, composição de superfícies, estados e regras de negócio expostas na interface. O documento orienta UX, UI, experiência de interface e componentes React.

Use antes de criar ou revisar uma tela, um fluxo CRUD, uma navegação, um formulário ou um componente global. Use também quando o documento não existir, estiver desatualizado ou entrar em conflito com uma tela já projetada.

Não use esta skill para catalogar componentes, props ou arquivos locais. Esse registro pertence a INTERFACE.md, que deve apontar para as escolhas macro sem copiá-las.

Fontes obrigatórias

Leia, nesta ordem:

1. DESIGNSYSTEM.MD na raiz do projeto consumidor, se existir.
2. .specsfy/templates/DESIGNSYSTEM.MD para criar a fonte ausente.
3. INTERFACE.md para conhecer componentes e telas já registradas.
4. .specsfy/STACK.md, manifests, rotas, telas, permissões e regras do domínio relacionadas à entrega.

Quando a fonte não existir, copie o template gerenciado para DESIGNSYSTEM.MD e preencha apenas o contexto já confirmado. Não esconda lacunas com texto genérico.

Fluxo

1. Identifique o produto, o módulo, a superfície e o fluxo afetado.
2. Compare a solicitação com DESIGNSYSTEM.MD e preserve as regras já ativas.
3. Se a pessoa não informa direção visual, aplique os defaults do documento e registre isso como direção padrão da entrega.
4. Se a pessoa fornece uma direção diferente, registre a exceção, seu alcance e a regra que ela substitui. Uma exceção de tela não altera o produto todo.
5. Atualize o documento somente quando a regra tiver alcance macro. Registre componentes e telas específicas em INTERFACE.md.
6. Mapeie os cenários canônicos da superfície antes de entregar a orientação para UX, UI ou implementação.
7. Retorne os arquivos lidos, a regra aplicada, as exceções registradas e os cenários cobertos.

Em toda entrega visual, faça a revisão durante o desenvolvimento mesmo sem pedido da pessoa. Confira bordas, espaçamentos, margens, padding e tipografia do sistema nos viewports e estados relevantes. Registre o método, o resultado e os ajustes no item VISUAL da tarefa.

Padrões

Defaults obrigatórios para SaaS

Quando não houver direção visual contrária, aplique estas composições:

• Lista de CRUD: PageHeader + resumo útil + DataGrid. Use busca, filtros, ordenação, paginação, seleção e ações por linha quando o volume ou o domínio pedir.
• Detalhe: PageHeader + DetailLists, com status, próxima ação e relações ou atividade quando forem úteis para o domínio.
• Criar e editar: PageHeader + seções de formulário em duas colunas responsivas, com coluna de contexto e painel de campos.
• Formulário: labels visíveis acima dos campos, ajuda contextual, valores preservados e estado de envio.
• Erro de campo: borda, fundo ou ícone semântico vermelho, mensagem visível abaixo do campo, associação semântica e foco no primeiro erro.
• Erros múltiplos: resumo no início com links para os campos afetados.
• Tela: loading, vazio, erro, sucesso, sem permissão, conteúdo parcial e não salvo quando o fluxo comportar esses estados.
• Breadcrumb: obrigatório em toda tela da aplicação, com o nome da equipe ativa visível antes do módulo e do título atual. Em Laravel, reaproveitar o Breadcrumb ou Breadcrumbs existente no layout e seus tipos de rota.
• DataGrid: linha inteira clicável para abrir o detalhe, com equivalente de teclado e controles internos protegidos por TableRowAction ou equivalente.
• CRUD: todas as telas reutilizam o mesmo PageHeader componentizado, a lista usa DataGrid em largura total, exibe a coluna ID e oferece botões de editar e apagar na linha. O link da linha leva ao detalhe sem capturar os botões.
• Componentes recorrentes de cabeçalho, tabela, linha, ações, formulário, estados e feedback entram em INTERFACE.md e são reaproveitados antes de uma nova implementação.

Esses defaults não significam aparência genérica. A personalidade vem da hierarquia dos dados, linguagem do domínio, tipografia, tokens, ritmo, estados, contraste e uso do shell. A composição deve informar e orientar a tarefa.

Dashboards e blocos comuns

Quando a entrega incluir um dashboard, use PageHeader, período ou escopo, filtros, uma faixa curta de KPI com valor, unidade, período, comparação e fonte, seguida da tendência ou distribuição principal e de uma lista detalhada ou DataGrid para investigação. Cada indicador e visualização deve declarar loading, vazio, erro e atualização, além de alternativa textual ou tabular para gráficos.

Use primitives do shadcn/ui para controles fundamentais e blocos gratuitos do ReUI para composições de CRUD e dashboard quando eles atenderem à tarefa. Adapte tokens, dados, permissões, acessibilidade e linguagem do produto. Registre origem, estados e consumidores em INTERFACE.md.

Formulários de criar e editar

Organize criar e editar em seções independentes. Cada seção apresenta contexto à esquerda e o painel de campos à direita. No painel, campos relacionados usam duas colunas nos breakpoints largos e uma coluna no mobile, campos longos, uploads e erros podem ocupar toda a largura. O rodapé mantém cancelar e salvar próximos do resultado da ação.

Breadcrumb e shell

Toda tela renderiza o Breadcrumb no shell global. A trilha deve mostrar a equipe ativa, o módulo e a tela atual, usando labels reais e links válidos nos itens anteriores. Em aplicações Laravel, localize e reaproveite o componente Breadcrumb ou Breadcrumbs já presente no layout, junto da tipagem dos itens, adapte apenas a composição necessária para inserir a equipe sem duplicar o primitive. A equipe e a tela atual continuam visíveis no mobile.

Cenários que toda entrega deve cobrir

Consulte a seção Cenários canônicos do template e registre o recorte aplicável em DESIGNSYSTEM.MD ou na spec da entrega:

• lista com registros,
• lista vazia,
• detalhe com status e ações,
• criação válida,
• edição válida,
• criação ou edição com erro de campo,
• ausência de permissão,
• falha de carregamento,
• alteração não salva, quando houver edição,
• resultado de ação destrutiva, quando houver exclusão ou cancelamento.

Para cada cenário, informe pré-condição, ação, resposta, estado visual, foco, mensagem e próximo passo.

Limites e handoff

• UX define fluxo, arquitetura da informação e linguagem da tarefa a partir desta fonte.
• UI define tokens, hierarquia, composição visual e estados a partir desta fonte.
• Componentes React escolhem primitives e composições compatíveis depois de ler esta fonte e INTERFACE.md.
• A skill de experiência de interface coordena a entrega e não deve iniciar uma tela sem carregar DESIGNSYSTEM.MD.

Antipadrões

• Parede de cards quando a pessoa precisa comparar registros.
• Formulário sem seções quando o domínio tem grupos de informação distintos.
• Duas colunas no mobile ou uma grade que separa campo, ajuda e erro.
• Placeholder usado como único label.
• Erro indicado somente por ícone, cor ou toast distante do campo.
• Tela sem PageHeader, sem estado vazio ou sem caminho de recuperação.
• Dashboard que mostra números sem pergunta, período, unidade ou próxima ação.
• Dashboard que usa uma parede de cartões sem hierarquia ou investigação.
• Bloco de ReUI ou primitive de shadcn/ui usado sem adaptar dados, estados, permissões e tokens do produto.
• Novo token ou componente criado sem verificar o documento e INTERFACE.md.
• Exceção visual local registrada como regra global sem alcance explícito.
• CRUD com cabeçalhos duplicados, DataGrid estreito, ID oculto ou sem ações de editar e apagar na linha.

Validação

Antes do handoff, confira:

• DESIGNSYSTEM.MD existe na raiz do projeto consumidor e tem classificação, política, defaults, estados, cenários e histórico.
• A lista usa DataGrid e PageHeader.
• Toda tela tem Breadcrumb com o nome da equipe ativa, módulo e tela atual.
• Laravel reaproveita o Breadcrumb ou Breadcrumbs já existente no layout.
• O detalhe usa DetailLists e PageHeader.
• Criar e editar usam seções, coluna de contexto, painel de campos em duas colunas nos breakpoints largos e uma coluna no mobile.
• Erros de campo aparecem em vermelho abaixo do campo e têm associação semântica.
• A direção padrão ou a exceção está registrada com alcance.
• INTERFACE.md contém somente o registro local da entrega.
• A spec e as tarefas cobrem estados, permissão, foco, mensagens e retorno.
• O dashboard, quando existir, tem filtros, contexto dos indicadores, alternativa acessível para visualizações e investigação detalhada.
• Primitives shadcn/ui e blocos ReUI têm origem, estados e consumidores registrados em INTERFACE.md.
• Cada tarefa possui o item VISUAL concluído antes de EVIDENCE, com a conferência de bordas, espaçamentos, margens, padding e tipografia ou a justificativa concreta de que não há interface.

Execute os testes e validadores da stack quando houver implementação. Para a skill do Specsfy, execute quick_validate.py e a suíte do monorepo.

Skills relacionadas

• references/standards.md
• skills/templates/DESIGNSYSTEM.MD
• skills/templates/Interface.md
• specsfy-specialist-interface-experience
• specsfy-specialist-ux-design
• specsfy-specialist-ui-design
• specsfy-specialist-react-ui-components