# 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.

## 🎨 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
- ❌ 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

---

## 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

---

**Last Updated**: Current Session
**Status**: Active Design System Rules