Marcus Andrey Estudo
Read in English Biblioteca

Design systems · Passo 2 · 8 min de leitura

Temas e modos

Claro e escuro, confortável e compacto: um modo é um segundo conjunto de respostas para os mesmos tokens semânticos. Como o Harbour troca de modo e de densidade sem mexer num componente, o CSS exato de uma demo ao vivo, por que o modo escuro é medido e não invertido, e como o Figma e o resolver do DTCG tratam a mesma ideia.

Um modo não muda os seus componentes. Ele muda para onde os seus tokens apontam. Se o modo escuro significa editar o botão, o card, a tabela e mais quarenta, o sistema tem um furo. Se o modo escuro significa reapontar uma dúzia de tokens semânticos, o sistema está funcionando. Os níveis do começo deste passo serviam para isso, e é aqui que eles se pagam.

O que você vai conseguir fazer depois de ler:

  • Separar tema, modo e densidade
  • Trocar de modo reapontando tokens semânticos, sem mudar nenhum componente
  • Ler e reaproveitar o CSS por trás de uma troca de modo ao vivo
  • Desenhar o modo escuro medindo, não invertendo

1. Temas, modos, densidade

As palavras se misturam, então é assim que este curso usa cada uma:

  • Modo: um contexto em que o mesmo produto roda. Claro e escuro são modos; alto contraste também.
  • Densidade: o quanto a interface é apertada. O Harbour tem a confortável (padrão) e a compacta, para o console da equipe, onde o pessoal do porto quer mais linhas na tela.
  • Tema ou marca: uma aparência diferente para outro produto ou outra empresa. A Tidewater e a Skiff, no Passo 7 (Sistemas multimarca e multiproduto).

A Atlassian junta tudo numa ideia só: "Light mode, dark mode, and high-contrast mode are all examples of theming" (modo claro, modo escuro e alto contraste são todos exemplos de tema), e "non-color themes are also possible: think cozy/comfortable/compact views, reduced motion, or custom typography styles" (também existem temas que não são de cor: visões aconchegante, confortável ou compacta, movimento reduzido, estilos de tipografia próprios) (Atlassian, Design tokens). O Carbon tem quatro temas de cor, White, Gray 10, Gray 90 e Gray 100, e a regra dele é a que vale lembrar: "Each theme shares the same variables and roles, with only the value changing for each individual theme" (cada tema divide as mesmas variáveis e papéis, e só o valor muda de um tema para outro) (Carbon, Themes).


2. Experimente

Modo
Densidade

Porto → Vigo · 09:40

Píer 2 · 184 de 220 passageiros com check-in

Atrasado 15 min

Fazer check-in
  • color.surface.default → color.sand.50color.ink.900
  • color.text.default → color.ink.900color.sand.50
  • color.action.primary → color.blue.600color.blue.400
  • color.feedback.danger → color.coral.600color.coral.400
  • space.inset.md → space.4 (16 px)space.3 (12 px)
  • button.primary.padding-inline → space.5 (24 px)space.4 (16 px)
  • button.primary.background → color.action.primary, em todos os modos
Um card de viagem do console da equipe, estilizado só com os tokens semânticos e de componente do Harbour. Troque o modo ou a densidade: o CSS do card nunca muda, só muda para onde os tokens apontam. A lista de tokens mostra cada ligação como está agora.CSS ao vivo: custom properties redeclaradas sob :has(:checked); as cores mudam num fade de 0,2 s, e sem fade com movimento reduzido. Demo: Marcus Andrey, CC BY 4.0.

O card nunca muda o próprio CSS. Ele lê --hb-color-surface-default, --hb-button-primary-background, --hb-space-inset-md e assim por diante. As chaves de modo e de densidade só mudam para onde esses tokens semânticos apontam. A lista ao lado do card mostra cada ligação como está agora.


3. O CSS, exatamente como roda

Esta é toda a parte de tokens da demo acima, copiada da folha de estilo dela:

.ds-a-live {
  /* primitives: raw values, never used by components directly */
  --hb-color-blue-400: #5B95DB;
  --hb-color-blue-600: #1F5FAE;
  --hb-color-sand-50: #FBF8F2;
  --hb-color-sand-300: #CFC6B6;
  --hb-color-ink-600: #4A5A69;
  --hb-color-ink-900: #14202B;
  --hb-color-coral-400: #E8735F;
  --hb-color-coral-600: #C2412D;
  --hb-space-2: 8px;
  --hb-space-3: 12px;
  --hb-space-4: 16px;
  --hb-space-5: 24px;
  --hb-radius-md: 8px;

  /* semantic: light mode and comfortable density are the defaults */
  --hb-color-surface-default: var(--hb-color-sand-50);
  --hb-color-text-default: var(--hb-color-ink-900);
  --hb-color-text-subtle: var(--hb-color-ink-600);
  --hb-color-action-primary: var(--hb-color-blue-600);
  --hb-color-text-on-action: var(--hb-color-sand-50);
  --hb-color-feedback-danger: var(--hb-color-coral-600);
  --hb-space-inset-md: var(--hb-space-4);
  --hb-radius-control: var(--hb-radius-md);

  /* component: points at semantic tokens only */
  --hb-button-primary-background: var(--hb-color-action-primary);
  --hb-button-primary-padding-inline: var(--hb-space-5);
}

/* dark mode: only semantic tokens change, components follow */
.ds-a-live:has([value="dark"]:checked) {
  --hb-color-surface-default: var(--hb-color-ink-900);
  --hb-color-text-default: var(--hb-color-sand-50);
  --hb-color-text-subtle: var(--hb-color-sand-300);
  --hb-color-action-primary: var(--hb-color-blue-400);
  --hb-color-text-on-action: var(--hb-color-ink-900);
  --hb-color-feedback-danger: var(--hb-color-coral-400);
}

/* compact density, for the staff console */
.ds-a-live:has([value="compact"]:checked) {
  --hb-space-inset-md: var(--hb-space-3);
  --hb-button-primary-padding-inline: var(--hb-space-4);
}

/* the card only ever reads semantic and component tokens */
.ds-a-card {
  padding: var(--hb-space-inset-md);
  border-radius: var(--hb-radius-control);
  background: var(--hb-color-surface-default);
  color: var(--hb-color-text-default);
}
.ds-a-card__meta { color: var(--hb-color-text-subtle); }
.ds-a-card__late { color: var(--hb-color-feedback-danger); }
.ds-a-card__btn {
  padding-block: var(--hb-space-2);
  padding-inline: var(--hb-button-primary-padding-inline);
  border-radius: var(--hb-radius-control);
  background: var(--hb-button-primary-background);
  color: var(--hb-color-text-on-action);
}

Três coisas para notar:

  • Só tokens semânticos aparecem nos blocos de modo. Os primitivos nunca mudam; os tokens de componente nunca mudam. O modo escuro tem seis linhas; a densidade compacta, duas.
  • As duas chaves são independentes. O modo só mexe na cor; a densidade só mexe no espaço. Por isso escuro mais compacto funciona sem um quarto bloco. Mantenha os seus eixos separados assim, ou as combinações se multiplicam.
  • Os aliases são declarados no mesmo elemento da chave. No CSS, uma custom property que diz var(--hb-color-action-primary) é resolvida no elemento onde foi declarada. Se --hb-button-primary-background estivesse no :root e o modo escuro reapontasse --hb-color-action-primary só num filho, o botão ficaria com o azul do claro. Declare a corrente inteira onde o modo é definido, ou mais abaixo (MDN, Using CSS custom properties).

A demo troca com :has(:checked) porque é uma lição (MDN, :has()). Num produto, você colocaria os mesmos blocos no :root, escolhidos pela configuração do sistema e por uma escolha que a pessoa salva:

@media (prefers-color-scheme: dark) {
  :root:not([data-mode="light"]) { /* the dark block */ }
}
:root[data-mode="dark"] { /* the dark block */ }

O CSS também tem o light-dark(), que escolhe entre dois valores conforme o esquema de cores em uso, depois que color-scheme: light dark está definido; o MDN lista ele como Baseline 2024 (MDN, light-dark()). Ele é prático para dois modos, mas só resolve claro e escuro; para densidade e marcas você continua precisando de reapontar os tokens.


4. O modo escuro é medido, não invertido

O modo escuro do Harbour não é "trocar o preto pelo branco". Cada par semântico foi medido de novo (Cor, tipografia e espaçamento como tokens):

  • color.action.primary vai de blue.600 para blue.400, porque blue.600 sobre a superfície escura dá só 2,6 para 1. O blue.400 dá 5,3 para 1.
  • color.text.on-action troca de areia para tinta, porque um rótulo claro sobre um azul mais claro reprovaria.
  • color.feedback.danger vai de coral.600 para coral.400: 5,5 para 1 sobre a superfície escura.

A superfície também não é preto puro: ink.900 é um azul muito escuro que mantém a sensação da marca. As imagens precisam de cuidado próprio no modo escuro; veja Imagens no modo escuro.

Respeite a configuração do sistema por padrão (MDN, prefers-color-scheme), e deixe a pessoa mudar. Quem trabalha no turno da noite do porto pode querer o escuro mesmo que o computador compartilhado esteja no claro.


5. A mesma ideia no Figma e no formato de tokens

As variáveis do Figma guardam um valor por modo: "each mode stores one value per variable" (cada modo guarda um valor por variável). As camadas ficam em Auto por padrão e "take on the mode of their parent container" (assumem o modo do contêiner pai), então você define Dark num frame e tudo dentro acompanha. Se nenhum pai define um modo, os objetos voltam ao padrão da coleção, o modo mais à esquerda (Figma Help, Modes for variables). Coloque claro e escuro numa coleção Semantic, e confortável e compacto numa coleção Density separada, para os eixos ficarem independentes, igual ao CSS.

O Resolver Module 2025.10 do DTCG descreve "a method to work with design tokens in multiple contexts (such as "light mode" and "dark mode" color themes)" (um método para trabalhar com tokens em vários contextos, como os temas de cor claro e escuro). Ele avisa que esses contextos "are susceptible to combinatorial explosion" (estão sujeitos a uma explosão de combinações), e resolve isso com modifiers (modificadores): cada um, como mode ou density, tem os próprios contextos e arquivos, combinados em ordem (DTCG, Resolver Module 2025.10). A mesma ideia de novo: eixos separados, um conjunto de nomes.


6. Erros comuns

  • Componentes com estilos próprios de modo escuro, fora dos tokens.
  • Inverter as cores e chamar isso de modo escuro, sem medir.
  • Misturar eixos: um modo "escuro-compacto", depois "escuro-confortável", depois "claro-compacto"…
  • Ignorar a configuração do sistema, ou não deixar a pessoa mudar.
  • Declarar os aliases no :root e trocar o modo mais abaixo, e a corrente não atualiza.

7. Vocabulário

Termo Significado
Modo Um contexto com valores próprios de token, como claro, escuro ou alto contraste
Densidade Um contexto de espaçamento, como confortável ou compacto
Tema Um conjunto completo de valores para um produto ou uma marca
Eixo Um tipo independente de modo: modo de cor, densidade, marca
Modifier O nome que o resolver do DTCG dá a um eixo, com um contexto por valor
prefers-color-scheme A media feature do CSS que lê a configuração de claro ou escuro do sistema

8. Experimente (sem ferramentas)

  1. Na demo, ligue o escuro e o compacto juntos. Anote cada token que mudou.
  2. Agora imagine um modo de alto contraste. Quais tokens semânticos ele reapontaria? Ele mexeria no espaçamento?
  3. Esboce o bloco de CSS extra de que ele precisaria, usando só tokens semânticos.

Perguntas para refletir: Quantas linhas o seu produto de hoje precisaria mudar para ter modo escuro? O que esse número diz sobre os níveis dele?


9. Se você já pratica

  • Conte quantos tokens cada modo reaponta. Se são centenas, o seu nível semântico provavelmente está fino demais, ou os seus componentes leem primitivos.
  • Gere capturas das telas principais em cada combinação de modos na integração contínua, para um par quebrado aparecer na revisão.
  • Guarde a escolha da pessoa, aplique antes da primeira pintura da tela, e teste a troca com leitor de tela: nada deve ser anunciado como alterado além da própria configuração.

Checklist

Para saber mais

Livros, cursos e vídeos para ir mais fundo

Os links dos livros são de afiliado da Amazon: como associado, recebo por compras qualificadas, sem custo a mais para você.

Relacionadas

Níveis de tokens · Cor, tipografia e espaçamento como tokens · Tokens do Figma ao código · Monte um conjunto de tokens com modos · Imagens no modo escuro · Sistemas multimarca e multiproduto · Cor e contraste

Salvo só neste dispositivo.

↑ ↓ para mover · Enter para abrir · Esc para fechar