@fabio.caffarello/react-design-system 1.7.0 → 1.9.0

package/src/ui/tokens/COLOR_USAGE_GUIDE.md

@@ -0,0 +1,248 @@
+# Color Usage Guide
+
+## Overview
+
+This guide defines the strategic use of color tokens across the design system. Colors are used semantically to convey meaning and create visual hierarchy.
+
+## Color Roles
+
+### Primary
+**Purpose**: Main actions, important links, primary CTAs
+
+**Usage**:
+- Primary action buttons
+- Important links
+- Key navigation elements
+- Brand elements
+
+**Example**:
+```tsx
+<Button variant="primary">Save Changes</Button>
+```
+
+### Secondary
+**Purpose**: Accents, active states, highlights (pink/rose in playground)
+
+**Usage**:
+- Active tab indicators
+- Accent elements
+- Secondary actions
+- Interactive highlights
+
+**Example**:
+```tsx
+className={getColorClass('secondary', 'DEFAULT', 'bg')}
+```
+
+### Success
+**Purpose**: Validation, confirmations, positive feedback
+
+**Usage**:
+- Success messages
+- Validation indicators
+- Confirmation states
+- Positive feedback
+
+**Example**:
+```tsx
+<Badge variant="success">Valid</Badge>
+```
+
+### Warning
+**Purpose**: Warnings, pending states, attention needed
+
+**Usage**:
+- Warning messages
+- Pending states
+- Attention indicators
+- Caution states
+
+**Example**:
+```tsx
+<Badge variant="warning">Unsaved</Badge>
+```
+
+### Error
+**Purpose**: Errors, critical states, destructive actions
+
+**Usage**:
+- Error messages
+- Critical states
+- Destructive actions
+- Failure indicators
+
+**Example**:
+```tsx
+<Badge variant="error">Error</Badge>
+```
+
+### Info
+**Purpose**: Information, tooltips, neutral information
+
+**Usage**:
+- Information messages
+- Tooltips
+- Help text
+- Neutral information
+
+**Example**:
+```tsx
+<Tooltip>Information</Tooltip>
+```
+
+### Neutral
+**Purpose**: Text, borders, backgrounds, default states
+
+**Usage**:
+- Body text
+- Borders
+- Backgrounds
+- Default states
+- Disabled states
+
+**Example**:
+```tsx
+className={getColorClass('neutral', 'DEFAULT', 'text')}
+```
+
+## Color Shades
+
+Each color role has three shades:
+
+- **light**: Lighter variant, used for backgrounds, hover states
+- **DEFAULT**: Standard variant, used for primary elements
+- **dark**: Darker variant, used for emphasis, active states
+- **contrast**: Contrast color for text on colored backgrounds
+
+## Usage Patterns
+
+### States
+
+#### Active State
+```tsx
+className={isActive 
+  ? `${getColorClass('secondary', 'DEFAULT', 'bg')} ${getColorClass('secondary', 'contrast', 'text')}`
+  : 'hover:bg-gray-100'
+}
+```
+
+#### Hover State
+```tsx
+className={`hover:${getColorClass('primary', 'light', 'bg')}`}
+```
+
+#### Disabled State
+```tsx
+className={`${getColorClass('neutral', 'DEFAULT', 'text')} opacity-50`}
+```
+
+### Contexts
+
+#### Buttons
+- Primary actions: `primary`
+- Secondary actions: `secondary` or `outline`
+- Destructive: `error`
+- Neutral: `neutral`
+
+#### Badges
+- Success: `success`
+- Warning: `warning`
+- Error: `error`
+- Info: `info`
+- Default: `neutral`
+
+#### Borders
+- Default: `neutral`
+- Active: `primary` or `secondary`
+- Error: `error`
+
+#### Backgrounds
+- Default: `neutral` (light)
+- Active: `primary` or `secondary` (light)
+- Hover: `neutral` or `primary` (light)
+
+## Best Practices
+
+1. **Consistency**: Always use color tokens, never hardcode colors
+2. **Semantic Meaning**: Use colors that match their semantic meaning
+3. **Contrast**: Ensure sufficient contrast for accessibility (WCAG AA minimum)
+4. **Hierarchy**: Use color to establish visual hierarchy
+5. **States**: Use consistent color patterns for states (active, hover, disabled)
+
+## Anti-Patterns
+
+❌ **Don't**: Hardcode colors
+```tsx
+className="bg-pink-500" // ❌
+```
+
+✅ **Do**: Use tokens
+```tsx
+className={getColorClass('secondary', 'DEFAULT', 'bg')} // ✅
+```
+
+❌ **Don't**: Use wrong semantic meaning
+```tsx
+<Button className={getColorClass('error', 'DEFAULT', 'bg')}>Save</Button> // ❌
+```
+
+✅ **Do**: Use appropriate semantic meaning
+```tsx
+<Button className={getColorClass('primary', 'DEFAULT', 'bg')}>Save</Button> // ✅
+```
+
+## Theme Support
+
+Colors automatically adapt to light/dark themes through the `ColorStrategy` pattern. The system uses:
+- `LightColorStrategy` for light theme
+- `DarkColorStrategy` for dark theme
+
+Colors are generated at runtime and cached for performance.
+
+## Migration Guide
+
+When migrating from hardcoded colors to tokens:
+
+1. Identify hardcoded color values
+2. Determine appropriate color role
+3. Replace with `getColorClass()` or `getColor()`
+4. Test in both light and dark themes
+5. Verify accessibility contrast
+
+## Examples
+
+### Tab Navigation
+```tsx
+<Tabs.Trigger
+  className={isActive 
+    ? `${getColorClass('secondary', 'DEFAULT', 'bg')} ${getColorClass('secondary', 'contrast', 'text')}`
+    : 'hover:bg-gray-100'
+  }
+>
+  Tab Label
+</Tabs.Trigger>
+```
+
+### Status Badge
+```tsx
+<Badge
+  className={`
+    ${getColorClass(status === 'success' ? 'success' : 'error', 'DEFAULT', 'bg')}
+    ${getColorClass(status === 'success' ? 'success' : 'error', 'contrast', 'text')}
+  `}
+>
+  {status}
+</Badge>
+```
+
+### Border
+```tsx
+<div
+  className={`
+    border
+    ${getColorClass('neutral', 'DEFAULT', 'border')}
+  `}
+>
+  Content
+</div>
+```

package/src/ui/tokens/README.md

@@ -0,0 +1,212 @@
+# Design Tokens System
+
+Este documento descreve o sistema de design tokens do `react-design-system`, que fornece valores centralizados e consistentes para cores, espaçamento, tipografia, sombras, bordas, raios e breakpoints.
+
+## Visão Geral
+
+O sistema de tokens utiliza o **Factory Pattern** para criar tokens de forma type-safe e consistente. Todos os tokens seguem uma estrutura padronizada e podem ser acessados através de helper functions.
+
+## Estrutura de Tokens
+
+### 1. Colors (`colors.ts`)
+
+Sistema de cores semânticas com suporte a temas claro e escuro.
+
+**Roles**: `primary`, `secondary`, `success`, `warning`, `error`, `info`, `neutral`
+
+**Shades**: `light`, `DEFAULT`, `dark`, `contrast`
+
+**Uso:**
+```typescript
+import { getColorClass, COLOR_TOKENS } from './tokens/colors';
+
+// Obter classe Tailwind
+const bgClass = getColorClass('primary', 'DEFAULT', 'bg'); // 'bg-indigo-500'
+const textClass = getColorClass('error', 'dark', 'text'); // 'text-red-600'
+
+// Acessar token diretamente
+const primaryColor = COLOR_TOKENS.primary.DEFAULT.hex; // '#6366f1'
+```
+
+### 2. Spacing (`spacing.ts`)
+
+Sistema de espaçamento baseado em unidades de 4px.
+
+**Escala**: `xs` (4px), `sm` (8px), `md` (12px), `base` (16px), `lg` (24px), `xl` (32px), `2xl` (40px), `3xl` (48px), `4xl` (64px), `5xl` (80px), `6xl` (96px)
+
+**Uso:**
+```typescript
+import { getSpacingClass, SPACING_TOKENS } from './tokens/spacing';
+
+// Obter classe Tailwind
+const paddingClass = getSpacingClass('md', 'p'); // 'p-3'
+const marginClass = getSpacingClass('lg', 'mx'); // 'mx-6'
+
+// Acessar token diretamente
+const mdSpacing = SPACING_TOKENS.md.px; // '12px'
+```
+
+### 3. Typography (`typography.ts`)
+
+Sistema de tipografia com tamanhos, pesos e line heights.
+
+**Tamanhos**: `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, `5xl`, `6xl`
+
+**Pesos**: `light`, `normal`, `medium`, `semibold`, `bold`
+
+**Line Heights**: `none`, `tight`, `snug`, `normal`, `relaxed`, `loose`
+
+**Uso:**
+```typescript
+import { getTypographyClasses, TYPOGRAPHY_TOKENS } from './tokens/typography';
+
+// Obter classes completas
+const headingClasses = getTypographyClasses('h1'); // 'text-4xl leading-tight font-bold'
+
+// Acessar token diretamente
+const h1Size = TYPOGRAPHY_TOKENS.h1.fontSize.px; // '36px'
+```
+
+### 4. Shadows (`shadows.ts`)
+
+Sistema de sombras para elevação e profundidade.
+
+**Tamanhos**: `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `inner`
+
+**Uso:**
+```typescript
+import { getShadowClass, SHADOW_TOKENS } from './tokens/shadows';
+
+// Obter classe Tailwind
+const shadowClass = getShadowClass('lg'); // 'shadow-lg'
+
+// Acessar token diretamente
+const lgShadow = SHADOW_TOKENS.lg.value; // '0 4px 6px -1px rgb(0 0 0 / 0.1)...'
+```
+
+### 5. Radius (`radius.ts`)
+
+Sistema de border radius para cantos arredondados.
+
+**Tamanhos**: `none`, `sm` (2px), `md` (6px), `lg` (8px), `xl` (12px), `2xl` (16px), `3xl` (24px), `full`
+
+**Uso:**
+```typescript
+import { getRadiusClass, RADIUS_TOKENS } from './tokens/radius';
+
+// Obter classe Tailwind
+const radiusClass = getRadiusClass('lg'); // 'rounded-lg'
+
+// Acessar token diretamente
+const lgRadius = RADIUS_TOKENS.lg.px; // '8px'
+```
+
+### 6. Borders (`borders.ts`)
+
+Sistema de bordas para larguras e estilos.
+
+**Larguras**: `none`, `thin` (1px), `base` (1px), `medium` (2px), `thick` (4px)
+
+**Estilos**: `solid`, `dashed`, `dotted`
+
+**Uso:**
+```typescript
+import { getBorderWidthClass, getBorderStyleClass, getBorderClasses, BORDER_TOKENS } from './tokens/borders';
+
+// Obter classes
+const widthClass = getBorderWidthClass('base'); // 'border'
+const styleClass = getBorderStyleClass('solid'); // 'border-solid'
+const fullBorder = getBorderClasses('base', 'solid'); // 'border border-solid'
+
+// Acessar token diretamente
+const baseBorder = BORDER_TOKENS.base.width.px; // '1px'
+```
+
+### 7. Breakpoints (`breakpoints.ts`)
+
+Sistema de breakpoints responsivos.
+
+**Breakpoints**: `sm` (640px), `md` (768px), `lg` (1024px), `xl` (1280px), `2xl` (1536px)
+
+**Uso:**
+```typescript
+import { BREAKPOINT_TOKENS } from './tokens/breakpoints';
+
+// Acessar breakpoint
+const mdBreakpoint = BREAKPOINT_TOKENS.md.value; // 768
+```
+
+## Tokens Factory
+
+O `TokensFactory` fornece uma interface unificada para criar todos os tipos de tokens:
+
+```typescript
+import { TokensFactory } from './tokens/tokens.factory';
+
+const factory = new TokensFactory('light');
+const tokenSet = factory.createTokenSet();
+
+// Acessar todos os tokens
+const spacing = tokenSet.spacing;
+const colors = tokenSet.colors;
+const shadows = tokenSet.shadows;
+```
+
+## Padrões de Uso
+
+### ✅ Usar Tokens
+
+```typescript
+import { getColorClass } from './tokens/colors';
+import { getSpacingClass } from './tokens/spacing';
+import { getRadiusClass } from './tokens/radius';
+import { getShadowClass } from './tokens/shadows';
+
+const className = `
+  ${getColorClass('primary', 'DEFAULT', 'bg')}
+  ${getSpacingClass('md', 'p')}
+  ${getRadiusClass('lg')}
+  ${getShadowClass('md')}
+`;
+```
+
+### ❌ Evitar Classes Hardcoded
+
+```typescript
+// ❌ Evitar
+const className = 'bg-indigo-500 p-3 rounded-lg shadow-md';
+
+// ✅ Preferir
+const className = `
+  ${getColorClass('primary', 'DEFAULT', 'bg')}
+  ${getSpacingClass('md', 'p')}
+  ${getRadiusClass('lg')}
+  ${getShadowClass('md')}
+`;
+```
+
+## Migração de Classes Hardcoded
+
+Ao refatorar componentes, substitua classes hardcoded por tokens:
+
+1. **Cores**: `bg-gray-500` → `getColorClass('neutral', 'DEFAULT', 'bg')`
+2. **Espaçamento**: `p-4` → `getSpacingClass('base', 'p')`
+3. **Sombras**: `shadow-lg` → `getShadowClass('lg')`
+4. **Radius**: `rounded-md` → `getRadiusClass('md')`
+5. **Bordas**: `border-2` → `getBorderWidthClass('medium')`
+
+## Benefícios
+
+1. **Consistência**: Valores centralizados garantem consistência visual
+2. **Manutenibilidade**: Mudanças em um lugar refletem em todo o sistema
+3. **Type Safety**: TypeScript garante uso correto dos tokens
+4. **Temas**: Suporte fácil a temas claro/escuro
+5. **Documentação**: Tokens são auto-documentados com descrições
+
+## Próximos Passos
+
+- [ ] Auditar todos os componentes para uso de tokens
+- [ ] Substituir classes hardcoded por tokens
+- [ ] Adicionar tokens para animações e transições
+- [ ] Criar tokens para z-index layers
+- [ ] Documentar tokens no Storybook