151 lines
5.3 KiB
Markdown
151 lines
5.3 KiB
Markdown
# 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
|