Consolidate docs: move design/docs files to docs folder
- Moved DESIGN-GUIDE.md → docs/30-FRONTEND/DESIGN-GUIDE.md - Moved frontend/DESIGN_SYSTEM.md → docs/30-FRONTEND/DESIGN-TOKENS.md - Moved IGNY8-APP.md → docs/00-SYSTEM/IGNY8-APP.md - Moved fixes-kb.md → docs/90-REFERENCE/FIXES-KB.md - Moved FINAL_PRELAUNCH.md → docs/plans/FINAL-PRELAUNCH.md - Updated all references in .rules, README.md, docs/INDEX.md - Updated ESLint plugin documentation comments - Root folder now only contains: .rules, CHANGELOG.md, README.md
This commit is contained in:
IGNY8 VPS (Salman)
241
docs/30-FRONTEND/DESIGN-GUIDE.md
Normal file
241
docs/30-FRONTEND/DESIGN-GUIDE.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# IGNY8 Design System Guide
|
||||
|
||||
> **Single Source of Truth for UI Components**
|
||||
>
|
||||
> 🔒 **STYLE LOCKED** - This design system is enforced by ESLint. All frontend code must comply.
|
||||
|
||||
**Last Updated:** January 2, 2026
|
||||
|
||||
---
|
||||
|
||||
## Quick Links
|
||||
|
||||
| Resource | Path | Description |
|
||||
|----------|------|-------------|
|
||||
| **Component System** | [COMPONENT-SYSTEM.md](COMPONENT-SYSTEM.md) | Full component reference with props, examples, and usage |
|
||||
| **Design Tokens Doc** | [DESIGN-TOKENS.md](DESIGN-TOKENS.md) | Detailed token documentation |
|
||||
| **ESLint Plugin** | `frontend/eslint/` | Custom rules enforcing design system |
|
||||
| **Live Demo** | `/ui-elements` route | Interactive component showcase |
|
||||
| **CSS Tokens** | `frontend/src/styles/design-system.css` | CSS variables source file |
|
||||
| **Icons** | `frontend/src/icons/` | All SVG icons |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Color System (CRITICAL!)
|
||||
|
||||
### Only 6 Base Colors in Entire System
|
||||
|
||||
All colors derive from 6 primary hex values defined in `design-system.css`:
|
||||
|
||||
| Token | Hex | Purpose |
|
||||
|-------|-----|---------|
|
||||
| `--color-primary` | #0077B6 | Brand Blue - main CTA, links |
|
||||
| `--color-success` | #2CA18E | Success Green - confirmations |
|
||||
| `--color-warning` | #D9A12C | Warning Amber - alerts |
|
||||
| `--color-danger` | #A12C40 | Danger Red - errors, destructive |
|
||||
| `--color-purple` | #2C40A1 | Purple - premium features |
|
||||
| `--color-gray-base` | #667085 | Neutral gray - text, borders |
|
||||
|
||||
### Tailwind Color Utilities
|
||||
|
||||
**⚠️ Tailwind default colors are DISABLED!** Only use:
|
||||
|
||||
```css
|
||||
/* ✅ AVAILABLE */
|
||||
brand-50 through brand-950 /* Primary blue scale */
|
||||
gray-25 through gray-950 /* Neutral scale */
|
||||
success-25 through success-950 /* Green scale */
|
||||
error-25 through error-950 /* Red scale */
|
||||
warning-25 through warning-950 /* Amber scale */
|
||||
purple-25 through purple-950 /* Purple scale */
|
||||
|
||||
/* ❌ DISABLED - These will NOT work */
|
||||
blue-*, red-*, green-*, emerald-*, amber-*, indigo-*,
|
||||
pink-*, rose-*, sky-*, teal-*, cyan-*, etc.
|
||||
```
|
||||
|
||||
### Usage Examples
|
||||
|
||||
```tsx
|
||||
// ✅ CORRECT
|
||||
<div className="bg-brand-500 text-white">Primary Button</div>
|
||||
<div className="text-gray-700 bg-gray-50">Card content</div>
|
||||
<Badge tone="success">Active</Badge>
|
||||
<Alert variant="error" message="Failed" />
|
||||
|
||||
// ❌ WRONG
|
||||
<div className="bg-blue-500">...</div> // Default blue disabled
|
||||
<div className="bg-[#0693e3]">...</div> // Hardcoded hex
|
||||
<div style={{ color: '#ff0000' }}>...</div> // Inline style
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Use Components, Never Raw HTML
|
||||
|
||||
```tsx
|
||||
// ❌ NEVER
|
||||
<button className="...">Click</button>
|
||||
<input type="text" className="..." />
|
||||
<select className="...">...</select>
|
||||
<textarea className="..."></textarea>
|
||||
|
||||
// ✅ ALWAYS
|
||||
<Button variant="primary">Click</Button>
|
||||
<InputField type="text" label="Name" />
|
||||
<Select options={options} />
|
||||
<TextArea rows={4} />
|
||||
```
|
||||
|
||||
### 2. Import Icons from Central Location
|
||||
|
||||
```tsx
|
||||
// ❌ NEVER
|
||||
import { XIcon } from '@heroicons/react/24/outline';
|
||||
import { Trash } from 'lucide-react';
|
||||
|
||||
// ✅ ALWAYS
|
||||
import { CloseIcon, TrashBinIcon } from '../../icons';
|
||||
```
|
||||
|
||||
### 3. Consistent Sizing
|
||||
|
||||
```tsx
|
||||
// Icons in buttons/badges
|
||||
<Icon className="w-4 h-4" />
|
||||
|
||||
// Standalone icons
|
||||
<Icon className="w-5 h-5" />
|
||||
|
||||
// Large/header icons
|
||||
<Icon className="w-6 h-6" />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Quick Reference
|
||||
|
||||
| Need | Component | Import |
|
||||
|------|-----------|--------|
|
||||
| Action button | `Button` | `components/ui/button/Button` |
|
||||
| Icon-only button | `IconButton` | `components/ui/button/IconButton` |
|
||||
| Text input | `InputField` | `components/form/input/InputField` |
|
||||
| Checkbox | `Checkbox` | `components/form/input/Checkbox` |
|
||||
| Radio | `Radio` | `components/form/input/Radio` |
|
||||
| Dropdown | `Select` | `components/form/Select` |
|
||||
| Multi-line text | `TextArea` | `components/form/input/TextArea` |
|
||||
| Toggle | `Switch` | `components/form/switch/Switch` |
|
||||
| Status label | `Badge` | `components/ui/badge/Badge` |
|
||||
| Container | `Card` | `components/ui/card/Card` |
|
||||
| Popup | `Modal` | `components/ui/modal` |
|
||||
| Loading | `Spinner` | `components/ui/spinner/Spinner` |
|
||||
| Notification | `useToast` | `components/ui/toast/ToastContainer` |
|
||||
|
||||
**→ See [COMPONENT-SYSTEM.md](docs/30-FRONTEND/COMPONENT-SYSTEM.md) for full props and examples**
|
||||
|
||||
---
|
||||
|
||||
## ESLint Enforcement
|
||||
|
||||
### Rules
|
||||
|
||||
| Rule | Level | Action |
|
||||
|------|-------|--------|
|
||||
| `no-raw-button` | warn | Use `Button` or `IconButton` |
|
||||
| `no-raw-input` | warn | Use `InputField`, `Checkbox`, `Radio` |
|
||||
| `no-raw-select` | warn | Use `Select` or `SelectDropdown` |
|
||||
| `no-raw-textarea` | warn | Use `TextArea` |
|
||||
| `no-icon-children` | warn | Use `startIcon`/`endIcon` props instead of icon children |
|
||||
| `no-restricted-imports` | error | Block `@heroicons/*`, `lucide-react`, `@mui/icons-material` |
|
||||
|
||||
### Check Violations
|
||||
|
||||
```bash
|
||||
# Inside container
|
||||
docker exec -it igny8_frontend npm run lint
|
||||
|
||||
# Or directly
|
||||
cd frontend
|
||||
npm run lint
|
||||
```
|
||||
|
||||
### Plugin Location
|
||||
|
||||
The custom ESLint plugin is at: `frontend/eslint/eslint-plugin-igny8-design-system.cjs`
|
||||
|
||||
---
|
||||
|
||||
## For AI Agents
|
||||
|
||||
When working on this codebase:
|
||||
|
||||
1. **Read first**: [docs/30-FRONTEND/COMPONENT-SYSTEM.md](docs/30-FRONTEND/COMPONENT-SYSTEM.md)
|
||||
2. **Never use**: `<button>`, `<input>`, `<select>`, `<textarea>` tags
|
||||
3. **Import icons from**: `src/icons` only
|
||||
4. **Verify after changes**: `npm run lint`
|
||||
5. **Reference pages**: Planner and Writer modules use correct patterns
|
||||
|
||||
### Correct Import Paths
|
||||
|
||||
```tsx
|
||||
// From a page in src/pages/
|
||||
import Button from '../components/ui/button/Button';
|
||||
import IconButton from '../components/ui/button/IconButton';
|
||||
import InputField from '../components/form/input/InputField';
|
||||
import { PlusIcon, CloseIcon } from '../icons';
|
||||
|
||||
// From a component in src/components/
|
||||
import Button from '../../components/ui/button/Button';
|
||||
import { PlusIcon } from '../../icons';
|
||||
|
||||
// From a nested component
|
||||
// Adjust ../ based on depth
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
frontend/
|
||||
├── eslint/
|
||||
│ └── eslint-plugin-igny8-design-system.cjs # Custom rules
|
||||
├── src/
|
||||
│ ├── components/
|
||||
│ │ ├── ui/ # Display components
|
||||
│ │ │ ├── button/ # Button, IconButton
|
||||
│ │ │ ├── badge/ # Badge
|
||||
│ │ │ ├── card/ # Card
|
||||
│ │ │ ├── modal/ # Modal
|
||||
│ │ │ └── ...
|
||||
│ │ └── form/ # Form components
|
||||
│ │ ├── input/ # InputField, Checkbox, Radio, TextArea
|
||||
│ │ ├── switch/ # Switch
|
||||
│ │ ├── Select.tsx
|
||||
│ │ └── ...
|
||||
│ ├── icons/ # All SVG icons
|
||||
│ │ └── index.ts # Export all icons
|
||||
│ └── styles/
|
||||
│ └── design-system.css # Design tokens
|
||||
docs/
|
||||
└── 30-FRONTEND/
|
||||
└── COMPONENT-SYSTEM.md # Full component documentation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
When fixing violations:
|
||||
|
||||
- [ ] Replace `<button>` with `Button` or `IconButton`
|
||||
- [ ] Replace `<input type="text/email/password/number">` with `InputField`
|
||||
- [ ] Replace `<input type="checkbox">` with `Checkbox`
|
||||
- [ ] Replace `<input type="radio">` with `Radio`
|
||||
- [ ] Replace `<select>` with `Select` or `SelectDropdown`
|
||||
- [ ] Replace `<textarea>` with `TextArea`
|
||||
- [ ] Replace external icon imports with `src/icons`
|
||||
- [ ] Run `npm run lint` to verify
|
||||
- [ ] Run `npm run build` to confirm no errors
|
||||
392
docs/30-FRONTEND/DESIGN-TOKENS.md
Normal file
392
docs/30-FRONTEND/DESIGN-TOKENS.md
Normal file
@@ -0,0 +1,392 @@
|
||||
# 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
|
||||
|
||||
---
|
||||
|
||||
## 📝 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
|
||||
```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 |
|
||||
|--------|---------------|-------|
|
||||
| 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 |
|
||||
|
||||
```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 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)
|
||||
|
||||
```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/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:**
|
||||
|
||||
```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/` |
|
||||
| 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)
|
||||
Reference in New Issue
Block a user