VErsion 1.3.2

docs/30-FRONTEND/DESIGN-TOKENS.md

@@ -1,64 +1,127 @@
 # Design System & Component Guidelines
 
-> 🔒 **STYLE SYSTEM LOCKED** - This design system is **LOCKED** as of 2025-01-XX. Read this entire document before making any styling changes.
+**Last Updated:** January 3, 2026  
+**Version:** 1.3.2
+
+> 🔒 **STYLE SYSTEM LOCKED** - This design system is **LOCKED**. 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`
+**Single Source of Truth**: `/src/styles/design-system.css`
 
-### Color Tokens
+⚠️ **CRITICAL**: Only 6 hex color values exist in the entire system. Everything else is derived using `color-mix()`.
 
-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)
+### The 6 Base Colors
+
+| Token | Hex | Purpose |
+|-------|-----|---------|
+| `--color-primary` | `#0077B6` | Brand blue |
+| `--color-success` | `#00B894` | Success green |
+| `--color-warning` | `#F59E0B` | Warning amber |
+| `--color-danger` | `#DC2626` | Error red |
+| `--color-purple` | `#7C3AED` | Premium purple |
+| `--color-gray-base` | `#667085` | Neutral gray |
+
+### Color Scales (Derived)
+
+Each base color generates a full scale (50-950) via `color-mix()`:
+
+```css
+/* Example: brand color scale */
+--color-brand-50    /* Lightest */
+--color-brand-100
+--color-brand-200
+--color-brand-300
+--color-brand-400
+--color-brand-500   /* Base = --color-primary */
+--color-brand-600
+--color-brand-700
+--color-brand-800
+--color-brand-900
+--color-brand-950   /* Darkest */
+```
+
+### Tailwind Color Classes
+
+**Available (Use These):**
+```css
+/* Brand */       bg-brand-50 ... bg-brand-950, text-brand-*, border-brand-*
+/* Success */     bg-success-50 ... bg-success-950, text-success-*, border-success-*
+/* Warning */     bg-warning-50 ... bg-warning-950, text-warning-*, border-warning-*
+/* Error */       bg-error-50 ... bg-error-950, text-error-*, border-error-*
+/* Purple */      bg-purple-50 ... bg-purple-950, text-purple-*, border-purple-*
+/* Gray */        bg-gray-50 ... bg-gray-950, text-gray-*, border-gray-*
+/* Info */        bg-info-50 ... bg-info-950 (alias for brand)
+```
+
+**DISABLED (DO NOT USE):**
+```css
+/* These Tailwind defaults are DISABLED and won't work */
+blue-*, red-*, green-*, yellow-*, orange-*, indigo-*, violet-*,
+pink-*, rose-*, cyan-*, teal-*, emerald-*, lime-*, amber-*,
+slate-*, zinc-*, neutral-*, stone-*
+```
 
 ### Using Colors
 
 **✅ DO:**
 ```tsx
-// Use Tailwind utilities with brand colors
-<div className="bg-brand-500 text-white">Content</div>
+// Use semantic Tailwind utilities
+<div className="bg-brand-500 text-white">Primary action</div>
+<div className="bg-success-100 text-success-700">Success message</div>
+<div className="bg-error-50 border-error-500">Error alert</div>
 
-// Use CSS variables for custom values
-<div className="bg-[var(--color-primary)]">Content</div>
+// Use CSS variables for custom cases
+<div className="bg-[var(--color-primary)]">Custom</div>
 
-// Use React components
-<Button tone="brand" variant="gradient">Click me</Button>
+// Use React components with tone prop
+<Button tone="brand">Primary</Button>
+<Button tone="success">Approve</Button>
+<Badge tone="warning">Pending</Badge>
 ```
 
 **❌ DON'T:**
 ```tsx
-// Don't use deprecated .igny8-* utility classes
-<div className="igny8-bg-blue">Content</div>
+// Don't use Tailwind default colors (DISABLED)
+<div className="bg-blue-500">Won't work!</div>
+<div className="text-slate-700">Won't work!</div>
 
-// Don't hardcode color values
-<div className="bg-[#0693e3]">Content</div>
-
-// Don't use inline styles
-<div style={{ backgroundColor: '#0693e3' }}>Content</div>
+// Don't hardcode hex values
+<div className="bg-[#0077B6]">Bad!</div>
+<div style={{ backgroundColor: '#DC2626' }}>Bad!</div>
 ```
 
 ## 🔒 Style System Lock Status
 
 **DO NOT:**
-- ❌ Create new CSS classes without documenting in this file
+- ❌ Use Tailwind default color classes (blue-*, red-*, green-*, etc.)
+- ❌ Hardcode hex color values anywhere
+- ❌ Use inline styles for colors/spacing/typography
+- ❌ Import from external icon libraries (lucide-react, @heroicons)
+- ❌ Create new CSS classes without documenting
 - ❌ Duplicate existing styling patterns
-- ❌ Create custom colors/utilities that already exist
-- ❌ 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 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
+- ✅ Use semantic color tokens (brand-*, success-*, etc.)
+- ✅ Import icons from `src/icons`
+- ✅ Use React components (Button, Badge, Card, InputField)
+- ✅ Run `npm run lint` to check for violations
+- ✅ Check `/ui-elements` for component examples
+
+---
+
+## Module Color Scheme (v1.3.2)
+
+Each module has a distinct color for visual identification:
+
+| Module | Color | Tailwind Classes |
+|--------|-------|------------------|
+| **Planner** (Keywords/Clusters/Ideas) | Purple | `bg-purple-*`, `text-purple-*` |
+| **Writer** (Tasks/Content/Images) | Green | `bg-success-*`, `text-success-*` |
+| **Automation** | Blue | `bg-brand-*`, `text-brand-*` |
+| **Publisher** | Orange | `bg-warning-*`, `text-warning-*` |
+| **Billing** | Purple | `bg-purple-*`, `text-purple-*` |
+| **Settings** | Gray | `bg-gray-*`, `text-gray-*` |
 
 ---
 
@@ -148,7 +211,7 @@ Before implementing any UI element:
 
 ## 📝 Typography Scale
 
-Typography tokens are defined in `index.css` and should be used consistently:
+Typography tokens are defined in `design-system.css` and should be used consistently:
 
 ### Title Sizes (for page/section headings)
 | Token | Size | Line Height | Use Case |
@@ -192,14 +255,15 @@ Module-specific colors are defined in `src/config/colors.config.ts`:
 
 | Module | Primary Color | Usage |
 |--------|---------------|-------|
-| Keywords | `brand-500` (blue) | Icons, progress bars, badges |
-| Clusters | `purple-500` | Icons, progress bars, badges |
-| Ideas | `purple-600` | Icons, progress bars, badges |
-| Tasks | `success-600` (green) | Icons, progress bars, badges |
-| Content | `success-500` | Icons, progress bars, badges |
-| Images | `purple-500` | Icons, progress bars, badges |
+| Planner (Keywords) | `brand-500` (blue) | Icons, progress bars, badges |
+| Planner (Clusters) | `purple-500` | Icons, progress bars, badges |
+| Planner (Ideas) | `purple-600` | Icons, progress bars, badges |
+| Writer (Tasks) | `success-600` (green) | Icons, progress bars, badges |
+| Writer (Content) | `success-500` | Icons, progress bars, badges |
+| Writer (Images) | `purple-500` | Icons, progress bars, badges |
 | Automation | `brand-500` | Pipeline cards |
-| Billing | `warning-500` (amber) | Credit displays |
+| Publisher | `warning-500` (amber) | Calendar, scheduling |
+| Billing | `purple-500` | Credit displays |
 
 ```tsx
 import { MODULE_COLORS } from '@/config/colors.config';
@@ -211,7 +275,7 @@ import { MODULE_COLORS } from '@/config/colors.config';
 
 ---
 
-**Last Updated**: January 2, 2026
+**Last Updated**: January 3, 2026
 **Status**: Active Design System Rules - 🔒 LOCKED
 
 ---
@@ -228,7 +292,7 @@ import { MODULE_COLORS } from '@/config/colors.config';
 |----------|--------------|------------|
 | **UI Components** | `@/components/ui/` or relative `../components/ui/` | Button, Card, Modal, Alert, Badge, Dropdown, Tooltip, Spinner, Tabs, Toast, Pagination, Progress, Avatar, Breadcrumb |
 | **Common Components** | `@/components/common/` | PageHeader, ComponentCard, ConfirmDialog, FormModal, TablePageTemplate |
-| **Icons** | `@/icons` or `@heroicons/react` | All SVG icons |
+| **Icons** | `@/icons` | All SVG icons (local icons only - external libraries disabled) |
 | **Templates** | `@/templates/` | TablePageTemplate, ContentViewTemplate |
 
 ### BANNED IMPORTS (DO NOT USE)
@@ -254,11 +318,12 @@ const MyButton = () => <button className="...">; // If used more than once, crea
 
 | File | Purpose | When to Use |
 |------|---------|-------------|
-| `src/index.css` | Main Tailwind config, utilities | Auto-imported, don't import manually |
-| `src/styles/tokens.css` | CSS variables (colors, shadows) | Use via `var(--color-name)` |
+| `src/styles/design-system.css` | ALL design tokens, colors, shadows, typography | Single source - auto-imported via main.tsx |
 
 **DO NOT CREATE OR USE:**
-- ❌ `styles/global.css` - Deprecated
+- ❌ `src/styles/global.css` - **Deleted** (consolidated into design-system.css)
+- ❌ `src/styles/tokens.css` - **Deleted** (consolidated into design-system.css)
+- ❌ `src/styles/index.css` - **Deleted** (consolidated into design-system.css)
 - ❌ `components/shared/blocks/blocks.css` - For marketing only
 - ❌ `components/shared/layouts/layouts.css` - For marketing only
 - ❌ Any new `.css` files in component folders
@@ -375,8 +440,10 @@ src/components/ui/
 |--------|-------|------|
 | Planner | Keywords, Clusters, Ideas | `src/pages/Planner/` |
 | Writer | Review, Approved, Content | `src/pages/Writer/` |
+| Publisher | ContentCalendar, PublishingQueue | `src/pages/Publisher/` |
 | Sites | List, Settings | `src/pages/Sites/` |
 | Dashboard | Home | `src/pages/Dashboard/` |
+| Setup | SetupWizard (Onboarding) | `src/pages/Setup/` |
 
 ### AUDIT CHECKLIST FOR CODE REVIEW