KIT-code-maker/color-system

Sistema de Cores

Visão Geral

Uma biblioteca curada de paletas de cores prontas para uso (claro + escuro) em quatro domínios — UI de aplicação web, marketing/landing, visualização de dados e terminal/TUI — além da metodologia para construir novas paletas e verificar sua acessibilidade.

Princípio central: escolha cores por função semântica (fundo, texto, primário, erro…), não por matiz bruto. Cada paleta aqui mapeia hexadecimais para funções, então um tema permanece intercambiável, consistente e acessível. Escolha uma função primeiro, depois leia seu hexadecimal — codificar um hexadecimal onde uma função pertence é o que quebra a tematização posteriormente.

Navegação

O índice e o contrato de funções abaixo respondem "qual paleta" por si só. Carregue um arquivo de referência quando a tarefa precisar de seu conteúdo — não todos os quatro.

Carregar	Quando
references/carbon.md	Construindo uma página ou artefato que deve usar Carbon — leia apenas este arquivo; ele contém as funções, kit de dashboard e tríades do Carbon em ambos os modos
references/palettes.md	Você precisa de valores hexadecimais para qualquer outra paleta — os quatro domínios, claro + escuro; as tríades fill/subtle/emphasis; as escalas de 12 passos por trás de Dusk, Driftwood e Meadow
references/contrast.md	Verificando limites WCAG/APCA, segurança para daltonismo, ou depurando um par que falha
references/build-your-own.md	Nenhuma paleta da biblioteca se encaixa e você está gerando uma nova escala (a receita OKLCH)
references/theory.md	Escolhendo um esquema de harmonia, ou justificando uma decisão de espaço de cor / escala

Biblioteca de Paletas (índice rápido)

Onde uma paleta é a primeira escolha certa, ela é marcada com ⭐; marketing e TUI não têm padrão porque a escolha segue a marca ou o tema de terminal do usuário.

UI de Aplicação Web — claro + escuro, 13 funções semânticas + uma tríade por cor

• Carbon ⭐ (padrão) — ardósia azul escura, escuro-primeiro. Dashboards analíticos, relatórios de desempenho e ferramentas de desenvolvimento. Inclui um kit de dashboard completo (pílulas de grau A-F, sequência ordenada de estágios, tom de código embutido, destaque de sucesso). Alcance para Graphite quando o modo claro precisa ser ajustado manualmente para igualdade.
• Graphite — ardósia fria + azul. Dashboards B2B densos, ferramentas de desenvolvimento; o padrão de paridade claro+escuro.
• Evergreen — marca esmeralda sobre zircão verdadeiramente neutro. Identidade fresca, confiante, não azul.
• Terracotta — neutros quentes de argila/café expresso + ferrugem. Editorial, plataformas de conteúdo, ferramentas de escrita.
• Bloom — pastel pervinca/violeta, modo escuro profundo. Ferramentas de desenvolvimento amigáveis, aplicações lúdicas-mas-limpos.
• Teal Slate — verde-azulado profundo sobre ardósia fria, um único acento quente. Relatórios técnicos, dashboards de SRE / limite de taxa; combina com uma face mono para figuras.

Gerado a partir de escalas OKLCH de 12 passos, que acompanham suas funções para que possam ser estendidas ou rederivadas:

• Dusk — primário índigo, acento turquesa, cinzas frios quase neutros. Ferramentas de foco, editores, aplicações de longa sessão.
• Driftwood — primário marinho profundo sobre neutros de areia quente, acento de argila. Aquele que muda seus neutros para frios no modo escuro.
• Meadow — primário sálvia suave, acento ouro velho, neutros de osso quente. O mais suave do conjunto; repousante em vez de confiante.

Marketing / Landing — claro + escuro, gradientes de herói

• Sunbloom — calor coral/âmbar refinado. Marcas acessíveis de consumo/criador.
• Tidewater — verde-azulado/sálvia. Fintech, bem-estar, confiança B2B.
• Obsidian & Gold — quase preto + ouro metálico. Premium, luxo, agência.
• Paper & Ink — papel quente + preto tinta + um acento terracota. Blogs, formato longo, portfólios.

Visualização de Dados — consciente de daltonismo, terra quente/fria

• Categórico: Lunar Valley ⭐ (padrão) · Hearthstead · Vintage Warm · Glass Wall · Okabe-Ito (use quando a segurança CVD for um requisito rigoroso)
• Sequencial: Viridis ⭐ (padrão) · Magma · Inferno · Plasma · ColorBrewer Blues · YlOrRd (todos perceptualmente uniformes)
• Divergente: Console & Window ⭐ (padrão) · Alien Sun · Orchard Dusk · Coffee & Coolant — todos quente↔frio, sem vermelho↔verde

Terminal / TUI — 16-ANSI + bg/fg/cursor/seleção

• Solarized Dark · Nord · Catppuccin Mocha · Catppuccin Latte (o único esquema claro) · Dracula · Tokyo Night

→ Tabelas hexadecimais completas: Carbon em references/carbon.md, todas as outras paletas em references/palettes.md

Funções semânticas (o contrato)

As paletas de UI preenchem estas funções. Mapeie a intenção para uma função, depois a função para um hexadecimal.

Função	O que é
background	Tela base da aplicação/página
surface	Cartões, painéis, folhas
surface-elevated	Superfícies elevadas (popovers, modais); no modo escuro mais claro = mais elevado
border	Divisores, bordas de entrada, anéis de foco
text-primary	Primeiro plano de alta ênfase
text-secondary	Rótulos silenciados, dicas, legendas
primary / primary-hover	Cor de ação da marca + seu estado de hover
accent	Ênfase secundária, distinta do primário
success / warning / error / info	Estados semânticos (verde / âmbar / vermelho / azul pela convenção ocidental)

Cada função colorida precisa então de uma tríade, porque um hexadecimal não pode fazer três trabalhos. Um valor criado para ser sentado em cima não é automaticamente legível como texto, e um preenchimento sólido é muito alto para um fundo de badge em densidade de tabela.

Token	Trabalho	Bootstrap 5.3 chama	Material 3 chama
{c}-fill + {c}-on-fill	Botões, chips ativos	--bs-{c} + color-contrast()	primary + on-primary
{c}-subtle + {c}-emphasis	Fundo de badge / callout + seu rótulo	--bs-{c}-bg-subtle + -text-emphasis	primary-container + on-primary-container
{c}-subtle-border	Borda ao redor desse fundo	--bs-{c}-border-subtle	—
link	O matiz da marca como texto sobre surface	(dividido na v6)	—

Tríades prontas para todas as nove paletas de UI estão em palettes.md, exceto as do Carbon, que estão em carbon.md. Preenchimentos do modo escuro são matizes claros, então seus rótulos são o neutro mais escuro da paleta, não branco.

Paletas de visualização de dados fornecem listas de cores ordenadas (categórico = séries distintas; sequencial = rampa baixo→alto; divergente = quente↔frio com um ponto médio neutro). Esquemas TUI fornecem os 16 slots ANSI mais 4 funções especiais.

Conceitos Centrais

• Projete em OKLCH, não HSL. OKLCH é perceptualmente uniforme; a "luminosidade" HSL mente (azul com L igual parece muito mais escuro que amarelo com L igual), então até passos HSL produzem escalas irregulares.
• Harmonia: escolha um esquema (monocromático / análogo / complementar / triádico…) e deixe uma cor dominar em saturação e área; dessature o resto.
• Escalas: 10–12 passos, luminosidade do passo uniforme, pico de croma no intervalo médio e afunilamento nas extremidades para que matizes não sejam lavados e sombras não sejam turvas.
• Contraste: WCAG AA — texto corporal ≥ 4,5:1, texto grande e UI/bordas ≥ 3:1.
• Claro vs escuro não é uma inversão, e as proporções WCAG 2 superestimam o contraste perto do preto. Ambos os modos de falha e suas correções estão em Pegadinhas abaixo; limites e o procedimento APCA estão em references/contrast.md.
• Segurança para daltonismo: codifique significado com texto, ícone ou posição além do matiz, já que ~8% dos homens não conseguem separar os matizes sozinhos. Para dados divergentes use quente↔frio (azul/laranja, verde-azulado/rosa) em vez de vermelho↔verde.

Exemplos

Exemplo: escolhendo cores para um dashboard SaaS

✅ Desejado

Usuário: "Preciso de cores para um dashboard de administrador, claro e escuro."
→ Recomende Carbon (ardósia azul escura, escuro-primeiro, feito para UI de dados densa) — o padrão;
  ofereça Graphite se a paridade de modo claro ajustada manualmente importar mais que o kit de dashboard.
→ Copie sua tabela função→hexadecimal de carbon.md (ambos os modos).
→ Aplique por função: background→surface→border→text, primary para o CTA principal,
  success/warning/error para badges de status. Confirme text-primary sobre background ≥ 4.5:1.

❌ Antipadrão

→ Escolha quatro matizes de uma paleta Coolors e atribua-os ad hoc: #2b2d42 nav, #8d99ae texto,
  #edf2f4 fundo, #ef233c botões. Modo escuro = inverta os hexadecimais.

Por que funciona: uma paleta mapeada por função cai diretamente em variáveis CSS e é acessível por construção. A versão ad hoc não tem rampa neutra, níveis de elevação, cores de estado, e inverter uma paleta clara produz superfícies preto puro e matizes de marca desbotados (veja Pegadinhas: claro vs escuro não é uma inversão).

Exemplo: cor de badge de status

✅ Desejado

.badge-error { background: var(--error); color: #fff; }   /* função, não um vermelho codificado */

❌ Antipadrão

.badge-error { background: #ff0000; color: #000; }   /* matiz bruto; #f00 sobre #000 ≈ 5,2:1 mas ofusca,
                                                         e não vai tematizar ou alternar para modo escuro */

Por que falha: codificar um matiz quebra a tematização e o modo escuro, e vermelho puro/preto puro causa halação.

Exemplo: escolhendo uma paleta de gráfico

✅ Desejado

Série categórica (≤8) → Lunar Valley (padrão), ou Okabe-Ito quando a segurança CVD for necessária.
Contínuo baixo→alto → Viridis (perceptual uniforme, seguro para daltonismo).
Dados assinados com um ponto médio → Console & Window (quente↔frio, centro neutro).
Após ~8 cores categóricas, as séries param de ser distinguíveis — agregue em "Outro" em vez disso.

❌ Antipadrão

Doze séries categóricas coloridas a partir das funções success/warning/error/info da paleta de UI mais
matizes de marca; lucro/perda codificado verde↔vermelho sem rótulos.

Por que funciona: combina a estrutura dos dados com a família de paletas certa e respeita o limite de distinguibilidade. O antipadrão reutiliza funções de estado de UI que colidem com a identidade da série, excede o limite de ~8 matizes e codifica vermelho↔verde sem backup de texto ou ícone para visualizadores daltônicos.

Pegadinhas

• Sintoma: Cor da marca é ilegível como texto corporal. Causa: Meio-tons saturados (âmbar, coral, verde-azulado) frequentemente falham 4,5:1 em seu próprio fundo — uma cor de preenchimento e uma cor de texto são passos diferentes da mesma rampa. Correção: mantenha fill e link como valores separados; escureça o texto um passo até que passe. Nesta biblioteca apenas Evergreen claro diverge (#059669 carrega um rótulo de botão a 4,70:1 mas atinge 3,77:1 como link sobre branco, então seu link é #00875b), que é exatamente por que a divisão é perdida.
• Sintoma: Badges de status parecem corretos mas gritam em densidade de tabela. Causa: um fundo --error sólido atrás de texto branco é certo para um botão e muito alto para um badge de nível de linha. Correção: use o fundo {c}-subtle com seu rótulo {c}-emphasis emparelhado. Reutilizar o matiz de status como seu próprio rótulo nesse tom falha 4,5:1 mais frequentemente do que não — pegue o valor emparelhado de palettes.md (o Carbon de carbon.md) em vez de assumir.
• Sintoma: Uma paleta gerada a partir de uma escala de 12 passos ainda falha contraste. Causa: o mapa de passos não é uma garantia de contraste. Radix garante passos 11 e 12 contra o passo 2 e nada mais; o passo 9 raramente carrega um rótulo de botão 4,5:1, e o passo 8 raramente atinge 3:1 como borda de controle. Correção: resolva esses dois contra seu fundo real. No modo claro, comprometa-se com um rótulo branco e escureça o preenchimento — resolver em direção ao rótulo que já pontua mais alto produz uma lavagem pálida que passa e parece fraca.
• Sintoma: Uma paleta que parece certa no modo claro parece turva no escuro. Causa: o tom neutro foi escolhido uma vez e herdado. Um matiz quente que lê como papel em alta luminosidade lê como marrom em baixa luminosidade. Correção: redecida tom e croma neutros por modo; mudar para frio em croma muito baixo é a resposta usual. Driftwood em palettes.md faz isso (matiz 64 claro, 224 escuro); Meadow sálvia não precisou.
• Sintoma: Uma paleta copiada do Color Hunt, Coolors ou um artigo de tendência não pode construir uma interface. Causa: paletas de galeria são quatro matizes decorativos sem rampa neutra, sem tinta escura e sem estados — 16 das 30 paletas mais curtidas do Color Hunt não podem carregar texto corporal 4,5:1 com qualquer par de suas cores. Correção: pegue os matizes como material de semente e construa escalas a partir deles (build-your-own.md); Dusk, Driftwood e Meadow foram feitos assim.
• Sintoma: Texto secundário/silenciado ("diminuído", text-secondary) parece bom na ferramenta de design, mas falha contraste na aplicação. Causa: bibliotecas de componentes enviam uma cor de texto silenciado padrão (ex.: dimmed do Mantine) ajustada para hierarquia visual, não contraste — comumente chegando a cerca de 3,4:1, bem abaixo do piso AA de 4,5:1. Correção: escolha e verifique seu próprio hexadecimal text-secondary contra contrast.md em vez de herdar o padrão da biblioteca, e verifique novamente por tema — a mesma substituição pode passar em um tema e falhar em outro. Verifique novamente em superfícies matizadas/elevadas (cartões, linhas listradas) também, não apenas na tela plana.
• Sintoma: Modo escuro "passa WCAG" mas é difícil de ler. Causa: a matemática WCAG 2 superestima o contraste perto do preto. Correção: verifique novamente pares escuros com APCA (Lc), não apenas a proporção 4,5:1.
• Sintoma: Tema escuro parece plano, elevação ilegível. Causa: fundo #000 puro + superfícies de mesma luminosidade. Correção: eleve a base para cerca de #0d1117–#1e1e2e e faça cada nível de elevação mais claro.
• Sintoma: Um gráfico é ilegível para visualizadores daltônicos. Causa: codificação vermelho↔verde ou significado apenas por matiz. Correção: mude para uma paleta divergente quente↔frio e adicione rótulos/ícones; para categórico use o conjunto seguro Okabe-Ito (em palettes.md).
• Sintoma: Texto do gráfico permanece de baixo contraste mesmo que sua paleta defina a cor de texto certa. Causa: bibliotecas de gráficos (Recharts, gráficos Mantine) renderizam texto de eixo/legenda/valor como SVG com seu próprio fill embutido, contornando seus tokens de cor completamente. Correção: mire nos elementos de texto da biblioteca diretamente (ex.: .recharts-wrapper text { fill: var(--text) }) — a cascata CSS nunca o alcança.
• Sintoma: Cores TUI desaparecem em alguns terminais. Causa: hexadecimal codificado, ou texto de suporte colocado em preto brilhante (slot 8). Correção: vincule significado aos slots ANSI 1–6 para que o próprio tema do usuário o renderize, e mantenha o slot 8 apenas para desênfase.
• Sintoma: Passos da paleta parecem irregulares/desiguais. Causa: Passar luminosidade em HSL/RGB. Correção: Reconstrua a escala em OKLCH com o passo croma também — o cromo de pico no passo 5–7 e redução nas extremidades lava e sujo igualmente.

Exemplo: Construindo sua própria paleta

Quando nenhuma paleta da biblioteca se encaixa, use a receita OKLCH. O esboço abaixo é a abordagem completa; uma referência detalhada está em references/build-your-own.md.

1. Escolha um matiz de semente — um hexadecimal que "se sinta" como seu primário. (Não codifique sua amostra de semente; a receita a usa apenas como um ponto de partida.)
2. Converta para OKLCH (ferramenta: https://oklch.com). Anote L, C e H.
3. Gere uma escala de 12 passos:
   • Luminosidade uniforme: 5%–95% (variação de 8,18pp por passo).
   • Croma: pico em 0,12–0,14 por passo 5–7, taper para 0,03 nas extremidades.
   • Matiz: mantenha constante para monocromática; gire para análoga/complementar a meio caminho.
4. Atribua funções (veja a tabela de funções acima). Normalmente passo 1–2 = background, passo 3 = surface, passo 4 = surface-elevated, passo 5 = border, passo 11–12 = text-primary… mas teste o contraste real; as atribuições exatas dependem de quão escuros são seus passos.
5. Construa tríades: fill = passo7, subtle = passo2, emphasis = ajuste contrast.md até que emphasis-on-subtle atinja 4,5:1. (fill + rótulo branco ≈ passo ≤

---

Traduzido do original SKILL.md