tfm_ainventory/CLAUDE.md

CLAUDE ENTRY POINT

You are Claude, operating on the TFM aInventory project.

IMMEDIATE MANDATORY ACTION: Before taking any action or writing code, you MUST read the following Single Source of Truth files:

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.

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.

🔒 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:

// ✅ 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
• All API endpoints must have tests
• All UI colors MUST follow DESIGN.md (see DESIGN_COLOR_RULES.md)