# Design System & Component Guidelines

**Last Updated:** January 20, 2026  
**Version:** 1.8.4

> 🔒 **STYLE SYSTEM LOCKED** - This design system is **LOCKED**. Read this entire document before making any styling changes.

## 🎨 Design Token System

**Single Source of Truth**: `/src/styles/design-system.css`

⚠️ **CRITICAL**: Only 6 hex color values exist in the entire system. Everything else is derived using `color-mix()`.

### 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 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 cases
<div className="bg-[var(--color-primary)]">Custom</div>

// 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 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 hex values
<div className="bg-[#0077B6]">Bad!</div>
<div style={{ backgroundColor: '#DC2626' }}>Bad!</div>
```

## 🔒 Style System Lock Status

**DO NOT:**
- ❌ 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

**DO:**
- ✅ 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-*` |

---

## Core Principles

### 1. **Reuse Existing Components Only**
- ✅ **DO**: Use existing components from `/src/components/ui/` and `/src/components/common/`
- ❌ **DON'T**: Create new components unless explicitly required and approved
- ❌ **DON'T**: Duplicate existing component functionality

### 2. **No Inline Styles**
- ✅ **DO**: Use Tailwind CSS utility classes
- ✅ **DO**: Use existing CSS classes from the design system
- ✅ **DO**: Use existing component props for styling
- ❌ **DON'T**: Use inline `style` attributes
- ❌ **DON'T**: Use inline `style={{}}` in JSX

### 3. **Component Consistency**
- All UI Elements pages should follow the same structure:
  - Use `PageMeta` for SEO
  - Use `PageBreadcrumb` for navigation
  - Use `ComponentCard` for consistent card styling
  - Import and use existing reusable components

### 4. **Available Component Libraries**

#### UI Components (`/src/components/ui/`)
- `alert/` - Alert components
- `avatar/` - Avatar components
- `badge/` - Badge components
- `breadcrumb/` - Breadcrumb navigation
- `button/` - Button components
- `button-group/` - Button group components
- `card/` - Card components
- `dropdown/` - Dropdown menu components
- `images/` - Image components
- `list/` - List components
- `modal/` - Modal components
- `pagination/` - Pagination components
- `progress/` - Progress bar components
- `ribbon/` - Ribbon components
- `spinner/` - Spinner/loading components
- `tabs/` - Tab components
- `table/` - Table components
- `toast/` - Toast notification components
- `tooltip/` - Tooltip components
- `videos/` - Video components

#### Common Components (`/src/components/common/`)
- `ComponentCard` - Consistent card wrapper for component showcases
- `PageBreadcrumb` - Breadcrumb navigation
- `PageMeta` - SEO meta tags
- `ConfirmDialog` - Confirmation dialogs
- `FormModal` - Form modals (when available)

### 5. **Styling Guidelines**
- Use Tailwind CSS classes exclusively
- 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
2. Documented in an approved feature request
3. No existing component can be adapted or extended

### 7. **Checking for Existing Components**
Before implementing any UI element:
1. Search existing components in `/src/components/ui/`
2. Check common components in `/src/components/common/`
3. Review existing UI Elements pages for patterns
4. Check if similar functionality exists in other modules

---

## 📝 Typography Scale

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 |
|-------|------|-------------|----------|
| `--text-title-2xl` | 72px | 90px | Hero sections only |
| `--text-title-xl` | 60px | 72px | Landing page headings |
| `--text-title-lg` | 48px | 60px | Major section headers |
| `--text-title-md` | 36px | 44px | Page titles |
| `--text-title-sm` | 30px | 38px | Section subtitles |

### Theme Sizes (for body text)
| Token | Size | Line Height | Use Case |
|-------|------|-------------|----------|
| `--text-theme-xl` | 20px | 30px | Large body text, intro paragraphs |
| `--text-theme-sm` | 14px | 20px | Standard body text, menu items |
| `--text-theme-xs` | 12px | 18px | Small text, labels, captions |

### Usage in Tailwind
```tsx
// Use Tailwind utilities mapped to tokens
<h1 className="text-title-md">Page Title</h1>
<p className="text-theme-sm">Body text</p>
<span className="text-theme-xs">Caption</span>

// Or use the custom utility classes
<h2 className="text-2xl font-semibold">Section Title</h2>
<p className="text-base">Body text</p>
```

### Font Weights
- `font-normal` (400) - Body text
- `font-medium` (500) - Labels, menu items
- `font-semibold` (600) - Headings, emphasis
- `font-bold` (700) - Strong emphasis

---

## 🎨 Module Colors

Module-specific colors are defined in `src/config/colors.config.ts`:

| Module | Primary Color | Usage |
|--------|---------------|-------|
| 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 |
| Publisher | `warning-500` (amber) | Calendar, scheduling |
| Billing | `purple-500` | Credit displays |

```tsx
import { MODULE_COLORS } from '@/config/colors.config';

// Use in components
<div className={MODULE_COLORS.keywords.bg}>Keywords Section</div>
<span className={MODULE_COLORS.clusters.text}>Cluster Label</span>
```

---

**Last Updated**: January 3, 2026
**Status**: Active Design System Rules - 🔒 LOCKED

---

## 🚨 MANDATORY COMPONENT & STYLING RULES

> **FOR ALL DEVELOPERS AND AI AGENTS**: This section defines the ONLY allowed sources for components, styling, and colors. Violating these rules will result in inconsistent UI and technical debt.

### ALLOWED COMPONENT SOURCES

**ONLY import components from these locations:**

| Category | Allowed Path | Components |
|----------|--------------|------------|
| **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` | All SVG icons (local icons only - external libraries disabled) |
| **Templates** | `@/templates/` | TablePageTemplate, ContentViewTemplate |

### BANNED IMPORTS (DO NOT USE)

```tsx
// ❌ BANNED - Material UI
import { Button, Dialog, Alert, Box } from '@mui/material';
import { SomeIcon } from '@mui/icons-material';

// ❌ BANNED - Chakra UI
import { Button } from '@chakra-ui/react';

// ❌ BANNED - Ant Design
import { Button } from 'antd';

// ❌ BANNED - Custom inline components
const MyButton = () => <button className="...">; // If used more than once, create in ui/
```

### ALLOWED CSS/STYLING SOURCES

**ONLY these CSS files should be used:**

| File | Purpose | When to Use |
|------|---------|-------------|
| `src/styles/design-system.css` | ALL design tokens, colors, shadows, typography | Single source - auto-imported via main.tsx |

**DO NOT CREATE OR USE:**
- ❌ `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

### COLOR USAGE RULES

**Allowed Color Methods:**

```tsx
// ✅ Tailwind brand colors (defined in index.css @theme)
className="bg-brand-500 text-brand-600 border-brand-200"
className="bg-success-500 text-warning-600 bg-error-50"
className="bg-gray-100 text-gray-700 border-gray-300"

// ✅ CSS variables from tokens.css
className="bg-[var(--color-primary)]"
style={{ '--accent': 'var(--color-success)' }}

// ✅ Dark mode variants
className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white"
```

**BANNED Color Methods:**

```tsx
// ❌ Hardcoded hex colors
className="bg-[#0693e3]"
className="text-[#ff7a00]"
style={{ color: '#4c1d95' }}

// ❌ Arbitrary Tailwind colors not in tokens
className="bg-[#4c1d95]"

// ❌ Inline SVG fills with hardcoded colors (use currentColor)
<svg fill="#F04438"> // ❌
<svg fill="currentColor" className="text-error-500"> // ✅
```

### COMPONENT-SPECIFIC RULES

#### Button Component
```tsx
// ✅ CORRECT - Use Button from ui/
import Button from '@/components/ui/button/Button';

<Button variant="primary" tone="brand" size="md">
  Click Me
</Button>

// ❌ WRONG
import { Button } from '@mui/material';
<button className="bg-blue-500 px-4 py-2">Click</button> // Use Button component
```

#### Modal/Dialog Component
```tsx
// ✅ CORRECT - Use Modal from ui/
import { Modal } from '@/components/ui/modal';

<Modal isOpen={open} onClose={() => setOpen(false)}>
  <div className="p-6">Modal content</div>
</Modal>

// ❌ WRONG
import { Dialog } from '@mui/material';
```

#### Alert Component
```tsx
// ✅ CORRECT
import Alert from '@/components/ui/alert/Alert';

<Alert variant="success" title="Success" message="Action completed" />

// ❌ WRONG
import { Alert } from '@mui/material';
```

#### Badge Component
```tsx
// ✅ CORRECT
import Badge from '@/components/ui/badge/Badge';

<Badge tone="success" variant="soft">Active</Badge>

// ❌ WRONG
import { Chip } from '@mui/material';
```

### FOLDER STRUCTURE FOR NEW COMPONENTS

If a new component is absolutely necessary:

```
src/components/ui/
├── new-component/
│   ├── NewComponent.tsx    # Main component
│   └── index.ts            # Export barrel
```

**Requirements for new components:**
1. Must be approved in a feature request
2. Must follow existing component patterns (see Button.tsx, Badge.tsx)
3. Must use design tokens for all colors
4. Must support dark mode
5. Must be documented in this file
6. Must NOT duplicate existing functionality

### REFERENCE: PROPERLY STYLED PAGES

**Use these pages as reference for correct styling:**

| Module | Pages | Path |
|--------|-------|------|
| 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

Before merging any PR, verify:

- [ ] No imports from `@mui/material` or `@mui/icons-material`
- [ ] All buttons use `Button` from `ui/button/Button`
- [ ] All modals use `Modal` from `ui/modal`
- [ ] All alerts use `Alert` from `ui/alert/Alert`
- [ ] No hardcoded hex colors (search for `#[0-9a-fA-F]{3,6}`)
- [ ] No new CSS files created
- [ ] Dark mode variants included where needed
- [ ] Component props match design system (tone, variant, size)