tfm_ainventory/PLAN.md

DESIGN.md Compliance Audit & Fix Plan

Status: PLAN READY FOR REVIEW (No code changes made yet) Date: 2026-04-25 Objective: Audit why DESIGN.md is not fully respected in UI/UX and plan comprehensive fixes

---

EXECUTIVE SUMMARY

The design system has partial implementation. While basic structure exists (sharp corners, no shadows, dark theme), critical issues prevent full DESIGN.md compliance:

1. Color system is incomplete — tailwind.config.ts missing 50%+ of DESIGN.md colors
2. Hardcoded tailwind classes bypass the design system (bg-slate-, focus:ring-blue-)
3. Global CSS variables only cover 5 colors instead of full palette
4. Spacing tokens missing (stack-sm, stack-md, container-gap)
5. Typography spacing incomplete (letter-spacing, line-height rules)

---

ROOT CAUSE ANALYSIS

Why DESIGN.md Is Not Being Respected

1. Incomplete Color Mapping (PRIMARY ISSUE)

DESIGN.md Specifies:

• Primary: #ffb781 (warm orange)
• Secondary: #c8c6c5 (light gray for contrast)
• Tertiary: #00e639 (terminal green for "healthy" status)
• Error: #ffb4ab + container #93000a
• On-surface: #e5e2e1 (text on dark surfaces)
• On-primary: #4e2600
• On-secondary: #303030
• Outline: #a48c7c, Outline-variant: #564335
• Surface variants: 5 tiers (#0e0e0e to #353534)

Current tailwind.config.ts Has:

primary: #F58618 ❌ WRONG (should be #ffb781)
secondary: #888888 ❌ WRONG (should be #c8c6c5)
success: #00FF41 ❌ WRONG (should be #00e639)
tertiary: MISSING ENTIRELY ❌
error: #FF3131 ❌ WRONG (should be #ffb4ab)
on-surface: MISSING ❌
on-primary: MISSING ❌
outline: MISSING ❌

Impact: Components using text-secondary get #888888 instead of #c8c6c5. Buttons and status indicators use wrong colors.

---

2. Hardcoded Tailwind Classes Bypass Design System

Found in Components:

• bg-slate-400, bg-slate-600, hover:bg-slate-600 — No such colors in design
• bg-gray-400, text-gray-300, text-gray-400 — Undefined colors
• focus:ring-blue-500 — Should use primary color system
• hover:bg-[#222222] — Hardcoded hex instead of tonal layer name

Examples from audit:

// ItemPhotoUpload.tsx
className="hover:bg-slate-600"  // ❌ Undefined in design

// ItemComparisonModal.tsx
focus:ring-2 focus:ring-blue-500  // ❌ Should be focus:ring-primary

// DebugRotationPanel.tsx
hover:bg-slate-600  // ❌ Multiple instances

Impact: Colors change without design system knowledge. No way to enforce consistency.

---

3. Global CSS Variables Only Partially Implemented

Currently Defined:

--background: #0A0A0A
--foreground: #FFFFFF
--primary: #F58618
--border: #222222
--muted: #888888

Missing 30+ Design System Variables:

• All on-surface, on-primary, on-secondary variants
• All surface container levels (surface-container-lowest, surface-container-high, etc.)
• Outline and outline-variant
• Tertiary color suite
• Error container colors
• All inverse color variants
• Semantic spacing tokens

Impact: Can't reference design colors via CSS variables. Forces hardcoded hex values.

---

4. Spacing Tokens Missing from Config

DESIGN.md Specifies:

spacing:
  unit: 4px
  gutter: 16px
  margin: 32px
  container-gap: 24px
  stack-sm: 8px
  stack-md: 16px

Current tailwind.config.ts: Uses default Tailwind spacing (no custom tokens)

Impact: Margins and padding inconsistent across pages. No semantic spacing vocabulary.

---

5. Typography Rules Partially Implemented

DESIGN.md Specifies Letter-Spacing:

• headline-lg: -0.02em
• headline-md: -0.01em
• body-md/lg: default (0)
• label-md: +0.05em

Current globals.css:

h1, h2, h3, h4, h5, h6 { @apply tracking-tighter; }

Only tracking-tighter applied to all headings. No distinction between sizes.

Impact: Typography doesn't match spec. Density and legibility inconsistent.

---

WHERE CHANGES ARE NEEDED

1. frontend/tailwind.config.ts (CRITICAL - 80+ lines)

Changes Required:

• Replace colors.primary with exact DESIGN.md hex values
• Add complete DESIGN.md color palette (50+ colors)
• Add missing typography scale entries
• Add spacing tokens (unit, gutter, margin, stack-*, container-gap)
• Add all color variants (on-surface, on-primary, etc.)

Files to Edit: frontend/tailwind.config.ts

---

2. frontend/app/globals.css (HIGH PRIORITY - 50+ lines)

Changes Required:

• Add CSS variables for ALL DESIGN.md colors (from :root)
• Add CSS variables for spacing tokens
• Update typography layer rules (different tracking per size)
• Add semantic classes for DESIGN.md color naming (.on-surface, .on-primary, etc.)
• Override default Tailwind focus ring color

Files to Edit: frontend/app/globals.css

---

3. Component Files (HIGH VOLUME - 30+ files)

Search and Replace Pattern:

bg-slate-* → bg-surface-bright or specific design color
bg-gray-* → bg-muted or specific design color
focus:ring-blue-500 → focus:ring-primary
hover:bg-slate-600 → hover:bg-surface-bright or level-2
text-gray-* → text-secondary or text-muted
bg-[#222222] → bg-border (when for borders)

Files to Review:

• frontend/components/ItemPhotoUpload.tsx
• frontend/components/DebugRotationPanel.tsx
• frontend/components/ImageAdjustmentModal.tsx
• frontend/components/ManualCropUI.tsx
• frontend/components/ItemComparisonModal.tsx
• frontend/components/CategoryCreationModal.tsx
• frontend/components/CreateUserModal.tsx
• All other components with hardcoded colors

---

DETAILED FIX PLAN

Phase 1: Color System Foundation

Step 1.1 - Update tailwind.config.ts

• Add complete DESIGN.md color palette as semantic color names
• Map all 40+ colors from DESIGN.md
• Ensure primary, secondary, tertiary, error, and all "on-" variants exist
• Add surface container levels

Step 1.2 - Update globals.css

• Add CSS variable definitions for all colors
• Create semantic class names for typography (.headline-lg, .body-md, etc.)
• Add proper tracking/letter-spacing rules per DESIGN.md spec
• Override Tailwind focus ring defaults to use primary color

Step 1.3 - Verify Color Consistency

• All hex values match DESIGN.md exactly
• No hardcoded colors remain in globals.css
• All semantic names follow Material Design naming convention

---

Phase 2: Spacing System

Step 2.1 - Add Spacing Tokens

• Add unit: 4px as base spacing
• Add gutter: 16px, margin: 32px, container-gap: 24px
• Add stack-sm: 8px, stack-md: 16px
• Update tailwind spacing scale to reference these

Step 2.2 - Component Spacing Audit

• Verify all page margins use m-[32px] or semantic class
• Verify internal padding respects 4px grid
• Verify gaps between items use stack tokens

---

Phase 3: Typography System

Step 3.1 - Implement Typography Scale

• Add custom Tailwind class for each typography level
• Implement correct letter-spacing per DESIGN.md (headline-lg: -0.02em, etc.)
• Add line-height rules (1.1 for headlines, 1.5 for body)

Step 3.2 - Font Weight Enforcement

• Ensure no font-weight values other than 400 in CSS
• Verify global font-weight: 400 !important is enforced
• Check that hierarchy comes ONLY from size + color

---

Phase 4: Component Compliance

Step 4.1 - Search and Replace Replace all hardcoded Tailwind colors:

Current	Replace With	Reason
bg-slate-*	bg-surface-bright or design color	Undefined in system
bg-gray-*	bg-muted or bg-secondary	Undefined in system
focus:ring-blue-500	focus:ring-primary	Wrong color system
hover:bg-slate-600	hover:bg-surface-bright or level-2	Undefined in system
text-gray-*	text-secondary or text-muted	Undefined in system
bg-[#222222] (for hover)	hover:bg-border or hover:bg-surface-bright	Use design token

Step 4.2 - Focus State Audit

• All :focus and :focus-visible should use primary color
• Verify ring width (2px) matches design spec
• Remove any blue-500 references

Step 4.3 - Border Audit

• All borders should use border-border or border-primary
• No hardcoded #222222 in border definitions
• Verify 1px vs 2px matches DESIGN.md spec

---

FILES REQUIRING CHANGES

Critical (Must Fix)

1. frontend/tailwind.config.ts — Add 50+ colors + spacing
2. frontend/app/globals.css — Add 50+ CSS variables + typography rules

High Priority (30+ files with hardcoded colors)

3. frontend/components/ItemPhotoUpload.tsx
4. frontend/components/DebugRotationPanel.tsx
5. frontend/components/ImageAdjustmentModal.tsx
6. frontend/components/ManualCropUI.tsx
7. frontend/components/ItemComparisonModal.tsx
8. frontend/components/CategoryCreationModal.tsx
9. frontend/components/CreateUserModal.tsx
10. All other /components/*.tsx files with bg-slate-, bg-gray-, focus:ring-blue-

Medium Priority

• frontend/app/items/create.tsx (has bg-slate-400)
• frontend/app/inventory/page.tsx
• frontend/app/admin/page.tsx

---

EXPECTED OUTCOMES

After implementation:

✅ All DESIGN.md colors mapped 1:1 to tailwind.config.ts ✅ All 40+ CSS variables available in globals.css ✅ Zero hardcoded Tailwind colors (bg-slate-, bg-gray-, focus:ring-blue-*) ✅ All components use semantic color names (primary, secondary, surface-bright, etc.) ✅ Spacing tokens enable consistent, grid-aligned layout ✅ Typography follows DESIGN.md letter-spacing rules exactly ✅ Focus states use primary color consistently ✅ 100% compliance with DESIGN.md specification

---

VERIFICATION CHECKLIST

• tailwind.config.ts has all 40+ DESIGN.md colors
• globals.css has CSS variables for all colors
• No bg-slate-* or bg-gray-* in any component
• No focus:ring-blue-* anywhere in codebase
• All typography uses proper letter-spacing per DESIGN.md
• Spacing tokens defined and used in config
• Primary color changed from #F58618 to #ffb781 (if this is correct)
• All component audits passed
• Visual inspection: colors match DESIGN.md visual palette

---

NEXT STEP: User reviews this plan and approves before code changes begin.