igny8/frontend/DESIGN_SYSTEM.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

---

Last Updated: Current Session Status: Active Design System Rules