From 0e57c50e56d7de64aaa498ba8e05ec4389134f56 Mon Sep 17 00:00:00 2001 From: "IGNY8 VPS (Salman)" Date: Thu, 1 Jan 2026 11:24:18 +0000 Subject: [PATCH] final styling and compoeents refacctor audit plan --- docs/plans/FRONTEND-AUDIT-PLAN.md | 684 +++++++++++++++++++++--------- 1 file changed, 485 insertions(+), 199 deletions(-) diff --git a/docs/plans/FRONTEND-AUDIT-PLAN.md b/docs/plans/FRONTEND-AUDIT-PLAN.md index 802a1a4b..35bf7c30 100644 --- a/docs/plans/FRONTEND-AUDIT-PLAN.md +++ b/docs/plans/FRONTEND-AUDIT-PLAN.md @@ -1,192 +1,408 @@ -# Frontend Standardization Audit Plan +# Frontend Complete Refactoring & Standardization Plan -## 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. +## 🎯 Objective + +**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={{ }}) -grep -rn "style={{" src/pages/ src/components/ --include="*.tsx" > audit-results/inline-styles.txt +## 🎨 Color Architecture: 6 Primary Colors Only -# 2. Find ALL sx={{ }} (MUI-style inline) -grep -rn "sx={{" src/pages/ src/components/ --include="*.tsx" > audit-results/sx-styles.txt +### Why Only 6 Primary Hex Colors? -# 3. Find ALL hardcoded hex colors -grep -rn "#[0-9a-fA-F]\{3,6\}" src/pages/ src/components/ --include="*.tsx" > audit-results/hardcoded-hex.txt +1. **Dynamic Theming**: Users can customize theme colors in the frontend +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 -grep -rn "rgb\|rgba" src/pages/ src/components/ --include="*.tsx" > audit-results/rgb-colors.txt +### The 6 Primary Color Tokens (ONLY THESE USE HEX) -# 5. Find ALL non-standard gray classes (should use design tokens) -grep -rn "gray-[0-9]\{2,3\}" src/pages/ src/components/ --include="*.tsx" > audit-results/gray-classes.txt +```css +: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) -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 +### ALL Other Colors MUST Derive From These 6 -# 7. Find ALL external UI library imports -grep -rn "from '@mui\|from 'lucide-react\|from '@chakra\|from 'antd" src/pages/ src/components/ --include="*.tsx" > audit-results/external-imports.txt +```css +/* ✅ 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) -grep -rn "const [A-Z][a-zA-Z]* = \(\)" src/pages/ --include="*.tsx" > audit-results/inline-components.txt +--color-brand-500: var(--color-primary); +--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 -grep -L "from.*components/ui" src/pages/**/*.tsx > audit-results/missing-ui-imports.txt +/* ❌ WRONG - Hardcoded hex for variants */ +--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) -grep -rn " audit-results/button-usage.txt +### Color Derivation Rules + +| 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 | -|----------|-------|--------|------------| -| 1 | Account | `pages/account/` | ~6 | -| 2 | Settings | `pages/Settings/` | ~10 | -| 3 | Sites | `pages/Sites/` | ~8 | +```bash +# Create audit results folder +mkdir -p /data/app/igny8/frontend/audit-results + +# ===================================================== +# 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 " +# 2. No inline styles +grep -rn "style={{" src/pages/ src/components/ --include="*.tsx" | wc -l + +# 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:** -```tsx -import { Modal } from '../../components/ui/modal'; +### 7.2 Visual Verification - - {/* content */} - +- [ ] All pages render correctly (no broken styles) +- [ ] Light mode works properly +- [ ] 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 -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'; - + + +// ❌ WRONG +import { Button } from '@mui/material'; +import { Check } from 'lucide-react'; + ``` -**Correct Icon Usage:** -```tsx -import { CheckCircleIcon, ErrorIcon } from '../../icons'; +### Where Hex Values ARE Allowed - +```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 -# 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 -``` +## 🎯 Design Consistency Goals -### 7.2 Visual Verification -- [ ] Check each page in browser (light mode) -- [ ] Check each page in browser (dark mode) -- [ ] Verify all buttons look consistent -- [ ] Verify all modals look consistent -- [ ] Verify all forms look consistent -- [ ] Verify all colors match brand palette +### The "One Designer" Principle + +The entire application must look like it was designed and built by **ONE person**: + +| Aspect | Requirement | +|--------|-------------| +| **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 `