# Component Catalog — AI Contract

Agents MUST check this file + platform `components/` before creating UI.

Naming: PascalCase; domain words from `.ai/domain.md`.  
Visual tokens: [design-system.md](design-system.md).  
Ship path today: `apps/user-h5/src/components/` (Vue). Mini Program / Flutter map 1:1 by name.

Status: `exists` | `required` (build when first needed) | `future`

---

## Primitives

### Button

Status: **required**

Types ONLY: `Primary` · `Secondary` · `Ghost` · `Danger` · `Loading` · `Disabled`

| Prop | Notes |
|---|---|
| variant | primary / secondary / ghost / danger |
| loading | shows progress; blocks double submit |
| disabled | uses `--color-primary-disabled` or neutral |
| block | full width on H5 forms |

MUST NOT: `SpecialButton`, `CustomButton2`, one-off gradient buttons outside Primary.

Primary visual: pill + brand CTA gradient from design-system.

### IconTile

Status: **required**

Square/rounded tile for Explore / Home grid. Soft accent bg + symbol (△ ◆ ☯ 问), not emoji.

### Avatar

Status: **required**

Profile face placeholder (initials or soft color). Sizes: sm 32 / md 40 / lg 56.

### Tag / Chip

Status: **required**

Filter chips, Soft labels. Active = white surface + primary text + light shadow.

### Divider

Status: **required** — `--color-border`, 1px.

### Skeleton

Status: **required** — list/card placeholders; calm pulse ≤300ms feel, no flashy shimmer rainbow.

### Toast / Banner

Status: **required** — success / error / info. Short copy; no fear wording.

---

## Layout chrome

### AppShell

Status: **exists** (TabBar + max-width column)

User column `max-width: var(--layout-max-user)`. Safe-area bottom padding.

### TabBar

Status: **exists**

Tabs: 首页 / 探索 / **问** / 陪伴 / 我的. Center Ask may use primary circle. Active = primary.

### TopBar

Status: **required**

Secondary pages: back · title · optional action. Soft wash or white; not heavy app bar.

### ContentSheet

Status: **required**

White rounded sheet over peach wash (home feed pattern).

---

## Forms

### TextField / DateField

Status: **required**

Label required · error · disabled · focus border soft primary. Birthday Decode uses compact year/month/day fields.

### FormSection

Status: **required** — label + control + helper/error.

Rules: Label, error, loading, disabled states always.

---

## Cards

### Card (base)

Status: **required**

Structure: Container → Padding (`--spacing-md`) → Content → Optional Action.  
Surface white, `--radius-lg`, `--shadow-card`. No random card skins.

### FeatureCard

Status: **required** — Explore entry (icon + title + one line).

### ReportCard

Status: **required**

Decode / Match summary. Shows free conclusion; locked sections use PaywallLock. Footer disclaimer slot.

### MoodCard

Status: **required** — Companion daily mood entry/result. Soft, never clinical.

### SolarTermCard

Status: **required** — Today’s SolarTerm title + short lifestyle tip (no 吉凶).

### SubscriptionCard

Status: **required**

Membership plans. Clear price · period · benefits. **MUST NOT** fake countdown / dark patterns. CTA = Primary Button.

### UnlockCard

Status: **required** — single Report / Match Unlock alternative to VIP.

---

## AI / Ask

### ChatThread

Status: **required** — scrollable Ask history; Profile context chip at top (Self / Other switch).

### ChatBubble

Status: **required**

User vs AI. AI bubble: soft surface, calm radius; no neon bot skins. Streaming = typing/skeleton, not decorative bounce spam.

### AIMessage

Status: **required**

Structured Ask answer: short answer · optional bullets · disclaimer when health-adjacent. Prefer structured blocks over wall of text.

### PromptChip

Status: **required** — suggested follow-ups under Ask input; path-aware (性格 / 关系 / 养生), never 运势.

### AskInputBar

Status: **required** — bottom composer; ≥44px hit; send loading state.

---

## Profile & social

### ProfileSwitcher

Status: **required** — Self / Other list; “帮 TA 测” entry.

### ShareCard

Status: **required** — Decode / ScaleResult share visual; brand + one conclusion line; no medical claims.

### ScaleQuestion / ScaleResultView

Status: **required** — progress · options · result type + CTA to Decode/Ask.

---

## Commerce

### PaywallLock

Status: **required** — blurred/locked reason+plan; CTA Unlock or Membership.

### OrderSummary

Status: **required** — plan/report line items before pay-mock.

---

## States

### EmptyState

Status: **required** — one sentence + one action.

### ErrorState

Status: **required** — message + retry/back.

### LoadingBlock

Status: **required** — page/section skeleton wrapper.

---

## Forbidden inventions

Without approval / catalog update:

- Parallel button systems
- “Glassmorphism” chat skins
- Emoji-only navigation
- New layout shells beside AppShell
- Countdown / guilt paywalls

---

## Extension rule

Need a new component → add a row here (name, status, props, do/don’t) in the **same PR** as the first implementation. Then build under platform `components/`.