Padrões de Design System

Domine a arquitetura de design system para criar bases de UI consistentes, fáceis de manter e escaláveis em aplicações web e mobile.

Quando Usar Esta Habilidade

• Criar tokens de design para cores, tipografia, espaçamento e sombras
• Implementar troca de temas claro/escuro com propriedades customizadas do CSS
• Construir sistemas de temas multi-marca
• Arquitetar bibliotecas de componentes com APIs consistentes
• Estabelecer fluxos de trabalho de design para código com tokens do Figma
• Criar hierarquias de tokens semânticos (primitivos, semânticos, de componente)
• Configurar documentação e diretrizes de design system

Capacidades Principais

1. Tokens de Design

• Tokens primitivos (valores brutos: cores, tamanhos, fontes)
• Tokens semânticos (significado contextual: text-primary, surface-elevated)
• Tokens de componente (uso específico: button-bg, card-border)
• Convenções de nomenclatura e organização de tokens
• Geração de tokens multi-plataforma (CSS, iOS, Android)

2. Infraestrutura de Temas

• Arquitetura de propriedades customizadas do CSS
• Provedores de contexto de tema em React
• Troca dinâmica de temas
• Detecção de preferência do sistema (prefers-color-scheme)
• Armazenamento persistente de temas
• Modos de movimento reduzido e alto contraste

3. Arquitetura de Componentes

• Padrões de componentes compostos
• Componentes polimórficos (prop as)
• Sistemas de variantes e tamanhos
• Composição baseada em slots
• Padrões de UI headless
• Props de estilo e variantes responsivas

4. Pipeline de Tokens

• Sincronização do Figma para código
• Configuração do Style Dictionary
• Transformação e formatação de tokens
• Integração CI/CD para atualizações de tokens

Início Rápido

// Design tokens with CSS custom properties
const tokens = {
  colors: {
    // Primitive tokens
    gray: {
      50: "#fafafa",
      100: "#f5f5f5",
      900: "#171717",
    },
    blue: {
      500: "#3b82f6",
      600: "#2563eb",
    },
  },
  // Semantic tokens (reference primitives)
  semantic: {
    light: {
      "text-primary": "var(--color-gray-900)",
      "text-secondary": "var(--color-gray-600)",
      "surface-default": "var(--color-white)",
      "surface-elevated": "var(--color-gray-50)",
      "border-default": "var(--color-gray-200)",
      "interactive-primary": "var(--color-blue-500)",
    },
    dark: {
      "text-primary": "var(--color-gray-50)",
      "text-secondary": "var(--color-gray-400)",
      "surface-default": "var(--color-gray-900)",
      "surface-elevated": "var(--color-gray-800)",
      "border-default": "var(--color-gray-700)",
      "interactive-primary": "var(--color-blue-400)",
    },
  },
};

Padrões Detalhados e Exemplos Práticos

A documentação detalhada dos padrões está em references/details.md. Leia este arquivo quando o nível de navegação acima for insuficiente.

Melhores Práticas

1. Nomeie Tokens por Propósito: Use nomes semânticos (text-primary) em vez de descrições visuais (dark-gray)
2. Mantenha a Hierarquia de Tokens: Primitivos > Semânticos > Tokens de Componente
3. Documente o Uso dos Tokens: Inclua diretrizes de uso com as definições dos tokens
4. Versionamento de Tokens: Trate mudanças em tokens como mudanças de API com semver
5. Teste Combinações de Temas: Verifique se todos os temas funcionam com todos os componentes
6. Automatize o Pipeline de Tokens: CI/CD para sincronização do Figma para código
7. Forneça Caminhos de Migração: Deprecie tokens gradualmente com alternativas claras

Problemas Comuns

• Proliferação de Tokens: Muitos tokens sem hierarquia clara
• Nomenclatura Inconsistente: Convenções mistas (camelCase vs kebab-case)
• Modo Escuro Ausente: Tokens que não se adaptam a mudanças de tema
• Valores Fixos (Hardcoded): Uso de valores brutos em vez de tokens
• Referências Circulares: Tokens se referindo uns aos outros em loops
• Lacunas de Plataforma: Tokens faltando para algumas plataformas (web, mas não mobile)