chore: seal Design Vision v1 and monorepo scaffold

Archive the differentiated YuXinGu product docs, AI engineering system, design contract, and Go/Vue scaffold. Next execution prioritizes Cece-parity over early innovation (see .ai/product/STRATEGY.md). Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-02 16:00:44 +08:00
parent 2686866376
commit 2fb1dfee14
193 changed files with 8854 additions and 1851 deletions
@@ -0,0 +1,276 @@
+# 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
+
+温和、清晰、尊重。禁止恐吓 / 道德绑架 / 虚假倒计时.  
+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.