diff --git a/CLAUDE.md b/CLAUDE.md index 73755e31..49026feb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,6 +7,7 @@ Before taking any action or writing code, you MUST read the following Single Sou 1. `AI_RULES.md` (Contains your operational constraints, Git rules, and UI fidelity laws). 2. `PROJECT_ARCHITECTURE.md` (Contains the tech stack, data models, and system logic). 3. `dev_docs/SESSION_STATE.md` (Contains the current handover status from the previous AI). +4. `DESIGN_COLOR_RULES.md` (MANDATORY for ALL UI/UX work - No hardcoded Tailwind colors allowed). **STRICT COMMUNICATION RULE:** Be concise! Do not explain a thousand details unless they are absolutely necessary. @@ -15,7 +16,23 @@ Do not proceed with any task until you have analyzed these three files. DO NOT, EVER, USE "uppercase" or "toUpper" in any UI/UX context, nowhere. This SHOULD NOT be used in UI/UX anywhere, no text should be displayed in CAPITAL LETTERS! But do not replace "toUpper" with "toLower" or "uppercase" with "lowercase" either, leave text in UI/UX as is. +## đ¨ CRITICAL COLOR RULE FOR ALL UI/UX WORK + +**NO HARDCODED TAILWIND COLORS ALLOWED** â +- â Never use `bg-green-500`, `text-red-600`, `border-blue-400`, etc. +- â Always use semantic colors from DESIGN.md: `bg-primary`, `text-tertiary`, `bg-error` +- đ **MANDATORY READ:** `DESIGN_COLOR_RULES.md` before ANY frontend code + +**Semantic Color Mapping:** +- â Success/Healthy: `tertiary` (#00e639) +- â Error/Destructive: `error` (#ffb4ab) +- â ī¸ Warning/Caution: `primary` (#ffb781) +- âšī¸ Info/Secondary: `secondary` (#c8c6c5) + +See `DESIGN_COLOR_RULES.md` for complete color mapping and examples. + ## Project-Specific Guidelines - Use TypeScript strict mode - All API endpoints must have tests +- All UI colors MUST follow DESIGN.md (see DESIGN_COLOR_RULES.md) diff --git a/DESIGN_COLOR_RULES.md b/DESIGN_COLOR_RULES.md new file mode 100644 index 00000000..936780a9 --- /dev/null +++ b/DESIGN_COLOR_RULES.md @@ -0,0 +1,277 @@ +# Design System Color Rules - MANDATORY FOR ALL UI/UX + +**Status:** ACTIVE | **Effective:** 2026-04-25 +**Owner:** AI Development Team | **Audience:** All Frontend Developers/AI Agents + +> â ī¸ **CRITICAL RULE:** No hardcoded Tailwind colors are permitted. All UI colors MUST come from `DESIGN.md` color system via tailwind.config.ts or globals.css. + +--- + +## THE RULE + +**NEVER use arbitrary Tailwind colors like:** +- â `bg-green-500`, `text-green-400` +- â `bg-red-600`, `text-rose-500` +- â `bg-blue-500`, `text-indigo-400` +- â `bg-amber-500`, `bg-yellow-400` +- â `bg-sky-500`, `text-cyan-400` +- â Any other standard Tailwind color names + +**ALWAYS use semantic colors from DESIGN.md:** +- â `bg-primary`, `text-primary` +- â `bg-secondary`, `text-secondary` +- â `bg-tertiary`, `text-tertiary` (for success/healthy states) +- â `bg-error`, `text-error` +- â `bg-success`, `text-success` +- â `bg-warning`, `text-warning` +- â `bg-muted`, `text-muted` +- â `border-outline`, `border-outline-variant` + +--- + +## SEMANTIC COLOR MAPPING + +Use these mappings for ALL UI decisions: + +### **Status Indicators** +| Intent | Color | Value | Use Case | +|--------|-------|-------|----------| +| â Success / Healthy | `tertiary` | #00e639 | "Scanner Ready", quantity +, check-in, online status | +| â Error / Destructive | `error` | #ffb4ab | "Delete item", errors, low stock, offline | +| â ī¸ Warning / Caution | `primary` | #ffb781 | "Caution Orange", warnings, important actions | +| âšī¸ Info / Secondary | `secondary` | #c8c6c5 | Secondary actions, hints, disabled text | +| đ Muted / Disabled | `muted` | #474746 | Disabled buttons, placeholder text | + +### **Action Elements** +| Element | Color | Example | +|---------|-------|---------| +| Primary Button | `bg-primary` | "Extract Data", "Create", "Upload" | +| Secondary Button | `bg-secondary` | "Cancel", alternative actions | +| Destructive Button | `bg-error` | "Delete Item", "Discard", "Remove" | +| Button Hover | `hover:opacity-80` | Darken any button on hover | +| Button Focus Ring | `focus:ring-{color}` | Use same color as button | + +### **Data Visualization** +| Data Type | Color | Context | +|-----------|-------|---------| +| Quantity Increased | `text-tertiary` | Stock added, items received | +| Quantity Decreased | `text-error` | Stock removed, items shipped | +| Neutral Change | `text-primary/50` | Muted primary | +| Negative Status | `text-error` | Low stock, missing items | +| Positive Status | `text-tertiary` | Available, in stock | + +### **Action Log Colors** +| Action Type | Color | Rationale | +|------------|-------|-----------| +| CHECK_IN (receive) | `tertiary` | Success/positive action | +| DELETE | `error` | Destructive action | +| TRASH/DISCARD | `error` | Destructive action | +| CREATE | `primary` | Primary/caution action | +| DB (database) | `secondary` | System/info action | +| REMOVE | `primary` | Warning/caution | + +--- + +## TECHNICAL IMPLEMENTATION + +### â CORRECT Examples + +```tsx +// Status indicator - success +
+Scanner: Ready + +// Destructive button + + +// Data change - quantity increased + 0 ? "text-tertiary" : "text-error"}> + {log.quantity_change} + + +// Conditional logic using design system +className={` + ${item.quantity <= minQty ? "text-error" : "text-primary"} + ${isOnline ? "bg-tertiary" : "bg-error"} + focus:ring-${isDestructive ? "error" : "primary"} +`} + +// From globals.css variables +const statusColor = { + "success": "var(--tertiary)", + "error": "var(--error)", + "warning": "var(--primary)" +} +``` + +### â WRONG Examples (DO NOT USE) + +```tsx +// â Hardcoded arbitrary colors + + + +// â Arbitrary Tailwind color names +className="text-amber-500 bg-indigo-500/10 border border-rose-500/20" + +// â Hex colors in className +className="bg-[#4b0082] text-[#ff6b6b]" + +// â Mixing design system with arbitrary colors +className="bg-primary hover:bg-green-500 text-error" +``` + +--- + +## COLOR AVAILABILITY IN TAILWIND + +All DESIGN.md colors are available in `tailwind.config.ts`: + +```typescript +// frontend/tailwind.config.ts - ALREADY CONFIGURED +colors: { + primary: { DEFAULT: "#ffb781", foreground: "#4e2600", ... }, + secondary: { DEFAULT: "#c8c6c5", foreground: "#303030", ... }, + tertiary: { DEFAULT: "#00e639", foreground: "#003907", ... }, + error: { DEFAULT: "#ffb4ab", foreground: "#690005", ... }, + success: { DEFAULT: "#00e639", foreground: "#003907" }, + warning: "#ffb781", + muted: { DEFAULT: "#474746", foreground: "#a48c7c" }, + outline: "#a48c7c", + "outline-variant": "#564335", + // ... all surface, border, background colors +} +``` + +--- + +## CSS VARIABLES (globals.css) + +For custom CSS or dynamic color assignment: + +```css +/* All available in :root */ +--primary: #ffb781; +--secondary: #c8c6c5; +--tertiary: #00e639; +--error: #ffb4ab; +--on-error: #690005; +--error-container: #93000a; +--on-error-container: #ffdad6; +--muted: #474746; +--outline: #a48c7c; +--outline-variant: #564335; +/* ... 50+ more */ +``` + +```tsx +// Usage in React +const statusColor = `var(--${isError ? 'error' : 'tertiary'})` + +``` + +--- + +## ENFORCEMENT RULES FOR AI AGENTS + +**BEFORE writing any color-related code:** + +1. â **Check DESIGN.md** for the semantic intent +2. â **Map intent to color** using the Semantic Color Mapping table above +3. â **Use design system color** from tailwind.config.ts +4. â **Reference this file** if uncertain about color choice +5. â **Never** use `bg-green`, `text-red`, `border-blue`, etc. + +**During code review:** +- â Flag any hardcoded Tailwind colors (green-*, red-*, blue-*, etc.) +- â Require fixes before merge +- â Reference DESIGN_COLOR_RULES.md in comments + +**For TypeScript/Linting:** +Add to `.eslintrc.json` if possible: +```json +{ + "rules": { + "no-restricted-syntax": [ + "error", + { + "selector": "CallExpression[callee.name='className'][arguments.0.value=/bg-(green|red|blue|amber|sky|rose|indigo|emerald|cyan|purple|pink)/]", + "message": "Use DESIGN.md colors (primary, secondary, tertiary, error) instead of arbitrary Tailwind colors" + } + ] + } +} +``` + +--- + +## EXCEPTION CASES (VERY RARE) + +**Only use arbitrary colors for:** +1. **Third-party libraries** (e.g., vitest UI, dev tools) - in node_modules only +2. **Debug/Development tools** - prefixed with `// debug-only` +3. **Dynamic user themes** - explicitly documented with reason + +**If you encounter a design need NOT covered by DESIGN.md colors:** +- â Do NOT use arbitrary Tailwind colors +- â Request new color be added to DESIGN.md +- â Create GitHub issue with screenshot and use case +- â Await approval before implementing + +--- + +## CHECKLIST FOR NEW FEATURES + +Before writing UI code, answer: + +- [ ] Have I read DESIGN.md colors section? +- [ ] Have I reviewed the Semantic Color Mapping in this file? +- [ ] Have I identified the intent: success/error/warning/info? +- [ ] Have I used the correct semantic color from design system? +- [ ] Have I avoided ALL arbitrary Tailwind colors (green-*, red-*, etc.)? +- [ ] Have I tested the color contrast meets WCAG AA (7:1 ratio)? +- [ ] Have I verified the color looks correct on both light and dark surfaces? + +--- + +## QUICK REFERENCE + +**If you need to color something:** + +``` +Status = Success/Healthy? â Use tertiary (#00e639) +Status = Error/Failed? â Use error (#ffb4ab) +Action = Warning/Caution? â Use primary (#ffb781) +Action = Secondary/Info? â Use secondary (#c8c6c5) +Text = Muted/Disabled? â Use muted (#474746) +Border = Regular? â Use outline (#a48c7c) +Border = Subtle variant? â Use outline-variant (#564335) +Data change = Increase/Positive? â Use tertiary +Data change = Decrease/Negative? â Use error +``` + +--- + +## RELATED DOCUMENTS + +- đ **DESIGN.md** - Full color palette, typography, spacing rules +- đ **DESIGN_COMPLIANCE_FIX_PLAN.md** - Detailed fix plan for all hardcoded colors +- đ **AI_RULES.md** - Section 3: UI/UX Premium Fidelity Standards +- đ **PROJECT_ARCHITECTURE.md** - Section 2.2: Styling specification + +--- + +## VERSION HISTORY + +| Date | Change | Author | +|------|--------|--------| +| 2026-04-25 | Created rule document | AI Development Team | +| 2026-04-25 | Fixed 44+ hardcoded colors | Phase 8 Remediation | + +--- + +**Last Reviewed:** 2026-04-25 +**Next Review:** 2026-05-25 +**Owner:** AI Development Team diff --git a/dev_docs/DESIGN_COMPLIANCE_FIX_PLAN.md b/dev_docs/DESIGN_COMPLIANCE_FIX_PLAN.md new file mode 100644 index 00000000..726cb0bd --- /dev/null +++ b/dev_docs/DESIGN_COMPLIANCE_FIX_PLAN.md @@ -0,0 +1,468 @@ +# DESIGN.md Hardcoded Colors Remediation - Detailed Fix Plan + +**Status:** READY FOR IMPLEMENTATION +**Date Created:** 2026-04-25 +**Total Files to Modify:** 23 +**Total Color Fixes:** 44+ +**Estimated Time:** 2-3 hours + +--- + +## SEMANTIC COLOR MAPPING (From DESIGN.md) + +```javascript +// Use these ONLY - no arbitrary Tailwind colors allowed +{ + // Status Indicators + "Success/Healthy": "tertiary (#00e639)", // Bright terminal green + "Error/Destructive": "error (#ffb4ab)", // Light error red + "Error Dark": "on-error (#690005)", // Dark error text + "Error Container": "error-container (#93000a)", // Error background + "Error Container Text": "on-error-container (#ffdad6)", // Error text + + // Actions + "Primary Action": "primary (#ffb781)", // Caution orange + "Secondary Action": "secondary (#c8c6c5)", // Gray + + // UI Elements + "Muted/Disabled": "muted (#474746)", // Dark gray + "Outline/Border": "outline (#a48c7c)", // Tan border + "Outline Variant": "outline-variant (#564335)", // Subtle border + + // Data Changes + "Increase/Add": "tertiary (#00e639)", // Green + "Decrease/Remove": "error (#ffb4ab)", // Red + "Warning": "primary (#ffb781)", // Orange +} +``` + +--- + +## FILE-BY-FILE FIX PLAN + +### **1. frontend/components/LogsTable.tsx** + +**Line 75-76: DB & DELETE action badges** +```tsx +// CURRENT (WRONG) +(log.action.includes('DB') ? "bg-sky-500/10 text-sky-400 border-sky-500/20" : + log.action.includes('DELETE') ? "bg-red-500/10 text-red-500 border-red-500/30" : + +// FIX TO +(log.action.includes('DB') ? "bg-secondary/10 text-secondary border-secondary/20" : + log.action.includes('DELETE') ? "bg-error/10 text-error border-error/30" : +``` + +**Line 77: CREATE action badge** +```tsx +// CURRENT (WRONG) +(log.action.includes('CREATE') ? "bg-indigo-500/10 text-indigo-400 border-indigo-500/20" : + +// FIX TO +(log.action.includes('CREATE') ? "bg-primary/10 text-primary border-primary/20" : +``` + +**Line 73: CHECK_IN action badge** +```tsx +// CURRENT (WRONG) +log.action.includes('CHECK_IN') ? "bg-green-500/10 text-green-500 border-green-500/20" : + +// FIX TO +log.action.includes('CHECK_IN') ? "bg-tertiary/10 text-tertiary border-tertiary/20" : +``` + +**Line 99: Quantity change indicator** +```tsx +// CURRENT (WRONG) +(log.quantity_change || 0) > 0 ? "text-green-500" : ((log.quantity_change || 0) < 0 ? "text-rose-500" : + +// FIX TO +(log.quantity_change || 0) > 0 ? "text-tertiary" : ((log.quantity_change || 0) < 0 ? "text-error" : +``` + +**Line 125: TRASH badge in modal** +```tsx +// CURRENT (WRONG) +(selectedLog.action.includes('TRASH') ? "bg-rose-500 text-black" : + +// FIX TO +(selectedLog.action.includes('TRASH') ? "bg-error text-on-error" : +``` + +**Line 147: Quantity change in modal** +```tsx +// CURRENT (WRONG) +(selectedLog.quantity_change || 0) > 0 ? "text-green-500" : "text-rose-500" + +// FIX TO +(selectedLog.quantity_change || 0) > 0 ? "text-tertiary" : "text-error" +``` + +--- + +### **2. frontend/components/NewItemDialog.tsx** + +**Lines 29-31: Upload prompt box** +```tsx +// CURRENT (WRONG) +className="w-full flex flex-col items-center justify-center p-4 md:p-6 rounded-none bg-indigo-500/5 border border-indigo-500/20 group hover:border-indigo-500/50 transition-all font-normal text-indigo-400 gap-2 md:gap-3" +... +