From 9c4588374f810c32b59cc68545e1dd741bb2102f Mon Sep 17 00:00:00 2001
From: Naiyuan Qing <145280634+NevilleQingNY@users.noreply.github.com>
Date: Wed, 11 Feb 2026 14:50:25 +0800
Subject: [PATCH] docs: add design system guidelines to CLAUDE.md

Add Design System section with:
- Core principles (restraint, clarity, consistency, density)
- Typography table (Geist Sans, Geist Mono, Playfair Display)
- Color philosophy (no brand color, semantic colors for state)
- Component library reference (Shadcn/UI)
- UI building guidelines

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 48244241..abdc22f4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -122,6 +122,46 @@ See `docs/package-management.md` for detailed package management guide.
 
 - **Comments**: Always write code comments in English, regardless of the conversation language.
 
+## Design System
+
+The UI follows a **restrained, professional** design language. This is a work tool, not a consumer app.
+
+### Core Principles
+
+1. **Restraint over decoration** — No flashy colors, minimal animations
+2. **Clarity over cleverness** — Obvious > subtle, explicit > implicit
+3. **Consistency over novelty** — Use Shadcn/UI patterns, don't reinvent
+4. **Density over sprawl** — Respect screen real estate
+
+### Typography
+
+| Font | CSS Variable | Usage |
+|------|--------------|-------|
+| Geist Sans | `font-sans` | Primary UI text |
+| Geist Mono | `font-mono` | Code, technical values |
+| Playfair Display | `font-brand` | Brand name "Multica" ONLY |
+
+Fonts are loaded via `@fontsource` packages (not Google Fonts) for cross-platform consistency.
+
+### Colors
+
+- **No brand color** — Purple/blue "AI colors" feel generic. We use neutral grays.
+- **Color is for state** — Running (blue), success (green), error (red)
+- **Dark mode is true dark** — Not gray, actual near-black
+
+### Component Library
+
+- **Base**: Shadcn/UI (Radix primitives + Tailwind)
+- **Styling**: Tailwind CSS v4 with OKLCH colors
+- **Config**: `packages/ui/src/styles/globals.css`
+
+### When Building UI
+
+- Prefer existing Shadcn components over custom implementations
+- Use semantic color variables (`--muted`, `--destructive`), not raw colors
+- Keep animations subtle and purposeful (no gratuitous motion)
+- Test in both light and dark modes
+
 ## Credentials Setup
 
 ```bash