# 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](component-catalog.md) | Reusable components — check before inventing |
| [platform/h5.md](platform/h5.md) | Mobile Web (primary) |
| [platform/mini-program.md](platform/mini-program.md) | WeChat Mini Program |
| [platform/website.md](platform/website.md) | Desktop / marketing Web |
| [platform/flutter.md](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

温和、清晰、尊重。禁止恐吓 / 道德绑架 / 虚假倒计时.  
成长报告 / 问答：生活建议向免责声明（非医疗、非占卜）.  
**中文命名强制：** `.ai/product/lexicon.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.