jackyu66gitandCursor
2fb1dfee14
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>
277 lines
7.7 KiB
Markdown
277 lines
7.7 KiB
Markdown
# 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.
|