From d78bb58faf7ffe16e84292add6236a58a0e9716e Mon Sep 17 00:00:00 2001
From: Daniel Bedeleanu <bede@tfm.ro>
Date: Sat, 25 Apr 2026 17:34:05 +0300
Subject: [PATCH] docs: add mandatory rule - all color changes via
 frontend/colors.mjs only
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Enforce single source of truth for all future color work:
- All DESIGN.md color changes → frontend/colors.mjs exclusively
- No direct edits to tailwind.config.ts or globals.css
- Build script auto-syncs all systems
- Added mandatory rule sections to:
  - CLAUDE.md (entry point for all AI agents)
  - DESIGN_COLOR_RULES.md (enforcement details)

Prevents:
- Color duplication across files
- Sync inconsistencies
- Manual CSS variable maintenance

References COLOR_SYSTEM_ARCHITECTURE.md for implementation.

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
---
 CLAUDE.md             | 35 +++++++++++++++++++++++++++++
 DESIGN_COLOR_RULES.md | 51 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 49026feb..514e8afe 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -31,6 +31,41 @@ DO NOT, EVER, USE "uppercase" or "toUpper" in any UI/UX context, nowhere. This S
 
 See `DESIGN_COLOR_RULES.md` for complete color mapping and examples.
 
+## 🔒 MANDATORY: All Color Changes → `frontend/colors.mjs` ONLY
+
+**SINGLE SOURCE OF TRUTH RULE:**
+When implementing any color changes from DESIGN.md (new colors, updates, or variants):
+
+1. **Edit ONLY:** `frontend/colors.mjs` (the authoritative source)
+2. **DO NOT edit:** `tailwind.config.ts` (auto-imports from colors.mjs)
+3. **DO NOT edit:** `frontend/app/globals.css` (auto-generated from colors.mjs)
+4. **Run:** `npm run build` (auto-syncs all systems)
+
+**Why:**
+- Single source of truth eliminates duplication
+- Build script auto-generates CSS variables
+- No manual sync needed
+- Zero risk of color inconsistency
+
+**Violation Examples (DO NOT DO):**
+- ❌ Editing hex values in `tailwind.config.ts` directly
+- ❌ Adding CSS variables to `globals.css` manually
+- ❌ Updating colors in multiple files
+
+**Correct Workflow:**
+```javascript
+// ✅ CORRECT: Update colors.mjs ONLY
+// frontend/colors.mjs
+export const colors = {
+  primary: {
+    DEFAULT: "#ffb781",  // ← Update here
+  },
+};
+// Then: npm run build (everything auto-syncs)
+```
+
+**Reference:** See `COLOR_SYSTEM_ARCHITECTURE.md` for implementation details.
+
 ## Project-Specific Guidelines
 
 - Use TypeScript strict mode
diff --git a/DESIGN_COLOR_RULES.md b/DESIGN_COLOR_RULES.md
index 936780a9..9f8020d7 100644
--- a/DESIGN_COLOR_RULES.md
+++ b/DESIGN_COLOR_RULES.md
@@ -187,6 +187,57 @@ const statusColor = `var(--${isError ? 'error' : 'tertiary'})`
 **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:**