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
Porto → Vigo · 09:40
Atrasado 15 min
Fazer check-incolor.→surface. default color.sand.50color.ink.900color.→text. default color.ink.900color.sand.50color.→action. primary color.blue.600color.blue.400color.→feedback. danger color.coral.600color.coral.400space.→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., em todos os modosaction. primary
: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-backgroundestivesse no:roote o modo escuro reapontasse--hb-color-action-primarysó 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.primaryvai deblue.600parablue.400, porqueblue.600sobre a superfície escura dá só 2,6 para 1. Oblue.400dá 5,3 para 1.color.text.on-actiontroca de areia para tinta, porque um rótulo claro sobre um azul mais claro reprovaria.color.feedback.dangervai decoral.600paracoral.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
:roote 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)
- Na demo, ligue o escuro e o compacto juntos. Anote cada token que mudou.
- Agora imagine um modo de alto contraste. Quais tokens semânticos ele reapontaria? Ele mexeria no espaçamento?
- 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
- MDN: Using CSS custom properties · prefers-color-scheme · light-dark() · color-scheme · :has()
- Figma Help: Modes for variables
- Design Tokens Community Group: Resolver Module 2025.10
- IBM Carbon: Themes · Atlassian: Design tokens
Livros, cursos e vídeos para ir mais fundo
- Expressive Design SystemsYesenia Perez-CruzLivro · A Book Apart, 2019 (Amazon)
- Design SystemsAlla KholmatovaLivro · Smashing Media, 2017 (Amazon)
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