Communitygithub.com

design-visual

Use ao construir ou alterar um sistema de design, como tokens de design, paleta de cores, contraste, tipografia, escala tipográfica, escala de espaçamento, modo escuro, tokens de movimento ou especificações de estados de componentes. Não usar para diagramar ou criticar uma página específica ou redesenho; use `designer`. Não usar para criar imagens; use `artist`.

O que é design-visual?

Esta habilidade (skill) é um guia abrangente para construção e manutenção de sistemas de design visual, cobrindo desde a definição de uma direção de design até a implementação de tokens e especificações de componentes. Ela ajuda desenvolvedores e designers a criar sistemas coesos, acessíveis e escaláveis, garantindo que cada decisão de token (cor, tipografia, espaçamento, etc.) seja consistente e justificada. A habilidade suporta a criação de sistemas para qualquer plataforma (web, mobile, etc.) e enfatiza o uso de tokens semânticos, verificação de contraste WCAG 2.2, modo escuro, e animações responsivas. O fluxo de trabalho segue uma ordem de construção lógica: direção de design, cores, tipografia, espaçamento, bordas/elevação, movimento, e finalmente tokens de componente. A habilidade também lista as 'regras que mais importam', como verificar contraste para cada par real de cores, especificar todos os estados de componente, e usar poucos valores de forma consistente. Para tarefas específicas de layout de página, ilustrações ou gráficos, ela redireciona para outras habilidades especializadas (`designer`, `artist`, `frontend`).

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/heliacon/claude-skills/tree/HEAD/skills/visual-design

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Design Visual

O sistema por trás de cada tela: tokens para cor, tipo, espaço, forma, profundidade e movimento, e as especificações de componentes construídas a partir deles. A habilidade designer aplica este sistema a páginas reais. Construa o sistema uma vez; deixe as páginas gastá-lo.

As regras que mais importam

  1. Escreva a direção de design em palavras antes de qualquer token. Três ou quatro frases: para quem é, como deve se sentir, como nunca deve se sentir, e a única coisa que empresta do assunto. Cada decisão de token é verificada em relação a esse parágrafo.
  2. Componentes referenciam tokens semânticos, nunca primitivos. --color-text-primary, não --grey-900. Modo escuro, temas e rebrandings tornam-se um remapeamento, não uma reescrita.
  3. Verifique o contraste para cada par real, em ambos os temas, de acordo com a tabela abaixo. Uma paleta que funciona no branco pode falhar em sua própria superfície matizada.
  4. Um padrão não é uma decisão. Cinzas de framework, Inter em tudo, um raio de 4px em cada caixa: cada um parece bom e juntos parecem com todos os outros produtos. Decida cada valor ou aceite-o conscientemente.
  5. Cada especificação de componente lista todos os estados: padrão, hover, foco, ativo, desabilitado, carregando, erro e selecionado quando aplicável. Estados ausentes são inventados na construção, inconsistentemente.
  6. Menos valores, usados consistentemente. Uma escala com 6 degraus usada em todos os lugares vence uma com 14 degraus usada aleatoriamente.

Quando não usar

  • Organizar uma página específica, escolher o que fica acima da dobra, criticar uma tela ou executar um redesenho: designer.
  • Gerar ilustrações, ícones, imagens de herói ou marcas: artist.
  • Gráficos e paletas de visualização de dados: a habilidade frontend em references/charts.md. Cores categóricas de gráficos têm restrições que uma paleta de marca não tem.
  • Implementar os tokens em um framework: frontend.

Ordem de construção

Cada camada depende da anterior:

  1. Parágrafo de direção.
  2. Cor: primitivos, depois tokens semânticos.
  3. Tipo: faces, depois escala e papéis.
  4. Escala de espaçamento e grid.
  5. Raio, borda e elevação.
  6. Tokens de movimento.
  7. Tokens de componente e especificações de componente.

Cor

Estrutura:

Primitivos (valores brutos, uma rampa por matiz, ex.: 50, 100 ... 900, 950):
  --blue-600: oklch(0.55 0.17 255)

Tokens semânticos (referenciam primitivos, nomeados pela função):
  --color-bg, --color-surface, --color-surface-raised
  --color-text, --color-text-muted, --color-text-on-accent
  --color-accent, --color-accent-hover
  --color-border, --color-focus-ring
  --color-danger, --color-success, --color-warning (cada um com uma variante segura para texto)

Regras que diferenciam uma paleta pensada de uma padrão:

  • Construa rampas em OKLCH. A luminosidade permanece perceptual uniforme entre os matizes, então um azul 600 e um verde 600 carregam o mesmo peso visual. A luminosidade HSL mente.
  • Matize os neutros. Cinza puro e preto ou branco puro parecem não pertencer a ninguém. Adicione uma pequena quantidade de croma (cerca de 0.005 a 0.015) em direção ao matiz da marca.
  • Texto em uma superfície colorida usa uma tonalidade escura do matiz dessa superfície, não cinza neutro. Cinza sobre cor parece desbotado.
  • Escolha um nível de compromisso e mantenha-o: contido (fundo neutro, um acento), comprometido (matiz da marca presente em todo lugar), paleta completa, ou encharcado (matiz da marca é o fundo). Meio compromisso parece indecisão.
  • Nunca deixe a cor carregar significado sozinha. Emparelhe-a com um ícone, um rótulo ou um padrão.
  • Cuidado com os reflexos atuais. Uma página creme quente com uma fonte de exibição serifada e um acento terracota, ou quase preto com um acento ácido, são o que designs gerados alcançam quando nada foi decidido. Use-os apenas quando o parágrafo de direção pedir por eles.

Contraste (WCAG 2.2)

ParAAAAA
Texto do corpo (abaixo do tamanho grande)4.5:17:1
Texto grande: 24px regular, ou cerca de 18.7px negrito, e acima3:14.5:1
Limites de componentes de UI, ícones, indicadores de foco, marcas de gráfico que carregam significado3:1nenhum
  • Texto placeholder que informa o usuário de algo é texto: 4.5:1.
  • Controles desabilitados são isentos, mas o usuário ainda precisa ver que um controle está lá.
  • Meça as cores computadas, incluindo opacidade e sobreposições. Um rótulo com 60% de opacidade em um cartão matizado é uma nova cor.

Tipografia

  • Escolha as faces para o registro do conteúdo, não por hábito. Três papéis: uma face de exibição com personalidade, usada com moderação; uma face de corpo confortável; uma face utilitária para rótulos, legendas e dados (figuras tabulares para números em tabelas).
  • Emparelhe com um contraste claro (serifada com sans-serif, geométrica com humanista) ou use uma família entre pesos. Duas faces que são similares mas não iguais parecem um erro.
  • Escala modular. Escolha uma proporção: 1.2 para UI de produto densa, 1.25 a 1.333 para conteúdo e marketing. Nomeie papéis, não tamanhos: display, h1 a h4, body-lg, body, body-sm, label, caption.
  • Medida 60 a 75 caracteres para texto do corpo (max-width: 70ch).
  • Tipo de exibição recebe tracking mais apertado (cerca de -0.02em a -0.04em) e um teto de tamanho (cerca de 6rem via clamp()). Maior raramente parece intencional.
  • text-wrap: balance em títulos, text-wrap: pretty em prosa do corpo.
  • Altura da linha: cerca de 1.5 para corpo, 1.1 a 1.25 para exibição.

Espaço, forma, profundidade

  • Escala de espaçamento baseada em 4 ou 8: por exemplo 4, 8, 12, 16, 24, 32, 48, 64. Componentes usam tokens, nunca valores brutos em pixels.
  • Raio: dois ou três valores com uma regra para qual se aplica onde. Raios aninhados: o raio interno é igual ao raio externo menos o padding entre eles.
  • Elevação: três ou quatro níveis, cada um vinculado a uma função (cartão em repouso, dropdown, modal). Em temas escuros, aumente a elevação com uma superfície mais clara, não uma sombra mais pesada.

Movimento

  • Tokens: durações (por exemplo 120ms, 200ms, 320ms) e duas ou três curvas de easing (uma para entrada, uma mais acentuada para saída). Elementos as reutilizam; ninguém escolhe um valor por elemento.
  • Movimento explica uma mudança: de onde algo veio, o que respondeu. Movimento que apenas decora parece gerado.
  • Um momento coreografado vence tudo desaparecendo ao mesmo tempo.
  • Honre prefers-reduced-motion: reduce: remova movimento e transições longas, mantenha alterações de opacidade.
  • Não dimensione fotos ao passar o mouse. Anime o contêiner (sombra, borda, fundo).

Modo escuro

  • Um tema escuro é um remapeamento de tokens semânticos, nunca uma inversão. Use cinzas escuros para o fundo, não preto puro, e reduza o croma de acentos que brilham.
  • Verifique novamente cada par de contraste no tema escuro.
  • Previna o flash do tema errado: decida o tema em um pequeno script inline no cabeçalho do documento, antes da primeira pintura.

Leia references/dark-mode.md ao implementar troca de tema, persistência ou imagens no modo escuro.

Especificações de componente

Leia references/component-spec.md antes de escrever uma especificação de componente. Ela contém o modelo e a lista de verificação de estados.

Pegadinhas

  • 11 tonalidades nomeadas de 100 a 900. Isso são 9 degraus. Nomeie rampas para que a contagem e os nomes concordem (50, 100 ... 900, 950 dá 11).
  • "Texto grande" significa 18 pontos, não 18 pixels. Texto do corpo regular de 18px precisa de 4.5:1, não 3:1. O limite de texto grande é 24px regular ou cerca de 18.7px negrito.
  • Tokens primitivos em componentes. Funciona até o primeiro tema. Então cada componente precisa de edição.
  • Contraste verificado no mockup, não na construção. Opacidade, sobreposições e anti-aliasing mudam a cor real. Meça os pixels renderizados ou estilos computados.
  • Um ajuste global para corrigir um problema local. Escurecer toda a paleta para resgatar um par falhando desloca todos os outros pares. Corrija o token do par.
  • Um token que ninguém usa, ou um valor bruto que ninguém tokenizou. Ambos significam que o sistema e a construção se distanciaram. Grepe a construção por valores hex e pixel brutos.
  • Uma nova fonte carregada para um título. Cada face custa tempo de carregamento. Use as faces que o sistema já carrega.

Verificação

  • Parágrafo de direção escrito, e cada família de token pode ser rastreada até ele.
  • Cada par de texto e UI passa AA no claro e no escuro, medido na página construída.
  • Componentes usam apenas tokens semânticos: grep não mostra valores brutos de cor ou espaçamento no código do componente.
  • Cada especificação de componente lista todos os seus estados.
  • Configuração de movimento reduzido testada: nenhum movimento permanece.
  • Troca de tema não mostra flash em uma recarga forçada com a configuração oposta do sistema.

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

api-design

Use when designing or changing an HTTP API contract, adding or editing a route, endpoint or webhook, writing an OpenAPI spec, choosing error, pagination or versioning shapes. Also when asking "is this a breaking change". Not for server internals such as jobs, retries or rate-limit storage; use `backend-patterns`.

artist

Use when making or directing visual assets such as illustrations, hero images, icons, logos, brand marks, textures or diagrams, or writing prompts for an image-generation model. Covers art direction, reference boards and critique against a brief. Not for page layout; use `designer`. Not for palettes and tokens; use `visual-design`.

copywriter

Use when writing, rewriting or reviewing words a customer reads, such as landing or marketing pages, headlines, taglines, calls to action, pricing pages, product descriptions, onboarding text, button labels, error messages and empty states. Not for long-form docs or articles; use `docs`. Not for positioning strategy; use `marketing`.

designer

Use when asked to critique, redesign or review the layout and hierarchy of a page, screen, landing page or dashboard (hero, CTAs, card grids, testimonials), or when a design \"looks off\", \"looks generic\" or \"looks AI-made\". Use it for any layout feedback, even if the word design is not used. Not for tokens, palettes or type scales; use `visual-design`. Not for images; use `artist`.

frontend

Use when building, reviewing or fixing browser UI, such as pages, components, forms, client state, charts, print or PDF views, accessibility or web performance (Core Web Vitals, bundle size, slow renders). Not for visual direction, layout critique or brand (use `designer` or `visual-design`). Not for native or React Native apps (use `mobile`).

game-design

Use when designing or reviewing how a game plays: core loop, mechanics, game feel and juice, difficulty curve, progression, economy and balance, tutorials, HUD and menus or a game design document (GDD) and playtest plan. Not for engine code or rendering (use `frontend`) or for non-game product UX (use `ux-research`).

ux-research

Use when planning or synthesising user research (interviews, usability tests, surveys), mapping a journey or job to be done, specifying an interaction's states, or running a heuristic review of a flow. Not for menus, labels, taxonomy or site structure; use `information-architecture`. Not for visual polish; use `designer`.

Habilidades Relacionadas