Sistema de Design Tokens na Prática: 5 Padrões para Arquitetura Escalável de Temas e Multi-Marca

前端工程

Design Tokens: A Infraestrutura Atômica dos Sistemas de Design

O maior ponto de dor nos sistemas de design não é a falta de componentes—é a troca de tema via sobrescritas, extensões de marca via duplicação e o modo escuro via patches. Os Design Tokens abstraem decisões de design como cores, espaçamento e tipografia em pares chave-valor independentes de plataforma, permitindo "definir uma vez, consumir em qualquer lugar". Em 2026, a especificação W3C Design Token alcançou a Recomendação Candidata, Style Dictionary 4.0+ suporta saída multi-plataforma, e os Design Tokens tornaram-se a infraestrutura padrão para sistemas de design.

Este artigo percorre 5 padrões centrais, cobrindo o pipeline completo de camadas de Tokens → troca de tema → multi-marca → pipeline de build → dinâmicas em tempo de execução.

Conceitos Centrais

Conceito Descrição
Design Token Representação atômica de uma decisão de design como um par chave-valor
Token Global Valores globais brutos, ex., blue-500: #3b82f6
Token Alias Alias semântico, ex., primary: {blue-500}
Token de Componente Token em nível de componente, ex., button-primary-bg: {primary}
Tema Uma coleção de valores de tokens, ex., tema claro/escuro
Multi-Marca Um mesmo sistema de design suportando múltiplos conjuntos de tokens de marca
Style Dictionary Ferramenta de compilação de tokens com saída multi-plataforma
W3C DTCG Especificação do Design Token Community Group

Análise do Problema: 5 Desafios nos Sistemas de Design Tokens

  1. Caos nas camadas de tokens: Limites pouco claros entre camadas globais/semânticas/de componente, cadeias de referência excessivamente longas
  2. Desempenho da troca de tema: Troca de tema em tempo de execução causa flicker de repintura
  3. Extensão multi-marca: Grandes diferenças de tokens entre marcas, herança complexa
  4. Saída de build: Formatos de saída variados entre plataformas (CSS/JS/Swift/Kotlin)
  5. Colaboração de design: Designers usam Figma, desenvolvedores usam código—a sincronização de tokens é difícil

Passo a Passo: 5 Padrões de Design Tokens

Padrão 1: Arquitetura de Tokens de Três Camadas

// tokens/global/color.json
{
  "color": {
    "blue": {
      "100": { "value": "#dbeafe", "type": "color" },
      "500": { "value": "#3b82f6", "type": "color" },
      "900": { "value": "#1e3a8a", "type": "color" }
    },
    "gray": {
      "50": { "value": "#f9fafb", "type": "color" },
      "900": { "value": "#111827", "type": "color" }
    },
    "red": {
      "500": { "value": "#ef4444", "type": "color" }
    },
    "green": {
      "500": { "value": "#22c55e", "type": "color" }
    }
  }
}

// tokens/semantic/color.json
{
  "color": {
    "primary": { "value": "{color.blue.500}", "type": "color" },
    "primary-hover": { "value": "{color.blue.600}", "type": "color" },
    "background": { "value": "{color.gray.50}", "type": "color" },
    "surface": { "value": "#ffffff", "type": "color" },
    "text": { "value": "{color.gray.900}", "type": "color" },
    "text-secondary": { "value": "{color.gray.500}", "type": "color" },
    "error": { "value": "{color.red.500}", "type": "color" },
    "success": { "value": "{color.green.500}", "type": "color" },
    "border": { "value": "{color.gray.200}", "type": "color" }
  }
}

// tokens/component/button.json
{
  "button": {
    "primary": {
      "bg": { "value": "{color.primary}", "type": "color" },
      "bg-hover": { "value": "{color.primary-hover}", "type": "color" },
      "text": { "value": "#ffffff", "type": "color" },
      "border-radius": { "value": "{radius.md}", "type": "borderRadius" },
      "padding-x": { "value": "{spacing.4}", "type": "spacing" },
      "padding-y": { "value": "{spacing.2}", "type": "spacing" }
    },
    "secondary": {
      "bg": { "value": "{color.surface}", "type": "color" },
      "text": { "value": "{color.primary}", "type": "color" },
      "border": { "value": "{color.border}", "type": "color" }
    }
  }
}

Padrão 2: Troca de Tema (Claro/Escuro)

// tokens/semantic/color.dark.json
{
  "color": {
    "primary": { "value": "{color.blue.400}", "type": "color" },
    "background": { "value": "{color.gray.900}", "type": "color" },
    "surface": { "value": "#1f2937", "type": "color" },
    "text": { "value": "{color.gray.50}", "type": "color" },
    "text-secondary": { "value": "{color.gray.400}", "type": "color" },
    "border": { "value": "{color.gray.700}", "type": "color" }
  }
}

/* Saída do build: tokens.css */
:root {
  --color-primary: #3b82f6;
  --color-background: #f9fafb;
  --color-surface: #ffffff;
  --color-text: #111827;
  --color-border: #e5e7eb;
  --button-primary-bg: var(--color-primary);
  --button-primary-text: #ffffff;
}

[data-theme="dark"] {
  --color-primary: #60a5fa;
  --color-background: #111827;
  --color-surface: #1f2937;
  --color-text: #f9fafb;
  --color-border: #374151;
  --button-primary-bg: var(--color-primary);
}

// Trocador de tema
type Theme = 'light' | 'dark' | 'system';

class ThemeManager {
  private mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
  private listeners: Set<(theme: Theme) => void> = new Set();

  init() {
    const saved = localStorage.getItem('theme') as Theme | null;
    if (saved && saved !== 'system') {
      this.apply(saved);
    } else {
      this.apply(this.mediaQuery.matches ? 'dark' : 'light');
    }
    this.mediaQuery.addEventListener('change', (e) => {
      if (this.getStored() === 'system') {
        this.apply(e.matches ? 'dark' : 'light');
      }
    });
  }

  setTheme(theme: Theme) {
    localStorage.setItem('theme', theme);
    if (theme === 'system') {
      this.apply(this.mediaQuery.matches ? 'dark' : 'light');
    } else {
      this.apply(theme);
    }
    this.listeners.forEach((fn) => fn(theme));
  }

  private apply(mode: 'light' | 'dark') {
    document.documentElement.setAttribute('data-theme', mode);
  }

  private getStored(): Theme {
    return (localStorage.getItem('theme') as Theme) || 'system';
  }

  onChange(fn: (theme: Theme) => void) {
    this.listeners.add(fn);
    return () => this.listeners.delete(fn);
  }
}

Padrão 3: Herança de Tokens Multi-Marca

// brands/brand-a/tokens.json
{
  "color": {
    "primary": { "value": "#3b82f6", "type": "color", "$extensions": { "brand": "A" } },
    "primary-hover": { "value": "#2563eb", "type": "color" }
  },
  "typography": {
    "font-family": { "value": "Inter, sans-serif", "type": "fontFamily" },
    "heading-weight": { "value": "700", "type": "fontWeight" }
  },
  "radius": {
    "base": { "value": "8px", "type": "borderRadius" }
  }
}

// brands/brand-b/tokens.json
{
  "color": {
    "primary": { "value": "#8b5cf6", "type": "color", "$extensions": { "brand": "B" } },
    "primary-hover": { "value": "#7c3aed", "type": "color" }
  },
  "typography": {
    "font-family": { "value": "Poppins, sans-serif", "type": "fontFamily" },
    "heading-weight": { "value": "600", "type": "fontWeight" }
  },
  "radius": {
    "base": { "value": "4px", "type": "borderRadius" }
  }
}

// Trocador de marca
type Brand = 'brand-a' | 'brand-b';

async function switchBrand(brand: Brand) {
  const brandCSS = await fetch(`/tokens/${brand}.css`).then((r) => r.text());
  let style = document.getElementById('brand-tokens') as HTMLStyleElement;
  if (!style) {
    style = document.createElement('style');
    style.id = 'brand-tokens';
    document.head.appendChild(style);
  }
  style.textContent = brandCSS;
  document.documentElement.setAttribute('data-brand', brand);
  localStorage.setItem('brand', brand);
}

Padrão 4: Pipeline de Build do Style Dictionary

// style-dictionary.config.mjs
import StyleDictionary from 'style-dictionary';

StyleDictionary.registerTransform({
  name: 'size/pxToRem',
  type: 'value',
  matcher: (token) => token.type === 'spacing' || token.type === 'fontSize',
  transformer: (token) => {
    const base = 16;
    const val = parseFloat(token.value);
    return `${val / base}rem`;
  },
});

StyleDictionary.registerTransformGroup({
  name: 'custom/css',
  transforms: [
    'attribute/cti',
    'name/kebab',
    'time/seconds',
    'size/pxToRem',
    'color/css',
  ],
});

const config = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'custom/css',
      buildPath: 'dist/css/',
      files: [
        {
          destination: 'tokens.css',
          format: 'css/variables',
          options: { outputReferences: true },
        },
      ],
    },
    js: {
      transformGroup: 'js',
      buildPath: 'dist/js/',
      files: [
        {
          destination: 'tokens.js',
          format: 'javascript/es6',
        },
        {
          destination: 'tokens.d.ts',
          format: 'typescript/es6-declarations',
        },
      ],
    },
    json: {
      transformGroup: 'json',
      buildPath: 'dist/json/',
      files: [
        {
          destination: 'tokens.json',
          format: 'json',
        },
      ],
    },
    ios: {
      transformGroup: 'ios-swift-separate',
      buildPath: 'dist/ios/',
      files: [
        {
          destination: 'DesignTokens.swift',
          format: 'ios-swift/class.swift',
          className: 'DesignTokens',
        },
      ],
    },
    android: {
      transformGroup: 'android',
      buildPath: 'dist/android/',
      files: [
        {
          destination: 'design_tokens.xml',
          format: 'android/resources',
        },
      ],
    },
  },
};

export default config;

# Build de todas as plataformas
npx style-dictionary build

# Observar mudanças nos tokens
npx style-dictionary build --watch

Padrão 5: Tokens Dinâmicos em Tempo de Execução

// runtime-token-engine.ts
interface TokenValue {
  value: string;
  type: string;
  description?: string;
}

class RuntimeTokenEngine {
  private tokens: Map<string, TokenValue> = new Map();
  private subscribers: Map<string, Set<(value: string) => void>> = new Map();

  loadFromCSS() {
    const styles = getComputedStyle(document.documentElement);
    const allVars = Array.from(document.styleSheets)
      .flatMap((sheet) => {
        try {
          return Array.from(sheet.cssRules);
        } catch {
          return [];
        }
      })
      .filter((rule) => rule instanceof CSSStyleRule)
      .flatMap((rule: CSSStyleRule) => {
        const props: string[] = [];
        for (let i = 0; i < rule.style.length; i++) {
          const prop = rule.style[i];
          if (prop.startsWith('--')) {
            props.push(prop);
          }
        }
        return props;
      });

    const uniqueVars = [...new Set(allVars)];
    uniqueVars.forEach((v) => {
      const val = styles.getPropertyValue(v).trim();
      if (val) {
        this.tokens.set(v, { value: val, type: 'unknown' });
      }
    });
  }

  setToken(name: string, value: string) {
    const varName = name.startsWith('--') ? name : `--${name}`;
    document.documentElement.style.setProperty(varName, value);
    this.tokens.set(varName, { value, type: 'unknown' });
    this.notify(varName, value);
  }

  getToken(name: string): string | undefined {
    const varName = name.startsWith('--') ? name : `--${name}`;
    return getComputedStyle(document.documentElement)
      .getPropertyValue(varName)
      .trim();
  }

  subscribe(name: string, callback: (value: string) => void) {
    const varName = name.startsWith('--') ? name : `--${name}`;
    if (!this.subscribers.has(varName)) {
      this.subscribers.set(varName, new Set());
    }
    this.subscribers.get(varName)!.add(callback);
    return () => this.subscribers.get(varName)?.delete(callback);
  }

  private notify(name: string, value: string) {
    this.subscribers.get(name)?.forEach((fn) => fn(value));
  }
}

Guia de Armadilhas

Armadilha 1: Cadeias de Referência de Tokens Muito Profundas

// ❌ Errado: cadeia de referência de 5 camadas, difícil de depurar
{
  "btn-bg": { "value": "{button.primary.bg}" },
  "button.primary.bg": { "value": "{color.primary}" },
  "color.primary": { "value": "{blue.500}" }
}

// ✅ Correto: Manter dentro de 3 camadas
{
  "button-primary-bg": { "value": "{color.primary}" },
  "color.primary": { "value": "#3b82f6" }
}

Armadilha 2: Valores de Cor Codificados

/* ❌ Errado: Cores codificadas */
.card { background: #ffffff; border: 1px solid #e5e7eb; }

/* ✅ Correto: Usar variáveis de tokens */
.card { background: var(--color-surface); border: 1px solid var(--color-border); }

Armadilha 3: Flicker na Troca de Tema

<!-- ❌ Errado: Tema definido após o JS carregar, causando flicker -->

<!-- ✅ Correto: Script inline bloqueia a renderização -->
<script>
  (function() {
    const theme = localStorage.getItem('theme');
    if (theme === 'dark' || (!theme && matchMedia('(prefers-color-scheme: dark)').matches)) {
      document.documentElement.setAttribute('data-theme', 'dark');
    }
  })();
</script>

Armadilha 4: Uso Excessivo de Tokens de Componente

// ❌ Errado: Criar um token para cada propriedade do componente
{
  "card-padding-top": { "value": "{spacing.4}" },
  "card-padding-right": { "value": "{spacing.4}" },
  "card-padding-bottom": { "value": "{spacing.4}" },
  "card-padding-left": { "value": "{spacing.4}" }
}

// ✅ Correto: Reutilizar tokens semânticos
{
  "card-padding": { "value": "{spacing.4}" }
}

Armadilha 5: Ignorar Validação de Tipos de Tokens

// ❌ Errado: Sem validação de tipos, token de cor recebe valor de espaçamento
// ✅ Correto: Validar em tempo de build
StyleDictionary.registerFilter({
  name: 'isValidColor',
  matcher: (token) => {
    if (token.type === 'color') {
      return /^#([0-9a-f]{3}){1,2}$/i.test(token.value) ||
             token.value.startsWith('{');
    }
    return true;
  },
});

Solução de Erros

# Mensagem de Erro Causa Solução
1 Reference not found: {color.xxx} Token referencia chave inexistente Verificar ortografia do caminho de referência
2 Circular reference detected Referência circular de tokens Quebrar a cadeia de referência circular
3 Invalid token value Formato de valor de token inválido Validar formato de cor/espaçamento
4 CSS variable not applied Especificidade do selector sobrescrita Aumentar especificidade do selector de variável CSS
5 Theme flash on load Inicialização do tema após renderização Script inline bloqueante para definir o tema
6 Style Dictionary build failed Erro de formato no arquivo de tokens Verificar sintaxe JSON e $extensions
7 Token not found in output Token não correspondido pela fonte Verificar caminho glob de source
8 Platform output mismatch Regras de transformação inconsistentes Unificar configuração de transformGroup
9 Figma sync conflict Tokens do Figma dessincronizados com o código Usar Token Studio para sincronização bidirecional
10 Runtime token override fails Sobrescrita em tempo de execução sem efeito Verificar prioridade e escopo da variável CSS

Otimização Avançada

  1. Integração com Token Studio: Plugin do Figma para sincronização bidirecional de tokens design-código
  2. Versionamento de Tokens: Versionamento semântico + geração automática de changelog
  3. Tokens para Testes A/B: Troca dinâmica de tokens em tempo de execução para testes A/B visuais
  4. Token Lint: Plugin ESLint para detectar valores de design codificados no código
  5. Site de Documentação de Tokens: Documentação visual de tokens gerada automaticamente

Comparação

Dimensão Variáveis CSS Design Tokens Configuração Tailwind Tema CSS-in-JS
Suporte de Plataforma Apenas Web Web/iOS/Android Apenas Web Apenas Web
Segurança de Tipos ❌ ✅ ✅ ✅
Troca de Tema ✅ ✅ ✅ ✅
Multi-Marca Manual Suporte nativo Troca de configuração Troca de configuração
Colaboração de Design ❌ ✅ Sincronização Figma ❌ ❌
Saída de Build CSS CSS/JS/Swift/Kotlin CSS/JS JS

Resumo: Os sistemas de Design Tokens são a infraestrutura chave para evoluir os sistemas de design de "bibliotecas de componentes" para "linguagens de design". A arquitetura de tokens de três camadas (global → semântico → componente) combinada com a saída multi-plataforma do Style Dictionary estabelece uma única fonte de verdade para as decisões de design. Em 2026, a especificação W3C DTCG em amadurecimento impulsionará a padronização de tokens, tornando tokens multi-marca e dinâmicos em tempo de execução recursos padrão para sistemas de design empresariais.

Ferramentas Online Recomendadas

Experimente estas ferramentas executadas localmente no navegador — nenhum cadastro necessário →

#Design Token#设计系统#主题切换#CSS变量#2026#前端工程