eduardopin/design-reference

design-reference — uma interface que se torna uma referência, não um template

Uma interface é uma referência quando alguém que conhece o assunto a reconhece como feita para este produto e por alguém no topo da área. O inimigo é o padrão: o que qualquer modelo produziria para qualquer briefing semelhante.

0. As regras do projeto

O primeiro passo de qualquer peça renderizada — tela, componente, documento HTML, Artifact, PDF, deck, diagrama (cloud-diagram), banner — é a varredura do sistema de design do projeto, uma vez por projeto por sessão:

python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <raiz>         # resumo
python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <raiz> --css   # :root com --ds-*

Ele lê a especificação escrita (DESIGN.md, docs/design*), os tokens (tailwind.config.*, CSS com :root/@theme, *.tokens.json), o tema de componentes, package.json, components.json, links do Storybook e Figma, e retorna o veredito: projeto (a peça usa seus tokens) ou neutro (a paleta neutra do squad). --css emite --ds-bg --ds-surface --ds-fg --ds-fg-2 --ds-accent --ds-border --ds-font-display --ds-font-body --ds-font-mono e o bloco escuro; os templates do squad leem essas variáveis. --json retorna o resultado completo. Precedência em conflito: especificação > tokens > componentes. Um sistema por página. Diga em uma linha qual sistema a peça usa e onde foi encontrado. A marca de um cliente ou terceiro: pergunte primeiro. Detalhes em references/design-system-sweep.md.

Em seguida, leia os componentes compartilhados que a nova tela usará. O briefing e o mundo visual já definidos superam qualquer gosto seu e qualquer regra aqui. Refinar preserva identidade, cópia e comportamento; redesgnar substitui todo o mundo visual — nunca polir a aparência que foi descartada. Uma skill de design própria do projeto (.claude/skills/) vence esta.

Sem um DESIGN.md o projeto não é necessariamente greenfield: a evidência é o código e as telas existentes, não o nome do arquivo.

1. Modo de superfície (decide tudo o que se segue)

Escolha pela superfície solicitada, não pelo produto:

Modo	Sucesso do visitante	Exemplos	O que rege
Persuadir	decide e age	landing page, preços, campanha	atenção, prova, chamada para ação — o design é o produto
Operar	completa uma tarefa	app, dashboard, admin, editor, configurações	escaneabilidade, consistência, expectativa nativa; a marca vive no detalhe
Ler	entende algo	docs, artigo, changelog, ajuda	estrutura para compreensão, depois conforto de leitura
Experiência	está dentro da obra	portfólio, galeria, museu, showcase	a obra lidera desde a primeira dobra; a interface fica em segundo plano

A landing page de uma ferramenta é Persuadir; a documentação de uma marca de moda é Ler; o tour de um museu é Experiência.

2. Direção antes do código (duas passagens, obrigatório)

Passagem 1 — plano compacto, antes de abrir qualquer arquivo de código:

• Assunto: uma frase: para quem é, qual é o único trabalho desta tela, e o que no mundo deste assunto (materiais, instrumentos, vocabulário, artefatos) pode se tornar uma escolha visual.
• Cor: 4–6 valores nomeados (hex ou oklch), com a função semântica de cada um.
• Tipografia: 2+ funções — uma face de exibição com caráter usada com moderação, uma face de corpo complementar, uma face utilitária para dados se necessário. Nunca o par que você usaria em qualquer outro projeto.
• Layout: conceito em uma frase + wireframe ASCII. Compare duas alternativas.
• Assinatura: o único elemento pelo qual a tela será lembrada. Toda a ousadia vai para lá; o resto permanece quieto e disciplinado.
• Movimento: um momento orquestrado, ou nenhum. Diga qual.

Passagem 2 — autocrítica. Para cada item, pergunte: "eu produziria isso para um briefing semelhante de outro produto?" Se sim, é um padrão, não uma escolha — reescreva-o e diga o que mudou. Só depois disso comece a codificar, derivando toda cor e tipo de letra do plano.

As três aparências que a IA produz por padrão hoje: (1) creme #F4F1EA + uma serifa de alto contraste + terracota; (2) quase preto + um acento ácido (verde lima ou vermelhão); (3) uma folha de regras finas, raio zero, colunas densas. Todas legítimas se o briefing as pedir. Onde o eixo é livre, não gaste a liberdade com elas.

Para um catálogo de estilos, paletas e pares tipográficos com busca local, use ui-ux-pro-max (python3 scripts/search.py "<domínio> <produto>"); é um motor de referência, não um diretor de arte — a decisão ainda é sua.

3. Tokens são a fonte da verdade

• Três camadas: primitivo → semântico → componente. Um componente nunca lê um primitivo ou um hex bruto; ele lê --color-surface-raised, não --gray-100.
• Formato: W3C DTCG 2025.10 (tokens.json) quando o projeto tem um pipeline; caso contrário, propriedades personalizadas CSS em :root com modo escuro em @media (prefers-color-scheme: dark) e [data-theme].
• Cor em oklch quando possível; contraste medido (APCA ou WCAG), não estimado.
• Um tema escuro é um mapeamento de luminância, não uma inversão.
• Quando terminar, se o projeto não tiver um DESIGN.md, ofereça para gerar um (tokens em YAML + a razão para cada valor em prosa) — é o que mantém a próxima sessão coerente com esta.

Escala, especificação de componente (variantes, tamanhos, estados com prioridade, anatomia) e notas sobre shadcn/Tailwind/modo escuro: references/tokens-and-components.md. Para gerar o sistema completo em DTCG + CSS/Tailwind: sumi:tokens.

4. Construção

• Stack e componentes: os do projeto. shadcn/Tailwind → references/tokens-and-components.md e a documentação ativa através do context7; um design vindo do Figma → figma:figma-design-to-code (MCP) ou a skill local do próprio projeto (por exemplo implement-from-figma, refactor-frontend-component); escrever no Figma → figma:figma-use.
• Mobile nativo: respeite a plataforma (HIG / Material) antes da marca.
• Um diagrama de arquitetura de nuvem ou infraestrutura (AWS, OCI, GCP, Azure, Cloudflare): cloud-diagram, sempre. É a skill de design para a tarefa; copie seu kit (o template.html nas referências dessa skill) e meça com seu render.sh. Sem mermaid, caixas genéricas ou ícones de imagem externos.
• Conteúdo real desde o início: teste texto curto, médio e muito longo; estado vazio; carregamento; erro; sem permissão. Lorem ipsum é um defeito.
• Cópia é material de design: um controle diz o que acontece ("Salvar alterações", não "Enviar"); o mesmo verbo do botão ao toast; um erro diz o que aconteceu e como sair; vazio é um convite para agir; voz ativa, frase inicial maiúscula.
• CSS: cuidado com especificidade que se anula (.section × .cta), transition: all nunca, apenas transform/opacity animam por padrão.
• Superfícies do navegador também são design: seleção de texto, cursor, scrollbar, foco, deslocamento de sublinhado, numerais tabulares. Tema-os a partir da paleta — é o sinal mais barato de que a página foi construída.

Companheiro de execução de UI de produto

Para UI de produto nativa ou responsiva, use a skill mobile-design-studio disponível como o único companheiro de design opcional: pequenas unidades de implementação, ergonomia mobile (alvos de toque, áreas seguras, teclado, escala de texto, volta), verificações de estado/recuperação e evidência de plataforma. design-reference permanece a única fonte de direção de design: reutilize seu briefing aprovado, tokens e componentes; não execute um segundo processo de branding/direção ou crie arquivos de token duplicados. Leia apenas a referência do companheiro necessária para a unidade atual. Não é a rota para decks, arte, pôsteres ou diagramas de nuvem; essas mantêm suas skills dedicadas.

Resolva o diretório do companheiro a partir do caminho de inventário original da skill selecionada, nunca de um cache de prompt gerado ou de uma instalação ~/.claude assumida. Se o companheiro estiver ausente ou for apenas manual, não o anuncie ou carregue automaticamente; continue com o método do projeto. Skills do projeto e pré-requisitos obrigatórios de plataforma/Figma (por exemplo, a visão geral do Expo, React Native e Figma design-to-code/use) ainda se aplicam; eles não são direções de design concorrentes opcionais. Mantenha o teto de duas skills de design: este método mais um companheiro, nunca uma pilha extra de estilo Sumi/UI.

5. Piso de qualidade (verificado no resultado, não na intenção)

Leia references/quality-floor.md imediatamente antes de editar a UI. Os pontos inegociáveis:

• Contraste ≥ 4.5:1 (texto), ≥ 3:1 (grande); texto secundário em uma superfície colorida matizada a partir do matiz dessa própria superfície, nunca cinza.
• Foco visível em tudo interativo; nunca remova um contorno sem um substituto.
• Alvo de toque ≥ 44×44 (nativo) / 24×24 px CSS (web), 8px entre alvos.
• prefers-reduced-motion respeitado; animação interrompível; nada iniciado por teclado anima.
• Responsivo até 320px sem rolagem horizontal; áreas seguras em layout sangrado.
• Imagem com dimensões declaradas; fonte com font-display; lista longa virtualizada.
• Estados: hover, active, focus, disabled, loading, error, empty — todos eles.
• Zero emoji como ícones; ícones de uma biblioteca, um traço, um peso.

Inspeção em rodadas limitadas, não em loop: construa tudo, capture desktop e mobile juntos (screenshot através do navegador quando houver um), corrija tudo em um lote, confirme com no máximo mais uma rodada, pare. QA sem fim queima o dinheiro do dono fazendo pior o que sumi:audit faz melhor.

6. Movimento com regras (Emil Kowalski)

1. Deve animar? 100+ vezes/dia (atalho, paleta) → nunca. Dezenas/dia (hover, navegação em lista) → reduza drasticamente. Ocasional (modal, drawer, toast) → padrão. Raro (onboarding, celebração) → pode encantar.
2. Um propósito declarado: continuidade espacial, indicação de estado, explicação, feedback, evitar um corte brusco. "Fica bonito" não é um propósito para algo visto com frequência.
3. Easing: entrada/saída → ease-out forte cubic-bezier(0.23, 1, 0.32, 1); mover/morfar na tela → ease-in-out cubic-bezier(0.77, 0, 0.175, 1); hover/cor → ease; movimento constante → linear; drawer iOS → cubic-bezier(0.32, 0.72, 0, 1). Nunca ease-in em UI.
4. Duração: botão 100–160ms; tooltip 125–200ms; dropdown 150–250ms; modal/drawer 200–500ms; UI sempre < 300ms exceto marketing.
5. Nada aparece do nada: scale(0.95) + opacity 0, não scale(0). Um popover escala a partir do seu gatilho (transform-origin); um modal permanece centrado. :active com scale(0.97). Uma entrada idêntica em cada seção é um anti-padrão; um momento autoral não é.

7. Arte, canvas e trabalho criativo

Quando a solicitação é um pôster, capa, peça gráfica, arte generativa, visual 3D ou "algo bonito sem briefing de UI", o método muda: primeiro uma filosofia visual (um movimento nomeado em 1–2 palavras + 4–6 parágrafos sobre espaço, cor, material, escala, ritmo, composição), depois a execução. A referência ao tema é sutil — quem conhece sente, os outros veem uma composição magistral. 90% visual, 10% texto. Nada sai da margem, nada se sobrepõe.

Superfície	Ferramenta
PNG/PDF estático (pôster, arte, capa)	vendor/canvas-design (Anthropic)
Arte generativa 2D, campos de fluxo, partículas	vendor/algorithmic-art (p5.js, seed reproduzível, sliders)
Cena 3D / shader / interativa	three.js (r160+), GLSL ShaderMaterial; sempre dispose() e remoção de listener no teardown
peça para mídia social / anúncio / banner / impresso	references/identity-and-pieces.md (tamanhos, área segura, chamada para ação) + HTML capturado no tamanho exato
slides	slides
Diagrama de arquitetura de nuvem	cloud-diagram
Guia de marca, paleta, regras de logo	references/identity-and-pieces.md; voz da marca e cópia → writing
Logo, ícone, mockup de identidade gerado por IA	design (claudekit: scripts de geração com uma API, precisa de chave)
Variantes lado a lado em um canvas infinito	plugin superdesign (pago; precisa de login — decisão do proprietário)
Imagem/vídeo gerado	sumi:generate ou os MCPs de imagem configurados

Nunca copie o trabalho de um artista identificável; cite a influência, crie o seu próprio. Fontes: baixe e auto-hospede uma com o caractere certo; a fonte do sistema "mais próxima" é uma falha, não um fallback.

8. Auditoria e correção do que já existe

• Pontuação rápida com as principais correções: sumi:roast. Auditoria completa (heurística, cognitiva, fluxo): sumi:audit. Acessibilidade WCAG 2.2 AA: sumi:a11y. Checklist web (a11y, formulários, movimento, tipografia, desempenho, i18n): references/quality-floor.md §B, saída como arquivo:linha.
• Corrigindo código de UI gerado: sumi:fix. Revisão de movimento: uma tabela | Antes | Depois | Porquê |, uma linha por descoberta.
• Nunca carregue mais de duas skills de design na mesma sessão: as descrições competem e o contexto incha sem melhorar a resposta.

9. Entrega

Modo             [Persuadir | Operar | Ler | Experiência]
Direção          [assunto · paleta nomeada · par tipográfico · assinatura · movimento]
O que era padrão [o que você reescreveu na autocrítica e porquê]
Tokens           [arquivo e camadas; DESIGN.md gerado/atualizado?]
Piso             [cada verificação da §5 com o valor medido, não "ok"]
Estados          [lista dos estados implementados]
Capturas         [desktop + mobile, se o ambiente permitir]
Pendente         [ativos que só o proprietário pode fornecer; decisões que são deles]