agentleFS
felvieirafelvieira/claude-skills-fv/skills/02-ui-ux-design/SKILL.md

ui-ux-design

Skill28 starsChanged 3 months agoApache-2.0View on GitHub

Projeta telas, fluxos e design systems; audita UX, acessibilidade e corrige achados focados. Facelift amplo vai para `89-ui-facelift`. Trigger em: "design system", "wireframe", "aesthetic anchor", "responsiva em telas", "protótipo no Figma", "paleta", "WCAG", "componente visual", "mobile first", "decisão de UX", "auditar essa tela", "design dessa interface".

20 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use prd-generator.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • dhzrxSkill

    prd-generator

    Generate comprehensive Product Requirements Documents with AI PM best practices for new features and products

    Also in 3 projects that use this

The file

Files
SKILL.md

UI/UX Designer - Interface e Usabilidade

O Designer é responsável por traduzir user stories em interfaces utilizáveis, acessíveis e bonitas.

Para criar ou redesenhar um produto inteiro, 92-design-director é a entrada principal e consulta esta skill para direção, estrutura e heurísticas. Esta skill continua disponível para desenho ou auditoria focada.

Governanca Global

Esta skill segue GLOBAL.md, policies/execution.md, policies/handoffs.md, policies/token-efficiency.md, policies/stack-flexibility.md, policies/evals.md e policies/visual-diff-precision.md (comparar dois screenshots/estados para achar diferença fina de posicionamento, espaçamento ou cor — obrigatória no modo Auditoria quando o achado depende de medir, não só descrever).

Conteúdo sob demanda vive em references/ (auditoria, marketing, produto, formulário) — não em docs/skill-guides/; tokens, breakpoints, componentes, skeleton e Nielsen já estão neste arquivo, não há guia externo duplicado. Dois arquivos cobrem conversão de tela: references/session-psychology.md (como a sessão é sentida: gradiente de meta, pico-fim, ilusão de trabalho honesta, isolamento, sobrecarga de escolha, com mapa tela→efeito) e references/product-page-conversion.md (página de produto e tela de compra: hierarquia canônica mobile e os 15 erros clássicos).

Para uso de MCPs de bibliotecas visuais como referencia ou aceleracao, consultar docs/skill-guides/ui-component-mcps.md.

Para checklist de acabamento fino (border radius concentrico, alinhamento optico, sombra vs borda, tabular numbers, hit area minima), ver skills/52-ui-polish/SKILL.md — despachar apos Frontend implementar, antes do Reviewer final.

Esta skill decide como a interface vai parecer, antes de existir. Para converter interface ja implementada em versao mobile, ou corrigir layout quebrado (componente que nao ocupa 100%, corta na tela, scroll horizontal, modal estourando viewport), ver skills/56-responsive-conversion/SKILL.md — inclui tambem os padroes de modal/bottom sheet e de confirmacao de acao destrutiva, que esta skill so cita como heuristica de Nielsen.

Se o produto pode receber outro idioma — mesmo que hoje seja so pt-BR — ver skills/58-i18n-localization/SKILL.md antes de fixar largura de botao, alinhamento ou formato de data: texto traduzido cresce ate 30% e RTL inverte o layout inteiro. Preparar depois custa muito mais que projetar assim desde o inicio.

Para ergonomia, temas escuros e contraste verificado nos temas existentes, ver skills/57-mobile-ux-foundations/SKILL.md. Essa skill tambem cobre percepcao de espera (skeleton vs. spinner por faixa de duracao) e UX de login/onboarding/permissao.

Quando o pedido for uma landing page ou site inteiro estruturado como jornada de scroll (scrollytelling, estilo Apple product page, video que escruba com o scroll) — nao so a interface estatica — ver skills/64-scroll-storytelling/SKILL.md. Ela consome a direcao estetica definida aqui (paleta, tipografia) como insumo pra escolher o mundo visual, mas decide a arquitetura de scroll (gramatica de pagina, jornada, variedade de efeito) por conta propria.

Para site, landing page, pricing ou página de produto, carregar references/marketing-surfaces.md também durante o desenho: a estrutura deve nascer da tarefa do visitante, do conteúdo e das provas disponíveis, não de uma sequência fixa de seções. Essa orientação não substitui a arquitetura de fluxos e telas de produtos operacionais.

Dois Modos: Desenhar vs. Auditar

O corpo deste arquivo (âncora estética, tokens, leis cognitivas) é para desenhar do zero — interface que ainda não existe.

Quando o pedido é revisar, avaliar ou corrigir uma interface que já existe, o protocolo é outro: carregar references/audit-framework.md. Ele define os dois submodos (auditoria = nenhuma alteração de arquivo; implementação = edição com escopo restrito), o fluxo de 9 passos, a classificação de achado em norma/evidência/heurística/preferência, a priorização por severidade×alcance×frequência×confiança, o formato de tabela de achados, e a definição de pronto. Não misturar os dois: pedido de análise nunca sai em diff.

Quando Usar

  • definir interface, fluxo e comportamento responsivo, do zero
  • transformar spec em estrutura de tela e decisao de usabilidade
  • auditar interface existente (ver "Dois Modos" acima — carrega references/audit-framework.md)
  • corrigir interface existente quando explicitamente autorizado a editar
  • aprofundar ou implementar uma correção estrutural delimitada de UX após auditoria

Quando Nao Usar

  • para decidir regras de negocio ou contrato de API sozinho
  • para editar arquivo quando o pedido só autorizou análise — ver modo Auditoria acima
  • para facelift completo de app, sistema ou landing existente — usar skills/89-ui-facelift
  • para construir feature nova a partir de spec — isso é skills/04-frontend-integration/SKILL.md. O modo Implementação desta skill é escopado a corrigir a causa de um achado de auditoria, não a implementar funcionalidade nova

Entradas Esperadas

  • spec do PO
  • restricoes de plataforma e acessibilidade
  • contexto de usuarios e fluxos principais
  • dossie de Design Intelligence (skill 29), quando disponivel: concorrentes analisados, tendencias visuais, moodboards, paleta e tipografia sugeridas, direcao estrategica (copiar/evitar/diferenciar)

Saidas Esperadas

  • wireframe, fluxo ou direcao de interface
  • regras de responsividade e acessibilidade
  • handoff claro para Frontend e, se necessario, Backend

Responsabilidades

  1. Definir arquitetura de informação e fluxos de navegação
  2. Criar wireframes e protótipos
  3. Manter design system consistente
  4. Garantir acessibilidade (WCAG 2.1 AA mínimo)
  5. Definir breakpoints e comportamento responsivo
  6. Validar usabilidade com heurísticas de Nielsen

Wireframe não é um estágio só. Baixa fidelidade (estrutura, sem cor nem tipografia real) valida conceito, hierarquia e sequência de tela — errar rápido aqui é barato. Alta fidelidade (com âncora estética, tokens e conteúdo real) só entra depois que a direção de baixa fidelidade está validada, porque é onde se testa conteúdo real, estado e entrega ao Frontend. Pular direto para alta fidelidade sem validar a estrutura é decorar um esqueleto que ainda pode mudar.

Direção Estética — Aesthetic Anchors

Antes de detalhar wireframes ou tokens, defina uma direção coerente com produto, tarefa, marca e conteúdo. A direção orienta paleta, tipografia, textura, densidade e movimento. Use uma âncora ou combine referências quando isso fizer sentido; nenhuma fonte ou cor isolada determina se a interface é genérica.

Exemplos de âncoras, não uma lista obrigatória:

  • Brutally minimal — preto/branco/cinza, tipografia neutra precisa (Helvetica, Söhne, Aktiv), espaço em branco generoso, zero ornamento
  • Maximalist chaos — múltiplas cores saturadas, sobreposições, layers, animações densas, tipografia mista e expressiva
  • Retro-futuristic — paletas anos 70/80 (laranja queimado, marrom, creme), grotescas geométricas (Eurostile, Orbitron), grids visíveis
  • Organic/natural — tons terrosos, serifs orgânicas (Cooper, Recoleta), texturas de papel, formas irregulares, ilustração feita à mão
  • Luxury/refined — paletas restritas (off-white, bordô, dourado fosco), serifs de alto contraste (Didot, Bodoni), espaçamento amplo, fotografia premium
  • Playful/toy-like — cores primárias vibrantes, tipografia arredondada (Fraunces wonky, Mochiy), formas chunky, ícones ilustrados
  • Editorial/magazine — grid tipográfico forte, mistura serif display + sans body, hierarquia jornalística, drop caps, fotografia com bleed
  • Brutalist/raw — HTML default exposto, bordas duras, tipografia monoespaçada ou system-ui propositalmente "feia", contraste agressivo
  • Art deco/geometric — simetria, linhas finas douradas/metálicas, paletas escuras profundas, tipografia geométrica (Poiret, Limelight)
  • Soft/pastel — pastéis dessaturados, serifs suaves ou rounded sans, sombras difusas, gradientes sutis
  • Industrial/utilitarian — monoespaçadas técnicas (JetBrains Mono, IBM Plex Mono), tabelas de dados, grids visíveis, paletas funcionais (verde terminal, âmbar)

Regra de complexidade casada com visão:

  • Uma direção expressiva pode precisar de composição, mídia ou movimento mais elaborados; use apenas o que contribuir para a tarefa e funcionar no ambiente.
  • Uma direção contida depende de precisão em hierarquia, espaçamento, tipografia e estados, sem exigir ausência de personalidade.

Reforço de atmosfera: uma vez escolhida a âncora, considerar gradient meshes, noise/grain overlays, padrões geométricos, transparências em camadas, sombras dramáticas, cursors customizados — desde que alinhados à âncora (não como ornamento solto).

Dials de intensidade (ajuste fino dentro da âncora):

Depois de escolher a âncora, calibrar 3 dials de 1-10 antes de gerar tokens ou wireframe. Eles não substituem a âncora — modulam o quão longe executá-la:

  • DESIGN_VARIANCE (1 = execução conservadora e previsível da âncora; 10 = interpretação ousada, quebra convenções do gênero) — subir para produtos que competem em diferenciação visual, baixar para produtos onde familiaridade reduz fricção (formulários financeiros, dashboards operacionais)
  • VISUAL_DENSITY (1 = muito espaço em branco, poucos elementos por tela; 10 = denso, muita informação simultânea) — dashboards e ferramentas B2B tendem alto; landing pages e onboarding tendem baixo
  • MOTION_INTENSITY (1 = estático ou só feedback essencial; 10 = movimento expressivo e contínuo) — só a referência aqui; a implementação real do dial pertence à skill 12 (skills/12-motion-design/SKILL.md), que recebe o valor como contexto de handoff

Registrar os 3 valores escolhidos (com justificativa de 1 frase cada) no handoff para Frontend — eles orientam decisões que o Frontend tomaria sozinho por falta de contexto.

Validar a direção antes de detalhar: resumir público, tarefa principal, paleta, tipografia, composição e princípios da tela; conferir cada escolha contra o conteúdo real do produto. Na hero, escolher a forma que melhor mostra o assunto (copy, imagem, demonstração ou interação), sem assumir headline centralizada com estatísticas como padrão. Para páginas web, derivar as seções do trabalho do visitante e variar a composição conforme o material e a decisão de cada trecho; não repetir a mesma sequência de hero, benefícios, depoimentos e CTA em páginas vizinhas sem justificativa. Depois da primeira implementação visual ou protótipo, e antes de finalizar, comparar a proposta com o brief e revisar o primeiro screenshot: se a composição servir igualmente a qualquer produto da categoria, ou se os adornos não explicarem hierarquia ou conteúdo, ajustar a direção e remover o que sobrou. O checklist de construção e crítica está em references/audit-framework.md; esta etapa é inspirada e curada da skill anthropics/skills/frontend-design.

Sinais para investigar, não proibições: fontes, gradientes, sombras, raios, cards, ícones e composições repetidas podem servir ao produto ou parecer arbitrários. Avalie função, conjunto, marca, leitura e acessibilidade antes de alterá-los. Siga a voz e as regras editoriais aplicáveis à copy.

Perguntas por contexto: em finanças, mantenha valores, unidades e ações claros; em saúde, não sugira segurança ou resultados sem evidência; em comércio, preserve comparação e decisão de compra; em dashboards, mantenha densidade útil; em educação, relacione motivação e feedback ao aprendizado. Paleta e tipografia pertencem à identidade e às necessidades reais de cada produto, não a uma lista de cores proibidas por setor.

Adotar um Design System Existente

Antes de derivar tokens do zero, decidir se um design system maduro resolve — Material 3, Apple HIG, Fluent 2, Carbon, ou primitiva + tokens próprios. Tabela de encaixe por tipo de produto, regra de decisão e o que compartilhar entre plataformas: references/product-apps.md.

A ordem de construção não é negociável: semântica → tokens → primitivas → componentes → estados → dados → responsivo → estilo visual → motion. Design que só funciona depois que a decoração entra está escondendo problema de hierarquia ou de arquitetura da informação.

Componente de Feedback — Escolher pela Gravidade

O componente de mensagem é escolhido por urgência × persistência × necessidade de ação, não pelo que é mais fácil implementar:

PadrãoQuandoEvitar
Inline (junto do elemento)Erro de campo, estado de uma seçãoAbrir modal para problema que se resolve no próprio contexto
Snackbar / toastResultado breve e não bloqueante, com ação opcional ("Desfazer")Informação que precisa continuar visível até ser resolvida — some antes de ser lida
BannerCondição relevante que deve permanecer visível (offline, conta suspensa, manutenção)Sucesso rotineiro; ruído permanente
Sheet / drawerSubtarefa focal que preserva relação com a tela anteriorEmpilhar sheet sobre sheet
Dialog / alertDecisão que justifica interromper, confirmação destrutiva"Salvo com sucesso" — isso é snackbar
PushInformação útil quando o app está fechadoReengajamento sem valor para quem recebe

Erro que exige ação nunca é toast: some sozinho e leva a informação junto.

Bibliotecas de Componentes Prontos

Quando a tarefa se beneficiar de bibliotecas prontas de componentes ou motion, esta skill pode consultar ou configurar bibliotecas via MCP ou via install direto, desde que:

  • o projeto seja compativel com a stack exigida
  • a integracao nao conflite com o design system existente
  • o componente seja adaptado ao contexto visual real do app

Se o projeto ja tiver componentes, branding ou linguagem visual estabelecidos, a biblioteca serve como referencia ou acelerador, nunca como desculpa para destoar do produto.

Via MCP — Magic UI MCP e React Bits MCP. Via install direto (React 19 + StyleX) — Astryx (Meta, MIT, 150+ componentes, CLI agent-friendly com --json/--dense). Detalhe de setup e diferencial confirmado em references/component-libraries.md — abrir só ao avaliar/configurar uma biblioteca de verdade.

Busca de decisão em catálogo (design_search.py)

Antes de decidir estilo, paleta, tipografia, tipo de gráfico, ícone, animação, ou checar uma guideline de UX/acessibilidade "de cabeça", consultar o catálogo local via scripts/design_search.py — 15 catálogos curados (BM25, sem dependência externa) cobrindo 84 estilos visuais, paletas de cor por tipo de produto, 74 pares de tipografia, ícones Phosphor com contexto de acessibilidade, 25 tipos de gráfico (dado → gráfico certo → biblioteca → threshold de volume → risco de a11y), padrões de landing page, snippets de motion/GSAP, 119 guidelines de UX/acessibilidade com exemplo de código bom/ruim, performance de React, e guidelines específicas de 21 stacks (React, Vue, Svelte, Next.js, Nuxt, Angular, Astro, SwiftUI, Flutter, React Native, shadcn, Three.js, e mais).

python skills/02-ui-ux-design/scripts/design_search.py "glassmorphism dashboard" --domain style
python skills/02-ui-ux-design/scripts/design_search.py "time series with many points" --domain chart
python skills/02-ui-ux-design/scripts/design_search.py "focus trap modal" --domain ux
python skills/02-ui-ux-design/scripts/design_search.py "useEffect cleanup" --stack react

Domínios: style, color, chart, landing, product, ux, typography, icons, gsap, react, web, google-fonts. Sem --domain, o domínio é auto-detectado pela query. Stacks: ver --stack --help ou data/stacks/*.csv — 21 disponíveis.

Sem resultado não é "sem dado que exista" — é "a query não bateu no índice desta base local". Tentar reformular antes de cair no julgamento genérico, e declarar explicitamente que não houve match na base se cair no genérico mesmo assim (o próprio script já avisa isso na saída). Fonte do dado ainda é a evidência do projeto real (18-repo-auditor) e a âncora estética escolhida — o catálogo é um acelerador de decisão, não substitui contexto do produto.

Derivar a Paleta — Não Copiar a Padrão

O azul #3b82f6 do bloco abaixo é um placeholder. Escolha a paleta a partir da marca, da tarefa e das superfícies reais; uma fonte ou raio isolado não define a identidade do produto:

  1. Uma cor de marca (hue primário). Vem do produto, do setor ou da âncora — não do framework. Se o produto já tem marca, ela manda.
  2. Escolher o esquema a partir do hue primário:
EsquemaComoServe paraCuidado
Monocromáticoum hue, variando luminosidade e saturaçãoproduto operacional, dashboard, ferramenta — cor fica livre para significar estadoprecisa de tipografia e espaçamento fortes, senão fica sem hierarquia
Análogo (hues vizinhos, ±30°)primário + 1-2 vizinhosinterface calma, wellness, conteúdo, marca coesacontraste baixo entre os hues — a separação tem que vir de luminosidade
Complementar (oposto, ~180°)primário + oposto só como acentodestacar CTA e alertas contra a basenunca em texto sobre fundo do hue oposto (vibração ótica); nunca em áreas grandes lado a lado
Tríade (3 hues a ~120°)um domina, dois em papel de apoiomarca expressiva, produto lúdico, ilustraçãodividir 60/30/10 — três cores em proporção igual não tem foco
  1. Considere OKLCH para escalas de cor. Sua luminosidade perceptual pode facilitar ajustes entre hues, mas valores iguais de L não garantem contraste WCAG equivalente. Meça os pares usados, respeite gamut e compatibilidade do projeto; HSL e outros modelos também podem ser adequados.
  2. Separar cor de marca de cor semântica. success/warning/error/info são canais de significado. Se o primário da marca for vermelho, o error precisa de outro sinal (ícone, peso, posição) — senão erro e marca se confundem.
  3. Validar contraste antes de fechar — a paleta bonita que reprova em 4.5:1 vai ser remendada depois com cinza aleatório. Rodar scripts/check-contrast.mjs; regras em skills/22-accessibility-specialist/SKILL.md.

Proporções de cor: 60/30/10 pode servir como ponto de partida para fundo, secundário e acento; ajuste à identidade, ao conteúdo e à hierarquia real, sem tratar percentuais como requisito.

Pistas para revisar a paleta: escolhas sem relação com a marca ou tarefa; cor usada sem hierarquia; e estados diferenciados apenas por cor. Azul, gradiente e proporção de acento não são defeitos isoladamente. Consulte a skill 22 para contraste e distinção de estados.

RGB é o único modelo relevante aqui. CMYK só entra se o entregável for impresso (material de marca, embalagem) — nesse caso, cor de tela e cor impressa divergem e a marca precisa dos dois valores especificados.

Três Camadas de Token — Nunca Pular Direto para o Componente

Cor (e, por extensão, espaçamento e raio) se organiza em três camadas. Pular a camada semântica e ir direto de primitivo para componente é o que torna dark mode, rebranding e diferença de plataforma um refactor em vez de uma troca de valor:

Primitivo   → blue-600, gray-100, space-4, radius-md
Semântico   → color-surface, color-text, color-border, color-primary,
              color-success, color-warning, color-danger, color-info, color-focus
Componente  → button-primary-bg, input-border-focus, card-surface
  • Primitivo é a paleta crua — não carrega significado, só valor
  • Semântico é onde a decisão de produto mora: color-danger aponta pra um primitivo hoje, pode apontar pra outro amanhã (dark mode, tema, rebranding) sem tocar em nenhum componente
  • Componente consome só o semântico, nunca o primitivo direto — button-primary-bg: var(--color-primary), não button-primary-bg: #3b82f6

Produto que estiliza direto em cima de blue-600 em 40 arquivos não sobrevive a um rebranding sem busca-e-substituição arriscada. Produto em cima de color-primary troca uma linha.

Design System - Tokens Base

Todo projeto começa com a definição destes tokens:

src/lib/design-tokens.ts

export const tokens = {
  colors: {
    primary: {
      50: '#eff6ff',
      100: '#dbeafe',
      200: '#bfdbfe',
      300: '#93c5fd',
      400: '#60a5fa',
      500: '#3b82f6',
      600: '#2563eb',
      700: '#1d4ed8',
      800: '#1e40af',
      900: '#1e3a8a',
    },
    success: '#22c55e',
    warning: '#f59e0b',
    error: '#ef4444',
    info: '#3b82f6',
    gray: {
      50: '#f9fafb',
      100: '#f3f4f6',
      200: '#e5e7eb',
      300: '#d1d5db',
      400: '#9ca3af',
      500: '#6b7280',
      600: '#4b5563',
      700: '#374151',
      800: '#1f2937',
      900: '#111827',
    },
  },
  spacing: {
    xs: '0.25rem',
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
    xl: '2rem',
    '2xl': '3rem',
    '3xl': '4rem',
  },
  typography: {
    fontFamily: {
      // CHOOSE ONE that fits the aesthetic anchor — see "Direção Estética" section.
      // Choose or retain fonts for readability, brand and available assets.
      // Examples by anchor: minimal → Helvetica/Söhne; editorial → Fraunces + Inter Tight;
      // retro-futuristic → Eurostile/Orbitron; refined → Didot/Bodoni + Söhne.
      // Pair a distinctive display font with a refined, legible body font.
      sans: "/* SET PER PROJECT — display + body pairing */",
      mono: "'JetBrains Mono', 'Fira Code', monospace",
    },
    fontSize: {
      xs: ['0.75rem', { lineHeight: '1rem' }],
      sm: ['0.875rem', { lineHeight: '1.25rem' }],
      base: ['1rem', { lineHeight: '1.5rem' }],
      lg: ['1.125rem', { lineHeight: '1.75rem' }],
      xl: ['1.25rem', { lineHeight: '1.75rem' }],
      '2xl': ['1.5rem', { lineHeight: '2rem' }],
      '3xl': ['1.875rem', { lineHeight: '2.25rem' }],
      '4xl': ['2.25rem', { lineHeight: '2.5rem' }],
    },
    fontWeight: {
      normal: '400',
      medium: '500',
      semibold: '600',
      bold: '700',
    },
  },
  borderRadius: {
    none: '0',
    sm: '0.25rem',
    md: '0.375rem',
    lg: '0.5rem',
    xl: '0.75rem',
    '2xl': '1rem',
    full: '9999px',
  },
  shadows: {
    sm: '0 1px 2px 0 rgb(0 0 0 / 0.05)',
    md: '0 4px 6px -1px rgb(0 0 0 / 0.1)',
    lg: '0 10px 15px -3px rgb(0 0 0 / 0.1)',
    xl: '0 20px 25px -5px rgb(0 0 0 / 0.1)',
  },
  breakpoints: {
    sm: '640px',
    md: '768px',
    lg: '1024px',
    xl: '1280px',
    '2xl': '1536px',
  },
  transitions: {
    fast: '150ms ease',
    normal: '250ms ease',
    slow: '350ms ease',
  },
  zIndex: {
    dropdown: 1000,
    sticky: 1020,
    fixed: 1030,
    modal: 1040,
    popover: 1050,
    tooltip: 1060,
    toast: 1070,
  },
} as const;

Breakpoints e Responsividade

Abordagem Mobile First obrigatória:

Mobile:  0 - 639px    → Layout single column, touch targets 44px mín
Tablet:  640 - 1023px → Layout adaptado, sidebar colapsável
Desktop: 1024px+      → Layout completo, múltiplas colunas

Regras de responsividade:

  • Imagens: usar object-fit: cover + aspect-ratio definido
  • Tabelas: viram cards em mobile (padrão stacked)
  • Navegação: hamburger em mobile, sidebar em desktop
  • Formulários: inputs full-width em mobile, grid em desktop
  • Touch targets: mínimo 44x44px em mobile
  • Font-size mínimo: 16px em inputs (evita zoom no iOS)
  • Altura de tela cheia: dvh, nunca vh puro (vh corta conteúdo atrás da barra do browser)
  • Elementos na borda: viewport-fit=cover + env(safe-area-inset-*) (notch e barra de gestos)

Estas regras orientam a decisão de design. A execução — auditar layout já implementado, achar a causa raiz de "não pega 100%", converter grid/modal/formulário para mobile — pertence à skill 56 (skills/56-responsive-conversion/SKILL.md), que tem o catálogo de bugs com fix por caso.

Componentes - Padrão de Especificação

Cada componente deve ter:

## Componente: [Nome]

### Variantes
- Default / Primary / Secondary / Ghost / Destructive

### Estados
- Default / Hover / Focus / Active / Disabled / Loading / Error

### Props
| Prop | Tipo | Default | Descrição |
|------|------|---------|-----------|
| variant | string | 'default' | Estilo visual |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Tamanho |
| disabled | boolean | false | Desabilita interação |
| loading | boolean | false | Mostra skeleton/spinner |

### Acessibilidade
- Role ARIA: [role]
- Keyboard: [teclas suportadas]
- Screen reader: [comportamento esperado]

### Skeleton
- Formato do skeleton que aparece durante loading
- Dimensões devem refletir o conteúdo final (evitar layout shift)

Comportamento dos Estados Interativos

Listar os estados não basta — cada um tem comportamento e propósito próprios. Especificar todos antes do handoff, porque o que fica indefinido o Frontend inventa.

EstadoComportamentoRegra
DefaultLegível como clicável sem depender de hover — cor, sombra, borda ou sublinhadoSe só o cursor revela que é clicável, o mobile perde a affordance
HoverMudança sutil de cor ou elevaçãoSó desktop. Nunca colocar informação exclusiva em hover (tooltip crítico não existe em touch)
FocusAnel de foco visível, contraste ≥ 3:1 contra o fundo adjacenteUsar :focus-visible (teclado sim, clique de mouse não). outline: none sem substituto quebra navegação por teclado
ActiveFeedback imediato do toque — leve escurecimento ou scale(0.96)Precisa aparecer em até 100ms, senão a ação parece ignorada
DisabledContraste reduzido e cursor bloqueadoSempre dizer por quê (tooltip ou texto ao lado). Alternativa melhor: manter habilitado e responder com erro específico no clique
LoadingSubstituir o rótulo por indicador, mantendo a largura do botãoPrecisa desabilitar o clique — senão o usuário envia duas vezes. Largura fixa evita o layout pular
ErrorMensagem específica + ícone, preservando o que foi digitadoNunca só cor; nunca limpar o formulário

Sobre disabled em botão de submit: desabilitar até o formulário estar válido esconde do usuário o que falta. Manter habilitado e, no clique, focar o primeiro campo inválido com a mensagem costuma converter mais — a exceção é ação destrutiva ou cobrança, onde bloquear é mais seguro.

Orçamento de Design para Performance

Decisão visual tem custo de carregamento, e o custo é decidido aqui — não no Frontend. Antes de fechar a direção, verificar o impacto nas Core Web Vitals (a skill 14 é dona das métricas e da medição; esta skill é dona das escolhas que as afetam):

  • LCP — a maior imagem ou bloco de texto acima da dobra é o gargalo. Hero em vídeo, imagem não comprimida ou fonte que bloqueia render empurram o LCP para além dos 2,5s
  • CLS — todo elemento que carrega depois precisa de espaço reservado (aspect-ratio em imagem, altura fixa em banner/anúncio). Skeleton com dimensão diferente do conteúdo final é causa de layout shift, não a cura
  • Fontes — cada peso/família extra é um arquivo. Duas famílias com 2-3 pesos é o teto saudável; usar font-display: swap e pré-carregar só a fonte da dobra

Estas escolhas cabem no handoff junto com os tokens, não como otimização posterior.

Skeleton Loading - Padrões

Skeleton é obrigatório em toda tela que faz fetch de dados:

Tipos de skeleton:
├── TextSkeleton    → Linhas com largura variável (100%, 80%, 60%)
├── AvatarSkeleton  → Círculo (sm: 32px, md: 40px, lg: 48px)
├── CardSkeleton    → Retângulo com rounded corners
├── TableSkeleton   → Grid de retângulos imitando rows
├── ImageSkeleton   → Retângulo com aspect-ratio da imagem
└── FormSkeleton    → Inputs placeholder com labels

Regras:

  • Skeleton DEVE refletir o layout final (mesmas dimensões)
  • Animação: pulse (não shimmer — mais leve)
  • Cor: gray-200 com pulse para gray-300
  • Nunca mostrar skeleton por mais de 3s — se demorar, mostrar mensagem

Estado Vazio — Tela Sem Dado É Tela, Não Ausência de Tela

Empty state é onde o produto perde o usuário em silêncio: ele chegou, não entendeu se está quebrado ou se é assim mesmo, e saiu. Todo empty state precisa de: o que aconteceu + o que fazer agora (ação clicável). Sem a ação, é tela morta.

Os tipos não se resolvem com a mesma mensagem:

TipoSituaçãoO que a tela deve fazerErro comum
Primeiro uso (zero data)conta nova, ainda não existe nadaexplicar o valor + CTA para criar o primeiro item — é o melhor momento de onboarding do produtotratar como erro ("Nada encontrado") e desperdiçar a única tela que ensina
Busca sem resultadofiltro/termo não casoumostrar o termo buscado, oferecer limpar filtro e sugerir alternativa"0 resultados" seco, deixando o usuário sem saber se o filtro ou o dado é o problema
Limpo por conclusãoinbox zerada, fila vazia, tudo concluídoreconhecer como sucesso — o tom aqui é positivo, não neutrousar a mesma tela de "não há nada", transformando conquista em vazio
Erro / falha de cargarequest falhoudizer que falhou e oferecer tentar de novo; nunca fingir lista vaziamascarar erro como vazio (.catch(() => [])) — ver agents/silent-failure-hunter.md
Sem permissãoexiste dado, o usuário não pode verexplicar a restrição e como pedir acessomostrar vazio genérico, sugerindo que o dado não existe
404 / rota inexistentedestino não existerota de volta para um lugar útil (home, busca), preservando a navegaçãobeco sem saída sem link

Regras: distinguir vazio de erro de carregando — os três são estados diferentes e nunca compartilham a mesma tela. Um destaque só (Von Restorff): o CTA. Ilustração é opcional e serve ao tom da marca; ela não substitui a ação — empty state bonito sem CTA continua sendo tela morta.

Leis Cognitivas — Justificar a Estrutura, Não o Gosto

Nielsen (abaixo) audita a interface pronta. Estas leis decidem a estrutura antes de desenhar — e dão vocabulário para defender a decisão em review sem apelar a "achei mais bonito".

Lei / viésO que dizDecisão que ela força
Hick-Hymantempo de decisão cresce com o número e a complexidade das opçõesmenu com 12 itens de peso igual → agrupar, priorizar ou revelar progressivamente. Onboarding não pede 3 decisões na mesma tela
Fittstempo para atingir um alvo depende do tamanho dele e da distânciaalvo primário grande e perto do polegar (ver skill 57); ação destrutiva longe da confirmação. Botão de 44px não é só acessibilidade, é velocidade
Miller / carga cognitivamemória de trabalho é curta e frágilquebrar sequências longas em grupos (telefone, cartão, código); formulário longo em passos com progresso visível
Jakobo usuário passa a maior parte do tempo em outros produtospadrão consagrado (carrinho no topo à direita, logo volta pra home) só se quebra com ganho comprovado. Inovar na navegação cobra caro
Gestalt: proximidadeo que está perto é lido como do mesmo grupoespaçamento é hierarquia. Label colada no campo errado é bug de layout, não de estética
Gestalt: similaridadeo que se parece é lido como mesma funçãodois botões com o mesmo visual precisam ter o mesmo peso de ação. Link que parece botão gera clique errado
Gestalt: fechamento/continuidadea mente completa formas e segue linhascard cortado na borda da viewport sinaliza "tem mais, role" — é affordance de carrossel, não defeito
Von Restorff (isolamento)o item que destoa é o lembradoum destaque por tela. Três CTAs em cores diferentes = nenhum destaque
Estética-usabilidadeinterface percebida como bonita é percebida como mais fácilpolimento visual não é opcional — mas também mascara problema real de usabilidade em teste. Nunca substitui teste com usuário (skill 51)
Tesler (complexidade irredutível)toda operação tem complexidade que não some, só muda de lugar"simplificar" escondendo campo obrigatório empurra o trabalho pro usuário depois. Decidir conscientemente quem absorve: sistema ou pessoa
Efeito do gradiente de metamotivação cresce perto do fimmostrar progresso e começar o checklist com um item já concluído aumenta conclusão (aplicação em onboarding: skill 57)
Ancoragema primeira informação vista enviesa o julgamento seguinteordem dos planos de preço não é neutra; primeiro número visto vira régua
Modelo mentalo usuário chega com ideia pronta de como aquilo funcionanomear função pelo que o usuário chama, não pelo nome interno da entidade no banco
Feedforwardo usuário quer saber o que vai acontecer antes de agirrótulo diz o resultado ("Excluir 3 arquivos"), não o mecanismo ("Confirmar"). Complementa feedback, não substitui
Adaptação sensorialestímulo repetido deixa de ser percebidobadge de notificação sempre aceso, banner permanente e toast a cada ação viram invisíveis — e junto com eles o alerta que importava
Fadiga de decisãodecisões seguidas degradam a qualidade da escolhafluxo longo precisa de default sensato, não de mais uma pergunta. Todo campo opcional exibido é uma decisão cobrada
Ilusão de trabalhoprocesso visivelmente "trabalhando" é percebido como mais valiosovale para busca/análise real (mostrar as etapas). Delay artificial em operação instantânea é manipulação — não fazer
Divulgação progressivacomplexidade não desaparece, mas pode ser adiada até que o usuário sinalize intençãomostrar só o essencial na primeira tela; opção avançada, campo condicional e configuração rara ficam atrás de um "mostrar mais" explícito — nunca escondidos sem pista de que existem
Pico-fim (peak-end)a sessão é lembrada pelo melhor momento e pelo final, não pela médiatela de sucesso celebra o artefato criado, não o clique; fim de onboarding é um reveal, não "conta criada"; pós-checkout não termina em dashboard vazio

Não aplicar as 19 em toda tela. Elas entram quando a decisão está em disputa: quantas opções mostrar, onde por o botão, o que destacar, o que agrupar. Para auditar a sensação de uma sessão inteira (quais efeitos pesam em qual tela, no máximo dois destaques por tela), usar references/session-psychology.md.

Dark Patterns — Onde a Manipulação Vira Categoria, Não Exceção

A linha de "Ilusão de trabalho" acima cita manipulação como exceção pontual. Dark pattern é o nome para quando isso vira prática deliberada de UI/copy para extrair uma ação que o usuário não teria tomado com informação completa. Reconhecer os seis padrões mais comuns evita reintroduzi-los sem perceber que têm nome:

PadrãoComo aparecePor que não fazer
Urgência falsacontagem regressiva ou "oferta expira" sem prazo real por trássome no reload ou reaparece idêntico amanhã — usuário percebe e a marca perde credibilidade acumulada, não só a conversão daquele clique
Escassez fabricada"só 3 restantes" sem estoque real checávelmentira verificável é o pior tipo — uma busca ou uma segunda visita expõe
Custo escondidopreço final maior que o anunciado, revelado só no checkoutabandono de carrinho no último passo é caro; a informação tinha que estar na página de preço (skill 61)
Pré-seleção enganosaopt-in de cobrança/newsletter marcado por padrão, opt-out difícil de achardado pessoal e cobrança recorrente exigem ação explícita do usuário, não omissão dele
Dificuldade artificial de cancelarassinar é 1 clique, cancelar exige ligação/chat/formuláriofricção assimétrica entre entrar e sair é o antipadrão mais citado em regulação de assinatura
Confirm-shamingbotão de recusa com texto que constrange ("Não, prefiro pagar mais")pressão emocional no texto do próprio controle, não no argumento de venda

Diferença de escopo com a skill 13: lá a regra é "urgência real, nunca fabricada" aplicada à copy de venda. Aqui a lista cobre o padrão de interface e fluxo, não só o texto — pré-seleção e dificuldade de cancelar são decisão de componente e de arquitetura de tela, não de palavra.

Heurísticas de Nielsen - Checklist

Antes de aprovar qualquer interface, validar:

  1. Visibilidade do status — Usuário sempre sabe o que tá acontecendo?
  2. Compatibilidade com o mundo real — Linguagem do usuário, não jargão técnico?
  3. Controle e liberdade — Tem "desfazer"? Tem "voltar"?
  4. Consistência e padrões — Mesma ação = mesmo visual em toda app?
  5. Prevenção de erros — Confirmação antes de ações destrutivas?
  6. Reconhecer ao invés de lembrar — Info visível, não memorizada?
  7. Flexibilidade e eficiência — Atalhos pra usuários avançados?
  8. Design minimalista — Só info relevante na tela?
  9. Recuperação de erros — Mensagens claras com ação sugerida?
  10. Ajuda e documentação — Tooltips, onboarding?

Nielsen audita a interação com a interface pronta. Não cobre se o problema certo foi resolvido, se a arquitetura de informação faz sentido, ou se alguém testou com usuário real — isso é o checklist abaixo.

Checklist de Fechamento — Além da Interação

Gate mais amplo que Nielsen, para as pontas que ele não cobre: estratégia, estrutura e validação. Rodar antes de considerar a interface pronta para handoff, não durante o desenho.

Estratégia — o público e o problema estão definidos (não "quem vai gostar", e sim "quem tem a dor")? Existe uma tarefa principal por tela, não uma lista de possibilidades? Há métrica de sucesso declarada, não só "parece melhor"?

Estrutura — a arquitetura de informação foi decidida antes do wireframe, não descoberta desenhando? Os fluxos cobrem erro e caminho alternativo, não só o feliz? Nenhuma página de conversão está órfã de link de entrada (ver "Plano de links internos" na skill 61)?

Validação — alguém testou com usuário representativo, ou só com quem já sabia onde clicar (skill 51)? A hipótese da próxima iteração está escrita, ou a interface "está pronta" sem plano do que medir depois de publicada?

Estratégia e estrutura sem checklist formal são o motivo mais comum de retrabalho tarde — a interface fica visualmente correta e resolve o problema errado.

Quando precisar de imagem (hero, ilustração, mascote, background)

Se uma imagem realmente ajudar a tarefa, prefira assets existentes. Quando geração for necessária e autorizada, consulte a skill 17 (image-generator) com o contexto visual:

Contexto: hero image pra landing de [produto]
Paleta: [primary], [secondary], [contrast]
Mood: minimalist / playful / corporate / etc
Composição esperada: [centro/lateral/full-bleed]
Referências (se houver): paths de assets existentes no projeto

Siga as regras vigentes de custo e autorização da skill 17 e do ambiente. Não gere mídia automaticamente para preencher uma seção ou ilustrar a própria skill.

Verificacao — a ancora foi mesmo aplicada?

Declarar a ancora nao garante que ela chegou no codigo. Dois checkers transformam as regras desta skill em verificacao:

node scripts/check-design-generic.mjs <path>   # indigo default, system-ui, gradiente AI, preto puro
node scripts/check-contrast.mjs <path>         # pares opacos identificáveis; verificar os temas usados

O primeiro relata pistas para revisão contextual; retorna 0 por padrão e oferece --strict para quem quiser tratar sinais como falha. O hook design-anchor-guard também só avisa quando padrões coincidem. Um detector limpo não comprova qualidade, e um sinal isolado não invalida a marca. O segundo calcula pares de cores identificáveis e deve ser complementado pela verificação das cores realmente renderizadas e dos estados relevantes.

Evidencia de Conclusao

  • fluxo principal definido
  • estados de loading, erro e vazio considerados
  • responsividade e acessibilidade especificadas

Handoff para Frontend

Entregar:

  1. Wireframes/mockups com estados (default, loading, error, empty, success)
  2. Design tokens configurados
  3. Especificação de cada componente novo
  4. Fluxo de navegação completo
  5. Comportamento responsivo definido por breakpoint
  6. Skeleton patterns para cada tela
  7. Micro-interações e animações especificadas
  8. Acessibilidade: roles ARIA, tab order, screen reader labels
  9. Comportamento dos 7 estados interativos por componente clicável — não só a lista de nomes
  10. Orçamento de performance: qual é o elemento de LCP da tela, o que reserva espaço para não gerar CLS, e quantos pesos de fonte a direção exige
  11. Paleta com o esquema declarado (mono/análogo/complementar/tríade), o hue de origem e a proporção 60/30/10 — não só a lista de hex
  12. Empty state especificado por tipo para toda tela que lista dados (primeiro uso, busca sem resultado, erro, sem permissão) — cada um com seu CTA

Handoff para Backend

Comunicar:

  1. Dados necessários por tela (quais campos, formatos)
  2. Paginação: tipo (offset vs cursor), itens por página
  3. Filtros e ordenação que a UI precisa
  4. Estados de loading e como o skeleton se comporta
  5. Feedback visual que depende de resposta da API (sucesso, erro)

Fontes

  • Aesthetic anchors pattern adapted from anthropics/skills/frontend-design (custom license, see source).
  • O passo de validar a direção visual contra público, conteúdo, tarefa e screenshot antes de implementar é uma síntese curada de anthropics/skills/frontend-design; não é uma cópia integral da skill.
  • Checklist local de revisão web em references/web-interface-review.md, sintetizado de Vercel Web Interface Guidelines (licença e termos na fonte). A lista foi selecionada para complementar as regras locais; consulta de atualizações upstream é opcional e só deve ocorrer quando atualidade da regra for relevante.
  • Intensity dials (DESIGN_VARIANCE, VISUAL_DENSITY, MOTION_INTENSITY) e em-dash ban inspirados em Leonxlnx/taste-skill.
  • Orientação de estruturar páginas pelo trabalho do visitante, usar conteúdo e provas reais para decidir a composição e variar a anatomia entre páginas adaptada de nutlope/hallmark (MIT); as regras foram curadas para o escopo do kit, sem importar limites universais de texto ou composição. Anti-padrões de "AI purple gradient"/layout centralizado genérico também foram reforçados por usehallmark.com.
  • Leis cognitivas, esquemas de cor e taxonomia de empty state consolidados a partir do blog da Blush (design psychology, color theory, empty states) — curados aqui para decisão de interface digital; recomendações de ilustração do material original, que são CTA do produto deles, ficaram de fora.
  • Estrutura de "Anti-padrões por indústria/vertical" (paleta banida + tipografia a evitar + anti-padrão específico por vertical) inspirado em nextlevelbuilder/ui-ux-pro-max-skill, que mapeia 161 combinações estilo→cor→tipografia→anti-padrão por indústria; aqui curado para as 6 verticais mais comuns neste kit, não um port literal.
  • scripts/design_search.py + data/*.csv (2026-08-22): motor de busca BM25 e os 15 catálogos de decisão portados de nextlevelbuilder/ui-ux-pro-max-skill (MIT) — o repo cresceu bastante desde a absorção acima (jul/2026): 84 estilos, 192 paletas, 74 pares de tipografia, 119 guidelines de UX/a11y com código, 25 tipos de gráfico, 21 stacks. scripts/design_search_core.py é o motor original quase inalterado (stdlib puro, já testado, calibrado por domínio); design_search.py é um wrapper CLI mais enxuto que o search.py original — não porta --design-system/--persist/--variance/--motion/--density (gerador de design system completo do produto deles), porque essa decisão já é papel desta skill em prosa guiada por contexto do projeto — portar o gerador duplicaria a mesma decisão de dois jeitos.
  • Três camadas de token, wireframe lo-fi/hi-fi como estágios distintos, divulgação progressiva nomeada, dark patterns como categoria e o checklist de fechamento (estratégia/estrutura/validação) vieram de um estudo do usuário sobre a biblioteca Design Basics da Figma — medido por grep contra o kit antes de aplicar; só entrou o que era gap real, não redundante com Nielsen ou com o que a skill já cobria.
  • Modo dual auditoria/implementação, fluxo de 9 passos, classificação de achado (norma/evidência/heurística/preferência), priorização por severidade×alcance×frequência×confiança e definição de pronto vieram de um protocolo de auditoria/implementação UI/UX fornecido pelo usuário — extraídos para references/audit-framework.md após medir que 6 das 8 peças não existiam em nenhuma skill do kit, e as outras 2 estavam fragmentadas sem ponto de consolidação (skills/11-reviewer tinha só 1 eixo de severidade; skills/22-accessibility-specialist tinha impacto×esforço, não os 4 eixos do protocolo).
  • Astryx (facebook/astryx, MIT) citado em "Bibliotecas de Componentes Prontos" (2026-08-22): design system open source do Meta (React 19 + StyleX, 150+ componentes, beta pública desde jan/2026, 12k+ stars), curado por ser o primeiro exemplo verificável de design system com infraestrutura dedicada a consumo por agente — não só claim de marketing, mas CLI com --json/--dense/error codes estáveis e suíte própria de testes medindo geração de código por LLM a partir da doc (confirmado lendo README.md, packages/cli/README.md e CLAUDE.md do repo real via gh api). Citado como referência de biblioteca de componentes, não integrado ao catálogo BM25 de design_search.py — são camadas diferentes (decisão de estilo vs. componente pronto).
  • Mecanismo de dupla avaliação cega (Avaliação A/B rodando em sub-agentes isolados sem contato entre si, com banner obrigatório de execução degradada quando isso não é possível) e o "Veredito de Especificidade" (julgar se a interface foi desenhada para o produto ou é intercambiável com a categoria, antes de ver evidência de detector, para não julgar sob âncora) vieram do comando critique de pbakaus/impeccable — Apache-2.0, não MIT (repo ativo, último push 2026-08-26; confirmado via gh api antes de citar, não presumido pelas outras fontes desta lista que costumam ser MIT). Curado em references/audit-framework.md, seção "Dupla Avaliação Cega": o repo já usa as 10 heurísticas de Nielsen (não um framework próprio) com a mesma escala 0-4/40 que esta skill já tinha em "Heurísticas de Nielsen - Checklist" — não duplicada, só referenciada. Só entrou o que era gap real medido por grep contra o kit: o fluxo de 9 passos do audit-framework.md já cobria inspeção, classificação de achado e priorização, mas nenhum passo previa duas avaliações isoladas nem um julgamento de especificidade anterior à evidência técnica. Ficaram de fora: o detector determinístico (detect.mjs é só um loader que importa detector/detect-antipatterns.mjs, arquivo não distribuído no source público do repo — as regras internas do detector não foram confirmadas, então não foram portadas), o sistema de persistência de snapshot/trend em .impeccable/critique/, as 5 personas fixas de teste e as integrações específicas de harness (Codex).
  • references/session-psychology.md e references/product-page-conversion.md (2026-09-27) vieram de duas skills (app-ux-psychology e product-page-conversion) de um pacote de UX/conversão consolidado pelo usuário, que resumem vídeos de Wyatt Feaster e do canal uxpeak. Medido por grep antes: gradiente de meta e ilusão de trabalho já estavam na tabela de leis; entrou só o que faltava (pico-fim, mapa tela→efeito, protocolo de auditoria de sessão, hierarquia e os 15 erros de PDP). Números das fontes não foram verificados e não aparecem como garantia.

Integração com Pipeline

  • Orquestrador (skill 09): Coordena quando esta skill é invocada e define a próxima etapa
  • Context Manager (skill 08): Rastreia progresso das tasks dentro desta skill
  • Documentador (skill 10): Documenta entregas desta skill durante o desenvolvimento

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.