Design System Starter

Design System Starter

Construa sistemas de design robustos e escaláveis que garantem consistência visual e experiências de usuário excepcionais.

Início Rápido

Basta descrever o que você precisa:

Create a design system for my React app with dark mode support

É só isso. A skill fornece tokens, componentes e diretrizes de acessibilidade.

Gatilhos

Referência Rápida

Recursos Inclusos

• references/component-examples.md - Implementações completas de componentes
• templates/design-tokens-template.json - Formato W3C para design tokens
• templates/component-template.tsx - Template de componente React
• checklists/design-system-checklist.md - Checklist de auditoria do sistema de design

Filosofia do Sistema de Design

O que é um Sistema de Design?

Um sistema de design é mais do que uma biblioteca de componentes—é uma coleção de:

1. Design Tokens: Decisões de design fundamentais (cores, espaçamento, tipografia)
2. Componentes: Blocos de construção reutilizáveis de UI
3. Padrões: Soluções e composições comuns de UX
4. Diretrizes: Regras, princípios e boas práticas
5. Documentação: Como usar tudo de forma eficaz

Princípios Fundamentais

1. Consistência Acima de Criatividade

• Padrões previsíveis reduzem carga cognitiva
• Usuários aprendem uma vez, aplicam em todos os lugares
• Designers e desenvolvedores falam a mesma linguagem

2. Acessibilidade por Padrão

• Conformidade WCAG 2.1 Nível AA mínimo
• Navegação por teclado integrada
• Suporte a leitura de tela desde o início

3. Escalável e Mantível

• Design tokens permitem mudanças globais
• Composição de componentes reduz duplicação
• Estratégias de versionamento e descontinuação

4. Amigável a Desenvolvedores

• Contratos de API claros
• Documentação abrangente
• Fácil de integrar e personalizar

Design Tokens

Design tokens são as decisões de design atômicas que definem a linguagem visual do seu sistema.

Categorias de Tokens

1. Tokens de Cor

Cores Primitivas (Valores brutos):

{
  "color": {
    "primitive": {
      "blue": {
        "50": "#eff6ff",
        "100": "#dbeafe",
        "200": "#bfdbfe",
        "300": "#93c5fd",
        "400": "#60a5fa",
        "500": "#3b82f6",
        "600": "#2563eb",
        "700": "#1d4ed8",
        "800": "#1e40af",
        "900": "#1e3a8a",
        "950": "#172554"
      }
    }
  }
}

Cores Semânticas (Significado contextual):

{
  "color": {
    "semantic": {
      "brand": {
        "primary": "{color.primitive.blue.600}",
        "primary-hover": "{color.primitive.blue.700}",
        "primary-active": "{color.primitive.blue.800}"
      },
      "text": {
        "primary": "{color.primitive.gray.900}",
        "secondary": "{color.primitive.gray.600}",
        "tertiary": "{color.primitive.gray.500}",
        "disabled": "{color.primitive.gray.400}",
        "inverse": "{color.primitive.white}"
      },
      "background": {
        "primary": "{color.primitive.white}",
        "secondary": "{color.primitive.gray.50}",
        "tertiary": "{color.primitive.gray.100}"
      },
      "feedback": {
        "success": "{color.primitive.green.600}",
        "warning": "{color.primitive.yellow.600}",
        "error": "{color.primitive.red.600}",
        "info": "{color.primitive.blue.600}"
      }
    }
  }
}

Acessibilidade: Garanta que as proporções de contraste de cor atendam ao WCAG 2.1 Nível AA:

• Texto normal: mínimo 4.5:1
• Texto grande (18pt+ ou 14pt+ negrito): mínimo 3:1
• Componentes UI e gráficos: mínimo 3:1

2. Tokens de Tipografia

{
  "typography": {
    "fontFamily": {
      "sans": "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
      "serif": "'Georgia', 'Times New Roman', serif",
      "mono": "'Fira Code', 'Courier New', monospace"
    },
    "fontSize": {
      "xs": "0.75rem",     // 12px
      "sm": "0.875rem",    // 14px
      "base": "1rem",      // 16px
      "lg": "1.125rem",    // 18px
      "xl": "1.25rem",     // 20px
      "2xl": "1.5rem",     // 24px
      "3xl": "1.875rem",   // 30px
      "4xl": "2.25rem",    // 36px
      "5xl": "3rem"        // 48px
    },
    "fontWeight": {
      "normal": 400,
      "medium": 500,
      "semibold": 600,
      "bold": 700
    },
    "lineHeight": {
      "tight": 1.25,
      "normal": 1.5,
      "relaxed": 1.75,
      "loose": 2
    },
    "letterSpacing": {
      "tight": "-0.025em",
      "normal": "0",
      "wide": "0.025em"
    }
  }
}

3. Tokens de Espaçamento

Escala: Use uma escala de espaçamento consistente (geralmente base de 4px ou 8px)

{
  "spacing": {
    "0": "0",
    "1": "0.25rem",   // 4px
    "2": "0.5rem",    // 8px
    "3": "0.75rem",   // 12px
    "4": "1rem",      // 16px
    "5": "1.25rem",   // 20px
    "6": "1.5rem",    // 24px
    "8": "2rem",      // 32px
    "10": "2.5rem",   // 40px
    "12": "3rem",     // 48px
    "16": "4rem",     // 64px
    "20": "5rem",     // 80px
    "24": "6rem"      // 96px
  }
}

Espaçamento Específico de Componentes:

{
  "component": {
    "button": {
      "padding-x": "{spacing.4}",
      "padding-y": "{spacing.2}",
      "gap": "{spacing.2}"
    },
    "card": {
      "padding": "{spacing.6}",
      "gap": "{spacing.4}"
    }
  }
}

4. Tokens de Border Radius

{
  "borderRadius": {
    "none": "0",
    "sm": "0.125rem",   // 2px
    "base": "0.25rem",  // 4px
    "md": "0.375rem",   // 6px
    "lg": "0.5rem",     // 8px
    "xl": "0.75rem",    // 12px
    "2xl": "1rem",      // 16px
    "full": "9999px"
  }
}

5. Tokens de Sombra

{
  "shadow": {
    "xs": "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
    "sm": "0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1)",
    "base": "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)",
    "md": "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)",
    "lg": "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)",
    "xl": "0 25px 50px -12px rgba(0, 0, 0, 0.25)"
  }
}

Arquitetura de Componentes

Metodologia de Design Atômico

Átomos → Moléculas → Organismos → Templates → Páginas

Átomos (Componentes Primitivos)

Blocos de construção básicos que não podem ser decompostos.

Exemplos:

• Button
• Input
• Label
• Icon
• Badge
• Avatar

Componente Button:

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  icon?: React.ReactNode;
  children: React.ReactNode;
}

Veja references/component-examples.md para implementação completa do Button com variantes, tamanhos e padrões de estilo.

Moléculas (Composições Simples)

Grupos de átomos que funcionam juntos.

Exemplos:

• SearchBar (Input + Button)
• FormField (Label + Input + ErrorMessage)
• Card (Container + Title + Content + Actions)

Molécula FormField:

interface FormFieldProps {
  label: string;
  name: string;
  error?: string;
  hint?: string;
  required?: boolean;
  children: React.ReactNode;
}

Veja references/component-examples.md para FormField, Card (padrão de componente composto), Input com variantes, Modal e mais exemplos de composição.

Organismos (Composições Complexas)

Componentes UI complexos compostos por moléculas e átomos.

Exemplos:

• Navigation Bar
• Product Card Grid
• User Profile Section
• Modal Dialog

Templates (Layouts de Página)

Estruturas no nível da página que definem a colocação de conteúdo.

Exemplos:

• Dashboard Layout (Sidebar + Header + Main Content)
• Marketing Page Layout (Hero + Features + Footer)
• Settings Page Layout (Tabs + Content Panels)

Páginas (Instâncias Específicas)

Páginas reais com conteúdo real.

Design de API de Componentes

Boas Práticas de Props

1. Nomes de Props Previsíveis

// ✅ Bom: Nomenclatura consistente
<Button variant="primary" size="md" />
<Input variant="outlined" size="md" />

// ❌ Ruim: Inconsistente
<Button type="primary" sizeMode="md" />
<Input style="outlined" inputSize="md" />

2. Defaults Sensatos

// ✅ Bom: Fornece defaults
interface ButtonProps {
  variant?: 'primary' | 'secondary';  // Default: primary
  size?: 'sm' | 'md' | 'lg';          // Default: md
}

// ❌ Ruim: Tudo obrigatório
interface ButtonProps {
  variant: 'primary' | 'secondary';
  size: 'sm' | 'md' | 'lg';
  color: string;
  padding: string;
}

3. Composição Sobre Configuração

// ✅ Bom: Componível
<Card>
  <Card.Header>
    <Card.Title>Title</Card.Title>
  </Card.Header>
  <Card.Body>Content</Card.Body>
  <Card.Footer>Actions</Card.Footer>
</Card>

// ❌ Ruim: Props demais
<Card
  title="Title"
  content="Content"
  footerContent="Actions"
  hasHeader={true}
  hasFooter={true}
/>

4. Componentes Polimórficos Permita que componentes sejam renderizados como diferentes elementos HTML:

<Button as="a" href="/login">Login</Button>
<Button as="button" Me</Button>

Veja references/component-examples.md para padrões completos de componentes polimórficos em TypeScript.

Temas e Dark Mode

Estrutura de Tema

interface Theme {
  colors: {
    brand: {
      primary: string;
      secondary: string;
    };
    text: {
      primary: string;
      secondary: string;
    };
    background: {
      primary: string;
      secondary: string;
    };
    feedback: {
      success: string;
      warning: string;
      error: string;
      info: string;
    };
  };
  typography: {
    fontFamily: {
      sans: string;
      mono: string;
    };
    fontSize: Record<string, string>;
  };
  spacing: Record<string, string>;
  borderRadius: Record<string, string>;
  shadow: Record<string, string>;
}

Implementação de Dark Mode

Abordagem 1: CSS Variables

:root {
  --color-bg-primary: #ffffff;
  --color-text-primary: #000000;
}

[data-theme="dark"] {
  --color-bg-primary: #1a1a1a;
  --color-text-primary: #ffffff;
}

Abordagem 2: Tailwind CSS Dark Mode

<div className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
  Content
</div>

Abordagem 3: Styled Components ThemeProvider

const lightTheme = { background: '#fff', text: '#000' };
const darkTheme = { background: '#000', text: '#fff' };

<ThemeProvider theme={isDark ? darkTheme : lightTheme}>
  <App />
</ThemeProvider>

Diretrizes de Acessibilidade

Conformidade WCAG 2.1 Nível AA

Contraste de Cor

• Texto normal (< 18pt): mínimo 4.5:1
• Texto grande (≥ 18pt ou ≥ 14pt negrito): mínimo 3:1
• Componentes UI: mínimo 3:1

Ferramentas: Use verificadores de contraste como WebAIM Contrast Checker

Navegação por Teclado

// ✅ Todos os elementos interativos devem ser acessíveis por teclado
<button
 
  => e.key === 'Enter' && handleClick()}
>
  Click me
</button>

// ✅ Gerenciamento de foco
<Modal>
  <FocusTrap>
    {/* Modal content */}
  </FocusTrap>
</Modal>

Atributos ARIA

Padrões ARIA essenciais:

• aria-label: Forneça nomes acessíveis
• aria-expanded: Comunique estado expandido/recolhido
• aria-controls: Associe controles com conteúdo
• aria-live: Anuncie mudanças de conteúdo dinâmico

Suporte a Leitor de Tela

• Use elementos HTML semânticos (<button>, <nav>, <main>)
• Evite div/span sem semântica para elementos interativos
• Forneça labels significativos para todos os controles

Veja references/component-examples.md para exemplos completos de acessibilidade incluindo Skip Links, focus traps e padrões ARIA.

Padrões de Documentação

Template de Documentação de Componente

Cada componente deve documentar:

• Propósito: O que o componente faz
• Uso: Instrução de importação e exemplo básico
• Variantes: Estilos visuais disponíveis
• Props: Tabela completa de props com tipos, defaults, descrições
• Acessibilidade: Suporte a teclado, atributos ARIA, comportamento de leitor de tela
• Exemplos: Casos de uso comuns com código

Use Storybook, Docusaurus ou ferramentas similares para documentação interativa.

Veja templates/component-template.tsx para a estrutura padrão de componente.

Workflow do Sistema de Design

1. Fase de Design

• Auditoria de padrões existentes: Identifique inconsistências
• Defina design tokens: Cores, tipografia, espaçamento
• Crie inventário de componentes: Liste todos os componentes necessários
• Design no Figma: Crie biblioteca de componentes

2. Fase de Desenvolvimento

• Configure ferramentas: Storybook, TypeScript, testes
• Implemente tokens: CSS variables ou configuração de tema
• Construa átomos primeiro: Comece com primitivos
• Compose para cima: Construa moléculas, organismos
• Documente conforme avança: Escreva docs junto com código

3. Fase de Adoção

• Crie guia de migração: Ajude times a adotar
• Forneça codemods: Automatize migrações quando possível
• Execute workshops: Treine times sobre uso
• Colete feedback: Itere com base em uso real

4. Fase de Manutenção

• Versionamento semântico: Releases major/minor/patch
• Estratégia de descontinuação: Descontinue componentes antigos com elegância
• Changelog: Documente todas as mudanças
• Monitore adoção: Acompanhe uso em todos os produtos

Checklist de Início Rápido

Ao criar um novo sistema de design:

• Defina princípios e valores de design
• Estabeleça estrutura de design tokens (cores, tipografia, espaçamento)
• Crie paleta de cor primitiva (escala 50-950)
• Defina tokens de cor semântica (brand, text, background, feedback)
• Estabeleça escala de tipografia e famílias de fontes
• Estabeleça escala de espaçamento (base 4px ou 8px)
• Design de componentes atômicos (Button, Input, Label, etc.)
• Implemente sistema de tema (light/dark mode)
• Garanta conformidade WCAG 2.1 Nível AA
• Configure documentação (Storybook ou similar)
• Crie exemplos de uso para cada componente
• Estabeleça estratégia de versionamento e release
• Crie guias de migração para times que adotam