salman/igny8
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

final styling and compoeents refacctor audit plan

Browse Source
This commit is contained in:
IGNY8 VPS (Salman)
2026-01-01 11:24:18 +00:00
parent c44d520a7f
commit 0e57c50e56
1 changed files with 485 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files

684
docs/plans/FRONTEND-AUDIT-PLAN.md
View File

@@ -1,192 +1,408 @@
# Frontend Standardization Audit Plan # Frontend Complete Refactoring & Standardization Plan
## Objective ## 🎯 Objective
Systematically audit every page and component to ensure 100% consistency with the design system defined in `DESIGN_SYSTEM.md` and eliminate all non-standard code patterns.
**Completely remove Tailwind default styles** and refactor the entire frontend to use **ONLY** the custom design system defined in `/src/styles/design-system.css`.
### Why This Refactor?
- AI agents keep defaulting to Tailwind's standard colors instead of our custom tokens
- Mixed Tailwind + custom styles cause conflicts and inconsistencies
- No single source of truth - styles scattered across files
- Inline components duplicated across multiple pages
### End Goal
- **Single CSS file** (`design-system.css`) as the ONLY source for all design tokens
- **All colors** come from CSS variables defined in `:root`
- **All components** extracted to `/components/ui/` - NO inline component definitions
- **Zero Tailwind default colors** - only our custom palette (brand, success, error, warning, purple, gray)
--- ---
## Phase 1: Automated Detection Scripts ## 📂 Single Source of Truth: `/src/styles/design-system.css`
### 1.1 Run These Detection Commands This file contains:
- **Section 1**: Design Tokens (CSS Variables) - colors, radius, shadows, gradients
- **Section 2**: Dark Mode Overrides
- **Section 3**: Tailwind Configuration (DEFAULT COLORS DISABLED)
- **Section 4**: Base Styles
- **Section 5**: Component Utilities
- **Section 6**: Form Element Styles
- **Section 7**: Table Styles
- **Section 8**: Header Metrics
- **Section 9**: Badge Styles
- **Section 10-13**: Library overrides, utilities, animations
```bash ---
# Save all results to audit-results/ folder
mkdir -p /data/app/igny8/frontend/audit-results
# 1. Find ALL inline styles (style={{ }}) ## 🎨 Color Architecture: 6 Primary Colors Only
grep -rn "style={{" src/pages/ src/components/ --include="*.tsx" > audit-results/inline-styles.txt
# 2. Find ALL sx={{ }} (MUI-style inline) ### Why Only 6 Primary Hex Colors?
grep -rn "sx={{" src/pages/ src/components/ --include="*.tsx" > audit-results/sx-styles.txt
# 3. Find ALL hardcoded hex colors 1. **Dynamic Theming**: Users can customize theme colors in the frontend
grep -rn "#[0-9a-fA-F]\{3,6\}" src/pages/ src/components/ --include="*.tsx" > audit-results/hardcoded-hex.txt 2. **Single Change = Entire System Updates**: Change one primary color → all shades/variants update automatically
3. **Consistency**: Whole app looks designed by ONE person, not scattered/mismatched
4. **Maintainability**: No hunting for hardcoded hex values scattered everywhere
# 4. Find ALL rgb/rgba colors ### The 6 Primary Color Tokens (ONLY THESE USE HEX)
grep -rn "rgb\|rgba" src/pages/ src/components/ --include="*.tsx" > audit-results/rgb-colors.txt
# 5. Find ALL non-standard gray classes (should use design tokens) ```css
grep -rn "gray-[0-9]\{2,3\}" src/pages/ src/components/ --include="*.tsx" > audit-results/gray-classes.txt :root {
/* ===== THE ONLY 6 HEX VALUES IN THE ENTIRE SYSTEM ===== */
--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 Base */
}
```
# 6. Find ALL blue/red/green direct Tailwind (should use brand/success/error) ### ALL Other Colors MUST Derive From These 6
grep -rn "bg-blue-\|text-blue-\|border-blue-\|bg-red-\|text-red-\|bg-green-\|text-green-" src/pages/ src/components/ --include="*.tsx" > audit-results/direct-colors.txt
# 7. Find ALL external UI library imports ```css
grep -rn "from '@mui\|from 'lucide-react\|from '@chakra\|from 'antd" src/pages/ src/components/ --include="*.tsx" > audit-results/external-imports.txt /* ✅ CORRECT - Derived from primary tokens */
--color-primary-dark: color-mix(in srgb, var(--color-primary) 80%, black);
--color-primary-light: color-mix(in srgb, var(--color-primary) 60%, white);
--color-primary-subtle: color-mix(in srgb, var(--color-primary) 8%, white);
# 8. Find ALL inline component definitions (const Component = () => inside pages) --color-brand-500: var(--color-primary);
grep -rn "const [A-Z][a-zA-Z]* = \(\)" src/pages/ --include="*.tsx" > audit-results/inline-components.txt --color-brand-600: color-mix(in srgb, var(--color-primary) 85%, black);
--color-brand-400: color-mix(in srgb, var(--color-primary) 75%, white);
/* ... all shades computed from the primary */
# 9. Find files NOT importing from ui/ folder /* ❌ WRONG - Hardcoded hex for variants */
grep -L "from.*components/ui" src/pages/**/*.tsx > audit-results/missing-ui-imports.txt --color-primary-dark: #005A8C; /* NO! Must derive from --color-primary */
--color-brand-600: #0369a1; /* NO! Must use color-mix() */
```
# 10. Find duplicate button patterns (custom buttons instead of Button component) ### Color Derivation Rules
grep -rn "<button\|<Button " src/pages/ --include="*.tsx" > audit-results/button-usage.txt
| Shade | Derivation Formula |
|-------|-------------------|
| `*-25` | `color-mix(in srgb, var(--color-*) 3%, white)` |
| `*-50` | `color-mix(in srgb, var(--color-*) 8%, white)` |
| `*-100` | `color-mix(in srgb, var(--color-*) 15%, white)` |
| `*-200` | `color-mix(in srgb, var(--color-*) 25%, white)` |
| `*-300` | `color-mix(in srgb, var(--color-*) 40%, white)` |
| `*-400` | `color-mix(in srgb, var(--color-*) 60%, white)` |
| `*-500` | `var(--color-*)` (the primary itself) |
| `*-600` | `color-mix(in srgb, var(--color-*) 85%, black)` |
| `*-700` | `color-mix(in srgb, var(--color-*) 70%, black)` |
| `*-800` | `color-mix(in srgb, var(--color-*) 55%, black)` |
| `*-900` | `color-mix(in srgb, var(--color-*) 40%, black)` |
| `*-950` | `color-mix(in srgb, var(--color-*) 25%, black)` |
### Future Theming Support
When user selects a theme, we only change these 6 values:
```javascript
// Theme switcher (future feature)
document.documentElement.style.setProperty('--color-primary', '#NEW_HEX');
document.documentElement.style.setProperty('--color-success', '#NEW_HEX');
// ... and the ENTIRE app updates automatically!
``` ```
--- ---
## Phase 2: Manual Page-by-Page Audit Checklist ## Phase 1: Audit Detection Scripts
### 2.1 Page Groups to Audit (in order) ### 1.1 Run These Detection Commands
| Priority | Group | Folder | Est. Files | ```bash
|----------|-------|--------|------------| # Create audit results folder
| 1 | Account | `pages/account/` | ~6 | mkdir -p /data/app/igny8/frontend/audit-results
| 2 | Settings | `pages/Settings/` | ~10 |
| 3 | Sites | `pages/Sites/` | ~8 | # =====================================================
# STYLE VIOLATIONS - Must be 0 after refactor
# =====================================================
# 1. ALL inline styles (style={{)
grep -rn "style={{" src/pages/ src/components/ --include="*.tsx" > audit-results/01-inline-styles.txt
echo "Inline styles found: $(wc -l < audit-results/01-inline-styles.txt)"
# 2. ALL hardcoded hex colors in className (text-[#xxx], bg-[#xxx])
grep -rn "\[#[0-9a-fA-F]\{3,6\}\]" src/pages/ src/components/ --include="*.tsx" > audit-results/02-hardcoded-hex-class.txt
echo "Hardcoded hex in className: $(wc -l < audit-results/02-hardcoded-hex-class.txt)"
# 3. ALL hardcoded hex colors anywhere (outside CSS)
grep -rn "#[0-9a-fA-F]\{6\}" src/pages/ src/components/ --include="*.tsx" > audit-results/03-hardcoded-hex-all.txt
echo "Hardcoded hex anywhere: $(wc -l < audit-results/03-hardcoded-hex-all.txt)"
# 4. ALL rgb/rgba inline values
grep -rn "rgba\?(" src/pages/ src/components/ --include="*.tsx" > audit-results/04-rgb-values.txt
echo "RGB/RGBA values: $(wc -l < audit-results/04-rgb-values.txt)"
# 5. TAILWIND DEFAULT COLORS (should NOT exist - we disabled them)
grep -rn "bg-blue-\|text-blue-\|border-blue-\|bg-red-\|text-red-\|border-red-\|bg-green-\|text-green-\|border-green-\|bg-yellow-\|text-yellow-\|bg-emerald-\|text-emerald-\|bg-indigo-\|text-indigo-\|bg-pink-\|text-pink-\|bg-rose-\|text-rose-\|bg-amber-\|text-amber-\|bg-cyan-\|text-cyan-\|bg-teal-\|text-teal-\|bg-violet-\|text-violet-\|bg-fuchsia-\|text-fuchsia-\|bg-lime-\|text-lime-\|bg-orange-\|text-orange-\|bg-sky-\|text-sky-\|bg-slate-\|text-slate-\|bg-zinc-\|text-zinc-\|bg-neutral-\|text-neutral-\|bg-stone-\|text-stone-" src/pages/ src/components/ --include="*.tsx" > audit-results/05-tailwind-default-colors.txt
echo "Tailwind default colors: $(wc -l < audit-results/05-tailwind-default-colors.txt)"
# =====================================================
# COMPONENT VIOLATIONS
# =====================================================
# 6. External UI library imports (MUI, Chakra, Ant, etc.)
grep -rn "from '@mui\|from '@chakra\|from 'antd\|from '@headlessui\|from '@radix" src/pages/ src/components/ --include="*.tsx" > audit-results/06-external-ui-imports.txt
echo "External UI imports: $(wc -l < audit-results/06-external-ui-imports.txt)"
# 7. lucide-react imports (should use /icons/)
grep -rn "from 'lucide-react" src/pages/ src/components/ --include="*.tsx" > audit-results/07-lucide-imports.txt
echo "Lucide imports: $(wc -l < audit-results/07-lucide-imports.txt)"
# 8. Inline component definitions (const ComponentName = () => { inside pages)
grep -rn "const [A-Z][a-zA-Z]*\s*=\s*(" src/pages/ --include="*.tsx" > audit-results/08-inline-components.txt
echo "Inline component definitions: $(wc -l < audit-results/08-inline-components.txt)"
# 9. Raw HTML buttons (should use Button component)
grep -rn "<button " src/pages/ --include="*.tsx" > audit-results/09-raw-buttons.txt
echo "Raw HTML buttons: $(wc -l < audit-results/09-raw-buttons.txt)"
# 10. Raw HTML selects (should use standard Select)
grep -rn "<select " src/pages/ --include="*.tsx" > audit-results/10-raw-selects.txt
echo "Raw HTML selects: $(wc -l < audit-results/10-raw-selects.txt)"
# 11. Raw HTML inputs without standard classes
grep -rn "<input " src/pages/ --include="*.tsx" > audit-results/11-raw-inputs.txt
echo "Raw HTML inputs: $(wc -l < audit-results/11-raw-inputs.txt)"
# =====================================================
# SUMMARY
# =====================================================
echo ""
echo "====== AUDIT SUMMARY ======"
echo "Run these counts after refactoring - ALL should be 0:"
echo " 01-inline-styles.txt"
echo " 02-hardcoded-hex-class.txt"
echo " 05-tailwind-default-colors.txt"
echo " 06-external-ui-imports.txt"
echo " 07-lucide-imports.txt"
echo " 08-inline-components.txt (review - extract to /components/)"
```
---
## Phase 2: Color System Standardization
### 2.1 The 6 Primary Color Tokens (ONLY HEX ALLOWED)
| Token | Hex Value | Purpose |
|-------|-----------|---------|
| `--color-primary` | `#0077B6` | Brand/Primary actions |
| `--color-success` | `#00B894` | Success states |
| `--color-warning` | `#F59E0B` | Warning states |
| `--color-danger` | `#DC2626` | Error/Danger states |
| `--color-purple` | `#7C3AED` | Premium/Special features |
| `--color-gray-base` | `#667085` | Neutral base for grays |
### 2.2 Allowed Color Classes (ALL derived from 6 primaries)
| Color Category | Tailwind Classes | CSS Variable Base |
|----------------|------------------|-------------------|
| **Primary/Brand** | `brand-25` to `brand-950` | `--color-primary` |
| **Gray/Neutral** | `gray-25` to `gray-950` | `--color-gray-base` |
| **Success** | `success-25` to `success-950` | `--color-success` |
| **Error** | `error-25` to `error-950` | `--color-danger` |
| **Warning** | `warning-25` to `warning-950` | `--color-warning` |
| **Purple** | `purple-25` to `purple-950` | `--color-purple` |
### 2.3 BANNED - Hardcoded Hex Values
**ZERO hardcoded hex values allowed in:**
- TSX/JSX files
- Component files
- Page files
- Inline styles
**ONLY place hex values exist:** The 6 primary tokens in `design-system.css`
### 2.4 BANNED - Tailwind Default Colors (DISABLED)
These are explicitly disabled and should NEVER appear:
```
❌ blue-*, red-*, green-*, emerald-*, teal-*, cyan-*, sky-*
❌ indigo-*, violet-*, fuchsia-*, pink-*, rose-*
❌ amber-*, yellow-*, lime-*, orange-*
❌ slate-*, zinc-*, neutral-*, stone-*
```
### 2.5 Color Replacement Map
| ❌ Wrong | ✅ Correct |
|----------|-----------|
| `bg-blue-500`, `text-blue-500` | `bg-brand-500`, `text-brand-500` |
| `bg-red-500`, `text-red-500` | `bg-error-500`, `text-error-500` |
| `bg-green-500`, `text-green-500` | `bg-success-500`, `text-success-500` |
| `bg-yellow-500`, `text-yellow-500` | `bg-warning-500`, `text-warning-500` |
| `bg-indigo-500`, `text-indigo-500` | `bg-purple-500`, `text-purple-500` |
| `#0693e3` (hardcoded) | `var(--color-primary)` or `text-brand-500` |
| `#10B981` (hardcoded) | `var(--color-success)` or `text-success-500` |
| `#EF4444` (hardcoded) | `var(--color-danger)` or `text-error-500` |
| `style={{ color: '#xxx' }}` | Use CSS class from design system |
| `bg-[#XXXXXX]` | Use design token class |
---
## Phase 3: Component Extraction & Standardization
### 3.1 Rules for Components
1. **NO inline component definitions** in page files
2. **Any component used in 2+ places** → Extract to `/components/`
3. **All components** use ONLY CSS classes from `design-system.css`
4. **No component-level inline styles**
### 3.2 Standard Component Location
| Component Type | Location | Notes |
|----------------|----------|-------|
| Buttons | `/components/ui/button/` | All button variants |
| Modals/Dialogs | `/components/ui/modal/` | All popup overlays |
| Alerts/Notifications | `/components/ui/alert/` | All status messages |
| Badges/Tags | `/components/ui/badge/` | All labels/chips |
| Dropdowns | `/components/ui/dropdown/` | All select menus |
| Forms | `/components/ui/form/` | Inputs, selects, checkboxes |
| Cards | `/components/ui/card/` | Card containers |
| Tables | `/components/ui/table/` | Data tables |
| Tabs | `/components/ui/tabs/` | Tab interfaces |
| Spinners/Loading | `/components/ui/spinner/` | Loading states |
| Tooltips | `/components/ui/tooltip/` | Hover info |
| Progress | `/components/ui/progress/` | Progress bars |
### 3.3 Inline Components to Extract
Search pattern: `const [A-Z][a-zA-Z]* = (` in `/pages/`
For each found:
1. Check if similar exists in `/components/ui/`
2. If used in multiple pages → Extract to appropriate folder
3. If page-specific → Keep but move to bottom of file or separate file in same folder
---
## Phase 4: Styling Classes Standardization
### 4.1 Standard CSS Classes (from design-system.css)
**Menu Items:**
```css
.menu-item /* Base menu item */
.menu-item-active /* Active state */
.menu-item-inactive /* Inactive state */
.menu-item-icon-size /* Icon sizing */
```
**Form Elements:**
```css
.igny8-select-styled /* Styled select dropdown */
.tableCheckbox /* Table checkbox */
```
**Tables:**
```css
.igny8-table-compact /* Compact table */
.igny8-table-container /* Table wrapper with min-height */
.igny8-table-wrapper /* Scrollable table wrapper */
.igny8-table-smooth /* Smooth transitions */
.igny8-data-row /* Animated data row */
```
**Header Metrics:**
```css
.igny8-header-metrics /* Metrics bar container */
.igny8-header-metric /* Single metric */
.igny8-header-metric-label
.igny8-header-metric-value
.igny8-header-metric-accent
```
### 4.2 Shadow Classes
Use these instead of Tailwind defaults:
```
shadow-theme-xs, shadow-theme-sm, shadow-theme-md, shadow-theme-lg, shadow-theme-xl
```
### 4.3 Typography Classes
```
text-title-2xl, text-title-xl, text-title-lg, text-title-md, text-title-sm
text-theme-xl, text-theme-sm, text-theme-xs
```
---
## Phase 5: Page-by-Page Audit Checklist
### 5.1 Audit Order (by priority)
| # | Module | Folder | Est. Files |
|---|--------|--------|------------|
| 1 | Account Settings | `pages/account/` | ~6 |
| 2 | Site Settings | `pages/Settings/` | ~10 |
| 3 | Sites Management | `pages/Sites/` | ~8 |
| 4 | Writer | `pages/Writer/` | ~5 | | 4 | Writer | `pages/Writer/` | ~5 |
| 5 | Planner | `pages/Planner/` | ~3 | | 5 | Planner | `pages/Planner/` | ~3 |
| 6 | Automation | `pages/Automation/` | ~2 | | 6 | Automation | `pages/Automation/` | ~2 |
| 7 | Optimizer | `pages/Optimizer/` | ~3 | | 7 | Optimizer | `pages/Optimizer/` | ~3 |
| 8 | Billing | `pages/Billing/` | ~4 | | 8 | Billing | `pages/Billing/` | ~4 |
| 9 | Other | Remaining pages | ~10+ | | 9 | Dashboard | `pages/Dashboard/` | ~2 |
| 10 | Other Pages | Remaining | ~10+ |
### 2.2 Per-Page Audit Checklist ### 5.2 Per-File Audit Checklist
For EACH `.tsx` file, check: For EACH `.tsx` file:
#### A. IMPORTS (Lines 1-30) #### A. IMPORTS ✓
- [ ] No imports from `@mui/material` or `@mui/icons-material` - [ ] NO `@mui/*` imports
- [ ] No imports from `lucide-react` (use `../../icons` instead) - [ ] NO `lucide-react` imports (use `/icons/`)
- [ ] No imports from `@chakra-ui`, `antd`, or other UI libraries - [ ] NO `@chakra-ui`, `antd`, `@headlessui`, `@radix-ui`
- [ ] Uses `Button` from `components/ui/button/Button` - [ ] All icons from `/icons/` folder
- [ ] Uses `Modal` from `components/ui/modal` - [ ] All UI components from `/components/ui/`
- [ ] Uses `Alert` from `components/ui/alert/Alert`
- [ ] Uses `Badge` from `components/ui/badge/Badge`
- [ ] Uses `Dropdown` from `components/ui/dropdown/Dropdown`
- [ ] Uses `Spinner` from `components/ui/spinner/Spinner`
- [ ] Uses `Tooltip` from `components/ui/tooltip/Tooltip`
- [ ] Uses icons from `../../icons` or `@/icons`
#### B. INLINE STYLES (Search entire file) #### B. COLORS ✓
- [ ] No `style={{` patterns - [ ] NO Tailwind default colors (blue-*, red-*, green-*, etc.)
- [ ] No `sx={{` patterns - [ ] NO hardcoded hex (`#XXXXXX`)
- [ ] No inline `className` with hardcoded hex (e.g., `text-[#xxx]`) - [ ] NO hardcoded rgb/rgba
- [ ] NO inline color styles (`style={{ color: '...' }}`)
- [ ] ONLY uses: brand-*, gray-*, success-*, error-*, warning-*, purple-*
#### C. COLOR USAGE (Search entire file) #### C. STYLES ✓
- [ ] No hardcoded hex colors (`#XXXXXX`) - [ ] NO `style={{` patterns
- [ ] No `rgb()` or `rgba()` values - [ ] NO `sx={{` patterns
- [ ] No direct Tailwind colors: `blue-500`, `red-500`, `green-500` - [ ] All styles via CSS classes from design-system.css
- [ ] Uses design tokens: `brand-500`, `success-500`, `error-500`, `warning-500` - [ ] Dark mode handled via CSS variables (automatic)
- [ ] Gray scale uses: `gray-50` through `gray-900` (these ARE allowed)
#### D. COMPONENT PATTERNS #### D. COMPONENTS ✓
- [ ] No inline component definitions (components defined inside the page file) - [ ] NO inline component definitions (extract to /components/)
- [ ] No duplicate code that exists in `components/ui/` - [ ] NO raw `<button>` elements (use Button component)
- [ ] No custom button implementations (use `Button` component) - [ ] NO custom modal implementations (use Modal)
- [ ] No custom modal implementations (use `Modal` component) - [ ] NO custom alert/toast (use Alert)
- [ ] No custom alert/toast implementations (use `Alert` component) - [ ] NO custom dropdown (use Dropdown)
- [ ] No custom dropdown implementations (use `Dropdown` component)
#### E. DARK MODE SUPPORT #### E. FORMS ✓
- [ ] All backgrounds have dark mode variant: `bg-white dark:bg-gray-900` - [ ] Inputs use standard pattern
- [ ] All text colors have dark mode: `text-gray-900 dark:text-white` - [ ] Selects use `.igny8-select-styled` or standard Select component
- [ ] All borders have dark mode: `border-gray-200 dark:border-gray-700` - [ ] Checkboxes use standard pattern
- [ ] Form labels consistent
#### F. FORM ELEMENTS
- [ ] Input fields use consistent styling pattern
- [ ] Select dropdowns use consistent styling pattern
- [ ] Checkboxes/radios use consistent styling pattern
- [ ] Form labels use consistent styling pattern
--- ---
## Phase 3: Component Audit ## Phase 6: Execution Tracker
### 3.1 Standard Components Inventory ### 6.1 Page Audit Progress
These are the ONLY allowed UI component sources: | File | Audited | Issues | Fixed | Verified |
|------|---------|--------|-------|----------|
| Component | Import Path | Usage | | **Account Module** |||||
|-----------|------------|-------|
| Button | `components/ui/button/Button` | All buttons |
| Modal | `components/ui/modal` | All modals/dialogs |
| Alert | `components/ui/alert/Alert` | All alerts/notifications |
| Badge | `components/ui/badge/Badge` | All badges/chips/tags |
| Dropdown | `components/ui/dropdown/Dropdown` | All dropdown menus |
| Spinner | `components/ui/spinner/Spinner` | All loading states |
| Tooltip | `components/ui/tooltip/Tooltip` | All tooltips |
| Card | `components/ui/card/*` | All card containers |
| Table | `components/ui/table/*` | All data tables |
| Tabs | `components/ui/tabs/*` | All tab interfaces |
| Progress | `components/ui/progress/*` | All progress bars |
### 3.2 Non-Standard Components to Find & Replace
| Pattern to Find | Replace With |
|----------------|--------------|
| `<button className=...>` | `<Button>` from ui/ |
| `<Dialog>` or `<dialog>` | `<Modal>` from ui/ |
| Custom alert divs | `<Alert>` from ui/ |
| `<Chip>` or chip patterns | `<Badge>` from ui/ |
| Custom loading spinners | `<Spinner>` from ui/ |
| `<Menu>` patterns | `<Dropdown>` from ui/ |
---
## Phase 4: Style Token Mapping
### 4.1 Color Replacements
| Wrong Pattern | Correct Pattern |
|---------------|-----------------|
| `bg-blue-500` | `bg-brand-500` |
| `text-blue-600` | `text-brand-600` |
| `border-blue-200` | `border-brand-200` |
| `bg-green-500` | `bg-success-500` |
| `text-green-600` | `text-success-600` |
| `bg-red-500` | `bg-error-500` |
| `text-red-600` | `text-error-600` |
| `bg-yellow-500` | `bg-warning-500` |
| `text-yellow-600` | `text-warning-600` |
| `#3B82F6` | Use `text-brand-500` or CSS var |
| `#10B981` | Use `text-success-500` or CSS var |
| `#EF4444` | Use `text-error-500` or CSS var |
### 4.2 Allowed Gray Scale (DO NOT REPLACE)
```
gray-25, gray-50, gray-100, gray-200, gray-300, gray-400,
gray-500, gray-600, gray-700, gray-800, gray-900, gray-950
```
---
## Phase 5: Execution Tracking
### 5.1 Audit Progress Tracker
| Page/Component | Audited | Issues Found | Fixed | Verified |
|----------------|---------|--------------|-------|----------|
| `pages/account/Profile.tsx` | ☐ | - | ☐ | ☐ | | `pages/account/Profile.tsx` | ☐ | - | ☐ | ☐ |
| `pages/account/Team.tsx` | ☐ | - | ☐ | ☐ | | `pages/account/Team.tsx` | ☐ | - | ☐ | ☐ |
| `pages/account/Security.tsx` | ☐ | - | ☐ | ☐ | | `pages/account/Security.tsx` | ☐ | - | ☐ | ☐ |
| `pages/account/Preferences.tsx` | ☐ | - | ☐ | ☐ | | `pages/account/Preferences.tsx` | ☐ | - | ☐ | ☐ |
| `pages/account/Notifications.tsx` | ☐ | - | ☐ | ☐ | | `pages/account/Notifications.tsx` | ☐ | - | ☐ | ☐ |
| `pages/account/ApiKeys.tsx` | ☐ | - | ☐ | ☐ | | `pages/account/ApiKeys.tsx` | ☐ | - | ☐ | ☐ |
| **Settings Module** |||||
| `pages/Settings/General.tsx` | ☐ | - | ☐ | ☐ | | `pages/Settings/General.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Settings/Integrations.tsx` | ☐ | - | ☐ | ☐ | | `pages/Settings/Integrations.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Settings/Notifications.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Settings/Publishing.tsx` | ☐ | - | ☐ | ☐ | | `pages/Settings/Publishing.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Settings/ContentDefaults.tsx` | ☐ | - | ☐ | ☐ | | `pages/Settings/ContentDefaults.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Settings/AIModels.tsx` | ☐ | - | ☐ | ☐ | | `pages/Settings/AIModels.tsx` | ☐ | - | ☐ | ☐ |
@@ -194,25 +410,23 @@ gray-500, gray-600, gray-700, gray-800, gray-900, gray-950
| `pages/Settings/SEO.tsx` | ☐ | - | ☐ | ☐ | | `pages/Settings/SEO.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Settings/Categories.tsx` | ☐ | - | ☐ | ☐ | | `pages/Settings/Categories.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Settings/Tags.tsx` | ☐ | - | ☐ | ☐ | | `pages/Settings/Tags.tsx` | ☐ | - | ☐ | ☐ |
| **Sites Module** |||||
| `pages/Sites/SitesList.tsx` | ☐ | - | ☐ | ☐ | | `pages/Sites/SitesList.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Sites/SiteDetail.tsx` | ☐ | - | ☐ | ☐ | | `pages/Sites/SiteDetail.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Sites/SiteSettings.tsx` | ☐ | - | ☐ | ☐ | | `pages/Sites/SiteSettings.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Sites/SiteDashboard.tsx` | ☐ | - | ☐ | ☐ | | `pages/Sites/SiteDashboard.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Sites/CreateSite.tsx` | ☐ | - | ☐ | ☐ | | `pages/Sites/CreateSite.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Sites/ContentCategories.tsx` | ☐ | - | ☐ | ☐ | | **Other Modules** |||||
| `pages/Sites/ContentTags.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Sites/Authors.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Writer/*.tsx` | ☐ | - | ☐ | ☐ | | `pages/Writer/*.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Planner/*.tsx` | ☐ | - | ☐ | ☐ | | `pages/Planner/*.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Automation/*.tsx` | ☐ | - | ☐ | ☐ | | `pages/Automation/*.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Optimizer/*.tsx` | ☐ | - | ☐ | ☐ | | `pages/Optimizer/*.tsx` | ☐ | - | ☐ | ☐ |
| `pages/Billing/*.tsx` | ☐ | - | ☐ | ☐ | | `pages/Billing/*.tsx` | ☐ | - | ☐ | ☐ |
| _Add remaining pages..._ | | | | |
### 5.2 Component Folder Audit ### 6.2 Component Folder Audit
| Component Folder | Audited | Issues | Fixed | | Folder | Audited | Issues | Fixed |
|------------------|---------|--------|-------| |--------|---------|--------|-------|
| `components/ui/button/` | ☐ | - | ☐ | | `components/ui/button/` | ☐ | - | ☐ |
| `components/ui/modal/` | ☐ | - | ☐ | | `components/ui/modal/` | ☐ | - | ☐ |
| `components/ui/alert/` | ☐ | - | ☐ | | `components/ui/alert/` | ☐ | - | ☐ |
@@ -221,85 +435,157 @@ gray-500, gray-600, gray-700, gray-800, gray-900, gray-950
| `components/ui/card/` | ☐ | - | ☐ | | `components/ui/card/` | ☐ | - | ☐ |
| `components/ui/table/` | ☐ | - | ☐ | | `components/ui/table/` | ☐ | - | ☐ |
| `components/ui/tabs/` | ☐ | - | ☐ | | `components/ui/tabs/` | ☐ | - | ☐ |
| `components/ui/form/` | ☐ | - | ☐ |
| `components/common/` | ☐ | - | ☐ | | `components/common/` | ☐ | - | ☐ |
| `components/layout/` | ☐ | - | ☐ | | `components/layout/` | ☐ | - | ☐ |
--- ---
## Phase 6: Reference Pages ## Phase 7: Verification
### 6.1 Gold Standard Pages (Use as Reference) ### 7.1 Zero-Tolerance Verification
These pages are correctly styled and should be used as reference:
- `pages/Planner/Dashboard.tsx` - Correct card layouts
- `pages/Writer/Dashboard.tsx` - Correct table patterns
- `components/ui/*` - All standard components
### 6.2 Reference Patterns After refactoring, these commands should return **0 results**:
**Correct Button Usage:** ```bash
```tsx # 1. No Tailwind default colors
import { Button } from '../../components/ui/button/Button'; grep -rn "bg-blue-\|text-blue-\|bg-red-\|text-red-\|bg-green-\|text-green-\|bg-yellow-\|text-yellow-\|bg-indigo-\|bg-emerald-\|bg-pink-\|bg-rose-" src/pages/ src/components/ --include="*.tsx" | wc -l
<Button variant="primary" tone="brand" size="md"> # 2. No inline styles
Save Changes grep -rn "style={{" src/pages/ src/components/ --include="*.tsx" | wc -l
</Button>
# 3. No hardcoded hex in className
grep -rn "\[#[0-9a-fA-F]\{3,6\}\]" src/pages/ src/components/ --include="*.tsx" | wc -l
# 4. No external UI libraries
grep -rn "from '@mui\|from '@chakra\|from 'antd" src/pages/ src/components/ --include="*.tsx" | wc -l
# 5. No lucide-react direct imports
grep -rn "from 'lucide-react" src/pages/ --include="*.tsx" | wc -l
``` ```
**Correct Modal Usage:** ### 7.2 Visual Verification
```tsx
import { Modal } from '../../components/ui/modal';
<Modal isOpen={isOpen} onClose={onClose} className="max-w-md p-6"> - [ ] All pages render correctly (no broken styles)
{/* content */} - [ ] Light mode works properly
</Modal> - [ ] Dark mode works properly (via `.dark` class)
- [ ] All buttons consistent
- [ ] All forms consistent
- [ ] All tables consistent
- [ ] All modals consistent
- [ ] Brand colors appear correctly
---
## 📋 Quick Reference: Correct Usage Patterns
### Colors (ALL derived from 6 primaries)
```tsx
// ✅ CORRECT - use design token classes (derived from 6 primaries)
className="text-brand-500 bg-brand-50 border-brand-200"
className="text-success-500 bg-success-50"
className="text-error-500 bg-error-50"
className="text-warning-500 bg-warning-50"
className="text-purple-500 bg-purple-50"
className="text-gray-700 bg-gray-100"
// ✅ CORRECT - use CSS variables when needed
className="bg-[var(--color-primary)]"
style={{ '--custom-color': 'var(--color-primary)' }} // Only for CSS custom properties
// ❌ WRONG - Tailwind defaults (DISABLED)
className="text-blue-500 bg-blue-50"
className="text-red-500 bg-green-500"
// ❌ WRONG - Hardcoded hex (NEVER in TSX)
style={{ color: '#0693e3' }}
className="bg-[#0077B6]"
className="text-[#DC2626]"
``` ```
**Correct Alert Usage:** ### Components
```tsx ```tsx
import Alert from '../../components/ui/alert/Alert'; // ✅ CORRECT
import { Button } from '@/components/ui/button/Button';
import { Modal } from '@/components/ui/modal';
import { CheckIcon } from '@/icons';
<Alert variant="success" title="Saved" message="Changes saved successfully" /> <Button variant="primary" tone="brand">Save</Button>
// ❌ WRONG
import { Button } from '@mui/material';
import { Check } from 'lucide-react';
<button className="...">Save</button>
``` ```
**Correct Icon Usage:** ### Where Hex Values ARE Allowed
```tsx
import { CheckCircleIcon, ErrorIcon } from '../../icons';
<CheckCircleIcon className="h-5 w-5 text-success-500" /> ```css
/* ✅ ONLY in design-system.css - the 6 primary tokens */
:root {
--color-primary: #0077B6;
--color-success: #00B894;
--color-warning: #F59E0B;
--color-danger: #DC2626;
--color-purple: #7C3AED;
--color-gray-base: #667085;
}
/* ✅ All other colors derived */
--color-brand-600: color-mix(in srgb, var(--color-primary) 85%, black);
``` ```
--- ---
## Phase 7: Verification ## 🚨 CRITICAL RULES
### 7.1 Final Verification Checklist 1. **6 PRIMARY HEX ONLY**: Only `--color-primary`, `--color-success`, `--color-warning`, `--color-danger`, `--color-purple`, `--color-gray-base` use hex values
2. **ALL SHADES DERIVED**: Every shade (25-950) is computed from primary using `color-mix()`
3. **NO TAILWIND DEFAULTS**: blue-*, red-*, green-*, etc. are DISABLED
4. **NO INLINE STYLES**: Never use `style={{}}` for colors/spacing
5. **NO HARDCODED HEX IN TSX**: All hex lives in design-system.css only
6. **EXTRACT COMPONENTS**: Any UI used 2+ times → `/components/ui/`
7. **USE STANDARD COMPONENTS**: Button, Modal, Alert, Badge from `/components/ui/`
After all fixes are applied, run: ---
```bash ## 🎯 Design Consistency Goals
# Should return 0 results for each:
grep -rn "from '@mui" src/pages/ src/components/ --include="*.tsx" | wc -l
grep -rn "from 'lucide-react" src/pages/ --include="*.tsx" | wc -l
grep -rn "style={{" src/pages/ --include="*.tsx" | wc -l
grep -rn "#[0-9a-fA-F]\{6\}" src/pages/ --include="*.tsx" | wc -l
grep -rn "bg-blue-\|bg-red-\|bg-green-" src/pages/ --include="*.tsx" | wc -l
```
### 7.2 Visual Verification ### The "One Designer" Principle
- [ ] Check each page in browser (light mode)
- [ ] Check each page in browser (dark mode) The entire application must look like it was designed and built by **ONE person**:
- [ ] Verify all buttons look consistent
- [ ] Verify all modals look consistent | Aspect | Requirement |
- [ ] Verify all forms look consistent |--------|-------------|
- [ ] Verify all colors match brand palette | **Colors** | Exact same 6 color palettes everywhere |
| **Spacing** | Consistent padding/margins (use Tailwind spacing scale) |
| **Typography** | Same font sizes, weights, line heights |
| **Borders** | Same border radius, colors, widths |
| **Shadows** | Same shadow tokens everywhere |
| **Buttons** | All use `<Button>` component, same variants |
| **Forms** | All inputs, selects, checkboxes styled identically |
| **Cards** | Same card patterns, padding, borders |
| **Tables** | Same table styles, row heights, headers |
| **Modals** | Same modal structure, animations |
### Visual Consistency Checklist
- [ ] All primary buttons use `bg-brand-500`
- [ ] All success messages use `success-*` palette
- [ ] All error states use `error-*` palette
- [ ] All warning states use `warning-*` palette
- [ ] All premium/special features use `purple-*` palette
- [ ] All neutral backgrounds use `gray-*` palette
- [ ] Border radius consistent (use `--radius-*` tokens)
- [ ] Shadows consistent (use `--shadow-*` tokens)
- [ ] Typography consistent (use `text-theme-*` classes)
--- ---
## Notes ## Notes
- **DO NOT** replace gray-* classes - these are part of the design system - Gray scale (`gray-25` to `gray-950`) is ALLOWED - derived from `--color-gray-base`
- **DO** replace blue/red/green with brand/error/success - Dark mode is handled automatically via CSS variables in `.dark` class
- **DO** replace all inline styles with Tailwind classes - When in doubt, check `design-system.css` for available classes
- **DO** replace all hardcoded hex with CSS variables or Tailwind classes - New utility classes should be added to `design-system.css`, not inline
- **DO** extract inline components to separate files - **Future theming**: Changing 6 primary hex values updates entire app automatically
- **DO** use standard ui/ components instead of custom implementations