phase 4

frontend/DESIGN_SYSTEM.md

@@ -2,24 +2,64 @@
 
 > 🔒 **STYLE SYSTEM LOCKED** - This design system is **LOCKED** as of 2025-01-XX. Read this entire document before making any styling changes.
 
+## 🎨 Design Token System
+
+**Single Source of Truth**: All design tokens (colors, gradients, shadows) are defined in `/src/styles/tokens.css`
+
+### Color Tokens
+
+Use CSS variables for colors:
+- `var(--color-primary)` - Primary brand blue (#0693e3)
+- `var(--color-primary-dark)` - Primary dark (#0472b8)
+- `var(--color-success)` - Success green (#0bbf87)
+- `var(--color-warning)` - Warning amber (#ff7a00)
+- `var(--color-danger)` - Danger red (#ef4444)
+- `var(--color-purple)` - Purple accent (#5d4ae3)
+
+### Using Colors
+
+**✅ DO:**
+```tsx
+// Use Tailwind utilities with brand colors
+<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>
+```
+
+**❌ DON'T:**
+```tsx
+// Don't use deprecated .igny8-* utility classes
+<div className="igny8-bg-blue">Content</div>
+
+// Don't hardcode color values
+<div className="bg-[#0693e3]">Content</div>
+
+// Don't use inline styles
+<div style={{ backgroundColor: '#0693e3' }}>Content</div>
+```
+
 ## 🔒 Style System Lock Status
 
 **DO NOT:**
 - ❌ Create new CSS classes without documenting in this file
 - ❌ Duplicate existing styling patterns
 - ❌ Create custom colors/utilities that already exist
-- ❌ Modify core classes (`.igny8-table-compact`, etc.) without updating documentation
+- ❌ Use deprecated `.igny8-*` utility classes (except `.igny8-table-*` and `.igny8-header-metric-*`)
 - ❌ Add inline styles for colors/spacing/typography
+- ❌ Hardcode color hex values
 
 **DO:**
 - ✅ Check this document before creating any styles
-- ✅ Use existing classes from `igny8-colors.css`
-- ✅ Use Tailwind defaults where possible
+- ✅ Use design tokens from `tokens.css` via CSS variables
+- ✅ Use Tailwind utilities (bg-brand-500, text-brand-500, etc.)
+- ✅ Use React components (Button, Badge, Card) from `/components/ui/`
 - ✅ Follow component patterns from this guide
 - ✅ Update this document if you MUST add something new
 
-Any new styling that duplicates existing functionality or creates new classes without documentation will be considered technical debt.
-
 ---
 
 ## Core Principles
@@ -76,11 +116,21 @@ Any new styling that duplicates existing functionality or creates new classes wi
 
 ### 5. **Styling Guidelines**
 - Use Tailwind CSS classes exclusively
-- Follow the existing color scheme from `igny8-colors.css`
+- Use design tokens from `tokens.css` via CSS variables: `var(--color-primary)`
+- Use Tailwind brand color utilities: `bg-brand-500`, `text-brand-500`, etc.
+- Use React components for buttons, badges, cards (Button, Badge, Card)
 - Use dark mode variants: `dark:bg-gray-900`, `dark:text-white`, etc.
 - Maintain consistent spacing using Tailwind spacing scale
 - Use existing utility classes: `shadow-theme-xs`, `text-theme-sm`, etc.
 
+### 5a. **Deprecated Patterns (DO NOT USE)**
+- ❌ `.igny8-bg-*`, `.igny8-text-*`, `.igny8-border-*` utility classes
+- ❌ `var(--igny8-blue)` - use `var(--color-primary)` instead
+- ❌ Hardcoded hex colors like `#0693e3`
+- ❌ Inline `style={{ color: ... }}` attributes
+
+**Exception**: `.igny8-table-*` and `.igny8-header-metric-*` classes are still active and should be used for table/header components.
+
 ### 6. **When Creating New Components is Acceptable**
 Only create new components if:
 1. Explicitly requested by the user