# 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:**
```tsx
// 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:**
```css
--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:**
```yaml
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:**
```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.