123fc50af9
30 references to removed CSS variables: border-brand-border → border-[#1e2130], text-brand-text-muted → text-[#4f5666], text-brand-dark → text-white, bg-white/[0.04] → bg-[#191c25], hover:border-white/[0.12] → hover:border-[#2a2f3d]. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
129 lines
5.2 KiB
Markdown
129 lines
5.2 KiB
Markdown
# 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:
|
|
|
|
```markdown
|
|
**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:
|
|
|
|
```markdown
|
|
- **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.
|