UI/UX Designer - Interface e Usabilidade

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

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.

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 as restricoes fisiologicas que os tokens desta skill tem de respeitar — zona do polegar (onde a navegacao pode morar), superficie base do dark mode (#121212, nunca preto puro) e contraste minimo verificado nos dois temas — 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.

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

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 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 qualquer wireframe ou token, escolher uma âncora estética e comprometer com ela. Interface sem direção vira média genérica — o padrão "SaaS azul com Inter". A âncora orienta paleta, tipografia, textura, densidade, ritmo visual e até a complexidade da implementação. Misturar âncoras dilui o resultado; escolher uma e executar com precisão diferencia.

Âncoras disponíveis (escolher 1):

• 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:

• Maximalist/editorial/art deco exigem implementação elaborada (layers, custom shaders, animações orquestradas) — código simples nessas âncoras parece preguiçoso
• Brutally minimal/refined exigem precisão obsessiva em espaçamento, tipografia e timing — código complicado nessas âncoras parece poluído

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.

Anti-padrões a evitar (independente da âncora):

• Fonts genéricas sem justificativa: Arial, Inter, Roboto, Space Grotesk, system-ui default
• Gradiente roxo-para-rosa em fundo branco (clichê "AI SaaS 2023")
• Paleta indigo-500/violet-500 default do Tailwind sem customização
• Sombras shadow-lg genéricas sem direção de luz definida
• Border-radius rounded-2xl em tudo sem razão estética
• "Bento grid" como solução padrão para qualquer landing
• Hero com headline + subhead + 2 CTAs centralizado sem identidade
• Em-dash (—) como recurso estilístico em copy de interface (headline, CTA, microcopy) — tell reconhecível de texto gerado por IA; usar ponto, vírgula ou quebrar em duas frases

Anti-padrões por indústria/vertical:

Quando o projeto se encaixa claramente em uma destas verticais, aplicar também as restrições específicas — além dos anti-padrões gerais acima:

Vertical	Paleta banida	Tipografia a evitar	Anti-padrão específico
Banking/fintech tradicional	Gradiente roxo-rosa, "AI purple" genérico	Sans geométrica sem peso (sinaliza informalidade)	Dashboards com excesso de cor — dados financeiros pedem paleta contida e hierarquia por peso tipográfico, não por cor
Fintech consumer/neobank	Verde escuro corporativo tradicional (sinaliza banco legado)	Serif (sinaliza "tradicional demais" pro público)	Copiar 1:1 o layout de app bancário legado — a expectativa do segmento é mobile-first, não desktop-first adaptado
Saúde/wellness	Azul clínico frio isolado sem calor (sinaliza hospital impessoal)	Tipografia condensada/técnica como corpo de texto	Ícones médicos genéricos de stock (cruz vermelha, estetoscópio) como atalho visual
E-commerce	— (paleta é dirigida pela marca do produto, não pela vertical)	Display font pesada em preço/CTA de compra (reduz legibilidade em decisão rápida)	Grid de produto sem hierarquia de destaque — tudo do mesmo tamanho força o usuário a escolher sem orientação
SaaS B2B (operacional/dashboard)	Paleta vibrante multi-cor sem função (cor deve significar estado, não decorar)	Display expressivo em dados tabulares	Onboarding com tour de 10 passos antes de deixar o usuário agir — fricção que a persona B2B não tolera
Educação/e-learning	Paleta infantilizada em produto para adulto (erro comum em upskilling B2C)	Tipografia lúdica quando o público é profissional	Gamificação genérica (barra de XP, badges) sem conexão com o resultado real de aprendizagem

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ão	Quando	Evitar
Inline (junto do elemento)	Erro de campo, estado de uma seção	Abrir modal para problema que se resolve no próprio contexto
Snackbar / toast	Resultado 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
Banner	Condição relevante que deve permanecer visível (offline, conta suspensa, manutenção)	Sucesso rotineiro; ruído permanente
Sheet / drawer	Subtarefa focal que preserva relação com a tela anterior	Empilhar sheet sobre sheet
Dialog / alert	Decisão que justifica interromper, confirmação destrutiva	"Salvo com sucesso" — isso é snackbar
Push	Informação útil quando o app está fechado	Reengajamento 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 é placeholder, não default. Paleta herdada sem decisão é a marca registrada de interface genérica — junto com Inter e border-radius: 8px. A paleta se deriva da âncora estética, nesta ordem:

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:

Esquema	Como	Serve para	Cuidado
Monocromático	um hue, variando luminosidade e saturação	produto operacional, dashboard, ferramenta — cor fica livre para significar estado	precisa de tipografia e espaçamento fortes, senão fica sem hierarquia
Análogo (hues vizinhos, ±30°)	primário + 1-2 vizinhos	interface calma, wellness, conteúdo, marca coesa	contraste baixo entre os hues — a separação tem que vir de luminosidade
Complementar (oposto, ~180°)	primário + oposto só como acento	destacar CTA e alertas contra a base	nunca 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 apoio	marca expressiva, produto lúdico, ilustração	dividir 60/30/10 — três cores em proporção igual não tem foco

3. Gerar a escala em OKLCH, não em HSL. Em HSL, mesma lightness em hues diferentes produz cores com brilho percebido diferente — é por isso que amarelo hsl(50 90% 50%) parece muito mais claro que azul hsl(240 90% 50%), e a escala fica inconsistente. OKLCH é perceptualmente uniforme: fixar L entrega contraste equivalente entre hues. Em CSS moderno: oklch(0.65 0.15 250).
4. 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.
5. 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.

Regra dos 60/30/10 — 60% neutro dominante (fundo/superfície), 30% secundário (blocos, bordas, estados), 10% acento (CTA, foco, destaque). Acento em mais de ~10% da tela deixa de ser acento.

Sinais de paleta genérica: azul-500 do Tailwind sem justificativa; gradiente roxo→rosa como "identidade"; cor de marca aplicada em toda superfície em vez de reservada ao acento; success verde / error vermelho como única distinção (falha para daltonismo — ver skill 22).

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.
      // NEVER default to Inter/Roboto/Arial without justification.
      // 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