Cor

Off-white dominante, cinzas industriais, quatro cores funcionais reservadas a estado. Acento V-B contido em elemento — nunca superfície global.

Princípio

Três paletas, três papéis. Surface & Ink cobre a maior parte do produto — é o chão. A paleta funcional reserva quatro cores exclusivamente para sinalizar estado de sistema: sucesso, alerta, erro, informação. A paleta Accent V-B traz os tons terrosos retrofuturistas como acento contido em elemento — nunca como fundo de tela. Cada paleta tem papel fixo; misturar papéis é violação.

Dentro da paleta Surface, o chão opera em dois tons com papéis distintos: --color-surface-base (#F7F7F7) é o ambiente de conteúdo — fundo da área de trabalho onde cards e componentes pousam; --color-surface-shell (#FFFFFF) é o invólucro estrutural — sidebar de navegação, topbar mobile e qualquer chrome que envolve o conteúdo. Ambos são V-A puro; a distinção não é de registro nem de elevação, é funcional. O contraste entre shell (branco) e base (off-white) é o que permite que os cards em raised se destaquem sobre o conteúdo sem exigir sombra mais pesada.

Tokens

Surface

Off-white e cinzas que constroem o chão V-A. Incluem os tokens de gradiente das superfícies raised e as bordas de sistema.

  • --color-surface-base

    #F7F7F7

    Off-white dominante — ambiente de conteúdo: fundo da área de trabalho onde cards e componentes pousam.

  • --color-surface-shell

    #FFFFFF

    Invólucro estrutural — sidebar e topbar mobile. Branco sólido; V-A puro. Distingue-se de surface/base por ser chrome, não conteúdo.

  • --color-surface-raised-top

    #F7F7F7

    Topo do gradiente raised — mesmo hex que surface-base, para emergir suavemente da base.

  • --color-surface-raised-bottom

    #FBFBFB

    Base do gradiente raised — levemente mais clara, sinaliza a direção da luz (canto sup-esq).

  • --color-surface-floating

    #FBFBFB

    Fundo de modal e popover — sólido, mais claro que base para elevar acima da cena.

  • --color-surface-carved

    #F8F8F8

    Fundo de campo afundado (input, Search Field) — ligeiramente mais escuro que base, indica cavidade.

  • --color-surface-divider

    #ECECEC

    Hairline e separadores de seção — cinza quase imperceptível; presença sem peso visual.

Bordas de superfície

Tokens de borda que reforçam a direção da luz em cada natureza de superfície. Não são bordas decorativas — são parte do sistema de elevação.

  • --border-base

    #EBEBEB

    Contorno sólido sutil da superfície base.

  • --border-raised-top

    #FCFCFC

    Borda raised — topo iluminado (luz vinda do canto sup-esq).

  • --border-raised-bottom

    #F8F8F8

    Borda raised — base sombreada.

  • --border-carved-top

    #E8E8E8

    Borda carved — topo em sombra (mais escuro que raised para enfatizar o sulco).

  • --border-carved-bottom

    #FFFFFF

    Borda carved — base iluminada.

Ink

Quatro tons de tinta para escala de hierarquia textual. Nenhum deles é cor funcional — não sinalizam estado.

  • --color-ink-primary

    #171717

    Tinta principal — corpo de texto, títulos de UI, valores de destaque. Também é o fundo do Button secondary (sólido V-A) e a base de --color-ink-primary-hover/-active, --color-overlay e --color-nav-active/-hover.

  • --color-ink-secondary

    #6B6B6B

    Texto de apoio — descrições, metadados, labels secundários.

  • --color-ink-tertiary

    #A1A1A1

    Texto desabilitado e caption — placeholder, texto de dica, kicker subordinado.

  • --color-ink-inverse

    #F7F7F7

    Tinta sobre fundo escuro — label do Button secondary. Mesmo hex que --color-surface-base, papéis distintos: aqui é tinta, lá é superfície. Nota: a Tecla V-B usa #FFFFFF hardcoded — divergência registrada na issue #108.

Funcional

Quatro cores reservadas exclusivamente a estado de sistema. Nunca decoração. Cada cor tem um papel fixo; usar fora do papel é violação. Tints são os fundos para chips de estado (fundo suave da mesma matiz).

  • --color-functional-success

    #37A35A · tint #E8F2EC

    Ação concluída com sucesso, meta atingida, pagamento confirmado.

    Pago

  • --color-functional-alert

    #D4A017 · tint #F6EEDA

    Atenção necessária — vencimento próximo, orçamento apertando.

    Atenção

  • --color-functional-error

    #C43D3D · tint #F3E2E1

    Erro de sistema, inadimplência, estado crítico.

    Atrasado

  • --color-functional-info

    #3875B0 · tint #E2EAF2

    Informação neutra, dica contextual, link de ação informativa.

    Aviso

Variantes text-accessible (WCAG AA)

Os hex padrão da paleta funcional falham WCAG AA quando aplicados em texto bold caps xs sobre seus tints (success ~3,7:1, alert ~2,2:1, error ~3,3:1, info ~3,8:1). Estas variantes substituem o token padrão no texto de chips, badges e composições análogas — o fundo continua sendo o tint correspondente. Origem: Decisão #7 do Epic #282; razões validadas em 2026-05-03.

  • --color-functional-success-text-accessible

    #1F6B36 · ~5,70:1 sobre #E8F2EC

    Substitui --color-functional-success em texto sobre --color-functional-success-tint.

    Pago AA

  • --color-functional-alert-text-accessible

    #7A5800 · ~6,88:1 sobre #F6EEDA

    Substitui --color-functional-alert em texto sobre --color-functional-alert-tint.

    Atenção AA

  • --color-functional-error-text-accessible

    #8A2828 · ~6,87:1 sobre #F3E2E1

    Substitui --color-functional-error em texto sobre --color-functional-error-tint.

    Atrasado AA

  • --color-functional-info-text-accessible

    #244D77 · ~7,21:1 sobre #E2EAF2

    Substitui --color-functional-info em texto sobre --color-functional-info-tint.

    Aviso AA

Accent V-B

Paleta retrofuturista — rim borgonha e cap âmbar — usada exclusivamente em elemento contido (ex.: tecla). Nunca superfície global. Ver Regras de uso §3 e .claude/ui-design/visual-language.md §2.2.

Rim — lateral de profundidade

  • --color-accent-rim

    #5F0000

    Rim borgonha — lateral de profundidade da tecla (rest state).

  • --color-accent-rim-border-top

    #FFFFFF

    Borda do rim — topo iluminado.

  • --color-accent-rim-border-bottom

    #CECECE

    Borda do rim — base sombreada.

Cap — rest

  • --color-accent-amber-top

    #F7692B

    Topo do gradiente do cap.

  • --color-accent-amber-bottom

    #FA4C00

    Base do gradiente do cap.

  • --color-accent-amber-border-top

    #FF9567

    Anel bisel do cap — topo pegando luz. Espelha a tecla canônica da landing page.

  • --color-accent-amber-border-bottom

    #FF4E00

    Anel bisel do cap — base em sombra. Espelha a tecla canônica da landing page.

Cap — hover

  • --color-accent-amber-hover-top

    #FF986B

    Topo do gradiente do cap (hover, mais claro).

  • --color-accent-amber-hover-bottom

    #FF7135

    Base do gradiente do cap (hover).

  • --color-accent-amber-hover-border-top

    #FF986B

    Borda do cap — topo iluminado (hover). Unificado com --color-accent-amber-hover-top.

  • --color-accent-amber-hover-border-bottom

    #FA4C00

    Borda do cap — base sombreada (hover). Unificado com --color-accent-amber-bottom.

Cap — disabled

  • --color-accent-amber-disabled-top

    #C9C9C9

    Topo do gradiente do cap (disabled, dessaturado).

  • --color-accent-amber-disabled-bottom

    #B8B8B8

    Base do gradiente do cap (disabled, dessaturado).

Regras de uso

  • Surface & Ink são permitidos em qualquer superfície — sem restrição de contexto. São o chão padrão de toda cena.
  • Funcional é reservada exclusivamente a estado de sistema (sucesso, alerta, erro, informação). Nunca como decoração, acento de marca ou diferenciação visual sem significado de estado.
  • Quando a cor funcional for o fundo de um chip ou badge, usar o tint correspondente como fundo e a cor principal como texto/ícone — nunca a cor saturada como fundo de texto pequeno.
  • Accent V-B é restrita a elementos contidos autorizados pela matriz de superfície (.claude/ui-design/visual-language.md §3). O número máximo de elementos V-B simultâneos no campo de visão é dois; três ou mais é violação.
  • Fundo de tela, shell do app, fundo de dashboard ou de seção dominante em tom terroso é sempre violação — independente de quantos elementos V-B coexistem sobre esse fundo.
  • Gradientes coloridos ou vibrantes em chrome de UI (botão, card, hero, background de seção) são proibidos. A exceção é componente de visualização de dados onde o gradiente tem função semântica — ver ui-design/anti-patterns.md §2.
  • Cor funcional não é acento de design. Se a intenção é "chamar atenção" sem indicar estado, a resposta correta é hierarquia tipográfica, não cor.

Anti-padrões referenciados

Os anti-padrões abaixo têm relação direta com decisões de cor. O arquivo-fonte está em .claude/ui-design/anti-patterns.md. As páginas do DS ainda não têm endereço permanente para esses itens — o link será atualizado quando a seção de anti-padrões visuais for publicada.

  • #2 — Gradiente colorido ou vibranteAplicar gradiente com duas ou mais matizes distintas em chrome de UI. Proibido em botão, card, hero, background de seção. Exceção: data-viz com função semântica.
  • #5 — Cor aplicada como decoraçãoUsar cor em superfície, card, ícone ou texto sem que ela represente estado funcional ou acento V-B autorizado. Quando tudo é colorido, nada é sinal.
  • #6 — Mistura 50/50 entre V-A e V-B (inclui V-B como superfície global)V-B cobrindo metade da tela ou assumindo superfície global. A única exceção autorizada é landing/marketing/campanha — e mesmo ali o terroso entra por blocos, não por tapete.

Contraste WCAG

Pareamentos canônicos ink × surface com razão de contraste calculada (WCAG 2.x, relative luminance). Conformidade AA exige 4,5:1 para texto normal e 3:1 para texto grande (acima de 18pt/24px regular ou 14pt/18,67px bold). AAA exige 7:1 para texto normal e 4,5:1 para texto grande.

Texto (Ink)Fundo (Surface)RazãoTexto normalTexto grandeUso típico
--color-ink-primary#171717--color-surface-base#F7F7F716,6:1AAAAAACorpo de texto, títulos, valores de destaque — pareamento principal
--color-ink-primary#171717--color-surface-floating#FBFBFB17,3:1AAAAAATexto em modal e popover
--color-ink-secondary#6B6B6B--color-surface-base#F7F7F74,64:1AAAAATexto de apoio, metadados, labels secundários
--color-ink-tertiary#A1A1A1--color-surface-base#F7F7F72,33:1abaixo AAabaixo AARestrito a decorativo/placeholder/disabled — nunca texto informativo obrigatório de leitura
--color-ink-inverse#F7F7F7--color-ink-primary#17171716,6:1AAAAAALabel do Button secondary (sólido preto) e texto em overlay sobre --color-overlay. A Tecla V-B (Button primary) faz pareamento similar com #FFFFFF hardcoded no lugar de --color-ink-inverse — divergência registrada na issue #108.
#FFFFFFhardcoded — issue #108--color-accent-amber-bottom#FA4C003,3:1abaixo AAAALabel da Tecla V-B sobre o cap âmbar — restrito a texto grande (bold ≥ 14pt) e acompanhado de text-shadow declarado no componente. O #FFFFFF é literal em sombra-e-elevacao.css; tokenização pendente (issue #108).
--color-functional-success-text-accessible#1F6B36--color-functional-success-tint#E8F2EC5,70:1AAAAATexto de chip tone=success (ex.: "Pago"). Substitui --color-functional-success em texto bold caps xs sobre o tint, onde o token padrão (#37A35A) ficaria em ~3,7:1.
--color-functional-alert-text-accessible#7A5800--color-functional-alert-tint#F6EEDA6,88:1AAAAAATexto de chip tone=alert em medicação (UC-13/UC-08 opt-in) e atenção geral. Substitui --color-functional-alert, que falha (~2,2:1) por ser amarelo de baixa luminância.
--color-functional-error-text-accessible#8A2828--color-functional-error-tint#F3E2E16,87:1AAAAAATexto de chip tone=error (ex.: "Atrasado") e badges de inadimplência. Substitui --color-functional-error, que ficaria em ~3,3:1.
--color-functional-info-text-accessible#244D77--color-functional-info-tint#E2EAF27,21:1AAAAAATexto de chip tone=info (ex.: "Aviso") e composições neutras. Substitui --color-functional-info, que ficaria em ~3,8:1.