spnngl/agent-skills

Especialista em UI

Esta skill define o que é a interface e prova que ela funciona para as pessoas. Os idioms de código (TypeScript, React, Next.js, testes, lint) vêm da skill ts-coding: carregue-a sempre que tocar em arquivos .ts ou .tsx.

Fluxo de Trabalho

1. Orientar. Leia as fontes de verdade da UI: package.json (react, next, tailwindcss, a biblioteca de primitivas: react-aria-components, @radix-ui/*, @base-ui-components/react ou components.json do shadcn; o conjunto de ícones; @playwright/test, @axe-core/playwright), a folha de estilo que contém @import "tailwindcss" e @theme, o mecanismo de modo escuro, o diretório de componentes compartilhados e duas ou três telas existentes próximas à que você está alterando. As escolhas existentes do projeto têm precedência sobre os padrões desta skill; reutilize suas primitivas, tokens, ritmo de espaçamento e terminologia. Concluído quando: você puder nomear o sistema de estilização, o arquivo de tokens, a biblioteca de primitivas, o conjunto de ícones, a troca de tema, o comando de desenvolvimento e a URL que renderizam o trabalho, e o executor de testes do navegador (ou que nenhum existe).

2. Enquadrar o briefing. Antes de qualquer marcação, escreva este bloco em sua resposta e construa a partir dele:

   Usuário e tarefa:    quem usa isto e a única tarefa que atende
   Destaque:            o único elemento em que o olho pousa primeiro
   Ação primária:       a única ação afirmativa; ações destrutivas nomeadas separadamente
   Densidade:           esparsa | confortável | densa, correspondente às telas vizinhas
   Tom:                 um adjetivo que o resultado deve merecer ("preciso", "calmo", "acolhedor")
   Estados:             vazio, carregando, erro, parcial, transbordamento, sem permissão: aqueles que se aplicam
   

   Layout, composição e arte visual: references/taste.md. Concluído quando: todo campo contém uma resposta concreta para esta tela, específica o suficiente para que um revisor pudesse rejeitar uma construção que a perca.

3. Resolver tokens. Mapeie toda cor, tamanho, espaço, raio, sombra e duração para um token semântico da etapa 1. Adicione um token ausente na fonte com valores claro e escuro, seguindo references/tokens.md. Concluído quando: o diff não contém cor bruta, valor arbitrário (p-[13px], bg-[#1a1a1a]) ou estilo inline para uma propriedade temável, cada novo token tem um valor claro e um escuro, e node scripts/contrast.ts <theme.css> (caminho relativo ao diretório desta skill) passa.

4. Construir. Componha a partir das primitivas do projeto (React Aria Components quando não houver nenhuma), mobile-first, seguindo as Regras e references/components.md. Semântica, teclado e detalhes WCAG: references/accessibility.md. Texto de interface: references/copy.md. Concluído quando: todo elemento interativo cobre cada estado que se aplica, toda visualização de dados renderiza cada estado nomeado no briefing, e os estilos sem prefixo são o layout de 320px.

5. Verificar. Execute as verificações de ts-coding, depois os portões estáticos e de navegador em references/verification.md: desvio de tokens, emoji, contraste de tokens, axe no claro e escuro, teclado, reflow em 320px, tamanho do alvo, movimento reduzido. Concluído quando: todo portão sai com código 0 e você relata o que cada um imprimiu; um portão que você não pôde executar é relatado como "não verificado" com a razão.

6. Olhar. Capture a tela do trabalho a 1280 e 390 de largura, claro e escuro, mais cada estado do briefing; abra cada imagem com a ferramenta de leitura e clique em cada controle. Em seguida, argumente pela rejeição com references/review.md. Quando uma ferramenta de subagente estiver disponível, entregue as capturas de tela e esse arquivo a um novo agente: um crítico que não construiu a tela vê com mais clareza. Concluído quando: você visualizou cada captura de tela, cada controle produziu uma mudança visível, e cada descoberta Crítica ou Grave foi corrigida ou relatada ao usuário.

Alterações pequenas (um ajuste de espaçamento, cor ou texto dentro de um componente existente): execute as etapas 1, 3 e os portões estáticos da etapa 5, depois capture a tela do elemento alterado no claro e escuro e visualize ambos.

Revisando UI existente: execute a etapa 1, escreva o briefing da etapa 2 como você o infere, execute as etapas 5 e 6 contra ela e relate no formato de references/review.md. Sem uma renderização, diga isso e limite as descobertas ao que o código-fonte prova.

Regras

Evidência

• Declare uma taxa de contraste, um passe ou uma pontuação apenas quando um comando acabou de imprimi-lo; caso contrário, diga "não verificado". Um portão que pulou (sem navegador, sem servidor) não mediu nada.
• Portões provam correção, nunca qualidade: julgue hierarquia e arte a partir de capturas de tela.

Hierarquia

• Um elemento lidera: o destaque do briefing é o maior, mais pesado ou de maior contraste, e seus pares ficam mais suaves. Em páginas de marketing e landing pages, o tipo de exibição é pelo menos 2,5x o tamanho do corpo; telas de produto mantêm o título da página um ou dois passos acima do corpo, com peso e posição fazendo o resto.
• O espaçamento cresce para fora: lacunas dentro de um grupo < preenchimento de seu contêiner < espaço entre seções.
• Um estado vazio preenche sua região e nomeia a primeira ação. Uma página termina com propósito: um resumo, um rodapé, um próximo passo.

Tokens e cor

• Token por intenção: escolha o token cujo significado corresponda à ação. Uma ação destrutiva usa o token destrutivo tanto em seu gatilho quanto em sua confirmação; o primário marca a única ação afirmativa principal por visualização.
• Cada status combina cor com um ícone ou texto. Um acento; neutros carregam o resto.
• A tematização é uma única edição na fonte do token: toda tela lê os mesmos tokens semânticos.
• Claro e escuro seguem a preferência do sistema; uma configuração Sistema / Claro / Escuro a substitui e persiste (references/tokens.md).

Estados

• Elementos interativos: padrão, hover, focus-visible, pressionado, desabilitado, pendente, inválido, selecionado. Cada um que se aplica é visualmente distinto, no claro e no escuro; seletores em references/components.md.
• Pendente mantém o controle em força total com um spinner ou rótulo de progresso (isPending, aria-busy). Desabilitado marca uma ação que o usuário não pode tomar agora, com a razão visível nas proximidades.
• Feedback relata o que aconteceu: um toast de sucesso aparece após os dados mudarem, e a visualização já mostra a mudança.

Layout

• Mobile é a base: utilitários sem prefixo são o layout de telefone; sm:, md:, lg: adicionam camadas em telas mais largas. Componentes reutilizados em diferentes larguras respondem ao seu contêiner (@container, @md:).
• Uma região que rola horizontalmente mostra uma dica visível: um desvanecimento na borda, uma barra de rolagem.

Salvaguardas

• Ícones vêm do lucide-react (ou do conjunto do projeto) como SVG com currentColor. Zero emoji na UI, no texto, no código e nos commits.
• Superfícies separam com uma borda fina de um pixel, um passo de superfície ou espaçamento. Uma borda colorida em apenas um lado de um cartão, alerta, toast ou callout é proibida.
• O conteúdo é realista: nomes plausíveis, strings longas, números grandes, zero e um itens. Texto placeholder e controles de depuração nunca são renderizados no produto.

Referências

Carregue a que corresponde ao branch em que você está:

• references/taste.md: indicadores de baixa qualidade, composição, tipografia, cor, profundidade; qualquer nova tela ou reformulação.
• references/tokens.md: @theme do Tailwind v4, tokens semânticos, tema do sistema e sua configuração de substituição, adicionar ou auditar tokens.
• references/components.md: React Aria Components, atributos de estado, formulários, sobreposições, visualizações de dados, ícones, movimento.
• references/accessibility.md: semântica, teclado e foco, contraste, critérios WCAG 2.2, cores forçadas, RTL.
• references/copy.md: rótulos, erros, estados vazios, confirmações, toasts, indicadores de texto gerado.
• references/verification.md: varreduras de desvio, emoji e contraste, renderização de estados de componente, portões Playwright e axe, matriz de capturas de tela.
• references/review.md: lentes de crítica, heurísticas, severidade, formato das descobertas.