# TVU Design System — Conventions Overview

> **Audience**: new team members onboarding to TVU Design System, and sibling product teams that consume the TVU library.
> **Purpose**: give a 5-minute tour of how the convention system works — what rules exist, where they live, how they get enforced, and how to contribute a new one.
> **Status**: reflects the 2026-05-18 consolidation (M-COLOR / M-INTEGRITY umbrellas, R15 library-first umbrella).

---

## 1. What this is

TVU Design System ships a Vue 3 component library plus a **convention system** — a curated set of rules that constrain how AI assistants (Claude Code, Codex, etc.) and humans build mockups and consume the library. Conventions exist because greenfield AI output drifts; we anchor it with rules that emerged from real incidents.

This doc is the **map**. It does not restate the rules themselves — it tells you where each rule lives, when it fires, and which automation (skill / script / agent) enforces it.

If you only read one other thing after this, read [`AGENTS.md`](../../AGENTS.md) (the cross-AI entry point).

---

## 2. Quick Start

| If you want to… | Read | Invoke skill | Run script |
|---|---|---|---|
| Understand project state right now | `docs/STATUS.md` | — | — |
| Get cross-AI working rules | `AGENTS.md` | — | — |
| Draw a Figma mockup using TVU library | `docs/internal/mockup-conventions.md` | `@TVU mockup` | — |
| Write code consuming TVU library | `docs/internal/code-conventions.md` | `@TVU code` | — |
| Audit a mockup's layout integrity | — | — | `scripts/audit-mockup-integrity.mjs` |
| Audit a mockup's color token usage | — | — | `scripts/audit-mockup-colors.mjs` |
| Diff implemented code vs Figma source | — | — | `scripts/visual-diff.py` |
| Look up which Figma component to use | `docs/internal/figma-component-catalog.md` | — | — |
| Understand TVU business domain (red=Live etc.) | `docs/internal/domain-tvu.md` | — | — |
| Learn AI working meta-practices | `docs/meta-rules.md` | — | — |
| Lint skill metadata | — | — | `scripts/lint-skills.mjs` |
| Act as a UX designer (thinking layer only) | — | `@UX` (role-ux) | — |

---

## 3. Rule Quick Reference

Rules are split into two families:

- **M-rules** = Mockup rules — apply when producing Figma artifacts. Live in `docs/internal/mockup-conventions.md`.
- **R-rules** = Code rules — apply when writing code that consumes the TVU library. Live in `docs/internal/code-conventions.md`.

IDs are stable. When a rule is absorbed into an umbrella, the original ID is kept as a **legacy stub** (an anchor that redirects to the new home) so external references don't break.

### 3.1 M-rules (Mockup)

| ID | Rule | Topic |
|---|---|---|
| M0 | Phase 0: Element-to-Component Mapping | Process gate (前置) |
| M1 | TVU Top bar 公共基建不准自画 | Visual |
| M-COLOR | Color Token Discipline (umbrella) — §C1 icon fill / §C2 state color / §C3 bg-vs-text grey | Visual; absorbs M10 / M25 / M26 |
| M-INTEGRITY | Mockup Layout Integrity (umbrella) — §I1 sibling layout / §I2 section overlap / §I3 children wrap | Structure; absorbs M27 / M28 / M34 |
| M23 | UX 交付注释多状态流程图格式 | Structure / annotation |
| M23.6 | Connector tip accuracy + frame content avoidance | Annotation extension |
| M24 | Code → Token Mapping Table | Process gate ("已有 code 还原效果图" 场景) |
| M29 | Table Cell Content Pattern (Copyable / Empty) | Visual |
| M31 | Layout function decision tree (Auto Layout default, absolute justified) | Layout |
| M32 | Library Component-First for all product UI elements (absorbs M30 icons) | Library use |
| M33 | Annotation vs Product UI 语言隔离 (M23 boundary) | Language |
| M35 | Affordance-Category Search Discipline (3-line trace product) | Search cognition |

**Legacy stubs** (anchor preserved, content moved):
- M10 / M25 / M26 → **M-COLOR**
- M27 / M28 / M34 → **M-INTEGRITY**
- M30 → **M32**

**Migrated to other files**:
- M2–M9 → `docs/internal/domain-tvu.md` (business domain rules)
- M11–M22 → `docs/internal/design-process.md` (process rules)

### 3.2 R-rules (Code)

| ID | Rule | Topic |
|---|---|---|
| R0 | Phase 0: Element-to-Component Mapping | Process gate |
| R2 | 颜色必须用 TVU token, 不写 hex literal | Token discipline |
| R3 | 复合组件优先 mirror canonical | Library use |
| R4 | 不"先实现，再问要不要换库" | Process |
| R5 | Session Handoff Convention | Workflow |
| R6 | Existing product 增量优先复用 local | Process |
| R7 | 任务意图 disambiguate (4 大场景) | Process gate |
| R8 | 视觉还原任务自检 protocol (uses `visual-diff.py`) | QA |
| R9 | Static-to-Interactive Augmentation Protocol | Workflow |
| R10 | Vector 元素导出策略决策 | Process |
| R12 | Designer Annotation 过滤 | Process |
| R13 | Affordance-Category Search Discipline (mirrors M35) | Search cognition |
| R14 | Layout primitive selection (mirrors M31; flex/grid > absolute) | Layout |
| R15 | Library-First for all product UI elements (umbrella; absorbs R1 icons) | Library use |
| R16 | Annotation vs Product UI String Boundary (i18n key; mirrors M33) | Language |

**Legacy stub**: R1 → **R15**.

### 3.3 Mirror pairs

Some rules intentionally mirror across M / R because the same discipline applies at both the design and code layer:

| Mockup | Code | Topic |
|---|---|---|
| M31 | R14 | Layout primitive selection |
| M32 | R15 | Library-first |
| M33 | R16 | Annotation vs product-UI language |
| M35 | R13 | Affordance-category search trace |

---

## 4. How rules emerge + flow

Rules are **not** designed upfront. They emerge from incidents.

```
incident (AI did the wrong thing in a session)
   ↓
postmortem in chat: "is this a one-off mistake or a pattern?"
   ↓
user 拍板: "this is rule-level"  ────→ if NO: log as one-off, move on
   ↓
draft rule entry (next free ID)
   ↓
write to mockup-conventions.md or code-conventions.md
   ↓
update skill if behavior change is needed (tvu-design-mockup / tvu-design-code)
   ↓
add audit probe to scripts/ if mechanically checkable
   ↓
commit + push (rules ship in git so any clone sees them)
   ↓
propagate to AGENTS.md cross-reference if it's a top-level rule
```

**Key principle**: every rule has a historical **实证** — a specific session that triggered it. Without 实证, it's a guess, not a rule. This is enforced informally during the "拍板" step.

---

## 5. Skills, agents, and scripts

### 5.1 Skills (Claude Code automation)

Skills live in `.claude/skills/` and are auto-loaded when wake-words are detected.

| Skill | Wake words | Reads | When to use |
|---|---|---|---|
| `tvu-design-mockup` | `@TVU mockup` / "画 mockup" / "用 TVU 库画 mockup" | `mockup-conventions.md` | Producing Figma mockups in TVU products |
| `tvu-design-code` | `@TVU code` / "写代码消费 TVU" / "consume TVU library" | `code-conventions.md` | Writing app code that imports `@tvu/design-system` |
| `role-ux` | `Hi，UX` / `@UX` | UX persona doc | Thinking layer only — no deliverables, just helps you frame UX decisions |
| `setup-tvu-consumer` | "在当前项目中使用 TVU 设计系统" | — | One-time wiring: symlinks skills into a sibling product repo |

### 5.2 Agents (sub-agents triggered via Task tool)

Sub-agents live in `.claude/agents/` and are invoked when their `description` matches the task. They are stateless single-turn helpers that produce structured trace output.

| Agent | When to invoke | Output |
|---|---|---|
| `affordance-search` | Before drawing/instancing any "basic semantic element" (chevron / arrow / sort / close / loading / link / etc.) | 3-line trace (Affordance / Vocabulary scan / Chosen) + ranked candidates table — enforces M35 / R13 |

Other Claude Code built-ins (`general-purpose`, `Explore`, `Plan`) remain available for general tasks.

### 5.3 Audit scripts (CI candidates)

| Script | Audits | Rule | npm script |
|---|---|---|---|
| `scripts/audit-mockup-integrity.mjs` | Sibling layout / section overlap / children wrap (Figma REST API) | M-INTEGRITY (§I1/§I2/§I3) | `audit:consumer-mockup` |
| `scripts/audit-mockup-colors.mjs` | Icon fill / state color / bg-vs-text grey (Figma REST API) | M-COLOR (§C1/§C2/§C3) | `audit:consumer-mockup` |
| `scripts/audit-product-code.mjs` | Inline SVG / hex literal / mixed CN+EN strings (grep-based on source tree) | R1 (icons via R15 §icons) / R2 / R16 | `audit:consumer-code` |
| `scripts/visual-diff.py` | Code render vs Figma source diff | R8 | (run manually) |
| `scripts/lint-skills.mjs` | Skill metadata (wake words, model, scope) | meta — skill hygiene | `lint-skills` |

Aggregate runner: `pnpm audit:consumer` (currently aliases to `audit:consumer-code`; mockup audit requires `FIGMA_PERSONAL_ACCESS_TOKEN` + target fileKey so it's left as a manual command).

### 5.4 CI integration

Consumer products can wire `audit:consumer-code` into GitHub Actions for PR enforcement. A ready-to-copy template lives at:

```
docs/templates/consumer-audit-ci.yml
```

Copy to your consumer repo's `.github/workflows/audit.yml` and adjust. The template runs `audit:consumer-code` on PR + push to main, failing the PR on violations.

`audit:consumer-mockup` is **not** in the CI template by default — it needs Figma access + per-task fileKey/nodeId args, so it fits better as a manual pre-PR command or a `workflow_dispatch` job.

---

## 6. Common usage scenarios (US-1 … US-6)

The same six labels apply across both M and R families. Each rule's "Task Entry Modes" table tells you whether that rule fires for a given scenario.

| ID | Scenario | Typical entry |
|---|---|---|
| **US-1** | Greenfield product mockup / code from scratch | New repo, new product, no prior artifact |
| **US-2** | Greenfield single frame / page | Add one new page to existing product |
| **US-3** | Existing product 增改删 frame / element | Modify an existing page (add row, remove column, etc.) |
| **US-4** | Figma frame → code mirror | 4a = visual fidelity 1:1; 4b = TVU-normalize (replace ad-hoc styling with library) |
| **US-5** | Small tweak (1–2 elements) | Quick edit, no full Phase 0 needed |
| **US-6** | Review / Audit existing artifact | Read-only QA pass |

US-4 is the most failure-prone — that's why R8 (visual-diff protocol) and M24 (code→token mapping) exist.

---

## 7. Contributing a new rule

Checklist before adding a new M / R rule:

1. **实证** — Cite at least one concrete session where the rule was needed. No incident, no rule.
2. **拍板** — Get explicit user confirmation: "this is rule-level, not a one-off."
3. **Pick the next free ID** — `grep` both Active and Resolved entries; pick max+1 (see project memory `feedback_backlog-id-collision.md`).
4. **Choose the right file**:
   - Mockup behavior → `mockup-conventions.md`
   - Code behavior → `code-conventions.md`
   - AI working practice → `docs/meta-rules.md`
   - TVU business domain → `docs/internal/domain-tvu.md`
5. **Check for umbrella fit** — If your rule is close to M-COLOR or M-INTEGRITY or R15, prefer adding a sub-section rather than a new top-level ID.
6. **Write the rule with these fields**:
   - Rule statement (1–2 sentences)
   - 实证 (session reference)
   - Task Entry Modes table (which US-N scenarios it fires for)
   - Trace product if any (e.g. 3-line affordance trace, audit log)
   - Cross-reference to mirrored rule if applicable
7. **Update skill if needed** — If the rule changes AI behavior, edit the relevant skill in `.claude/skills/`.
8. **Add audit probe if mechanical** — If the rule is checkable by a script, add a probe to the relevant `scripts/audit-*.mjs`.
9. **Commit + push** — One commit per rule, message format: `docs(conventions): add M-XX / R-XX — <short topic>`.
10. **Update AGENTS.md cross-ref** if the rule is top-level enough to belong in the entry point.

---

## 8. Convention philosophy (核心理念)

1. **Rules emerge from incidents** — Each rule has historical 实证. New rules require explicit user 拍板 "this is rule-level, not a one-off mistake."
2. **WHERE-vs-HOW split** — Most rules describe **WHERE** to search/find (e.g., M32/R15 library priorities). M35 / R13 describe **HOW** to think before searching (affordance category trace).
3. **Externalize thinking as trace** — Several rules require 3-line trace outputs (M35 affordance, M-COLOR audit log, M-INTEGRITY overlap check). AI must produce these as deliverable artifacts — cannot just "promise to think."
4. **Annotation vs Product UI separation** — M23 / M33 / R16 split: annotation = bilingual (designer-facing); product UI = device language only (end-user-facing).
5. **Library-first** — M32 / R15 unify: do not draw custom; search local + team library + canonical first, only build new when the search trace fails.

---

## 9. Glossary

| Term | Meaning |
|---|---|
| **实证** | Historical evidence — a specific session or incident that motivated a rule. Required for any new rule. |
| **拍板** | User-confirmed decision (literally "slap the gavel"). Required to promote an incident into a rule. |
| **Umbrella rule** | A consolidated rule that absorbs multiple sub-rules under one ID (e.g. M-COLOR absorbed M10/M25/M26). Sub-rules live as sections (§C1, §C2, …) inside the umbrella. |
| **Legacy stub** | A retained ID anchor whose content has moved into an umbrella or another file. Preserves external links. Example: M10 stub points readers to M-COLOR §C1. |
| **Trace product** | A short text artifact (typically 3 lines) that the AI must emit to externalize its thinking — e.g. an affordance trace before component search, or an audit log after a color check. |
| **Affordance** | The user-facing capability an element offers (e.g. "copyable text," "destructive action"). Rules M35 / R13 require categorizing affordance before searching the library. |
| **Mirror pair** | Two rules — one M, one R — that enforce the same discipline at design layer and code layer (M31↔R14, M32↔R15, M33↔R16, M35↔R13). |
| **Phase 0** | Element-to-Component Mapping pre-step (M0 / R0). Must be done before any drawing or coding starts. |
| **Task Entry Modes table** | A small table inside each rule listing which US-1…US-6 scenarios trigger that rule. |
| **Canonical** | The reference implementation inside TVU library. "Mirror canonical" = match the canonical's API and visual contract. |
| **Greenfield** | New product / new frame, no prior artifact (US-1 / US-2). |
| **Sibling product** | A product repo that consumes `@tvu/design-system` (sits next to this repo, hence "sibling"). |

---

## 10. Where to go next

- **Just joined the team?** → read `AGENTS.md`, then `docs/STATUS.md`, then come back here.
- **Joining as a mockup author?** → read `mockup-conventions.md` start-to-finish.
- **Joining as a sibling-product engineer?** → read `code-conventions.md` and run `setup-tvu-consumer` skill in your repo.
- **Want to propose a rule change?** → see §7 above.
- **Want to understand WHY a rule exists?** → look at the 实证 entry under that rule; it cites the session that triggered it.