From 0de822c2a18ed548e328acdcc09cc917bfb97b6c Mon Sep 17 00:00:00 2001
From: Desktop <desktop@igny8.com>
Date: Fri, 14 Nov 2025 15:09:32 +0500
Subject: [PATCH] phase 4

---
 frontend/DESIGN_SYSTEM.md            |  62 +++++++-
 frontend/MIGRATION_GUIDE.md          | 216 +++++++++++++++++++++++++++
 frontend/src/styles/README.md        |  89 +++++------
 frontend/src/styles/igny8-colors.css |  33 ++--
 4 files changed, 340 insertions(+), 60 deletions(-)
 create mode 100644 frontend/MIGRATION_GUIDE.md

diff --git a/frontend/DESIGN_SYSTEM.md b/frontend/DESIGN_SYSTEM.md
index 4689087c..dcb56507 100644
--- a/frontend/DESIGN_SYSTEM.md
+++ b/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
diff --git a/frontend/MIGRATION_GUIDE.md b/frontend/MIGRATION_GUIDE.md
new file mode 100644
index 00000000..0722b10d
--- /dev/null
+++ b/frontend/MIGRATION_GUIDE.md
@@ -0,0 +1,216 @@
+# CSS Migration Guide
+
+This guide documents the migration from legacy `.igny8-*` classes and `--igny8-*` variables to the new standardized design token system.
+
+## Overview
+
+All design tokens are now centralized in `/src/styles/tokens.css` with plain naming (no "igny8" prefix). The legacy `igny8-colors.css` file is maintained for backward compatibility but should not be used in new code.
+
+## Color Token Migration
+
+### CSS Variables
+
+**Before:**
+```tsx
+<div className="bg-[var(--igny8-blue)]">Content</div>
+```
+
+**After:**
+```tsx
+<div className="bg-[var(--color-primary)]">Content</div>
+```
+
+### Complete Variable Mapping
+
+| Legacy Variable | New Token | Usage |
+|----------------|-----------|-------|
+| `--igny8-blue` | `--color-primary` | Primary brand color |
+| `--igny8-blue-dark` | `--color-primary-dark` | Primary dark variant |
+| `--igny8-green` | `--color-success` | Success states |
+| `--igny8-green-dark` | `--color-success-dark` | Success dark variant |
+| `--igny8-amber` | `--color-warning` | Warning states |
+| `--igny8-amber-dark` | `--color-warning-dark` | Warning dark variant |
+| `--igny8-red` | `--color-danger` | Danger/error states |
+| `--igny8-red-dark` | `--color-danger-dark` | Danger dark variant |
+| `--igny8-purple` | `--color-purple` | Purple accent |
+| `--igny8-purple-dark` | `--color-purple-dark` | Purple dark variant |
+
+## Utility Class Migration
+
+### Background Colors
+
+**Before:**
+```tsx
+<div className="igny8-bg-blue">Content</div>
+```
+
+**After (Option 1 - Tailwind):**
+```tsx
+<div className="bg-brand-500">Content</div>
+```
+
+**After (Option 2 - CSS Variable):**
+```tsx
+<div className="bg-[var(--color-primary)]">Content</div>
+```
+
+### Text Colors
+
+**Before:**
+```tsx
+<span className="igny8-text-blue">Text</span>
+```
+
+**After (Option 1 - Tailwind):**
+```tsx
+<span className="text-brand-500">Text</span>
+```
+
+**After (Option 2 - CSS Variable):**
+```tsx
+<span className="text-[var(--color-primary)]">Text</span>
+```
+
+### Border Colors
+
+**Before:**
+```tsx
+<div className="igny8-border-blue">Content</div>
+```
+
+**After (Option 1 - Tailwind):**
+```tsx
+<div className="border-brand-500">Content</div>
+```
+
+**After (Option 2 - CSS Variable):**
+```tsx
+<div className="border-[var(--color-primary)]">Content</div>
+```
+
+## Component Migration
+
+### Buttons
+
+**Before:**
+```tsx
+<a className="inline-flex items-center rounded-full bg-gradient-to-r from-[var(--igny8-blue)] to-[var(--igny8-blue-dark)] text-white px-6 py-3">
+  Click me
+</a>
+```
+
+**After:**
+```tsx
+import Button from '@/components/ui/button/Button';
+
+<Button
+  variant="gradient"
+  tone="brand"
+  shape="pill"
+  size="lg"
+  as="a"
+  href="/path"
+>
+  Click me
+</Button>
+```
+
+### Badges
+
+**Before:**
+```tsx
+<span className="igny8-badge igny8-badge-primary">New</span>
+```
+
+**After:**
+```tsx
+import Badge from '@/components/ui/badge/Badge';
+
+<Badge variant="solid" tone="brand">New</Badge>
+```
+
+### Cards
+
+**Before:**
+```tsx
+<div className="igny8-card">
+  <div className="igny8-card-header">Title</div>
+  Content
+</div>
+```
+
+**After:**
+```tsx
+import { Card, CardTitle, CardContent } from '@/components/ui/card/Card';
+
+<Card>
+  <CardTitle>Title</CardTitle>
+  <CardContent>Content</CardContent>
+</Card>
+```
+
+## Gradients
+
+**Before:**
+```tsx
+<div className="bg-gradient-to-r from-[var(--igny8-blue)] to-[var(--igny8-blue-dark)]">
+  Content
+</div>
+```
+
+**After:**
+```tsx
+<div className="bg-gradient-to-r from-[var(--color-primary)] to-[var(--color-primary-dark)]">
+  Content
+</div>
+```
+
+Or use the Button component with `variant="gradient"`:
+```tsx
+<Button variant="gradient" tone="brand">Content</Button>
+```
+
+## Active Classes (Still in Use)
+
+These classes are still actively used and should continue to be used:
+
+- `.igny8-table-container` - Table wrapper with loading states
+- `.igny8-table-wrapper` - Table scroll wrapper
+- `.igny8-table-compact` - Compact table styling
+- `.igny8-table-smooth` - Smooth table transitions
+- `.igny8-table-body` - Table body styling
+- `.igny8-skeleton-row` - Loading skeleton rows
+- `.igny8-header-metrics` - Header metrics container
+- `.igny8-header-metric` - Individual metric
+- `.igny8-header-metric-accent` - Metric accent color
+- `.igny8-header-metric-label` - Metric label
+- `.igny8-header-metric-value` - Metric value
+- `.igny8-header-metric-separator` - Metric separator
+
+## Migration Checklist
+
+When updating a file:
+
+- [ ] Replace `--igny8-*` variables with `--color-*` tokens
+- [ ] Replace `.igny8-bg-*` with `bg-brand-500` or `bg-[var(--color-primary)]`
+- [ ] Replace `.igny8-text-*` with `text-brand-500` or `text-[var(--color-primary)]`
+- [ ] Replace `.igny8-border-*` with `border-brand-500` or `border-[var(--color-primary)]`
+- [ ] Replace hardcoded buttons with `<Button>` component
+- [ ] Replace hardcoded badges with `<Badge>` component
+- [ ] Replace hardcoded cards with `<Card>` component
+- [ ] Keep `.igny8-table-*` and `.igny8-header-metric-*` classes as-is
+- [ ] Test visual appearance matches (no color changes)
+
+## Benefits of Migration
+
+✅ **Single source of truth** - All colors defined in one place  
+✅ **Type safety** - React components provide prop validation  
+✅ **Consistency** - Standardized components across marketing and dashboard  
+✅ **Maintainability** - Easier to update colors globally  
+✅ **Performance** - Tailwind utilities are optimized  
+✅ **Developer experience** - Better autocomplete and IntelliSense
+
+## Questions?
+
+See `DESIGN_SYSTEM.md` for complete design system guidelines.
+
diff --git a/frontend/src/styles/README.md b/frontend/src/styles/README.md
index d348839f..068b10e0 100644
--- a/frontend/src/styles/README.md
+++ b/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.
 
diff --git a/frontend/src/styles/igny8-colors.css b/frontend/src/styles/igny8-colors.css
index c47c92cd..33fcad5b 100644
--- a/frontend/src/styles/igny8-colors.css
+++ b/frontend/src/styles/igny8-colors.css
@@ -1,22 +1,26 @@
 /* ===================================================================
-   IGNY8 CUSTOM COLOR SCHEME
+   IGNY8 UTILITY CLASSES & LEGACY SUPPORT
    ===================================================================
-   This file contains IGNY8 brand colors from WordPress plugin.
-   All classes use 'igny8-' prefix to avoid conflicts with TailAdmin defaults.
-   Import this file separately to keep TailAdmin updates from affecting it.
+   ⚠️  DEPRECATED: This file is maintained for backward compatibility.
+   New code should use:
+   - CSS variables: var(--color-primary), var(--color-success), etc.
+   - Tailwind utilities: bg-brand-500, text-brand-500, etc.
+   - React components: Button, Badge, Card from /components/ui/
    
    🔒 DESIGN SYSTEM LOCKED - See DESIGN_SYSTEM.md for complete style guide
    
-   IMPORTANT: Before adding new CSS classes, check DESIGN_SYSTEM.md to ensure
-   you're not duplicating existing functionality. All visual styling patterns
-   are documented and locked.
+   This file provides:
+   1. Legacy variable aliases (--igny8-* → --color-*)
+   2. Active utility classes (.igny8-table-*, .igny8-header-metric-*)
+   3. Deprecated utility classes (marked below - do not use in new code)
    =================================================================== */
 
 /* === CSS CUSTOM PROPERTIES (Variables) === */
 /* Import tokens from centralized tokens.css */
 @import "./tokens.css";
 
-/* Legacy variable aliases for backward compatibility during migration */
+/* Legacy variable aliases for backward compatibility */
+/* These allow old code using --igny8-* to continue working */
 :root {
   --igny8-blue: var(--color-primary);
   --igny8-blue-dark: var(--color-primary-dark);
@@ -47,13 +51,18 @@
 }
 
 /* ===================================================================
-   IGNY8 UTILITY CLASSES
+   DEPRECATED UTILITY CLASSES
    ===================================================================
-   Use these classes instead of Tailwind defaults for IGNY8 branding.
-   Example: Use 'igny8-bg-blue' instead of 'bg-brand-500'
+   ⚠️  DO NOT USE IN NEW CODE
+   These classes are deprecated. Use Tailwind utilities or React components instead:
+   - .igny8-bg-blue → bg-brand-500 or bg-[var(--color-primary)]
+   - .igny8-text-blue → text-brand-500 or text-[var(--color-primary)]
+   - .igny8-border-blue → border-brand-500 or border-[var(--color-primary)]
+   
+   Migration: Replace with Tailwind utilities or use Button/Badge/Card components.
    =================================================================== */
 
-/* === Background Colors === */
+/* === Background Colors (DEPRECATED) === */
 .igny8-bg-blue { background-color: var(--igny8-blue); }
 .igny8-bg-blue-dark { background-color: var(--igny8-blue-dark); }
 .igny8-bg-green { background-color: var(--igny8-green); }