460 lines
15 KiB
Markdown
460 lines
15 KiB
Markdown
# Design System & Component Guidelines
|
|
|
|
**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**: `/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)
|