phase 4

frontend/src/styles/README.md

@@ -1,59 +1,64 @@
-# IGNY8 Custom Styles
+# Design Tokens & Styles
 
-This directory contains IGNY8-specific custom styles that are **completely separate** from TailAdmin defaults.
+This directory contains the centralized design token system and legacy compatibility styles.
 
 ## Files
 
-- `igny8-colors.css` - IGNY8 brand color scheme with custom CSS variables and utility classes
+- `tokens.css` - **Single source of truth** for all design tokens (colors, gradients, shadows)
+- `igny8-colors.css` - Legacy compatibility file (deprecated - use tokens.css instead)
+- `global.css` - Global base styles
 
-## Usage
+## Design Tokens (`tokens.css`)
 
-### Import in your component:
-```typescript
-// Already imported globally in main.tsx
-// No need to import in individual components
-```
+All design tokens use plain naming (no "igny8" prefix):
 
-### Use IGNY8 classes:
+### Color Tokens
+- `--color-primary` - Primary brand blue (#0693e3)
+- `--color-primary-dark` - Primary dark variant (#0472b8)
+- `--color-success` - Success green (#0bbf87)
+- `--color-warning` - Warning amber (#ff7a00)
+- `--color-danger` - Danger red (#ef4444)
+- `--color-purple` - Purple accent (#5d4ae3)
+
+### Usage
+
+**✅ DO:**
 ```tsx
-// ✅ Use IGNY8 custom classes
-<div className="igny8-bg-blue igny8-text-white igny8-card">
-  Content
-</div>
+// Use Tailwind utilities
+<div className="bg-brand-500 text-white">Content</div>
 
-// ❌ Don't use TailAdmin defaults (unless you want TailAdmin branding)
-<div className="bg-brand-500 text-white">
-  Content
-</div>
+// Use CSS variables for custom values
+<div className="bg-[var(--color-primary)]">Content</div>
+
+// Use React components
+<Button tone="brand" variant="gradient">Click me</Button>
 ```
 
-## Color Variables
+**❌ DON'T:**
+```tsx
+// Don't use deprecated utility classes
+<div className="igny8-bg-blue">Content</div>
 
-All colors are available as CSS variables:
-- `--igny8-blue` - Primary brand blue
-- `--igny8-green` - Success green
-- `--igny8-amber` - Warning amber
-- `--igny8-red` - Danger red
-- `--igny8-purple` - Purple accent
-- `--igny8-surface` - Page background
-- `--igny8-panel` - Card background
-- `--igny8-text` - Primary text
-- `--igny8-stroke` - Borders
+// Don't hardcode colors
+<div className="bg-[#0693e3]">Content</div>
+```
 
-## Utility Classes
+## Legacy File (`igny8-colors.css`)
 
-All utility classes use `igny8-` prefix:
-- Backgrounds: `.igny8-bg-blue`, `.igny8-bg-green`, etc.
-- Text: `.igny8-text-blue`, `.igny8-text-primary`, etc.
-- Borders: `.igny8-border-blue`, `.igny8-border-stroke`, etc.
-- Gradients: `.igny8-gradient-blue`, `.igny8-gradient-success`, etc.
-- Buttons: `.igny8-btn`, `.igny8-btn-primary`, etc.
-- Badges: `.igny8-badge`, `.igny8-badge-primary`, etc.
+⚠️ **DEPRECATED** - This file is maintained for backward compatibility only.
 
-## Benefits
+- Legacy variable aliases (`--igny8-*` → `--color-*`)
+- Active utility classes (`.igny8-table-*`, `.igny8-header-metric-*`)
+- Deprecated utility classes (marked - do not use in new code)
 
-✅ **No conflicts** - Separate prefix prevents TailAdmin update issues
-✅ **Easy updates** - TailAdmin can be updated without affecting IGNY8 styles
-✅ **Clear separation** - Easy to identify IGNY8 vs TailAdmin styles
-✅ **Consistent branding** - All IGNY8 components use same color scheme
+See `MIGRATION_GUIDE.md` for migration instructions.
+
+## Migration
+
+All new code should use:
+1. Design tokens from `tokens.css`
+2. Tailwind utilities (`bg-brand-500`, `text-brand-500`)
+3. React components (`Button`, `Badge`, `Card`)
+
+See `../MIGRATION_GUIDE.md` for complete migration guide.