# Prompt — NPM-002: README install/Components 扩充 + GETTING_STARTED.md 新建 (v0.1 publish 阻塞)

> **角色**：executor（被 plan owner 调用 / 或单独跑）
> **范围**：更新 `README.md` 三处（Install 段 / Components 表 / 加 GETTING_STARTED 链接）+ 新建 `docs/GETTING_STARTED.md`（5min quickstart 教程）
>
> ⚠️ **不要 commit / 不要 git add** — dirty 累积到 plan owner 复审通过后由 user 决定 commit
> ⚠️ 完成后 **STOP**，按 §4 报告格式回报
> ⚠️ **不扩范围**：仅改 README 三处 + 新建 GETTING_STARTED.md — **不动 src/** / **不改 package.json** / 不实际 publish / 不动 `.github/` / 不改 CHANGELOG / 不写 INSTALL.md（D1=A 路线不需要）/ 不加 npm version badge（依赖 NPM-003 publish 后才有 URL）
> ⚠️ **不做 NPM-003 范围内的事**（publish workflow + license/scope + `.github/workflows/` 全走 NPM-003）

---

## §0 — Plan owner 已定决策（user 拍板"全推荐"）

User 在 NPM-002 backlog entry 三个决策点上 2026-05-11 plan owner 对话拍板：

- **D1 = A 路线** — 保持 README 单一 install 来源，**新建** `docs/GETTING_STARTED.md` 作 5min quickstart 教程；不写 `INSTALL.md`
- **D2 = Button** — quickstart "第一个组件" 用 Button（最直观；几乎所有 design system 都用 Button 当 hello world）
- **D3 = npm / pnpm / yarn 三个全列** — 外部 consumer 用 npm 居多；不锁 pnpm

executor 不需重新决策这 3 项，**直接按 §2 写定内容**。

---

## §1 — 上下文 / 现状基线

### 1.1 项目位置

- 项目目标见 [`AGENTS.md`](../../../AGENTS.md) + [`docs/PROJECT_GOAL.md`](../../PROJECT_GOAL.md)
- v0.1 publish 阻塞物：NPM-001 ✅（commit `7e54d50d`）/ NPM-002（本任务）/ NPM-003（publish CI）+ INFRA-F27 ✅（commit `5125e625`）
- 受众：外部开发 P0（npm 安装 / 看 README / 跑 quickstart 渲染第一个组件）

### 1.2 当前 README.md 现状基线

实测 [`README.md`](../../../README.md) 已有完整段：
- `## Install`（**git+url 模式** — `npm install git+https://github.com/NancyZeng0210/TVU-Design-System.git`，需改）
- `## Setup`（main.ts 全局 install — 不需改）
- `## Usage`（Button + Input 例 — 不需改，已正确示意 import）
- `## Icons`（含 Vue / 其它框架 ESM / CDN 三模式 — 不需改）
- `## Theme switching`（`data-theme="light"` — 不需改）
- `## Components`（**表过时**：仅列 Button + Input 2 项，但 `src/index.ts` 实证 29 component named export — 需扩）
- `## Development` / `## Team usage notes` / `## Figma sync` / `## AI handoff`（不需改）

### 1.3 src/index.ts 实证 29 component named export（用于 §2.1.b Components 表填充）

按 [`src/index.ts:2-31`](../../../src/index.ts#L2) import 顺序 + `export { ... }` 段实证：

| # | Component | 1-line 用途 |
|---|---|---|
| 1 | `Button` | 按钮（fill / ghost / text 三族 × 6 颜色 × 3 size） |
| 2 | `Badge` | 计数 / 状态点 / 文字徽章 |
| 3 | `Breadcrumb` | 面包屑容器 |
| 4 | `BreadcrumbItem` | 面包屑节点（`Breadcrumb` 子组件） |
| 5 | `InputBoxLine` | 输入框 - 下划线变体 |
| 6 | `InputBoxFilled` | 输入框 - 填充变体 |
| 7 | `CheckBox` | 复选框 |
| 8 | `FormItem` | 表单项容器（label + control + error / helper text） |
| 9 | `InputNumber` | 数字输入框（加减按钮 + 直接输入） |
| 10 | `Notification` | 通知气泡（命令式 API + dynamic mount） |
| 11 | `PromptMessage` | 静态消息条（页面内 inline 提示） |
| 12 | `Pagination` | 分页器 |
| 13 | `Progress` | 进度条 |
| 14 | `Radio` | 单选框 |
| 15 | `Rating` | 评分（5 星） |
| 16 | `Slider` | 滑块 |
| 17 | `Switch` | 开关 |
| 18 | `Table` | 表格 |
| 19 | `TopBar` | 顶栏导航 |
| 20 | `SelectBoxLine` | 下拉选择 - 下划线变体 |
| 21 | `SelectBoxFilled` | 下拉选择 - 填充变体 |
| 22 | `DropDownListSelect` | 下拉列表选择器（多选 + 搜索） |
| 23 | `StepItem` | 步骤节点（`Steps` 子组件） |
| 24 | `Steps` | 步骤条容器 |
| 25 | `Tab` | 单个标签页 |
| 26 | `TabItem` | 标签节点（`TabList` 子组件） |
| 27 | `TabList` | 标签页容器 |
| 28 | `Tooltip` | 气泡提示 |
| 29 | `Icon` | 图标组件（`name="category/name"` 形式） |

> Props / events / slots 完整说明在 docs site（`pnpm dev` → `http://localhost:5173`）；README 表保持 name + 1-line 用途即可，**executor 不要尝试展开 props**——会与 canonical/*.vue 真源漂移。

### 1.4 NPM-003 D1 依赖说明（README install 命令选择依据）

NPM-003 D1（License 与发布渠道）3 路线：A 公共 npm / B GitHub Packages / C 保持 git+url。**当前尚未拍板**，但：

- A 与 B 路线 install 命令**形态相同**：`pnpm add @tvu/design-system` / `npm install @tvu/design-system` / `yarn add @tvu/design-system`
- B 路线 GitHub Packages 额外需 `.npmrc` auth setup（属 NPM-003 范围，与本任务无关）
- 仅 C 路线（保持 git+url）会让本任务 install 段需 rollback；pickup §3 明示 v0.1 走 A 或 B（registry 路径），C 已被默认排除

→ **executor 直接按 registry 形态写 install 命令**，不需 conditional / 不需 fallback git+url。如 NPM-003 最终 D1=C，再走单独任务回滚 README install 段。

### 1.5 Pre-flight 状态（plan owner 2026-05-11 已 verify，blocker 概率低）

- `README.md` Install 段当前是 git+url 形态 ✅
- `README.md` Components 表仅 Button + Input 2 项 ✅
- 仓库根 `docs/GETTING_STARTED.md` 不存在 ✅
- 仓库根 `INSTALL.md` 不存在（D1=A 不需建） ✅
- `CHANGELOG.md` 已含 `[0.1.0]` 段（NPM-001 已 commit `7e54d50d`） ✅

如执行时发现以上任一不成立 → 走 §5 blocker 协议。

---

## §2 — 任务（按顺序执行）

### 2.1 更新 `README.md` 三处

**仅这三处改动**，其余 README 段一律不动：

#### (a) 替换 `## Install` 段全部内容

定位：[`README.md:5-11`](../../../README.md#L5)（`## Install` 标题到 `## Setup` 标题之间）

**executor 一字不改 copy 进文件**（替换原 git+url 块）：

````markdown
## Install

```bash
npm install @tvu/design-system
```

```bash
pnpm add @tvu/design-system
```

```bash
yarn add @tvu/design-system
```

For a guided 5-minute walkthrough (Vite + Vue 3 project → render first Button → theme toggle), see [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md).
````

> **删除原"The package builds itself during Git-based installation..."** 整段——registry install 模式不需要此说明。

#### (b) 替换 `## Components` 表全部内容

定位：[`README.md:114-119`](../../../README.md#L114)（`## Components` 标题到 `## Development` 标题之间）

**executor 一字不改 copy 进文件**（替换原 2-row 表）：

````markdown
## Components

29 components across foundation / layout / form / feedback / navigation categories. Full props / events / slots documented in the docs site (`pnpm dev` → `http://localhost:5173`).

| # | Component | Purpose |
|---|-----------|---------|
| 1 | `Button` | 按钮（fill / ghost / text 三族 × 6 颜色 × 3 size） |
| 2 | `Badge` | 计数 / 状态点 / 文字徽章 |
| 3 | `Breadcrumb` | 面包屑容器 |
| 4 | `BreadcrumbItem` | 面包屑节点（`Breadcrumb` 子组件） |
| 5 | `InputBoxLine` | 输入框 - 下划线变体 |
| 6 | `InputBoxFilled` | 输入框 - 填充变体 |
| 7 | `CheckBox` | 复选框 |
| 8 | `FormItem` | 表单项容器（label + control + error / helper text） |
| 9 | `InputNumber` | 数字输入框（加减按钮 + 直接输入） |
| 10 | `Notification` | 通知气泡（命令式 API + dynamic mount） |
| 11 | `PromptMessage` | 静态消息条（页面内 inline 提示） |
| 12 | `Pagination` | 分页器 |
| 13 | `Progress` | 进度条 |
| 14 | `Radio` | 单选框 |
| 15 | `Rating` | 评分（5 星） |
| 16 | `Slider` | 滑块 |
| 17 | `Switch` | 开关 |
| 18 | `Table` | 表格 |
| 19 | `TopBar` | 顶栏导航 |
| 20 | `SelectBoxLine` | 下拉选择 - 下划线变体 |
| 21 | `SelectBoxFilled` | 下拉选择 - 填充变体 |
| 22 | `DropDownListSelect` | 下拉列表选择器（多选 + 搜索） |
| 23 | `StepItem` | 步骤节点（`Steps` 子组件） |
| 24 | `Steps` | 步骤条容器 |
| 25 | `Tab` | 单个标签页 |
| 26 | `TabItem` | 标签节点（`TabList` 子组件） |
| 27 | `TabList` | 标签页容器 |
| 28 | `Tooltip` | 气泡提示 |
| 29 | `Icon` | 图标组件（`name="category/name"` 形式） |

In addition to components, `@tvu/design-system` also exports icon helpers (`iconManifest`, `iconRegistry`, `resolveIcon`, `listIconsByCategory`) and pre-built icon constants (`IconAdd` / `IconMinus` / `IconArrowDropdown` / `IconSelected` / `LogoTVU` / `LogoTS`). See [`src/icons/index.ts`](src/icons/index.ts) for the full surface.
````

#### (c) 不改其它段

`## Setup` / `## Usage` / `## Icons` / `## Theme switching` / `## Development` / `## Team usage notes` / `## Figma sync` / `## AI handoff` 全部保留原内容。

### 2.2 新建 `docs/GETTING_STARTED.md`

完整 inline 内容如下（**executor 一字不改 copy 进文件，不要补充 / 删减 / 重排**）：

````markdown
# Getting Started — TVU Design System (5 min)

This guide walks you from zero to rendering your first TVU component in a fresh Vue 3 project. ~5 minutes.

For the cross-AI workflow contract (Claude / Codex / Cursor / Cline), see [`AGENTS.md`](../AGENTS.md). For full product goals, see [`docs/PROJECT_GOAL.md`](./PROJECT_GOAL.md).

---

## 1. Create a Vue 3 project

If you already have a Vue 3 + TypeScript project, skip to step 2.

```bash
npm create vite@latest my-app -- --template vue-ts
cd my-app
npm install
```

(Replace `npm` with `pnpm` / `yarn` if preferred — the rest of this guide assumes `pnpm`.)

---

## 2. Install the design system

```bash
pnpm add @tvu/design-system
```

`vue@^3.4.0` is a peer dependency and should already be in your project.

---

## 3. Import token CSS (required)

TVU Design System components rely on CSS variables for colors, spacing, typography, and theme switching. **You must import the bundled stylesheet once**, typically in `main.ts`:

```typescript
// src/main.ts
import { createApp } from 'vue'
import App from './App.vue'
import '@tvu/design-system/style.css'

createApp(App).mount('#app')
```

Without this import, components will render unstyled (no token resolution).

---

## 4. Pick an import mode

You have two options. Both are supported; pick what fits your project.

### Option A — Global registration (simplest)

Register the whole library once; use any component by tag name anywhere:

```typescript
// src/main.ts
import { createApp } from 'vue'
import TVUDesignSystem from '@tvu/design-system'
import '@tvu/design-system/style.css'
import App from './App.vue'

createApp(App).use(TVUDesignSystem).mount('#app')
```

Then in any `.vue` file:

```vue
<template>
  <Button variant="fill-green">Save</Button>
</template>
```

### Option B — Per-component import (tree-shake friendly)

Skip `.use(TVUDesignSystem)` and import each component locally:

```vue
<script setup lang="ts">
import { Button } from '@tvu/design-system'
</script>

<template>
  <Button variant="fill-green">Save</Button>
</template>
```

Option B keeps your bundle smaller if you only use a few components.

---

## 5. Render your first component — Button

Create `src/App.vue`:

```vue
<script setup lang="ts">
import { Button } from '@tvu/design-system'

function onSave() {
  console.log('saved!')
}
</script>

<template>
  <main style="padding: 32px;">
    <h1>Hello TVU</h1>
    <Button variant="fill-green" size="m" @click="onSave">Save</Button>
    <Button variant="ghost-gray" size="m">Cancel</Button>
  </main>
</template>
```

Run the dev server:

```bash
pnpm dev
```

Open `http://localhost:5173` — you should see a green "Save" button and a gray ghost "Cancel" button on a dark background (dark is the default theme).

---

## 6. Toggle the theme

The design system ships with a complete dark / light theme system driven by `data-theme` on `<html>`. Default is dark. Switch to light at runtime:

```typescript
document.documentElement.setAttribute('data-theme', 'light')
```

Switch back to dark:

```typescript
document.documentElement.setAttribute('data-theme', 'dark')
```

All component colors, surfaces, borders, and shadows respond automatically — no per-component prop needed.

To make a toggle button:

```vue
<script setup lang="ts">
import { Button } from '@tvu/design-system'
import { ref } from 'vue'

const isDark = ref(true)

function toggleTheme() {
  isDark.value = !isDark.value
  document.documentElement.setAttribute('data-theme', isDark.value ? 'dark' : 'light')
}
</script>

<template>
  <Button variant="ghost-gray" @click="toggleTheme">
    Switch to {{ isDark ? 'light' : 'dark' }}
  </Button>
</template>
```

---

## 7. Next steps

- Browse all 29 components and their full props / events / slots in the local docs site: `pnpm dev` in the design system repo → `http://localhost:5173`
- Read [`AGENTS.md`](../AGENTS.md) for the AI-assisted Figma → code workflow if you're using Claude / Codex / Cursor with this library
- See the [`README.md`](../README.md) Icons section for icon usage (`<Icon name="time/clock" />`) including React / CDN consumption modes

---

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Components render unstyled | Forgot `import '@tvu/design-system/style.css'` | Add the import to `main.ts` |
| TypeScript "cannot find module" | Vue version < 3.4 | Upgrade `vue` to `^3.4.0` (peer dep) |
| Icons show as empty boxes | Using legacy alias not in catalog | Use `category/name` form (e.g. `time/clock`), not legacy aliases |
| Theme toggle doesn't update colors | Setting attribute on wrong element | Must be `<html>` element (`document.documentElement`), not `<body>` |
````

---

## §3 — 验证（exit 0 / 输出预期）

执行完 §2 全部步骤后，按下面 verify。每条命令的预期输出在右列：

| 命令 | 预期输出 / exit |
|---|---|
| `grep -c 'git+https' README.md` | `0`（git+url 已全删） |
| `grep -c '^## Install$' README.md` | `1` |
| `grep -c 'npm install @tvu/design-system' README.md` | `1` |
| `grep -c 'pnpm add @tvu/design-system' README.md` | `1`（README 中；GETTING_STARTED 不算 README） |
| `grep -c 'yarn add @tvu/design-system' README.md` | `1` |
| `grep -c 'docs/GETTING_STARTED.md' README.md` | `1`（Install 段末尾链接） |
| `grep -c '^| [0-9]\+ \\| ' README.md` | `29`（Components 表 29 row 的"\| N \| Component \|"行；如 grep regex 在 macOS BSD 上不兼容，executor 用 `awk '/^\\| [0-9]/ {c++} END {print c}' README.md` 替代，应输出 29） |
| `ls docs/GETTING_STARTED.md` | 存在 |
| `grep -c '^## [1-7]\.' docs/GETTING_STARTED.md` | `7`（七段标题：1.Create / 2.Install / 3.Import / 4.Pick / 5.Render / 6.Toggle / 7.Next） |
| `grep -c 'Button' docs/GETTING_STARTED.md` | ≥ `5`（quickstart 反复用 Button 当第一个组件） |
| `grep -c 'data-theme' docs/GETTING_STARTED.md` | ≥ `3`（§6 Theme toggle 段） |
| `pnpm exec vue-tsc --noEmit; echo "exit: $?"` | `exit: 0`（README/GETTING_STARTED 纯文档改动；不影响 typecheck） |

---

## §4 — 报告格式（完成后 STOP 回报到对话）

```
## NPM-002 执行报告

### 文件改动
- 修改：README.md（Install 段 +9/-7 行 / Components 表 +30/-3 行 / 共 +N/-M）
- 新增：docs/GETTING_STARTED.md（约 XXX 行）

### 验证
- §3 全部 12 条命令 PASS / FAIL（贴关键输出）
- INFRA-F27 build 副作用：未跑 build，本任务纯文档，无副作用

### 未解决项 / blocker
- 无 / 列出

STOP — 等 plan owner 复审 + user 拍板 commit。
```

---

## §5 — Blocker 自检（pre-flight 强制）

executor 在跑 §2 之前 verify 以下，命中任一 → STOP，不执行，按 §4 格式仅填"未解决项"汇报：

- [ ] `grep -n '^## Install$' README.md` 应有 1 命中。如 0 或 >1 → blocker（README 结构变了，prompt 失效）
- [ ] `grep -n '^## Components$' README.md` 应有 1 命中。如 0 或 >1 → blocker
- [ ] `ls docs/GETTING_STARTED.md` 应是 "no such file"。如已存在 → blocker（user 决定追加 vs overwrite，不 executor 决定）
- [ ] `git status --short docs/GETTING_STARTED.md README.md` 应只有 README.md M（plan owner 可能有 dirty）；如有其他人改 README → 列出给 user 看，等指示
- [ ] `cat src/index.ts | grep -E '^import .* from .*(canonical|components/Icon)' | wc -l` 应是 `29`。如 ≠ 29 → blocker（component 数量变了，§2.1.b 表过时）

---

## §6 — 反模式自检（plan owner 已过，executor 不需重做；只列在此供审阅）

| # | 反模式 | 自检结论 |
|---|---|---|
| 1 | 硬编码项目级规则到工具 | ✗ 本 prompt 产文档（README + GETTING_STARTED），无规则硬编码 |
| 2 | 打补丁方案 | ✗ 扩充 README + 新建 quickstart 教程是 mainline 工程实践，非补丁 |
| 3 | to-do list 思维（无产出契约） | ✗ §3 验证含可机械验证的 schema（29 row count / 7 section count / 3 install command 各 1 命中 / data-theme ≥ 3 命中）|
| 4 | 没问下游怎么消费 | ✗ 下游：外部开发 P0 装包后看 README → 跳 GETTING_STARTED → render Button → 切 theme → 用所有 29 组件；链路明确 |
| 5 | 扩展时改哪里 | ✗ 后续添组件时改 `src/index.ts` → README Components 表对应一处更新；未来可加 audit 验证 README 表 vs `src/index.ts` 漂移（NPM-002 不做） |

---

## §7 — 关联

- backlog entry: [`docs/internal/backlog.md`](../backlog.md) §NPM-002
- handoff: [`_plans/next-session-pickup-2026-05-11.md`](../_plans/next-session-pickup-2026-05-11.md) §3 第 1 步
- 系统性 review: [`_reports/systematic-review-2026-05-09.md`](../_reports/systematic-review-2026-05-09.md) §1.3
- 前置依赖：NPM-001 ✅（CHANGELOG `[0.1.0]` 已落 commit `7e54d50d`）/ INFRA-F27 ✅（commit `5125e625`）
- 后续依赖：NPM-003（publish workflow — 拍板 D1 选 A/B/C 后，README install 段可能再调整 `.npmrc` setup 说明，但 install 命令形态不变）