igny8/docs/30-FRONTEND/DESIGN-TOKENS.md

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:

// 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:

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

---

📝 Typography Scale

Typography tokens are defined in index.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

// 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
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
Automation	brand-500	Pipeline cards
Billing	warning-500 (amber)	Credit displays

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 2, 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 or @heroicons/react	All SVG icons
Templates	@/templates/	TablePageTemplate, ContentViewTemplate

BANNED IMPORTS (DO NOT USE)

// ❌ 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/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)

DO NOT CREATE OR USE:

• ❌ styles/global.css - Deprecated
• ❌ 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:

// ✅ 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:

// ❌ 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

// ✅ 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

// ✅ 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

// ✅ CORRECT
import Alert from '@/components/ui/alert/Alert';

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

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

Badge Component

// ✅ 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/
Sites	List, Settings	src/pages/Sites/
Dashboard	Home	src/pages/Dashboard/

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)