@lugom.io/hefesto 0.2.0 → 0.3.0

package/skills/hefesto-design/references/token-architecture.md

@@ -0,0 +1,394 @@
+# Arquitetura de Design Tokens — 3 Camadas
+
+## O que são tokens e por que importam
+
+Design tokens são decisões de design codificadas como variáveis. Em vez de espalhar `#2563EB` por 47 arquivos, você define uma vez e referencia sempre. Tokens são o contrato entre design e código — quando o designer muda a cor primária, o dev muda um token e tudo atualiza.
+
+Sem tokens: valores mágicos espalhados, inconsistência acumulada, dark mode impossível.
+Com tokens: fonte única de verdade, theming trivial, escala previsível.
+
+---
+
+## Camada 1: Primitivos (Core)
+
+Valores brutos e absolutos. Não expressam intenção — são a paleta completa de possibilidades. Nomeados pelo que SÃO, não pelo que FAZEM.
+
+### Convenção de nomes
+
+`--color-{hue}-{shade}` para cores, `--space-{number}` para espaçamento, `--font-{property}-{value}` para tipografia.
+
+### Exemplos completos
+
+```css
+/* ═══ Cores ═══ */
+--color-blue-50: #eff6ff;
+--color-blue-100: #dbeafe;
+--color-blue-200: #bfdbfe;
+--color-blue-300: #93c5fd;
+--color-blue-400: #60a5fa;
+--color-blue-500: #3b82f6;
+--color-blue-600: #2563eb;
+--color-blue-700: #1d4ed8;
+--color-blue-800: #1e40af;
+--color-blue-900: #1e3a8a;
+--color-blue-950: #172554;
+
+--color-gray-50: #f9fafb;
+--color-gray-100: #f3f4f6;
+--color-gray-200: #e5e7eb;
+--color-gray-300: #d1d5db;
+--color-gray-400: #9ca3af;
+--color-gray-500: #6b7280;
+--color-gray-600: #4b5563;
+--color-gray-700: #374151;
+--color-gray-800: #1f2937;
+--color-gray-900: #111827;
+--color-gray-950: #030712;
+
+--color-red-500: #ef4444;
+--color-red-600: #dc2626;
+--color-green-500: #22c55e;
+--color-green-600: #16a34a;
+--color-amber-500: #f59e0b;
+--color-white: #ffffff;
+--color-black: #000000;
+
+/* ═══ Espaçamento ═══ */
+--space-0: 0;
+--space-1: 0.25rem;   /* 4px */
+--space-2: 0.5rem;    /* 8px */
+--space-3: 0.75rem;   /* 12px */
+--space-4: 1rem;      /* 16px */
+--space-5: 1.25rem;   /* 20px */
+--space-6: 1.5rem;    /* 24px */
+--space-8: 2rem;      /* 32px */
+--space-10: 2.5rem;   /* 40px */
+--space-12: 3rem;     /* 48px */
+--space-16: 4rem;     /* 64px */
+--space-20: 5rem;     /* 80px */
+--space-24: 6rem;     /* 96px */
+
+/* ═══ Tipografia ═══ */
+--font-family-sans: 'Inter', system-ui, -apple-system, sans-serif;
+--font-family-serif: 'Lora', Georgia, serif;
+--font-family-mono: 'JetBrains Mono', 'Fira Code', monospace;
+
+--font-size-xs: 0.75rem;    /* 12px */
+--font-size-sm: 0.875rem;   /* 14px */
+--font-size-base: 1rem;     /* 16px */
+--font-size-lg: 1.125rem;   /* 18px */
+--font-size-xl: 1.25rem;    /* 20px */
+--font-size-2xl: 1.5rem;    /* 24px */
+--font-size-3xl: 1.875rem;  /* 30px */
+--font-size-4xl: 2.25rem;   /* 36px */
+--font-size-5xl: 3rem;      /* 48px */
+
+--font-weight-regular: 400;
+--font-weight-medium: 500;
+--font-weight-semibold: 600;
+--font-weight-bold: 700;
+
+--line-height-tight: 1.25;
+--line-height-normal: 1.5;
+--line-height-relaxed: 1.75;
+
+/* ═══ Bordas ═══ */
+--radius-none: 0;
+--radius-sm: 0.25rem;   /* 4px */
+--radius-md: 0.375rem;  /* 6px */
+--radius-lg: 0.5rem;    /* 8px */
+--radius-xl: 0.75rem;   /* 12px */
+--radius-2xl: 1rem;     /* 16px */
+--radius-full: 9999px;
+
+/* ═══ Sombras ═══ */
+--shadow-xs: 0 1px 2px rgba(0,0,0,0.05);
+--shadow-sm: 0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06);
+--shadow-md: 0 4px 6px rgba(0,0,0,0.1), 0 2px 4px rgba(0,0,0,0.06);
+--shadow-lg: 0 10px 15px rgba(0,0,0,0.1), 0 4px 6px rgba(0,0,0,0.05);
+--shadow-xl: 0 20px 25px rgba(0,0,0,0.1), 0 10px 10px rgba(0,0,0,0.04);
+
+/* ═══ Duração (animação) ═══ */
+--duration-fast: 100ms;
+--duration-normal: 200ms;
+--duration-slow: 300ms;
+--duration-slower: 500ms;
+
+--easing-default: cubic-bezier(0.4, 0, 0.2, 1);
+--easing-in: cubic-bezier(0.4, 0, 1, 1);
+--easing-out: cubic-bezier(0, 0, 0.2, 1);
+```
+
+---
+
+## Camada 2: Semânticos
+
+Expressam propósito e intenção. Não dizem qual cor — dizem para que serve. É aqui que o theming acontece: dark mode troca semânticos apontando para primitivos diferentes.
+
+### Exemplos completos
+
+```css
+/* ═══ Superfícies ═══ */
+--surface-primary: var(--color-white);
+--surface-secondary: var(--color-gray-50);
+--surface-tertiary: var(--color-gray-100);
+--surface-inverse: var(--color-gray-900);
+--surface-elevated: var(--color-white);
+
+/* ═══ Texto ═══ */
+--text-primary: var(--color-gray-900);
+--text-secondary: var(--color-gray-600);
+--text-tertiary: var(--color-gray-400);
+--text-inverse: var(--color-white);
+--text-link: var(--color-blue-600);
+--text-link-hover: var(--color-blue-700);
+
+/* ═══ Bordas ═══ */
+--border-default: var(--color-gray-200);
+--border-strong: var(--color-gray-300);
+--border-focus: var(--color-blue-500);
+
+/* ═══ Status ═══ */
+--status-info: var(--color-blue-500);
+--status-success: var(--color-green-500);
+--status-warning: var(--color-amber-500);
+--status-error: var(--color-red-500);
+--status-info-bg: var(--color-blue-50);
+--status-success-bg: var(--color-green-50);
+--status-warning-bg: var(--color-amber-50);
+--status-error-bg: var(--color-red-50);
+
+/* ═══ Interação ═══ */
+--interactive-primary: var(--color-blue-600);
+--interactive-primary-hover: var(--color-blue-700);
+--interactive-primary-active: var(--color-blue-800);
+--interactive-secondary: var(--color-gray-100);
+--interactive-secondary-hover: var(--color-gray-200);
+--interactive-disabled: var(--color-gray-300);
+--interactive-disabled-text: var(--color-gray-400);
+
+/* ═══ Layout ═══ */
+--spacing-page-x: var(--space-6);
+--spacing-page-y: var(--space-8);
+--spacing-section: var(--space-16);
+--spacing-element: var(--space-4);
+--spacing-inline: var(--space-2);
+--container-max: 1200px;
+--radius-component: var(--radius-lg);
+```
+
+---
+
+## Camada 3: Componente
+
+Tokens específicos por componente. Usados quando um componente precisa de valores que não fazem sentido como semânticos globais. Derivam de semânticos.
+
+### Quando usar
+
+Use tokens de componente quando:
+- O valor é único para aquele componente (ex: altura fixa de um botão)
+- Múltiplos componentes usariam o mesmo semântico mas precisam divergir
+- A complexidade do componente justifica namespace próprio
+
+### Exemplos completos
+
+```css
+/* ═══ Button ═══ */
+--button-height-sm: 2rem;        /* 32px */
+--button-height-md: 2.5rem;      /* 40px */
+--button-height-lg: 3rem;        /* 48px */
+--button-padding-x: var(--space-4);
+--button-font-size: var(--font-size-sm);
+--button-font-weight: var(--font-weight-medium);
+--button-radius: var(--radius-component);
+--button-primary-bg: var(--interactive-primary);
+--button-primary-bg-hover: var(--interactive-primary-hover);
+--button-primary-text: var(--text-inverse);
+
+/* ═══ Input ═══ */
+--input-height: 2.5rem;
+--input-padding-x: var(--space-3);
+--input-font-size: var(--font-size-base);
+--input-border: var(--border-default);
+--input-border-focus: var(--border-focus);
+--input-border-error: var(--status-error);
+--input-bg: var(--surface-primary);
+--input-radius: var(--radius-component);
+--input-placeholder: var(--text-tertiary);
+
+/* ═══ Card ═══ */
+--card-bg: var(--surface-elevated);
+--card-border: var(--border-default);
+--card-radius: var(--radius-xl);
+--card-padding: var(--space-6);
+--card-shadow: var(--shadow-sm);
+--card-shadow-hover: var(--shadow-md);
+
+/* ═══ Modal ═══ */
+--modal-bg: var(--surface-primary);
+--modal-overlay: rgba(0, 0, 0, 0.5);
+--modal-radius: var(--radius-2xl);
+--modal-padding: var(--space-8);
+--modal-shadow: var(--shadow-xl);
+--modal-max-width: 32rem;
+```
+
+---
+
+## Dark Mode via Tokens
+
+O dark mode NÃO inverte cores — redefine semânticos apontando para primitivos diferentes.
+
+```css
+/* Light (default) */
+:root {
+  --surface-primary: var(--color-white);
+  --surface-secondary: var(--color-gray-50);
+  --text-primary: var(--color-gray-900);
+  --text-secondary: var(--color-gray-600);
+  --border-default: var(--color-gray-200);
+  --interactive-primary: var(--color-blue-600);
+}
+
+/* Dark */
+[data-theme="dark"] {
+  --surface-primary: var(--color-gray-950);
+  --surface-secondary: var(--color-gray-900);
+  --surface-elevated: var(--color-gray-800);
+  --text-primary: var(--color-gray-50);
+  --text-secondary: var(--color-gray-400);
+  --border-default: var(--color-gray-800);
+  --interactive-primary: var(--color-blue-400);
+  --shadow-sm: 0 1px 3px rgba(0,0,0,0.4);
+  --shadow-md: 0 4px 6px rgba(0,0,0,0.4);
+}
+
+/* Respeitar preferência do sistema */
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    /* mesmos valores de [data-theme="dark"] */
+  }
+}
+```
+
+Regras de dark mode:
+1. Fundo nunca é `#000000` — usar `#030712` a `#111827`
+2. Texto nunca é `#ffffff` — usar `#f9fafb` a `#e5e7eb`
+3. Saturação das cores deve ser reduzida 10-20% em dark
+4. Sombras precisam ser mais fortes (maior opacidade) ou substituídas por bordas sutis
+5. Testar contraste WCAG AA separadamente para dark mode
+
+---
+
+## Export para CSS Custom Properties
+
+```css
+/* tokens.css — gerado automaticamente */
+:root {
+  /* Primitivos */
+  --color-blue-600: #2563eb;
+  /* ... todos primitivos ... */
+
+  /* Semânticos */
+  --surface-primary: var(--color-white);
+  --text-primary: var(--color-gray-900);
+  /* ... todos semânticos ... */
+}
+
+/* Componentes importam separadamente */
+/* button.css */
+.button {
+  height: var(--button-height-md);
+  padding: 0 var(--button-padding-x);
+  /* ... */
+}
+```
+
+---
+
+## Export para Tailwind Config
+
+```js
+// tailwind.config.js
+export default {
+  theme: {
+    colors: {
+      // Primitivos como palette
+      blue: {
+        50: 'var(--color-blue-50)',
+        100: 'var(--color-blue-100)',
+        // ...
+        900: 'var(--color-blue-900)',
+      },
+      // Semânticos como aliases
+      surface: {
+        primary: 'var(--surface-primary)',
+        secondary: 'var(--surface-secondary)',
+        elevated: 'var(--surface-elevated)',
+      },
+      foreground: {
+        primary: 'var(--text-primary)',
+        secondary: 'var(--text-secondary)',
+        inverse: 'var(--text-inverse)',
+      },
+      border: {
+        DEFAULT: 'var(--border-default)',
+        strong: 'var(--border-strong)',
+        focus: 'var(--border-focus)',
+      },
+    },
+    borderRadius: {
+      none: 'var(--radius-none)',
+      sm: 'var(--radius-sm)',
+      md: 'var(--radius-md)',
+      lg: 'var(--radius-lg)',
+      xl: 'var(--radius-xl)',
+      '2xl': 'var(--radius-2xl)',
+      full: 'var(--radius-full)',
+    },
+    // spacing usa a escala do Tailwind
+    // apontando para custom properties
+  },
+};
+```
+
+---
+
+## Validação de Cobertura
+
+Como verificar que tokens estão sendo usados corretamente:
+
+1. **Grep por valores hardcoded**: buscar hex colors, px values diretos no CSS
+   ```bash
+   grep -rn '#[0-9a-fA-F]\{3,8\}' src/ --include='*.css' --include='*.tsx'
+   ```
+
+2. **Verificar tokens não utilizados**: listar tokens definidos vs referenciados
+   ```bash
+   # Tokens definidos
+   grep -oh 'var(--[a-z-]*)' tokens.css | sort -u > defined.txt
+   # Tokens usados
+   grep -roh 'var(--[a-z-]*)' src/ | sort -u > used.txt
+   # Diferença
+   comm -23 defined.txt used.txt  # definidos mas não usados
+   ```
+
+3. **Camada correta**: componentes nunca referenciam primitivos diretamente
+   ```bash
+   # Componentes não devem usar --color-* diretamente
+   grep -rn 'var(--color-' src/components/ --include='*.css'
+   ```
+
+---
+
+## Anti-padrões
+
+| Anti-padrão | Problema | Solução |
+|---|---|---|
+| Hardcoded `#2563eb` no componente | Impossível tematizar, dark mode quebra | Usar `var(--interactive-primary)` |
+| Token sem semântica: `--blue-button` | Mistura valor com propósito | Separar: `--button-primary-bg` → `--interactive-primary` → `--color-blue-600` |
+| Over-tokenization: token para cada pixel | Complexidade sem benefício | Tokenizar padrões repetidos, não valores únicos |
+| Componente referencia primitivo | Pula camada semântica, theming não funciona | Componente → semântico → primitivo |
+| Naming inconsistente | `--bgColor` vs `--bg-color` vs `--backgroundColor` | kebab-case sempre: `--surface-primary` |
+| Tokens no JavaScript | Duplicação, dessincronização | CSS custom properties como fonte, ler com `getComputedStyle` |
+| Sombras sem token | Inconsistência entre componentes | Definir escala de sombras como primitivos |