1.1 As definições que confundem

1.2 As partes de um design system

• Fundamentos / tokens: cor, tipografia, espaçamento, grade, raios, sombras, motion, z-index — as decisões atômicas (Módulos 2–3).
• Componentes: botão, campo, modal, tabela… em design e código, com a mesma API e o mesmo comportamento (Módulo 6).
• Padrões (patterns): composições recorrentes — formulário, página de detalhe, estado vazio, paginação, fluxo de confirmação destrutiva.
• Guidelines: conteúdo/UX writing, acessibilidade, uso de cor, do's & don'ts.
• Ferramentas: site de documentação, Storybook, plugins de lint, o pipeline de tokens.
• Governança: time, processo de contribuição, versionamento, suporte, medição.

1.3 Por que existe

• Consistência: a mesma coisa parece e se comporta igual em todo lugar — confiança do usuário, menos carga cognitiva.
• Velocidade: não redesenhar/reimplementar um botão a cada tela; times focam no problema do produto.
• Qualidade: acessibilidade, estados, responsivo e edge cases resolvidos uma vez, bem.
• Escala: muitos produtos, plataformas e times sem divergir.
• Manutenção: mudar a cor de marca ou o raio padrão em um lugar, não em 400.

1.4 Quando NÃO fazer (ou adiar)

Um produto único, pequeno, em fase de descoberta, com um time — um design system formal é custo sem retorno. Comece com uma escala de tokens e alguns componentes compartilhados; invista em sistema quando há múltiplos produtos/times e a divergência já dói. Design system é resposta a um problema de escala, não um troféu.

2.1 O que é um token

Um design token é uma decisão de design nomeada, guardada como dado, e não como valor solto no código. Em vez de #0E7C6B espalhado, você tem color.action.default = #0E7C6B. O nome carrega a intenção; o valor pode mudar (tema, marca, plataforma) sem tocar em quem o usa.

Tokens são a menor unidade compartilhável de um design system e a peça que viaja melhor entre plataformas: o mesmo space.4 vira 1rem na web, 16pt no iOS, 16dp no Android.

2.2 Formato: nome, valor, tipo

// spec do Design Tokens Community Group (W3C DTCG) — arquivo .tokens.json
{
  "color": {
    "brand": {
      "$type": "color",
      "500": { "$value": "#0E7C6B" },
      "600": { "$value": "#0A5A4E" }
    }
  },
  "space": {
    "$type": "dimension",
    "4": { "$value": "16px" }
  },
  "radius": {
    "$type": "dimension",
    "2": { "$value": "8px" }
  }
}

• $value: o valor bruto ou uma referência a outro token ("{color.brand.500}").
• $type: color, dimension, fontFamily, fontWeight, duration, cubicBezier, number, shadow, typography, border, gradient, transition… (a spec define o conjunto).
• $description: para que serve — vira documentação.

2.3 Tokens compostos (composite)

{
  "typography": {
    "heading-1": {
      "$type": "typography",
      "$value": {
        "fontFamily": "{font.family.sans}",
        "fontSize": "{font.size.800}",
        "fontWeight": "{font.weight.bold}",
        "lineHeight": "1.15",
        "letterSpacing": "-0.02em"
      }
    }
  },
  "shadow": {
    "raised": {
      "$type": "shadow",
      "$value": { "offsetX": "0", "offsetY": "1px", "blur": "3px", "spread": "0", "color": "#0000001f" }
    }
  }
}

Compostos agrupam vários valores numa decisão só (um "estilo de texto", uma "elevação") — o mesmo conceito de "type style" da apostila Tipografia.

2.4 Por que a spec importa

Antes do DTCG, cada ferramenta tinha seu formato e a interoperabilidade era zero. A spec do W3C dá um formato comum (.tokens.json) que Figma, Style Dictionary, Tokens Studio, Storybook e afins podem ler e escrever — o token deixa de ser refém de uma ferramenta. Ainda está evoluindo; acompanhe.

3.1 As camadas

/* PRIMITIVO */
--blue-500: oklch(64% 0.17 254);
--gray-900: oklch(22% 0.012 260);
--space-4: 1rem;

/* SEMÂNTICO — os componentes usam SÓ estes */
--color-action: var(--blue-500);
--color-text: var(--gray-900);
--space-inset-md: var(--space-4);

/* COMPONENTE (opcional) — quando um componente precisa desviar do semântico */
--button-primary-bg: var(--color-action);
--button-padding-x: var(--space-inset-md);

3.2 Por que componentes só consomem semânticos

• Temas funcionam: trocar dark mode / marca = redefinir a camada semântica; se o botão aponta para blue-500 direto, ele não acompanha.
• Intenção fica explícita: color-action diz por que aquela cor está ali; blue-500 não.
• Refatorar é seguro: mudar qual primitivo o semântico aponta não quebra nada a jusante.

3.3 Quando criar tokens de componente

Só quando um componente precisa legitimamente desviar do semântico ou quando expor um "gancho" de customização é o objetivo (theming por componente). Criar button.text.color = color.text.on-action só para "ter simetria" incha o sistema. Regra: comece sem a camada de componente; adicione um token só quando a dor aparece.

3.4 Nomenclatura

• Primitivos por escala (blue-500, space-4) — descritivo, sem uso.
• Semânticos por papel, num padrão consistente: categoria.papel.variante.estado → color.text.muted, color.border.focus, color.bg.danger.subtle.
• Evite números em semânticos (color-text-2 não diz nada); evite acoplar ao valor (color-action-blue mente quando a marca vira roxa).
• Documente o padrão de nomes — é o contrato mais usado do sistema.

4.1 Um tema é a camada semântica trocada

Se a arquitetura de token estiver certa (Módulo 3), um tema é só outro conjunto de valores para os mesmos nomes semânticos. Os primitivos podem até ser os mesmos; o que muda é para onde color.surface, color.text, color.action apontam.

:root{                                   /* tema claro (default) */
  --color-surface: var(--gray-50);
  --color-text: var(--gray-900);
  --color-action: var(--blue-600);
}
[data-theme="dark"]{
  --color-surface: var(--gray-950);
  --color-text: var(--gray-50);
  --color-action: var(--blue-400);      /* +L, -C no escuro */
}
@media (prefers-color-scheme: dark){
  :root:not([data-theme="light"]){ /* mesmos overrides do dark */ }
}

4.2 Modos independentes

• Aparência (light/dark) e densidade (confortável/compacto) e contraste (normal/alto) são eixos ortogonais — combináveis. Modele cada um como um conjunto de overrides próprio, aplicável por atributo/classe num escopo.
• Densidade: um --density que multiplica a escala de espaçamento e reduz alturas de linha (ver Layout, Grade & Espaçamento).
• @media (prefers-contrast: more) e (forced-colors: active): ofereça a variante de alto contraste e teste o modo do SO (ver Acessibilidade Digital & WCAG).

4.3 Multi-brand / white-label

• Cada marca é um token set que sobrescreve os semânticos (e às vezes alguns primitivos: a paleta de marca, a fonte).
• Padrão robusto: o cliente fornece poucas entradas (cor de marca, talvez a fonte e o raio) e o sistema deriva o resto — rampa via OKLCH, estados, semânticas (ver Cor, Módulo 7).
• Fixe as semânticas de status — o cliente não pode tornar "erro" verde.
• Valide contraste automaticamente para qualquer entrada e ajuste (texto sobre a cor de marca vira preto ou branco conforme a luminosidade dela).

4.4 Onde os temas vivem em runtime

• CSS custom properties são a melhor sede: trocar tema é mudar um atributo no <html>, sem rebuild, sem recarregar, com transição possível.
• Evite gerar um CSS por tema e trocar o arquivo (flash, cache, mais bytes). Um CSS com os blocos de override é mais simples.
• Persistir a escolha do usuário (localStorage) + respeitar prefers-color-scheme como default + evitar o "flash" de tema errado (script inline no <head>).

5.1 O problema

Você tem os tokens em .tokens.json. Precisa deles como: CSS custom properties (web), objeto JS/TS (para lógica e RN), .xml/Compose (Android), .swift/asset catalog (iOS), variáveis do Figma. Mantê-los à mão em 5 formatos = divergência garantida. A resposta é uma fonte, muitas saídas, geradas.

5.2 Style Dictionary

// style-dictionary config (resumo)
{
  "source": ["tokens/**/*.tokens.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "dist/css/",
      "files": [{ "destination": "tokens.css", "format": "css/variables",
                  "options": { "outputReferences": true } }]
    },
    "ts": {
      "transformGroup": "js",
      "buildPath": "dist/ts/",
      "files": [{ "destination": "tokens.ts", "format": "javascript/es6" }]
    },
    "android": { "transformGroup": "android", "buildPath": "dist/android/",
      "files": [{ "destination": "tokens.xml", "format": "android/resources" }] }
  }
}

• Parsers leem o formato DTCG; transforms convertem valores (16px → 16.00dp, #RRGGBBAA → UIColor, nome color.text.muted → --color-text-muted / colorTextMuted); formats montam o arquivo final.
• outputReferences: preserva var(--blue-500) em vez de "achatar" para o hex — mantém a cascata e o tema no CSS gerado.
• Compostos (typography, shadow) têm formats próprios ou transforms custom.

5.3 Tokens Studio

Plugin do Figma para criar e editar tokens dentro do Figma (com temas/sets), exportando o JSON DTCG para o repositório. Fecha o loop "designer edita token → PR → pipeline gera código". Alternativa/complemento: as Variables nativas do Figma (Módulo 8).

5.4 O build no CI

• O repositório de tokens roda o pipeline a cada PR: valida o JSON (schema DTCG), checa referências quebradas e ciclos, roda testes de contraste nos pares semânticos, gera as saídas e publica um pacote versionado.
• Os produtos consomem o pacote (@empresa/tokens) por versão — não copiam arquivos.

5.5 Versionamento

• SemVer: patch = ajuste de valor sem mudança perceptível/renome; minor = token novo; major = remoção/renome de token ou mudança de valor com impacto visual grande.
• Changelog humano por versão; codemods/mapa de renome para majors.
• Deprecação antes de remover: marcar $deprecated, manter um release, avisar.

6.1 Anatomia e API

• Anatomia: as partes nomeadas (um Button tem: container, label, ícone opcional à esquerda/direita, spinner de loading). O mesmo mapa de partes existe no design e no código.
• Props / API: poucas, ortogonais, previsíveis. Para o Button: variant (primary/secondary/ghost/danger), size (sm/md/lg), state derivado (hover/active/focus/disabled/loading), iconStart/iconEnd, fullWidth.
• Configuração vs composição: props para o que é finito e padronizado (variant, size); slots/children para o que varia livremente (o conteúdo de um Card, as ações de um Dialog). Evite a "prop explosion".

6.2 Variantes, tamanhos, estados

• Defina a matriz: variant × size × state. Nem toda célula precisa existir, mas as que existem são especificadas (tokens de cada parte em cada combinação).
• Estados obrigatórios em todo componente interativo: default, hover, active/pressed, focus-visible, disabled, e quando aplicável loading, error, selected, read-only.
• Estados são derivados de tokens semânticos (ex.: hover = color.action −8% L), não cores novas à mão.

6.3 Acessibilidade embutida

• O componente já vem acessível: papel/ARIA correto, foco visível e gerenciado, navegação por teclado, aria-label/associações, respeito a prefers-reduced-motion, alvo de toque ≥ 24–44px.
• Padrões complexos (menu, combobox, dialog, tabs) seguem o APG (ARIA Authoring Practices) — não reinvente.
• Isso é metade do valor de um design system: acessibilidade resolvida uma vez, bem. Ver Acessibilidade Digital & WCAG.

6.4 Headless + estilo

Separar comportamento/acessibilidade (headless: Radix, React Aria, Ark, Headless UI) do estilo (seus tokens) é o padrão atual: você herda anos de edge cases de teclado/ARIA e aplica a sua skin. Para multi-framework, um core headless em Web Components ou lógica compartilhada + camadas finas por framework.

6.5 Documentação do componente

• Visão geral: o que é, quando usar, quando não usar (e o que usar no lugar).
• Anatomia ilustrada; props tabeladas; variantes/estados renderizados (Storybook).
• Do's & don'ts visuais; acessibilidade (o que o componente garante e o que cabe a quem usa); conteúdo (como escrever o label).
• Código e design lado a lado; link para o componente no Figma (Code Connect — Módulo 8).

7.1 Modelos de time

7.2 "Resolvido, não resolvido, não vamos resolver"

Todo elemento do sistema tem um status explícito: resolvido (use), em progresso (RFC aberto), não resolvido (ainda faça no produto, mas siga a convenção X), fora de escopo. Isso evita que times esperem por algo que nunca virá e que reinventem o que já existe.

7.3 O processo de contribuição

• Intake: um canal único para pedidos/ideias, triados regularmente.
• RFC / proposal: problema, casos de uso, alternativas, proposta de API — revisado por design + eng + acessibilidade antes de escrever código.
• Definição de pronto: design + código + testes + a11y + docs + entrada no Figma + changelog. Um componente não "existe" sem todos.
• Revisão: checklist (tokens, estados obrigatórios, APG, responsivo, RTL, dark mode).

7.4 Breaking changes e deprecação

• Deprecar antes de remover: marcar como deprecated, manter funcionando ≥ 1 ciclo, avisar, oferecer a alternativa e um codemod.
• Major agrupa breaking changes; changelog detalhado; guia de migração; ferramentas automáticas onde possível (oasdiff-style para APIs de componente, jscodeshift para props).
• Janela de suporte: quanto tempo a versão N-1 recebe correções.

7.5 Adoção: as métricas que importam

• Cobertura: % dos componentes de UI em produção que vêm do design system (via análise estática / scanners como a "component analytics" do próprio DS).
• Adoção por produto/time ao longo do tempo; nº de detached/overrides no Figma.
• Velocidade: tempo para montar uma tela nova antes/depois; nº de bugs de a11y/visual reportados.
• Saúde: issues abertas, tempo de resposta, NPS interno do sistema.
• Essas métricas são como o time de DS justifica orçamento — trate-as como parte do produto.

8.1 Variables e modes

• Variables do Figma = tokens: tipos color, number, string, boolean; organizadas em collections; com modes (ex.: a collection "theme" tem modes Light/Dark; "density" tem Comfortable/Compact).
• Aliases: uma variable aponta para outra — as três camadas do Módulo 3 reproduzidas no Figma (primitivos numa collection, semânticos noutra que referencia a primeira).
• Aplicar um mode a um frame troca todos os valores de uma vez — o "dark mode" do protótipo.

8.2 Component properties

• Variant (a matriz variant/size/state), boolean (mostrar ícone?), instance swap (qual ícone), text (o label) — o equivalente visual das props do componente de código.
• Os nomes das properties devem bater com os nomes das props no código. variant=primary no Figma ↔ variant="primary" no React.

8.3 Bibliotecas e publicação

• O DS vive numa ou mais bibliotecas publicadas; produtos as habilitam e recebem updates com aviso de mudança.
• Versione as libs em paralelo aos pacotes de código; comunique breaking changes de componente do Figma como você comunica os do código.

8.4 Code Connect

Code Connect liga um componente do Figma ao seu componente de código real: no Dev Mode, quem for implementar vê o seu snippet (import certo, props mapeadas), não um CSS genérico. Mantém a ponte viva e reduz o "traduzi errado do design".

8.5 Divergência: o inimigo

• Sintomas: a cor no Figma não é a do CSS; um espaçamento "18" solto; um componente detached; uma variante que só existe de um lado.
• Prevenção: tokens como fonte única (Tokens Studio ou Variables exportadas para o pipeline), paridade de nomes, Code Connect, e design lint (plugins que apontam valores fora dos tokens, camadas soltas, uso de estilos locais).
• Detecção: auditorias periódicas (component analytics do Figma: quantas instâncias, quantos overrides, quantos detached por arquivo).

9.1 Multi-produto: core + extensões

• Core: tokens e componentes verdadeiramente comuns a todos os produtos.
• Camadas de produto: cada produto pode ter um conjunto de tokens semânticos e componentes próprios que estendem o core, sem forká-lo.
• Evite o "sistema que serve a todos e a ninguém": o core resolve o comum; a variação legítima mora nas camadas.

9.2 Arquitetura de token em grande escala

• Alguns sistemas usam 4 tiers: tier-0 (constantes brutas) → tier-1 (primitivos/opções) → tier-2 (semânticos/sistema) → tier-3 (componente). A profundidade extra ajuda quando há muitas marcas e plataformas; em sistemas menores, 2–3 camadas bastam — não adicione tiers por estética.
• Namespacing: empresa.core.color.action vs empresa.produtoX.color.action.
• Ferramentas de resolução de referência e detecção de ciclo tornam-se críticas.

9.3 Performance

• CSS de tokens: centenas de custom properties é barato; milhares por tema × modo × marca, todos sempre carregados, não. Carregue só os modes ativos; considere escopar.
• Componentes: tree-shaking real (imports por componente), CSS por componente, evitar um bundle monolítico.
• Medir o custo do DS no LCP/CLS/JS transferido dos produtos que o consomem.

9.4 Migração de um sistema legado

• Inventário: quantos botões diferentes existem hoje? (scanners de código e de Figma). O número costuma chocar e vender o projeto.
• Ponte: uma camada de compatibilidade (tokens antigos apontando para os novos) para migrar incremental, tela a tela, sem "big bang".
• Ordem: tokens primeiro (ganho rápido, baixo risco) → componentes de alta frequência (botão, campo, tipografia) → padrões.
• Codemods e um "modo estrito" opcional que falha o build em uso de padrão antigo.

9.5 ROI e quando parar

• Custo: o time de DS, o tempo de adoção dos produtos, a manutenção.
• Retorno: horas não gastas reimplementando, bugs de a11y/visual evitados, velocidade de novas telas, consistência (mais difícil de quantificar, mas real).
• Anti-padrões de escala: gold-plating (componentes que ninguém pede), governança tão pesada que ninguém contribui, sistema que trava a inovação dos produtos. Um DS existe para acelerar — se está freando, ajuste o escopo.

10.1 Os cargos

• Design Systems Designer: tokens, componentes no Figma, padrões, guidelines, documentação, contribuição do lado do design.
• Design Systems Engineer / Design Technologist: a biblioteca de código, o pipeline de tokens, Storybook, testes visuais, a ponte Figma↔código, performance.
• DS Product Manager / Lead: roadmap, governança, adoção, stakeholders, ROI.
• Accessibility specialist frequentemente dedicado ou muito próximo.
• Em times menores, uma pessoa acumula design + engenharia do sistema — o "design engineer".

10.2 Roadmap de estudo (6–8 semanas)

10.3 Banco de perguntas de entrevista (com a resposta que aprova)

10.4 Projetos de portfólio que geram entrevista

1. Pipeline de tokens (âncora): um .tokens.json DTCG completo → Style Dictionary → CSS + TS + (mock) mobile, com dark mode e um 2º brand só por overrides, rodando no CI, com contraste testado. README explicando a arquitetura de camadas.
2. Um componente completo cross design+código: Button ou Field com headless + tokens + todos os estados + a11y (APG) + Storybook + o mesmo componente no Figma com component properties de nomes idênticos + Code Connect.
3. Tema / white-label: um gerador que recebe uma cor de marca e deriva a paleta e os semânticos, com validação de contraste e status fixo.
4. Estudo de migração: pegar um projeto open source com CSS inconsistente, fazer o inventário (quantos botões/cores distintas), propor a camada de compatibilidade e migrar 2–3 telas, documentando o antes/depois.
5. Site de documentação: um mini-DS documentado como produto — visão geral, tokens visualizados, componentes com do's/don'ts, changelog, guia de contribuição.

10.5 Fontes para continuar

• Livros: Design Systems (Alla Kholmatova); Expressive Design Systems (Yesenia Perez-Cruz); Atomic Design (Brad Frost); Laying the Foundations (Andrew Couldwell).
• Web: designsystems.com (Figma); os artigos de Nathan Curtis / EightShapes (tokens, contribuição, medição); the-elements-of-typographic-style-applied… — e sobretudo os design systems públicos com código aberto: Polaris (Shopify), Primer (GitHub), Carbon (IBM), Spectrum (Adobe), Material, Atlassian, Base (Uber).
• Tokens: a spec do Design Tokens Community Group (W3C); a documentação do Style Dictionary e do Tokens Studio; os Figma Variables docs.
• Componentes/a11y: ARIA Authoring Practices Guide (APG); Radix Primitives, React Aria, Ark UI; Storybook docs.
• Nesta trilha: Tipografia, Cor, Layout, Grade & Espaçamento, Logótipos & Lettering; e Figma, Guia de Elementos de Interface, Acessibilidade Digital & WCAG, CSS, Tailwind CSS, Full Stack com TypeScript & Next.js.