# Component Affordances — AI 组合组件语义层

> ⚠️ **本文件由脚本生成，勿手改**。真源是 [`component-affordances.json`](./component-affordances.json)；改 JSON 后跑 `pnpm generate:component-affordances`。
>
> 让 AI 在设计产品（生成 Vue 代码 / 生成 Figma mockup）时，先知道每个 canonical 组件内置了什么能力，避免把已有组件（如 InputNumber 的 step / DropDownListSelect 的 multi）拆开自己用 primitive 拼。对标图标的 affordance-categories.json：图标解决「别自画 SVG」，本文件解决「别自拼组合组件」。

**给 AI 的用法**：设计产品（写 Vue / 画 Figma）前，先在这里按「是什么 / 何时用 / 别名」找到对的组件，再看它的「内置能力」——能力已内置的，**用 prop/轴开，不要拆成 primitive 自己拼**（如 InputNumber 的 step、DropDownListSelect 的 multi）。

覆盖 37 个 canonical 组件。mockup 任务的 library key / frame 归属另见 [figma-component-catalog.md](./figma-component-catalog.md)。

## 速查索引

- **Form / Input（表单与录入）**: InputNumber · Slider · DropDownListSelect · SelectBoxBase · SelectBoxLine · SelectBoxFilled · InputBoxBase · InputBoxLine · InputBoxFilled · FormItem · CheckBox · Radio · Switch · Rating
- **Data Display（数据展示）**: Table · Tooltip · Badge · PillStatus · PillCounter · Progress · Chart
- **Navigation（导航）**: Pagination · Tab · TabList · TabItem · Breadcrumb · BreadcrumbItem · Steps · StepItem · TopBar · MenuList · UserMenu
- **Feedback（反馈 / 弹层）**: Notification · Message · PopupBox
- **General（通用）**: ButtonBridge · Logo

---

## Form / Input（表单与录入）

### InputNumber

- **Figma**: `InputNumber` · **npm**: `InputNumber` · **import**: `import { InputNumber } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 数字步进输入框（spinbox）—— 输入框 + 内置加减按钮 + 上下界约束。
- **何时用**: 需要受约束的整数/数值录入并希望提供加减微调时（如数量、并发数、时长）。需要连续区间拖动用 Slider。
- **别名**: 数字输入框 · 步进器 · 数量输入 · 计数器 · 数值输入 · number input · stepper · spinbox · spinner · quantity input · numeric field · counter input

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 加减步进按钮（+/-） | 组件自带，无需外接按钮；步长用 prop:step（默认 1） |
| 上下界约束 | prop:min（默认 0）/ prop:max（默认 10），到界自动禁用对应按钮 |
| 只增 / 只减 / 只读形态 | prop:property1 = Default \| Only Add \| Only Reduce \| Readonly |
| 禁用态 | prop:disabled |

> ⛔ **别自拼**: 别用 InputBox + 两个 Button(+/-) 自拼步进器，也别用裸 <input type=number>。直接用 InputNumber，步长/边界走 step/min/max，单向用 type=Only Add|Only Reduce。

- **组合关系**: 通常被 FormItem 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `modelValue` | number | — |
| `type` | Default \| Only Add \| Only Reduce \| Readonly | `Default` |
| `min` | number | `0` |
| `max` | number | `10` |
| `step` | number | `1` |
| `disabled` | boolean | `false` |

- **事件**: `update:modelValue`
- **相关**: Slider / InputBoxLine

### Slider

- **Figma**: `Slider` · **npm**: `Slider` · **import**: `import { Slider } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 连续数值滑块 —— 拖动选值 + 内置 step/min/max + 可选数值显示。
- **何时用**: 在连续区间内选一个值、且拖动比键入更自然时（音量、亮度、百分比）。需要精确键入用 InputNumber。
- **别名**: 滑块 · 滑动条 · 区间选择 · 音量条 · 进度拖拽 · slider · range · range input · track · volume control · seek bar

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 步进 / 区间 | prop:step / prop:min / prop:max |
| 当前值显示 | prop:showValue（默认 true） |
| 尺寸 / 主题 | prop:size = M ... / prop:theme = dark\|light |
| 禁用态 | prop:disabled |

> ⛔ **别自拼**: 别用 <input type=range> 裸控件或自画轨道+滑块 div。用 Slider，值标签走 showValue 而非外接一个 <span>。

- **组合关系**: 通常被 FormItem 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `modelValue` | number | `60` |
| `size` | Size | `M` |
| `theme` | dark \| light | `dark` |
| `min` | number | `0` |
| `max` | number | `100` |
| `step` | number | `1` |
| `showValue` | boolean | `true` |
| `disabled` | boolean | `false` |

- **事件**: `update:modelValue`
- **相关**: InputNumber / Progress

### DropDownListSelect

- **Figma**: `Drop down List/Select` · **npm**: `DropDownListSelect` · **import**: `import { DropDownListSelect } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 下拉列表面板 —— 渲染 items 列表，支持单选/多选/操作列表/排序四种列表语义，内置键盘 roving focus。
- **何时用**: 需要展示一组可选行（单选/多选/带勾选/操作项）。整体「输入框+下拉」选择器用 SelectBoxLine/Filled；本组件是下拉里的列表面板本体。
- **别名**: 下拉列表 · 下拉面板 · 选项列表 · 多选列表 · 操作菜单 · 排序菜单 · dropdown · dropdown list · listbox · option list · menu list · multi select list · operation list

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 列表语义（单选/多选/操作/排序） | prop:type = Radio \| Multi \| Operation List \| Sort By |
| 多选勾选标记 | type=Multi 时内置勾选，无需手撸 <span class=check>（见 CANONICAL-012） |
| 禁用单项 | items[].disabled |
| 键盘 roving focus + aria-activedescendant | 组件内置（CANONICAL-016），无需自管 tabindex |

> ⛔ **别自拼**: 别用 <ul><li> + 自撸勾选 <span> 拼下拉列表，也别给每行自管 tabindex。用 DropDownListSelect，多选走 type=Multi（勾选已内置），禁用项走 items[].disabled。

- **组合关系**: 通常被 SelectBoxBase / SelectBoxLine / SelectBoxFilled 包裹；内部用到 CheckBox

| prop | 类型 | 默认 |
|---|---|---|
| `darkTheme` | DarkTheme | `on` |
| `type` | Radio \| Multi \| Operation List \| Sort By | `Radio` |
| `items` | readonly Item[] | `[]` |

- **事件**: `select` · `close`
- **相关**: SelectBoxLine / SelectBoxFilled / CheckBox

### SelectBoxBase

- **Figma**: `select box/{variant}` · **npm**: —（内部） · **import**: _内部 base，不在 npm 公开导出_
- **是什么**: 下拉选择器底层实现（输入框 + 下拉面板）。内部 base，消费方请用 SelectBoxLine / SelectBoxFilled。
- **何时用**: 内部 base 组件，不直接消费。需要 select 时用 SelectBoxLine（线框）或 SelectBoxFilled（填充）。
- **别名**: 选择器底层 · 下拉选择基类 · select · select box · combobox base

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 单选/多选 | prop:multiple 或 status=multi select |
| 可编辑（搜索/筛选） | prop:editable 或 ux=editable |
| 线框/填充形态 | prop:variant = line \| filled |

> ⛔ **别自拼**: 不要直接 import SelectBoxBase。用 SelectBoxLine / SelectBoxFilled。

- **组合关系**: 通常被 FormItem 包裹；内部用到 DropDownListSelect

| prop | 类型 | 默认 |
|---|---|---|
| `modelValue` | string \| number \| Array<string\|number> | — |
| `options` | Option[] | `[]` |
| `variant` | line \| filled | `line` |
| `multiple` | boolean | `false` |
| `editable` | boolean | `false` |
| `darkTheme` | DarkTheme | `on` |
| `status` | Status | `default` |
| `enable` | Enable | `on` |
| `ux` | UX | `default` |
| `size` | Size | `M` |
| `feature` | Feature | `default` |
| `placeholder` | string | `` |

- **事件**: `update:modelValue`
- **相关**: SelectBoxLine / SelectBoxFilled / DropDownListSelect

### SelectBoxLine

- **Figma**: `select box/line` · **npm**: `SelectBoxLine` · **import**: `import { SelectBoxLine } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 线框下拉选择器（输入框 + 下拉面板，单选/多选/可搜索）。
- **何时用**: 从选项中选一个或多个值，线框（透明底）风格。深底填充风格用 SelectBoxFilled。
- **别名**: 选择器 · 下拉框 · 下拉选择 · 选择框 · select · select box · combobox · dropdown select · picker

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 多选 | prop:multiple（内置多选 chip + 勾选） |
| 可编辑/搜索 | prop:editable |
| 尺寸 / 状态 / 禁用 | prop:size / prop:status / prop:enable |

> ⛔ **别自拼**: 别用 input + 浮层 div + 自撸 chip 拼 select。用 SelectBoxLine，多选走 multiple（chip 与勾选已内置），可搜索走 editable。

- **组合关系**: 通常被 FormItem 包裹；内部用到 DropDownListSelect

| prop | 类型 | 默认 |
|---|---|---|
| `modelValue` | string \| number \| Array<string\|number> | — |
| `options` | {label;value}[] | `[]` |
| `multiple` | boolean | `false` |
| `editable` | boolean | `false` |
| `darkTheme` | DarkTheme | `on` |
| `status` | Status | `default` |
| `enable` | Enable | `on` |
| `ux` | UX | `default` |
| `size` | Size | `M` |
| `feature` | Feature | `default` |
| `placeholder` | string | `` |

- **事件**: `update:modelValue`
- **相关**: SelectBoxFilled / DropDownListSelect / InputBoxLine

### SelectBoxFilled

- **Figma**: `select box/filled` · **npm**: `SelectBoxFilled` · **import**: `import { SelectBoxFilled } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 填充底下拉选择器（输入框 + 下拉面板，单选/多选/可搜索）。
- **何时用**: 从选项中选值，填充（深底）风格。透明线框风格用 SelectBoxLine。
- **别名**: 选择器 · 下拉框 · 填充选择框 · select · select box · combobox · dropdown select · filled select

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 多选 | prop:multiple |
| 可编辑/搜索 | prop:editable |
| 尺寸 / 状态 / 禁用 | prop:size / prop:status / prop:enable |

> ⛔ **别自拼**: 同 SelectBoxLine：别自拼 select，用本组件 + multiple/editable。

- **组合关系**: 通常被 FormItem 包裹；内部用到 DropDownListSelect

| prop | 类型 | 默认 |
|---|---|---|
| `modelValue` | string \| number \| Array<string\|number> | — |
| `options` | {label;value}[] | `[]` |
| `multiple` | boolean | `false` |
| `editable` | boolean | `false` |
| `darkTheme` | DarkTheme | `on` |
| `status` | Status | `default` |
| `enable` | Enable | `on` |
| `ux` | UX | `default` |
| `size` | Size | `M` |
| `feature` | Feature | `default` |
| `placeholder` | string | `` |

- **事件**: `update:modelValue`
- **相关**: SelectBoxLine / DropDownListSelect / InputBoxFilled

### InputBoxBase

- **Figma**: `input box/{variant}` · **npm**: —（内部） · **import**: _内部 base，不在 npm 公开导出_
- **是什么**: 文本输入框底层实现。内部 base，消费方请用 InputBoxLine / InputBoxFilled。
- **何时用**: 内部 base，不直接消费。需要文本输入用 InputBoxLine（线框）或 InputBoxFilled（填充）。
- **别名**: 输入框底层 · 文本输入基类 · input · text input · text field · input base

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 线框/填充 | prop:variant = line \| filled |
| 清除按钮 / feature 图标 | prop:feature = yes（配合 ux=click 显示 clear） |
| 只读 / 禁用 | prop:readonly / prop:enable |

> ⛔ **别自拼**: 不要直接 import InputBoxBase。用 InputBoxLine / InputBoxFilled。

- **组合关系**: 通常被 FormItem 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `modelValue` | string | `` |
| `variant` | line \| filled | `line` |
| `placeholder` | string | `` |
| `feature` | Feature | `no` |
| `readonly` | boolean | `false` |
| `darkTheme` | DarkTheme | `on` |
| `status` | Status | `default` |
| `enable` | Enable | `on` |
| `ux` | UX | `default` |
| `size` | Size | `M` |

- **事件**: `update:modelValue`
- **相关**: InputBoxLine / InputBoxFilled

### InputBoxLine

- **Figma**: `input box/line` · **npm**: `InputBoxLine` · **import**: `import { InputBoxLine } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 线框文本输入框（透明底 + 下划线/边框）。
- **何时用**: 单行文本录入，线框风格。深底填充风格用 InputBoxFilled；数值用 InputNumber。
- **别名**: 输入框 · 文本框 · 线框输入框 · input · text input · text field · line input · underline input

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 清除按钮 | prop:feature=yes + ux=click（有值时显示 clear） |
| 尺寸 / 状态 / 只读 / 禁用 | prop:size / prop:status / prop:readonly / prop:enable |

> ⛔ **别自拼**: 别用裸 <input> + 自定义边框样式。用 InputBoxLine，清除图标走 feature=yes 而非外接一个 close icon。

- **组合关系**: 通常被 FormItem 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `modelValue` | string | `` |
| `placeholder` | string | `` |
| `feature` | Feature | `no` |
| `readonly` | boolean | `false` |
| `darkTheme` | DarkTheme | `on` |
| `status` | Status | `default` |
| `enable` | Enable | `on` |
| `ux` | UX | `default` |
| `size` | Size | `M` |

- **事件**: `update:modelValue`
- **相关**: InputBoxFilled / InputNumber / SelectBoxLine

### InputBoxFilled

- **Figma**: `input box/filled` · **npm**: `InputBoxFilled` · **import**: `import { InputBoxFilled } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 填充底文本输入框（深底）。
- **何时用**: 单行文本录入，填充风格。透明线框风格用 InputBoxLine。
- **别名**: 输入框 · 文本框 · 填充输入框 · input · text input · text field · filled input

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 清除按钮 | prop:feature=yes + ux=click |
| 尺寸 / 状态 / 只读 / 禁用 | prop:size / prop:status / prop:readonly / prop:enable |

> ⛔ **别自拼**: 同 InputBoxLine：别自拼输入框，用本组件。

- **组合关系**: 通常被 FormItem 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `modelValue` | string | `` |
| `placeholder` | string | `` |
| `feature` | Feature | `no` |
| `readonly` | boolean | `false` |
| `darkTheme` | DarkTheme | `on` |
| `status` | Status | `default` |
| `enable` | Enable | `on` |
| `ux` | UX | `default` |
| `size` | Size | `M` |

- **事件**: `update:modelValue`
- **相关**: InputBoxLine / InputNumber / SelectBoxFilled

### FormItem

- **Figma**: `FormItem` · **npm**: `FormItem` · **import**: `import { FormItem } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 表单行容器 —— label + 控件插槽 + required 星号 + error/hint 文案 + 布局对齐。
- **何时用**: 给任意表单控件加标签、必填标记、错误/提示文案并统一对齐。包裹 InputBox / SelectBox / InputNumber 等。
- **别名**: 表单项 · 表单行 · 字段 · 标签输入组 · 表单字段 · form item · form field · form row · field wrapper · label input group

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 标签 + 必填星号 | prop:label / prop:required |
| 错误 / 提示文案 | prop:error / prop:hint（无需自己加一行红字 <span>） |
| 标签宽度 + 单/双行布局 | prop:labelWidth / prop:layout |
| label 命名插槽（富标签） | #label slot（v0.4.0 dual-form） |

> ⛔ **别自拼**: 别用 <label> + 控件 + 红字 <div> 手拼表单行。用 FormItem 包控件，必填走 required，报错走 error，对齐走 labelWidth/layout。

- **组合关系**: 内部用到 InputBoxLine / InputBoxFilled / InputNumber / SelectBoxLine / SelectBoxFilled / CheckBox / Radio / Switch

| prop | 类型 | 默认 |
|---|---|---|
| `label` | string | `Form Label` |
| `required` | boolean | `false` |
| `error` | string | — |
| `hint` | string | `` |
| `labelWidth` | LabelWidth | `120 px` |
| `layout` | Layout | `1 line` |
| `status` | Status | `Normal` |
| `theme` | Theme | `Dark` |
| `type` | Type | `Label & Input` |
- **相关**: InputBoxLine / SelectBoxLine / InputNumber

### CheckBox

- **Figma**: `check box` · **npm**: `CheckBox` · **import**: `import { CheckBox } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 复选框 —— 勾选/未勾选/半选三态，支持只读展示态。
- **何时用**: 布尔多选 / 三态勾选。下拉列表里的勾选请用 DropDownListSelect type=Multi（已内置 CheckBox）。
- **别名**: 复选框 · 勾选框 · 多选 · 半选 · checkbox · check · tick box · multi select toggle · indeterminate

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 三态（勾/未勾/半选） | prop:status = on \| off \| some |
| 只读展示态 | prop:readonly（行本身是点击目标时用，CANONICAL-012） |
| 禁用态 | prop:enable = no |

> ⛔ **别自拼**: 别用裸 <input type=checkbox> 或自画方块+对勾。用 CheckBox，半选走 status=some，纯展示走 readonly。

- **组合关系**: 通常被 FormItem / DropDownListSelect / Table 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `status` | on \| off \| some | `off` |
| `darkTheme` | DarkTheme | `on` |
| `enable` | Enable | `yes` |
| `readonly` | boolean | `false` |

- **事件**: `update:status`
- **相关**: Radio / Switch / DropDownListSelect

### Radio

- **Figma**: `radio` · **npm**: `Radio` · **import**: `import { Radio } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 单选按钮 —— 选中/未选中两态。
- **何时用**: 一组互斥选项里选一个。下拉里的单选用 DropDownListSelect type=Radio。
- **别名**: 单选按钮 · 单选框 · 单选 · radio · radio button · option button · single select

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 选中态 | prop:status = on \| off |
| 禁用态 | prop:enable = no |

> ⛔ **别自拼**: 别用裸 <input type=radio> 或自画圆圈。用 Radio，选中走 status=on。

- **组合关系**: 通常被 FormItem / DropDownListSelect 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `status` | on \| off | `off` |
| `darkTheme` | DarkTheme | `on` |
| `enable` | Enable | `yes` |

- **事件**: `update:status`
- **相关**: CheckBox / Switch

### Switch

- **Figma**: `switch` · **npm**: `Switch` · **import**: `import { Switch } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 开关 —— 开/关/直播(live) 态 + 内置 loading。
- **何时用**: 即时生效的布尔开关（启用/停用某功能）。需要确认后才生效的多选用 CheckBox。
- **别名**: 开关 · 切换 · 拨动开关 · 切换开关 · switch · toggle · on off · toggle switch

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 开/关/直播态 | prop:status = on \| off \| live |
| 加载中（异步切换） | prop:loading = yes（无需外接 spinner） |
| 禁用态 | prop:enable = no |

> ⛔ **别自拼**: 别用 div + transition 自画拨钮，也别在切换时外接一个 spinner。用 Switch，异步等待走 loading=yes。

- **组合关系**: 通常被 FormItem / Table 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `status` | on \| off \| live | `off` |
| `loading` | yes \| no | `no` |
| `darkTheme` | DarkTheme | `on` |
| `enable` | Enable | `yes` |

- **事件**: `update:status`
- **相关**: CheckBox / Radio

### Rating

- **Figma**: `Rating` · **npm**: `Rating` · **import**: `import { Rating } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 星级评分 —— 显示/选择 1-5 星，默认只读。
- **何时用**: 展示或采集星级评分。
- **别名**: 评分 · 星级 · 打分 · 星星 · rating · stars · star rating · score

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 星值 | prop:value（'1'..'5'） |
| 只读/可选 | prop:readonly（默认 true 只读） |

> ⛔ **别自拼**: 别用循环画 star 图标拼评分。用 Rating，值走 value，可交互走 readonly=false。

- **组合关系**: 通常被 Table / FormItem 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `value` | '1' \| '2' \| '3' \| '4' \| '5' | `1` |
| `readonly` | boolean | `true` |

- **事件**: `update:value`

---

## Data Display（数据展示）

### Table

- **Figma**: `Table` · **npm**: `Table` · **import**: `import { Table } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 数据表格 —— 列定义 + 数据驱动渲染 + 对齐 + 斑马纹；分页请配 Pagination。
- **何时用**: 结构化行列数据展示。分页用 Pagination 配合（不要 Table 内自实现）。
- **别名**: 表格 · 数据表 · 列表表格 · 数据网格 · table · data table · grid · datagrid · list table

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 列定义 + 数据驱动 | prop:columns / prop:data（无需手写 <tr><td>） |
| 对齐 | prop:align（列可单独 column.align 覆盖） |
| 斑马纹 | prop:striped |
| 表头形态 | prop:type |

> ⛔ **别自拼**: 别手写 <table><thead><tbody> 拼数据表。用 Table，列走 columns、数据走 data；分页另配 Pagination。

- **组合关系**: 内部用到 Pagination / Badge / Switch / CheckBox / Rating

| prop | 类型 | 默认 |
|---|---|---|
| `columns` | readonly TableColumn[] | `[]` |
| `data` | Record<string,unknown>[] | `[]` |
| `align` | Align | `Center` |
| `type` | Type | `Header` |
| `striped` | boolean | `false` |
- **相关**: Pagination

### Tooltip

- **Figma**: `Tooltip` · **npm**: `Tooltip` · **import**: `import { Tooltip } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 气泡提示 —— 悬浮文案 + 6 个指向方位，内置定位。
- **何时用**: hover/focus 时补充说明。常驻行内提示用 Message。
- **别名**: 气泡提示 · 悬浮提示 · 工具提示 · 提示气泡 · tooltip · hint · popover · hover hint · bubble

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 指向方位 | prop:pointing（6 向，内部映射到 placement） |
| 文案 | prop:content 或 #content slot（v0.4.0 dual-form） |
| 受控显隐 / 禁用 | prop:open / prop:disabled |

> ⛔ **别自拼**: 别用 title 属性或自管绝对定位 div 拼 tooltip。用 Tooltip，方位走 pointing。

| prop | 类型 | 默认 |
|---|---|---|
| `content` | string | `Description` |
| `pointing` | Pointing | `Center down` |
| `darkTheme` | DarkTheme | `off` |
| `open` | boolean | `false` |
| `disabled` | boolean | `false` |
- **相关**: Message

### Badge

- **Figma**: `Badge` · **npm**: `Badge` · **import**: `import { Badge } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 状态/计数标记 —— 圆形/矩形 × 5 色 × 填充/线框，只读指示。
- **何时用**: 只读的状态/计数指示（行内状态、计数角标）。可点击的 chip/选择用 Tab；运行态会话指示用 PillStatus。
- **别名**: 徽标 · 标签 · 状态点 · 计数标记 · 角标 · badge · tag · pill · status dot · count badge · label

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 形状 | prop:type = Circle \| Rectangle |
| 状态色 | prop:color = Green \| Blue \| Orange \| Red \| Neutral |
| 填充/线框 | prop:fill = Filled \| Line |

> ⛔ **别自拼**: 别用带背景色的 <span> 自拼状态标。用 Badge，色走 color、形态走 type/fill。

- **组合关系**: 通常被 Table / TopBar 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `type` | Circle \| Rectangle | `Circle` |
| `color` | Green \| Blue \| Orange \| Red \| Neutral | `Green` |
| `fill` | Filled \| Line | `Filled` |
- **相关**: PillStatus / PillCounter

### PillStatus

- **Figma**: `Pill Status` · **npm**: `PillStatus` · **import**: `import { PillStatus } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 会话运行状态药丸 —— On-air/Preview/Analyzing/Inactive + active 态 + 可选计数。
- **何时用**: TVU 会话/流的运行状态指示（直播/预览/分析中/未激活）。通用状态/计数用 Badge。
- **别名**: 状态药丸 · 会话状态 · 直播状态 · 运行状态 · status pill · session status · live pill · state badge

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 状态语义色 | prop:status = On-air(red) \| Preview(brand) \| Analyzing(blue) \| Inactive(grey) |
| 激活/未激活态 | prop:active（false 时统一灰态） |
| 计数 | prop:count |

> ⛔ **别自拼**: 别自拼带圆点的状态药丸。用 PillStatus，运行语义走 status，未激活走 active=false。

- **组合关系**: 通常被 Table / TopBar 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `status` | On-air \| Preview \| Analyzing \| Inactive | `On-air` |
| `active` | boolean | `true` |
| `count` | number \| string | — |
- **相关**: Badge / PillCounter

### PillCounter

- **Figma**: `Pill/Counter` · **npm**: —（内部） · **import**: _内部 base，不在 npm 公开导出_
- **是什么**: 计数药丸（neutral/success/warning/info 配色）。内部组件，未在 npm 公开导出。
- **何时用**: 内部组件，当前未公开导出。通用计数标记请用 Badge。
- **别名**: 计数药丸 · 计数标记 · counter pill · count badge

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 配色语义 | prop:kind = neutral \| success \| warning \| info |

> ⛔ **别自拼**: 当前不在 npm 公开 API；通用计数用 Badge。

| prop | 类型 | 默认 |
|---|---|---|
| `kind` | neutral \| success \| warning \| info | `neutral` |
- **相关**: Badge / PillStatus

### Progress

- **Figma**: `Progress` · **npm**: `Progress` · **import**: `import { Progress } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 进度条 —— 百分比值 + 状态色 + 可选标签。
- **何时用**: 展示任务完成百分比（只读）。可拖动选值用 Slider。
- **别名**: 进度条 · 进度 · 百分比条 · 加载条 · progress · progress bar · loading bar · percentage bar

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 进度值 | prop:value（0-100） |
| 状态色 | prop:status |
| 百分比标签 | prop:showLabel（默认 true） |

> ⛔ **别自拼**: 别用嵌套 div + width% 自画进度条。用 Progress，值走 value，标签走 showLabel。

| prop | 类型 | 默认 |
|---|---|---|
| `value` | number | `60` |
| `size` | Size | `M` |
| `status` | Status | `default` |
| `theme` | Theme | `dark` |
| `showLabel` | boolean | `true` |
- **相关**: Slider

### Chart

- **Figma**: `Chart` · **npm**: `Chart` · **import**: `import { Chart } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 图表 —— Chart.js 封装，按 type 渲染多种图，datasets 驱动 + 12 色调色板。
- **何时用**: 数据可视化（柱/线/饼等，按 type）。
- **别名**: 图表 · 图形 · 统计图 · 柱状图 · 折线图 · 饼图 · chart · graph · plot · bar chart · line chart · pie chart

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 图表类型 | prop:type |
| 数据集 + 标签 | prop:datasets / prop:labels |
| 尺寸 | prop:width / prop:height |

> ⛔ **别自拼**: 别直接引 Chart.js 或自画 svg 图表。用 Chart，类型走 type、数据走 datasets（内置 12 色 palette）。

| prop | 类型 | 默认 |
|---|---|---|
| `type` | ChartType | — |
| `datasets` | ChartDatasetInput[] | — |
| `labels` | string[] | `[]` |
| `height` | number | `200` |
| `width` | number | `320` |

---

## Navigation（导航）

### Pagination

- **Figma**: `Pagination` · **npm**: `Pagination` · **import**: `import { Pagination } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 分页器 —— 页码导航 + 总数/页大小驱动，支持经典/其它形态。
- **何时用**: 长列表 / 表格分页。通常放 Table 下方。
- **别名**: 分页 · 分页器 · 翻页 · 页码 · pagination · pager · page nav · page navigation

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 页码计算 | prop:total / prop:pageSize（自动算页数） |
| 当前页双向绑定 | v-model（update:modelValue） |
| 形态 | prop:type = Classic \| ... |

> ⛔ **别自拼**: 别用 button 列表自拼页码。用 Pagination，页数由 total/pageSize 自动算，当前页 v-model。

- **组合关系**: 通常被 Table 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `modelValue` | number | `3` |
| `total` | number | `120` |
| `pageSize` | number | `10` |
| `type` | Type | `Classic` |

- **事件**: `update:modelValue` · `update:pageSize`
- **相关**: Table

### Tab

- **Figma**: `Tab` · **npm**: `Tab` · **import**: `import { Tab } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 单个 Tab 触发器（单标签）。多标签用 TabList 一次给一组。
- **何时用**: 需要单独一个标签时。整组标签优先用 TabList（数据驱动）。
- **别名**: 标签页 · 选项卡 · 单个标签 · tab · tab trigger

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 线框/文字/填充形态 | prop:fill = Line \| Text \| Filled |
| 白/绿配色 | prop:color = White \| Green |

> ⛔ **别自拼**: 整组标签别用一排 button 自拼；用 TabList。单个用 Tab。

- **组合关系**: 通常被 TabList 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `modelValue` | string \| number | `overview` |
| `fill` | Line \| Text \| Filled | `Line` |
| `color` | White \| Green | `White` |

- **事件**: `update:modelValue`
- **相关**: TabList / TabItem

### TabList

- **Figma**: `TabList` · **npm**: `TabList` · **import**: `import { TabList } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 标签组 —— items 数组驱动整组 tab，内置当前选中 v-model。
- **何时用**: 一组互斥视图切换。这是 tab 的首选入口（数据驱动整组）。
- **别名**: 标签组 · 选项卡组 · 标签栏 · 分段切换 · tabs · tab list · tab bar · tab group · segmented

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 整组渲染 | prop:items（[{label,value,disabled?}]） |
| 当前选中双向绑定 | v-model（update:modelValue） |
| 形态 | prop:fill = Line \| Text \| Filled |

> ⛔ **别自拼**: 别用一排 button + 自管 active class 拼 tab。用 TabList，整组走 items，当前页 v-model。

- **组合关系**: 内部用到 TabItem

| prop | 类型 | 默认 |
|---|---|---|
| `items` | {label;value;disabled?}[] | — |
| `modelValue` | string \| number | `overview` |
| `fill` | Line \| Text \| Filled | `Line` |

- **事件**: `update:modelValue`
- **相关**: Tab / TabItem

### TabItem

- **Figma**: `TabItem` · **npm**: `TabItem` · **import**: `import { TabItem } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: TabList 内的单个标签项（通常由 TabList 内部渲染）。
- **何时用**: 一般不直接用，由 TabList 渲染；需要细粒度控制单项时用。
- **别名**: 标签项 · 单个选项卡 · tab item · tab

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 普通/激活态 | prop:state = Normal \| Active |
| 禁用 | prop:disabled |
| 形态 / 配色 | prop:fill / prop:color |

> ⛔ **别自拼**: 优先用 TabList 整组；单项才用 TabItem，激活走 state=Active。

- **组合关系**: 通常被 TabList 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `value` | string \| number | `overview` |
| `state` | Normal \| Active | `Normal` |
| `color` | White \| Green | `White` |
| `fill` | Line \| Text \| Filled | `Line` |
| `disabled` | boolean | `false` |
- **相关**: TabList / Tab

### Breadcrumb

- **Figma**: `Breadcrumb/Item` · **npm**: `Breadcrumb` · **import**: `import { Breadcrumb } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 面包屑容器 —— slot 放一组 BreadcrumbItem，分隔符内置。
- **何时用**: 展示当前页在层级结构中的位置路径。
- **别名**: 面包屑 · 路径导航 · 层级导航 · breadcrumb · breadcrumbs · path nav · trail

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 分隔符 | BreadcrumbItem.showSeparator（容器自动串联） |

> ⛔ **别自拼**: 别用 <a> + '/' 字符自拼路径。用 Breadcrumb 包 BreadcrumbItem，分隔符内置。

- **组合关系**: 通常被 TopBar 包裹；内部用到 BreadcrumbItem
- **相关**: BreadcrumbItem

### BreadcrumbItem

- **Figma**: `Breadcrumb/Item` · **npm**: `BreadcrumbItem` · **import**: `import { BreadcrumbItem } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 面包屑单项 —— 链接 + 状态（当前/hover/disabled）+ 分隔符开关。
- **何时用**: Breadcrumb 内的每一级。最后一级通常 state=current。
- **别名**: 面包屑项 · 路径段 · breadcrumb item · crumb · path segment

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 状态 | prop:state = Default \| hover \| current \| disabled |
| 链接 | prop:href |
| 分隔符显隐 | prop:showSeparator（最后一项设 false） |

> ⛔ **别自拼**: 用 BreadcrumbItem，当前页走 state=current（不要用纯文本 + 手动去掉链接）。

- **组合关系**: 通常被 Breadcrumb 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `href` | string | — |
| `state` | Default \| hover \| current \| disabled | `current` |
| `showSeparator` | boolean | `true` |
- **相关**: Breadcrumb

### Steps

- **Figma**: `Step/Item` · **npm**: `Steps` · **import**: `import { Steps } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 步骤条容器 —— 横/竖方向 + 当前步 + 数字/图标样式，内部串联 StepItem。
- **何时用**: 多步流程/向导的进度指示。注意区别 InputNumber 的「步进」——那是数值不是流程。
- **别名**: 步骤条 · 步骤 · 向导 · 流程步骤 · steps · stepper · wizard · progress steps · stepline

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 当前步高亮 + 连接线 | prop:current（连接线由容器自动算） |
| 横/竖方向 | prop:direction = horizontal \| vertical |
| 数字/图标样式 | prop:type = number \| icon |

> ⛔ **别自拼**: 别用 circle + 连线 div 自拼步骤条。用 Steps，当前步走 current，方向走 direction。

- **组合关系**: 内部用到 StepItem

| prop | 类型 | 默认 |
|---|---|---|
| `current` | number | `0` |
| `active` | number | — |
| `direction` | horizontal \| vertical | `horizontal` |
| `type` | number \| icon | `number` |
- **相关**: StepItem

### StepItem

- **Figma**: `Step/Item` · **npm**: `StepItem` · **import**: `import { StepItem } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 步骤条单步 —— 标题/描述 + 状态 + 前后连接线 + 数字/图标。
- **何时用**: Steps 内的每一步；一般由 Steps 串联，需要细控时单用。
- **别名**: 步骤项 · 单步 · step item · step · wizard step

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 状态 | prop:state |
| 前后连接线显隐 | prop:showLeadingConnector / prop:showTrailingConnector |
| 图标 / 数字 | prop:iconName / prop:type |

> ⛔ **别自拼**: 优先用 Steps 串联；单步才用 StepItem。

- **组合关系**: 通常被 Steps 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `title` | string | `Step Title` |
| `description` | string | `` |
| `index` | number | `0` |
| `state` | State | — |
| `direction` | Direction | — |
| `type` | StepStyle | — |
| `iconName` | string | — |
| `showLeadingConnector` | boolean | `true` |
| `showTrailingConnector` | boolean | `true` |
- **相关**: Steps

### TopBar

- **Figma**: `TopBar` · **npm**: `TopBar` · **import**: `import { TopBar } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 顶部应用栏 —— 标题 + 可选菜单按钮 + 可选搜索框 + 登录前/后形态。
- **何时用**: 页面/应用顶部全局栏。
- **别名**: 顶栏 · 顶部栏 · 应用栏 · 导航栏 · 标题栏 · top bar · app bar · header bar · navbar · title bar

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 菜单按钮显隐 | prop:showMenu |
| 搜索框显隐 | prop:showSearchBox |
| 登录前/后形态 | prop:tag = After Login \| ... |

> ⛔ **别自拼**: 别用 header + flex 自拼顶栏。用 TopBar，菜单/搜索走 showMenu/showSearchBox。

- **组合关系**: 内部用到 Breadcrumb

| prop | 类型 | 默认 |
|---|---|---|
| `title` | string | `Product Name` |
| `tag` | Tag | `After Login` |
| `showMenu` | boolean | `true` |
| `showSearchBox` | boolean | `false` |
- **相关**: Breadcrumb

### MenuList

- **Figma**: `—（无独立 Figma 组件；等价物 = TopBar 内部 "Menu List" 图层；见 divergence logo-menulist-usermenu-code-first-2026-07-02）` · **npm**: —（内部） · **import**: _内部 base，不在 npm 公开导出_
- **是什么**: 菜单列表 —— topbar 菜单模式抽取。horizontal（品牌下划线）/ vertical（品牌色 + 末尾 action/selected 勾选）。双框架 code-first 组件（tvu-menu-list），不经 src/index.ts。
- **何时用**: 顶栏/下拉面板里的菜单项分组。别用 ul+li 自拼——用 MenuList，items 驱动，选中态走 item.selected。
- **别名**: 菜单 · 菜单列表 · 导航列表 · 菜单项 · menu · menu list · nav list · menu items

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 方向 | prop:orientation = horizontal \| vertical |
| 菜单项（含 action/selected 勾选） | prop:items[] |

> ⛔ **别自拼**: 别用 ul/li + flex 自拼菜单。用 MenuList，图标走 registry，勾选态走 item.selected。

- **组合关系**: 通常被 TopBar / UserMenu 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `items` | MenuListItem[] | `[]` |
| `orientation` | horizontal \| vertical | `vertical` |
- **相关**: TopBar / UserMenu

### UserMenu

- **Figma**: `—（无独立 Figma 组件；等价物 = TopBar 内部账号区 PM 头像 + Account Name；下拉壳 code-first；见 divergence logo-menulist-usermenu-code-first-2026-07-02）` · **npm**: —（内部） · **import**: _内部 base，不在 npm 公开导出_
- **是什么**: 用户菜单 —— 实心首字母/图片头像 → 下拉面板（账号头 name+role+email · custom actions[MenuList] · 行内语言切换 · 退出）。双框架 code-first 组件（tvu-user-menu），不经 src/index.ts。
- **何时用**: 登录后顶栏右侧账号入口（§3：after-login TopBar rightContent 必须是 UserMenu，别手搓头像+菜单）。
- **别名**: 用户菜单 · 账号菜单 · 头像菜单 · 个人菜单 · user menu · account menu · avatar menu · profile menu

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 头像（首字母底色或图片） | prop:name / prop:image / prop:color |
| 账号头（name+role+email） | prop:name / prop:role / prop:email |
| 自定义操作 | prop:actions[]（渲染为 MenuList 面板体） |
| 行内语言切换 | prop:languages[] / prop:lang |

> ⛔ **别自拼**: 别手搓头像+下拉菜单。登录后顶栏右区用 UserMenu，操作走 actions（MenuList），语言切换走内建 languages/lang（别外接切换器）。

- **组合关系**: 通常被 TopBar 包裹；内部用到 Logo / MenuList

| prop | 类型 | 默认 |
|---|---|---|
| `name` | string | `''` |
| `email` | string | — |
| `role` | string | — |
| `image` | string | — |
| `color` | string | — |
| `actions` | MenuListItem[] | `[]` |
| `languages` | UserMenuLanguage[] | `[]` |
| `lang` | string | — |
- **相关**: TopBar / MenuList / Logo

---

## Feedback（反馈 / 弹层）

### Notification

- **Figma**: `Notification` · **npm**: `Notification` · **import**: `import { Notification } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 通知 —— 双轴 form×type：dialog/alert/pop confirm 居中模态（按钮按 form 固定）、slide 侧边被动 toast；分类图标随 type 内置。
- **何时用**: 状态反馈/告警/轻确认：被动告知用 form=slide；需决策用 form=dialog 或 pop confirm；单一确认用 form=alert。轻量行内提示用 Message；表单类模态用 PopupBox。
- **别名**: 通知 · 提示卡 · 告警 · 横幅 · 消息卡 · 确认弹窗 · notification · alert · toast · banner · callout · confirm dialog

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 交互形态 | prop:form = dialog \| alert \| pop confirm \| slide（按钮按 form 固定：dialog/pop confirm=Cancel+Confirm、alert=单 OK、slide=无） |
| 严重度图标 | prop:type = warning \| secondary warning \| error \| info \| success \| none（图标随 type 内置） |
| 关闭按钮 | prop:closable（默认 true，无需外接 close icon） |
| 按钮文案 | prop:cancelText / prop:confirmText / prop:okText（仅改文案，按钮有无由 form 决定） |

> ⛔ **别自拼**: 别用带图标的 div + close × + button 自拼通知/确认框。用 Notification，形态走 form、严重度走 type，按钮是 form 固定的不要外拼。

| prop | 类型 | 默认 |
|---|---|---|
| `form` | Form | `dialog` |
| `type` | Type | `none` |
| `theme` | Theme | `dark` |
| `title` | string | — |
| `description` | string | — |
| `closable` | boolean | `true` |
| `cancelText` | string | — |
| `confirmText` | string | — |
| `okText` | string | — |
- **相关**: Message / PopupBox

### Message

- **Figma**: `Message` · **npm**: `Message` · **import**: `import { Message } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 行内提示条 —— 状态色 + 尺寸 + 可关闭，比 Notification 轻。
- **何时用**: 轻量行内状态提示（表单上方一行提示、页面内联反馈）。成块带操作用 Notification。
- **别名**: 提示信息 · 行内提示 · 消息条 · 提示条 · prompt · inline message · hint message · alert inline · tip · toast

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 状态色 + 图标 | prop:status = info \| ... |
| 尺寸 | prop:size = L \| ... |
| 关闭 | prop:closable（默认 true） |

> ⛔ **别自拼**: 别用 icon + 文本 div 自拼行内提示。用 Message。

| prop | 类型 | 默认 |
|---|---|---|
| `status` | MessageStatus | `info` |
| `size` | MessageSize | `L` |
| `closable` | boolean | `true` |
- **相关**: Notification / Tooltip

### PopupBox

- **Figma**: `Popup Box` · **npm**: `PopupBox` · **import**: `import { PopupBox } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 模态弹窗 —— 标题 + 内容插槽 + footer(取消/确认) + 背板/Esc 关闭控制。
- **何时用**: 需要打断流程的模态对话（确认、表单、详情）。非模态轻提示用 Notification/Message。
- **别名**: 弹窗 · 对话框 · 模态框 · 模态弹窗 · modal · dialog · popup · popup box · overlay dialog

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 显隐双向绑定 | prop:visible + v-model:visible |
| 关闭手段 | prop:closable / prop:closeOnBackdrop / prop:closeOnEscape |
| footer 取消/确认 | prop:showFooter + cancelText/confirmText，或 #footer slot |
| 宽度 | prop:width（默认 680） |

> ⛔ **别自拼**: 别用 fixed 遮罩 div + 自管 z-index/Esc 拼模态。用 PopupBox，显隐 v-model:visible，关闭走 closeOnBackdrop/closeOnEscape，按钮走 footer。

| prop | 类型 | 默认 |
|---|---|---|
| `visible` | boolean | `false` |
| `title` | string | — |
| `width` | string \| number | `680` |
| `theme` | Theme | `dark` |
| `closable` | boolean | `true` |
| `closeOnBackdrop` | boolean | `false` |
| `closeOnEscape` | boolean | `true` |
| `showFooter` | boolean | `true` |
| `cancelText` | string | — |
| `confirmText` | string | — |

- **事件**: `update:visible` · `close` · `cancel` · `confirm`
- **相关**: Notification

---

## General（通用）

### ButtonBridge

- **Figma**: `Button` · **npm**: `Button` · **import**: `import { Button } from '@nancyzeng0210/tvu-design-system'`
- **是什么**: 按钮 —— 8 轴覆盖 Figma 全部 Button sets（色/尺寸/形态/图标/状态/圆角/定宽/主题）。npm 导出名为 Button。
- **何时用**: 任何点击操作。导出名是 Button（不是 ButtonBridge）。
- **别名**: 按钮 · 操作按钮 · 主按钮 · button · btn · cta · action button

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 配色 | prop:color = green \| red \| orange \| gray 1 |
| 形态 | prop:fill = filling \| ghost \| rimless |
| 图标位 | prop:icon = no \| left \| right \| loading |
| 尺寸/圆角/定宽/状态 | prop:size / prop:radius / prop:fixedWidth / prop:status |
| 主题（跟随 docs 或显式） | prop:theme（缺省 inject docsTheme） |

> ⛔ **别自拼**: 别用裸 <button> + 自定义样式。用 Button（`import { Button }`），loading 走 icon=loading 而非外接 spinner。

- **组合关系**: 通常被 Notification / PopupBox / Pagination 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `color` | green \| red \| orange \| gray 1 | `gray 1` |
| `fill` | filling \| ghost \| rimless | `filling` |
| `icon` | no \| left \| right \| loading | `no` |
| `size` | Size | `M` |
| `radius` | square \| round | `square` |
| `fixedWidth` | yes \| no | `no` |
| `status` | default \| hover \| disable \| loading | `default` |
| `theme` | dark \| light | — |

### Logo

- **Figma**: `—（无独立 Figma 组件；等价物 = TopBar 内部 logo 图层 + 品牌图标资产 icon/logo/TVU · icon/logo/ts；见 divergence logo-menulist-usermenu-code-first-2026-07-02）` · **npm**: —（内部） · **import**: _内部 base，不在 npm 公开导出_
- **是什么**: 品牌 Logo —— 渲染 registry 品牌 SVG（tvu 全称 / ts 简写）。双框架库 code-first 组件（tvu-logo），不经 src/index.ts（已发布 Vue 包未含）。
- **何时用**: 顶栏或页面品牌标识。别手搓 SVG——用 Logo，type 切换 tvu/ts。
- **别名**: 标志 · 品牌标识 · 商标 · logo · logo · brand · brand mark · wordmark

**内置能力（别自拼）**

| 能力 | 用什么开 |
|---|---|
| 品牌变体 | prop:type = tvu \| ts |
| 尺寸 | prop:size（px） |

> ⛔ **别自拼**: 别内联/自画品牌 SVG。用 Logo，图形走 icon registry（icon/logo/TVU · icon/logo/ts）。

- **组合关系**: 通常被 TopBar / UserMenu 包裹

| prop | 类型 | 默认 |
|---|---|---|
| `type` | tvu \| ts | `tvu` |
| `size` | number | `16` |
- **相关**: TopBar / UserMenu