digital-psychology/.ai/design/design-system.md

AI Design System Contract — 愈心谷

Mandatory. Agents MUST read this before creating or modifying frontend UI
(apps/user-h5, apps/mini-program, apps/admin-h5, future website / Flutter).

File	Role
component-catalog.md	Reusable components — check before inventing
platform/h5.md	Mobile Web (primary)
platform/mini-program.md	WeChat Mini Program
platform/website.md	Desktop / marketing Web
platform/flutter.md	Native app (future)

Tokens: packages/ui/src/tokens.css
IA / tabs: .ai/ui.md · Domain: .ai/domain.md

---

0. Purpose

This is an AI contract, not a traditional design deck.

• Consistent brand across H5 / Mini Program / Web / App
• Stop random UI decisions
• Reuse components before inventing
• Shared language here; platform limits in platform/*

When uncertain: DO NOT invent. ASK FIRST. Consistency > creativity.

---

1. Design Philosophy

Core values

Value	UI implication
Simple	One job per section; short copy
Calm	Warm soft surfaces; low motion; no neon
Trustworthy	Clear hierarchy; disclaimer on reports
Professional	Stable tokens; no gaming chrome
Human-centered	Soft language; easy exit from paywalls
AI-first	Ask / chat are first-class patterns

Domain (psychology / wellness) — MUST

• Gentle self-understanding — not clinical hospital UI, not fortune-telling casino.
• Atmosphere: warm peach / coral wash → white content sheet.
• Unicode symbols (△ ☯ ◈) or SVG over emoji in chrome.
• Copy: friendly, clear, respectful, encouraging.
• MUST NOT: fear, guilt, fake urgency, medical cure claims, 吉凶祸福.

MUST NOT create

• Excessive multi-stop gradients on chrome
• Neon, glow, dark-mode-by-default, purple-on-white “AI slop”
• Gaming HUD, particle spam, continuous decorative animation
• Random illustrations / emoji clusters
• Inconsistent spacing / one-off hex colors
• Dashboard clutter in home first viewport

---

2. Design Architecture

Foundation (tokens) → Components (catalog) → Platform implementation

AI MUST follow this order. Never invent page magic numbers or duplicate components.

---

3. Foundation — Design Tokens

All UI values MUST use tokens from packages/ui (or platform mapping of the same names).

Forbidden: padding:17px; color:#2563eb; border-radius:13px;
Required: padding:var(--spacing-md); color:var(--color-primary); border-radius:var(--radius-md);

If a token is missing: ASK or add it to packages/ui/src/tokens.css in the same change — do not hardcode.

Legacy --yxg-* remains valid; new code SHOULD prefer semantic names below.

---

4. Color System

Use only these semantic colors. Do not invent brand hues.

Primary

Token	Value	Use
--color-primary	#E54D42	CTA, brand, active tab
--color-primary-hover	#D44338	Hover / pressed
--color-primary-soft	#FFE4E4	Soft chip / Ask surface
--color-primary-disabled	#F5B5B0	Disabled primary

Brand CTA gradient (only this one):
linear-gradient(135deg, #FF7A6E, var(--color-primary))

Atmosphere

Token	Value
--color-bg-start	#FFD1C7
--color-bg-end	#FFC8B5
--color-bg-sheet	#FFF9F7

Do not replace with flat gray or purple gradients.

Neutral

Token	Value	Use
--color-surface	#FFFFFF	Cards, sheets, nav
--color-text-primary	#333333	Titles / body
--color-text-secondary	#999999	Subcopy
--color-text-tertiary	#BBBBBB	Meta
--color-border	#F0F0F0	Dividers
--color-border-strong	#EEEEEE	Inputs
--color-input-bg	#FDFAF8	Form fields

Domain accents (tint only — not global CTA)

Token	Value	Feature
--color-accent-gold	#C8923A	Decode
--color-accent-gold-soft	#FFF3D6	Decode tile
--color-accent-blue	#4A90E2	Scale
--color-accent-blue-soft	#E3EEFF	Scale tile
--color-accent-green	#5CB85C	Companion / SolarTerm
--color-accent-green-soft	#E0F6E4	Companion tile
--color-accent-orange	#E8985A	Warm secondary
--color-accent-purple	#8B5CF6	Sparse only — never page theme

Status (only)

success · warning · error · info
Map: success≈green, warning≈orange/gold, error≈primary family, info≈blue.

Forbidden

Neon / pure-black full-bleed / random Tailwind blue as brand / purple global theme.

---

5. Typography

Stack: -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", "Helvetica Neue", sans-serif
Do not add Inter/Roboto/display fonts on product UI without ADR.

Level	Size	Weight	Use
Display	28–32px	700	Brand 愈心谷 only
Heading 1	20–22px	700	Page hero
Heading 2	16–17px	600–700	Section
Heading 3	15px	600	Card title
Body	14px	400	Default
Body Small	12–13px	400	Secondary
Caption	10–11px	400	Tab / disclaimer

No arbitrary sizes. Body line-height ≈ 1.6–1.7.

---

6. Spacing

Scale: 4 · 8 · 12 · 16 · 24 · 32 · 48 · 64

Token	px
--spacing-2xs	4
--spacing-xs	8
--spacing-sm	12
--spacing-md	16
--spacing-lg	24
--spacing-xl	32
--spacing-2xl	48
--spacing-3xl	64

Forbidden: 13 / 18 / 27 / 35. Page pad default: 16.

---

7. Radius, shadow, width

Token	Value	Use
--radius-sm	10px	Back / small controls
--radius-md	12px	Inputs / tiles
--radius-lg	16px	Cards
--radius-xl	18–20px	Large sheets
--radius-pill	999px	CTA capsule

Shadows: --shadow-card: 0 2px 10px rgba(0,0,0,.04); --shadow-nav: 0 -2px 8px rgba(0,0,0,.03). No glow.

--layout-max-user: 430px · --layout-nav-h: 56px

---

8. Components

MUST reuse. Before creating: catalog → src/components/ → extend.
No SpecialButton / CustomButton2 / NewCard.

---

9. Layout Patterns

Pattern	Screens
HomeWash	Brand + Decode + white sheet
List	Explore, orders
Detail	Report / Match
Form	Decode birthday, edit Profile
Profile	Mine / switch Profile
Settings	Account, privacy
AI Chat	Ask
Paywall	Membership / Unlock
Companion	SolarTerm + Mood

Home first viewport: brand · headline · Decode form · CTA. No stats/promo clutter.

---

10. Interaction States

Network UI MUST have: Loading (skeleton) · Empty · Error (+ recovery) · Success · Disabled.
Paywall: free conclusion, lock reason/plan; no fake countdown.

---

11. Motion

Durations: 150 / 200 / 300ms. Feedback only.
No continuous loops or decorative scroll animation.

---

12. Accessibility

Contrast for body text; touch ≥ 44px; no hover-only essentials; label interactive controls.

---

13. Brand Voice

温和、清晰、尊重。禁止恐吓 / 道德绑架 / 虚假倒计时.
Report/Ask: lifestyle disclaimer（非医疗、非算命）. Labels follow .ai/domain.md.

---

14. Platforms

Shared language = this file. Limits = platform/*.
Priority: H5 → Mini Program → Website → Flutter.

---

15. Before Coding Checklist

• Catalog + components checked
• Correct platform/*.md read
• Tokens only
• Loading / empty / error
• Compliance copy if Report / Ask / Membership
• A11y (touch / contrast)
• No emoji chrome; no medical / 吉凶 wording

---

16. Final Rule

Uncertain → ASK. Do not invent colors, components, or layouts.