resolutionflow/Design/DESIGN-SYSTEM-SETUP-GUIDE.md

How To Make Claude Code Follow The New Design System

The Problem

Your project currently has MULTIPLE contradicting design documents:

• CLAUDE.md references purple gradients, glass-morphism, AND cyan accents
• Old docs like DESIGN_SYSTEM_GUIDE.md describe monochrome glass-card patterns
• UI-DESIGN-SYSTEM.md describes a purple gradient workspace system
• REBRAND-IMPLEMENTATION-GUIDE.md has the old Patherly → ResolutionFlow rebrand
• Your actual CSS has Tailwind v4 with OKLCH cyan tokens

Claude Code sees ALL of these and gets confused about which to follow.

The Fix — 4 Steps

Step 1: Place the new DESIGN-SYSTEM.md in your project root

Copy DESIGN-SYSTEM.md (the file I created alongside this one) to:

C:\Dev\Projects\patherly\DESIGN-SYSTEM.md

This is the SINGLE SOURCE OF TRUTH for all design decisions going forward.

---

Step 2: Update CLAUDE.md — Branding Section

Find the ### Branding section and REPLACE EVERYTHING between **Brand details:** and the next --- separator with this:

**Brand details:**

- **Design system:** [DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) — THE source of truth for all design decisions
- **Design aesthetic:** Flat, high-contrast dark theme (Sentry/PostHog-inspired). No glass morphism, no gradients on surfaces, no ambient effects.
- **Accent color:** Cyan (#22d3ee / #06b6d4). Used sparingly — ≤5% of the UI.
- **Fonts:** IBM Plex Sans (body), Bricolage Grotesque (headings), JetBrains Mono (code) — loaded via Google Fonts
- **Logo:** 30px gradient square (cyan) + "ResolutionFlow" in Bricolage Grotesque 700
- **Layout:** Icon rail sidebar (72px, default) with hover flyout panels. Pinnable to full 260px sidebar.
- **Brand assets:** `brand-assets/` (source SVGs), `frontend/src/assets/brand/` (app assets), `frontend/public/icons/` (favicon)
- **Landing page:** Shares color system and typography. Full-width marketing layout at `/` route.
- **Reference mockups:** `docs/mockups/` (HTML files, open in browser)

**Component rules:**
- Primary buttons: solid `accent` background (#22d3ee), white text
- Cards: `bg-card` with 1px `border-default`, 8px radius. NO shadows, NO blur, NO gradients.
- Badges: pill-shaped (20px radius), semantic dim background + matching text color
- Active nav: `accent-dim` background + `accent-text` color + 3px left accent bar
- Stat cards: 3px colored left border (accent/success/warning by position)
- Code blocks: `bg-code` with JetBrains Mono, material-inspired syntax highlighting
- Status colors: green (success), amber (warning), red (danger) — ONLY for semantic meaning

When adding new pages/components: reference DESIGN-SYSTEM.md. Use flat dark surfaces, 1px borders, no decorative effects. All colors via CSS variables.

---

Step 3: Update CLAUDE.md — Tech Stack Line

Find the styling line under Tech Stack → Frontend and change it to:

- **Styling:** Tailwind CSS v4 — flat dark theme with cyan accent (see DESIGN-SYSTEM.md)

Remove any references to "monochrome glass-morphism" or "dark-only" limitations.

---

Step 4: Archive Old Design Docs

Move these files into an archive/ folder (don't delete — you might want to reference them later):

mkdir archive
mkdir archive\design-docs

move DESIGN_SYSTEM_GUIDE.md archive\design-docs\
move UI-DESIGN-SYSTEM.md archive\design-docs\
move REBRAND-IMPLEMENTATION-GUIDE.md archive\design-docs\
move COMPONENT_EXAMPLES.md archive\design-docs\   (if it exists in root)
move docs\plans\Frontend\DESIGN_SYSTEM_GUIDE.md archive\design-docs\  (if it exists here)

If any of these files are referenced elsewhere in CLAUDE.md, remove those references.

---

Why This Works

Claude Code prioritizes files in this order:

1. CLAUDE.md — reads this first, every time
2. Files referenced in CLAUDE.md — follows links to read referenced docs
3. Files in the project root — scans these for context
4. Files deeper in the tree — only reads if specifically asked

By putting DESIGN-SYSTEM.md in the root AND linking it from CLAUDE.md's branding section, Claude Code will find it immediately and treat it as authoritative. By archiving the old docs, Claude Code won't stumble on contradicting information.

---

Verification

After making these changes, test by asking Claude Code:

1. "What color system does this project use?" — Should say cyan/teal flat dark theme, NOT purple gradients or monochrome
2. "Create a new card component" — Should use bg-card with 1px border, NOT glass-card with backdrop-blur
3. "What fonts does this project use?" — Should say IBM Plex Sans + Bricolage Grotesque, NOT Inter + Plus Jakarta Sans
4. "Add a sidebar nav item" — Should follow the icon rail pattern, NOT a traditional full sidebar

If any of these come back wrong, check that the old docs are actually archived and not still being found.

---

Place These Mockup Files in docs/mockups/

Also copy the HTML mockups we created into your project so Claude Code has visual references:

mkdir docs\mockups

copy resolutionflow-redesign.html docs\mockups\
copy resolutionflow-sidebar-final.html docs\mockups\
copy resolutionflow-landing.html docs\mockups\

Then Claude Code can open these in a browser to see exactly what the target looks like.