# 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
<div className="w-2 h-2 bg-tertiary animate-pulse" />
<span className="text-tertiary">Scanner: Ready</span>

// Destructive button
<button className="bg-error hover:opacity-80 focus:ring-error">
  Delete Item
</button>

// Data change - quantity increased
<span className={log.quantity_change > 0 ? "text-tertiary" : "text-error"}>
  {log.quantity_change}
</span>

// 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
<div className="w-2 h-2 bg-green-500 animate-pulse" />
<button className="bg-red-600 hover:bg-red-700">Delete</button>

// ❌ 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'})`
<div style={{ color: statusColor }} />
```

---

## 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

---

## 🔒 MANDATORY: All Color Definition Changes → `frontend/colors.mjs` ONLY

**SINGLE SOURCE OF TRUTH RULE (Updated 2026-04-25):**

When adding, updating, or modifying ANY color from DESIGN.md:

### ✅ CORRECT WORKFLOW:
1. Edit ONLY: `frontend/colors.mjs` (the authoritative color source)
2. Update the color definition in the `colors` export object
3. Run: `npm run build` or `npm run dev`
4. Build script AUTOMATICALLY:
   - Generates CSS variables in `globals.css` `:root`
   - Syncs with `tailwind.config.ts` (which imports from colors.mjs)
   - Zero manual sync required

### ❌ INCORRECT WORKFLOWS (DO NOT DO):
- ❌ Editing `tailwind.config.ts` color definitions directly
- ❌ Manually adding CSS variables to `globals.css`
- ❌ Updating colors in multiple files
- ❌ Assuming changes in one file will propagate to another

### Why This Matters:
| Before | After (colors.mjs SSOT) |
|--------|------------------------|
| 2 files to edit | 1 file (colors.mjs) |
| High sync risk | Zero sync risk |
| Manual duplication | Auto-generated |
| Easy to break | Build validates |

### Example: Adding a New Color Variant
```javascript
// ✅ CORRECT: Edit frontend/colors.mjs ONLY
export const colors = {
  primary: {
    DEFAULT: "#ffb781",
    // ← Add new variant here
    "subtle": "#f5c5a3",  // ← NEW
  },
};

// Then: npm run build
// Result: Automatic sync to all systems
```

### Reference Documentation:
- **CLAUDE.md** — Mandatory rule entry point
- **COLOR_SYSTEM_ARCHITECTURE.md** — Technical implementation details
- **colors.mjs** — The authoritative source (keep comments updated)
- ✅ 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