Design de UI
Um agente que recebe a tarefa de escrever uma tela, escreve a tela. Esta habilidade fecha a lacuna em ambos os lados disso. Primeiro, decidindo para que serve a superfície e qual deve ser sua aparência. Depois, descobrindo se a coisa construída realmente cumpre o papel.
Duas regras governam tudo abaixo. Nomeie o resultado para o cliente antes do primeiro arquivo. Execute o produto em funcionamento antes de dizer que funciona.
Escolha a profundidade primeiro
| A mudança | Etapas |
|---|---|
| Cópia, uma cor, uma prop | 1, 7, depois veja o resultado |
| Um componente, um estado | 1, 4, 6, 7, 9 |
| Uma tela, um formulário, um fluxo | 0 a 10, resumidamente |
| Uma nova superfície, ou "deixe isso moderno" | 0 a 10 completo, com a etapa 3 aprovada antes da etapa 7 |
| "Audite isto" | Use ui-review. Não comece a editar |
| "Encontre um componente para…" | Use ui-find |
Diga qual profundidade você escolheu, em uma linha, antes de começar. Uma etapa é pulada apenas quando a mudança não pode alcançar o que aquela etapa protege.
0. Pré-voo: leia o projeto antes de perguntar qualquer coisa
Leia, nesta ordem, e pare na primeira que responder à pergunta:
DESIGN.mdna raiz do projeto. Um sistema de design que já existe tem precedência sobre todas as configurações padrão desta habilidade e sobre seu próprio gosto. Siga-o. Onde o trabalho precisar de algo que o arquivo não cobre, adicione isso ao arquivo em vez de inventar em uma folha de estilo.PRODUCT.md,README.md,.claude/, um briefing existente.- A stack, o sistema de estilo e a biblioteca de componentes em uso.
- A tela existente mais próxima e os testes que a cobrem.
Uma tela que contradiz o próprio sistema do produto é uma descoberta, não uma licença para iniciar um terceiro sistema.
1. O sistema de design
references/design-system.md contém o formato e ambas as rotas.
| O projeto tem | Faça isto |
|---|---|
Um DESIGN.md | Leia-o, siga-o e diga isso em uma linha |
| Um sistema de design real em código: tokens, arquivo de tema, configuração Tailwind | Codifique-o em DESIGN.md lendo os valores do código, nunca adivinhando-os |
| Um produto vivo ou uma marca sem sistema escrito | Codifique a partir da coisa real: renderize-a, leia os valores computados, registre-os |
| Nada | Escreva um na etapa 3, a partir da direção que o usuário escolher |
Nunca escreva um DESIGN.md que declare valores que o produto não usa. Um sistema codificado é um registro do que está lá. Um sistema novo é uma proposta e é marcado como tal até que o usuário o escolha.
Proteja o arquivo antes de construir contra ele:
pnpm dlx @google/design.md lint DESIGN.md
É um pacote publicado real. Ele detecta referências de token quebradas, um primary ausente, tipografia que nunca foi definida e qualquer par de cor de componente abaixo do piso de contraste 4.5:1. Corrija o que ele relatar antes da etapa 7.
2. O resultado para o cliente
references/product-thinking.md contém o método. O resultado de negócio, o cliente e sua tarefa, e a menor versão útil. Duas linhas cada.
Escreva o resultado como algo observável:
Um despachante com 40 corridas abertas pode ver qual corrida está atrasada e reatribuí-la sem sair da lista.
Depois, critérios de aceitação que podem ser verificados em um navegador. "Parece bom" não é um critério. "Em 375px, o status de cada corrida e seu controle de reatribuição estão acessíveis sem rolagem horizontal" é.
Onde não houver evidência, escreva a suposição e rotule-a. Nunca escreva uma persona, uma citação ou um número de conversão que ninguém produziu.
3. Direções e a escolha do usuário
references/directions.md contém o método e o vocabulário.
Apresente três direções, não uma. Uma única proposta é a estética padrão do modelo vestindo uma justificativa. Cada direção recebe um nome, o matiz âncora, o par de tipografia, a densidade e a única coisa memorável, em quatro linhas.
Então pare e apresente-as ao usuário com a ferramenta de pergunta interativa. Este é um portão de aprovação: não construa além dele baseado em suposição. Onde o usuário disser "você escolhe", escolha uma, diga qual e por que em uma linha, e continue.
Com um sim, escreva ou atualize DESIGN.md com os valores reais da direção escolhida e execute o lint.
4. A jornada e seus estados
references/journey-and-states.md.
Liste os estados que esta superfície realmente tem: vazio, um item, muitos, o caso real mais denso, carregando, falha parcial, erro, sem permissão. Uma tela construída com um único fixture esconde todos os outros estados, e essa é a razão mais comum pela qual uma tela finalizada falha ao contato com o cliente.
5. Encontre componentes antes de escrevê-los
Execute ui-find, ou seu script diretamente:
node .claude/skills/ui-design/scripts/find-components.js <termos> --limit 15
Pesquise os próprios componentes do projeto primeiro. Uma segunda implementação de um componente que o produto já possui é um defeito. Escreva um componente do zero apenas depois de nomear os candidatos lidos e por que cada um era inadequado.
6. Mock ou o produto real
Pergunte qual, em uma linha, a menos que o usuário já tenha dito. Ambas as rotas constroem HTML e CSS reais; a diferença é onde o arquivo cai e ao que está conectado.
| Rota | Quando | Onde vai |
|---|---|---|
| Mock | Uma nova superfície, um redesenho, uma parte interessada a convencer, ou o usuário pede um | Uma página autônoma em mock/, com os tokens de design reais e dados de exemplo que dizem claramente que são exemplo |
| Direto | Uma mudança dentro de um produto vivo, ou o usuário diz para construir | Os próprios arquivos do produto |
Um mock é aprovado e depois reconstruído nos componentes do produto. Diga isso antes de construí-lo, para que ninguém espere que o arquivo mock seja enviado.
7. Construa
Construa os estados da etapa 4, não apenas o caminho feliz. Use os tokens e componentes do próprio produto.
Leia references/gates.md e references/craft.md imediatamente antes da primeira edição de UI, toda vez, mesmo uma pequena.
gates.md é o piso: os padrões em que todo modelo cai e o que fazer em vez disso. craft.md é a camada acima. Profundidade como sombra em vez de borda. Raios concêntricos. Aceleração suave abaixo de 300ms. Entradas que disparam uma vez e nunca em uma interação repetida. Figuras tabulares. Duas partes de uma tela conectadas, para que o cliente veja que são uma coisa só.
Construa a tela mais importante, ou o herói, sozinha e primeiro. Revise-a antes de construir o restante, com novos olhos: um subagente sem memória das decisões captura o que você não consegue. Depois construa o restante.
8. Execute e olhe para ela
Não é uma revisão de código. Inicie a aplicação, abra-a em um navegador e use-a a partir do ponto de entrada real como o cliente faria.
references/playwright.md contém a mecânica e o que fazer quando a aplicação não iniciar aqui.
Olhe para as capturas de tela. Ler uma lista de arquivos não é olhar.
9. Revise e corrija
Execute ui-review contra o que você construiu. Ele mede a renderização ao vivo, percorre a jornada, verifica o resultado contra DESIGN.md e classifica as descobertas por dano.
Corrija na ordem de gravidade. Uma mudança que você não pode justificar contra o resultado da etapa 2 é escopo que ninguém pediu. Diga o que você deixou de lado e por quê.
Depois references/regression.md: identifique as jornadas que já funcionavam antes de tocar no código e separe as falhas causadas pela sua mudança das falhas que já estavam lá.
10. Relatório
- O resultado para o cliente e se foi atendido.
- A direção escolhida e por quem.
- O que foi construído ou alterado, por arquivo.
- O que foi verificado, por quais meios, em quais larguras, em quais estados.
- O que não foi verificado e por quê.
- Descobertas corrigidas e descobertas deixadas com sua justificativa.
- Suposições que ainda são suposições.
Honestidade, que tem precedência sobre todas as etapas acima
- Nunca relate uma medição que você não fez ou uma tela que você não renderizou.
- Nomeie cada substituto. Um fixture para dados ao vivo, uma página estática para a aplicação, uma fonte local para a fonte da marca.
- Quando a aplicação não puder ser iniciada ou acessada, diga isso e marque cada alegação de jornada como não verificada. Não descreva o código como se o tivesse visto executar.
- Nunca invente uma métrica, um depoimento, uma parede de logotipos ou uma contagem de clientes. Onde o número real estiver faltando, deixe um slot rotulado e diga que está vazio.
- Um formulário sem nada por trás diz isso claramente. Uma página que imprime "Enviado" sem enviar é um defeito, não um placeholder.
- Percorrer uma jornada você mesmo encontra atritos. Isso não mede o que os clientes fazem.
O que esta habilidade pega emprestado e de onde
NOTICE registra. Fontes de componentes e suas licenças estão em sources.json; scripts/check-sources.js valida esse arquivo e tests/run.sh testa os scripts.