# TVU Figma Component Catalog

> **本文档 = mockup 任务专属**（library key / frame used-by / Extension scenarios）。
> 组件的「内置能力 / props / 别自拼 / 组合关系」（code + mockup 通用语义层）在 [`component-affordances.md`](./component-affordances.md)（真源 `.json`），**不在本文件重复登记 props**——本文件聚焦 Figma 库归属与 mockup 复用场景。
>
> AI 工具（Claude Code / Codex / Cursor / Cline / Gemini / 其它）在 TVU 产品 mockup 任务里**第一个该查的文档**。
>
> Bootstrap 自 [`figma-data/normalized/components.manifest.json`](../../figma-data/normalized/components.manifest.json) +
> [`figma-data/figma-to-code-mapping.json`](../../figma-data/figma-to-code-mapping.json)。
>
> Last bootstrap: 2026-05-06 · 49 unique non-icon components + 647 icons across 28 namespaces.

---

## 工作流（必读）

```
[task] → grep this catalog → 命中 ✅ entry → 直接用
                          → 命中 🟡 entry → 用 + 把 Extension/Don't-use 写实，回填本文档
                          → 没命中 → search_design_system + import sample（M2 流程）
                                  → 找到 → 加 entry 到本文档（即使本任务用不到也补完）
                                  → 真没有 → 自画 + 标 🟡 候选（M6）
```

**不要凭直觉跳过 catalog 直接 search_design_system**——70% 的"library 缺件"判断在 catalog 已经有答案。

## Status legend

- ✅ **Verified** — Library key + Primary use + Extension scenarios + Don't-use 都填了，至少在一次 mockup 里实证过
- 🟡 **Skeleton** — manifest 自动生成基础信息，使用语义未填
- ⚠️ **File-local** — 不是库组件，是 product file 内嵌的 component_set，跨 file 不可用

---

## 真源

| 维度 | 值 |
|---|---|
| Library 名 | `TVU UX Design System` |
| Library key | `lk-057f6ba0f771bfa7f63a6a197502999462c2974f995488b381708ca5faadb7f9f6675e04aa442b3a5ffb31732150a7f5aa8ca3102073ab210edc684022fc6c21` |
| Library file key | `YbsPRUVmNdsbN40NNwh1Gn` |
| Manifest source | `figma-data/normalized/components.manifest.json`（运行 `node figma-sync/generate-manifest.mjs` 重建） |
| Code mapping | `figma-data/figma-to-code-mapping.json` |

---

## 📐 Styles & Variables（库样式 / 变量目录）— 2026-06-12 新增

> mockup 绑样式/变量前**查这里或直读库源文件**（`getLocalTextStylesAsync` / `getLocalVariableCollectionsAsync`），**禁止**扫产品文件"使用中"的 id 反推库有什么（M52.1；2026-06-12 BM-1047 实证：扫现场误报"库无 20/24 字号与 spacing 变量"）。

- **Text Styles（14）**：`Roboto/12 tips`(lh16) · `14 body` · `16 pop title` · `18 headline 2` · `20 headline 1` · `22 large title` · `24 large title`（14+ lh150%；16-24 SemiBold）+ `Roboto/PingFang SC/*` 双语系列同档 ×7
- **Effect Styles（4）**：`L1/L2/L3 shadow`（**popup 卡基线 = L3**，Notification 自带实证）+ `Mask blur8 #000-60%`
- **Variables（TVU Design System collection · 98 个）**：色彩（`UX/*` · `Color Type/*`）· `Spacing/XXS-M` · `Basic Size/#2-#80`（2/4/8/12/16/20/24/32/36/40/48/56/64/80）· `Radius/XS-XXL` · `Size/*` · `Module Width/*`
- **间距纪律**：mockup 取值必须落在档位上并 `setBoundVariable`；非档位值起手吸附到最近档（M52.1），库缺档不默认触发新增

---

## ✅ Verified Components

### Badge
- **Library key**: `4db5246d0782fe13bcc01747a7a2578c2da77b2a`
- **Axes**: `Type` (Circle / Rectangle) × `Color` (Green / Blue / Orange / Red / Black) × `Tag` (Filled / Line)
- **Variants**: 20
- **Code mapping**: `Badge` (status: approved)

#### Primary use
状态/计数指示器 (status pill)。最常用于 row-level INPUT/OUTPUT 状态显示。

#### Extension scenarios
- **Status pill**（INPUT/OUTPUT 列）：`Type=Rectangle, Color=Red/Green/Black, Tag=Filled` —— Live=Red, Preview=Green, Inactive=Black
- **N/A pill**（input-only/output-only app 的对应空列）：`Type=Rectangle, Color=Black, Tag=Line` —— outline 表达"该位置不存在"
- **CapabilityTag**（`input-only` / `output-only` metadata）：`Type=Rectangle, Color=Black, Tag=Line` + 文本覆盖 —— outline 矩形是只读信息标签的标准 primitive
- **Active count badge**（卡片头 "X active"）：`Type=Rectangle, Color=Green, Tag=Filled` + 文本覆盖
- **Sessions count badge**（折叠卡片 "X sessions"）：`Type=Rectangle, Color=Black, Tag=Filled` + 文本覆盖
- **Top-bar status counters**（"8 Live" / "12 Previewing" / "19 Total Sessions"）：同状态色 mapping，文本覆盖为 "数字 + 标签"
- **Session ON state pill**（Video Sync Multi-Session 等"running 中"指示）：`Type=Rectangle, Color=Green, Tag=Line` —— **BRAND Green outline pill**（不是 Filled），区别于 Live=Red filled 的广播 on-air 语义；ON=BRAND 表达"已配置在运行"，是品牌身份延伸而非 broadcast on-air。**2026-05-20 实证**：Video Sync v3 用 Blue Filled (BLUE=#3892F3) 当 ON 被用户判错 → 改 BRAND Green + Tag=Line outline，与 selected indicator 4px BRAND rail 同源视觉。
- **Session OFF state pill**（同上"未运行"指示）：`Type=Rectangle, Color=Black, Tag=Line` —— Neutral outline，跟 N/A pill / CapabilityTag 共用 outline 风格

#### Don't use for
- 大块 callout / inline message —— 用 `Notification` 或 `Message`
- 可点击的 selector / chip —— 用 `Tab/Item`（Badge 是只读 indicator，不是 interactive primitive）

#### Used by
- Session Dashboard (Frame 1, node `2969:85`, 2026-05-06)

---

### Button/dark M
- **Library key**: `12b38c8b68cd67dd3978e0d68712bc646f1e97c1`
- **Axes**: `icon` (right / left / loading / no) × `style` (filling / ghost / rimless) × `color` (gray 1 / green / orange / red) × `status` (default / loading / hover / disable) × `radius` × `fixed width`
- **Variants**: 400
- **Code mapping**: `Button` (status: approved)

#### Primary use
Dark theme 中等尺寸按钮 (32px 高)。**所有 row-level / header-level / modal action 按钮的默认选择**。

#### Extension scenarios
- **Action buttons in table rows** (operator console)：`style=ghost`，颜色由 row state 决定 —— `gray 1` (Open GUI 中性), `red` (Stop / Remove destructive), `green` (Start)
- **Modal destructive button**：`style=filling, color=red, status=default`
- **Modal cancel button**：`style=ghost, color=gray 1, status=default`
- **Header CTA**：`style=filling, color=green` (positive primary action)

#### Don't use for
- **不要自画 XS chip 替代它**（M7 + M2 双重违反）。column 不够宽就让 column 变宽
- 行内极小按钮：虽然有 `Button/dark XS`，但 operator console **必须**用 M 维持 Fitts 命中率（M7）
- Filter chip：用 `Tab/Item Type=Filled` 而非 Button

#### Used by
- Session Dashboard (Frame 1, 2026-05-06) — 27 instances

---

### Tab/Item
- **Library key**: `2267405386cb3186ba920b0d0b790d54e65a1529`
- **Axes**: `Property 1` (Active / Normal) × `Property 2` (Green / White) × `Type` (Line / Filled / Text)
- **Variants**: 6

#### Primary use
单选导航 tab（切换内容面板）。

#### Extension scenarios
- **FilterChip — 单选过滤器**（如 Filter Bar 的 All / Live / Previewing / Inactive Only）：
  - Selected: `Property 1=Active, Property 2=Green, Type=Filled`
  - Default: `Property 1=Normal, Property 2=White, Type=Filled`
  - 视觉差异：tab 是矩形小圆角而非 cornerRadius=999 的 pill；语义匹配（单选 + 缩范围）。

#### Don't use for
- 多选 filter（Tab 是单选语义；多选用 checkbox 或 chip-with-checkmark pattern）
- 静态信息标签（用 `Badge` Type=Rectangle, Tag=Line）

---

### Tab List
- **Library key**: `47efe04ff35b46602f0827f24c87af9dca3bae4b`
- **Axes**: `Type` (Line / Filled / Text)
- **Variants**: 3
- **Slot**: `List#4605:0` —— preferredValue 直接绑定 `Tab/Item` component_set

#### Primary use
`Tab/Item` 的容器组件，处理多 tab 排版。

#### Extension scenarios
- **Filter Bar 容器**：搭配 `Tab/Item` 当 FilterChip 用时，用 `Tab List Type=Filled` 作 wrapper，自动管理间距

---

### Top bar
- **Library key**: `918b928e4541f1573de5c98c32b408af663d7f2f`
- **Axes**: `Tag` (After Login / Before Login)
- **Variants**: 2
- **Properties**: `Show Menu` (BOOLEAN) / `Show Search box` (BOOLEAN) / `Menu` (SLOT) / `Right_content` (SLOT)

#### Primary use
TVU 全产品页面顶部 bar（1920×56 After Login / 1920×64 Before Login）。**M1 硬规则**：任何 TVU 产品页面**必须** instance 此组件，不允许自画。

#### Extension scenarios
- **Product 标题**：用自带 product-name slot（默认 placeholder "Product Name"），手动覆写为实际产品名（如 "MicroApps Sessions"）。**不要**在 top bar 下方加重复 page-title strip
- **Right side custom content** (notifications / user / settings)：用 `Right_content` SLOT

#### Don't use for
- 把 page-level 元素塞进 slot —— **不允许**：counters / filter chips / 批量操作按钮。这些必须放在 top bar **下方**独立 strip
- 修改 top bar 结构本身（菜单数量 / Tokens 段 / Network Delay 等只能开关显示）
- 旧库 `TVU UX Library` 里有同名 `Top bar` (key `2f36c51a...`)，**不要用**

#### Used by
- 所有 TVU 产品 mockup（强制硬规则 M1）

---

### Notification  ⟨confirm dialog / prompt / popconfirm / 确认弹窗 / 警告 / toast / alert / 信息条⟩
> **2026-06-04 修正**：本条原把一个 `prompt`-类幻影别名（key `e9574b39…` 实测 `importComponentByKeyAsync` **not found**）错挂到 Notification 上（并错把 Notification 描述成"inline message bar 不是 modal"）。本条真源 = **`Notification` component-set**。关键词别名列在标题，确保 grep `confirm`/`popover`/`dialog`/`弹窗` 都命中本条。**注**：真正的轻量提示消息组件是独立的 **`Message`** set（node `1408:17153`，见上方 Message 条目），与 Notification 不是同一个。
- **Library key (SET)**: `23535120dbdc93bf90af9a118b5091e58b590dc6`
- **Axes**（2026-06-11 live 实测刷新，原 theme×status 记录过期）: `theme` (dark/light) × `form` (**pop confirm / dialog / slide / alert**) × `type` (warning / secondary warning / error / info / none / **success**) + BOOLEAN **`closable`** + SLOT `Notification_content`
- **Variants**: 32 — `slide` = 320×89 无按钮 toast（success/error/info/warning 全有）/ `alert` = 480 单按钮 / `dialog` = 480 双按钮+close。**反馈类 UI 一律从本 set 取 variant，不自画**（M52.3）
- ⚠️ 2026-06-12 Figma↔code 原子同步进行中（type 改名 secondary warning→danger / none→default，见 STATUS v0.10.0）——用前以 live probe `componentPropertyDefinitions` 为准

#### Primary use
多用途反馈面：toast / side-pop / alert / info banner / **AND 确认弹窗**。
- **`pop confirm` / `quick confirm` = 设计系统的确认对话框**（含 X close + Title + Description + Cancel + destructive 按钮，destructive 默认 "Delete"，按场景改 label 如 "Remove"）。

#### Extension scenarios
- **Destructive 二次确认 modal**（Remove on-air layer / Stop In-Out / 删除 session 等）：用 `theme=dark, status=pop confirm`。
- 注：作 mockup 里的"确认弹窗状态预览" → 必 frame 外 + 连线（M23.9，**不可叠在产品 frame 上**）。

#### Don't use for
- 自画 modal（M2 / M32 重灾区）。
- 大量内容 / 多 step 表单 → Drawer / 全屏 view。

#### How to instance（file-local import-by-key 会 fail，走 set）
- `importComponentByKeyAsync('23535120…')` 取的是 **SET** → 用 **`importComponentSetByKeyAsync`** 拿 set，再从 `set.children` 按名 `theme=dark, status=pop confirm` `createInstance()`。
- **Title / Description 在嵌套 content SLOT（`Notification_content#…` 是 SLOT property），无 TEXT component-property** → 改文本必走下方精化协议（2026-06-05 BM-1047 S5 实证补全）。
- **SLOT 默认 text 编辑精化协议（实证机制）**：SLOT 默认内容里的 leaf TEXT 一旦 `node.characters = '…'` 即被 override **替换、原 ref 失效**。连带踩坑：
  1. `getNodeByIdAsync('I…;…')` **解析不了** SLOT 内部复合 ID → 必须从 instance **遍历**拿 ref，不能按 ID 直取。
  2. `await loadFontAsync` 会让已拿到的 SLOT-text ref 失效（"node not found"）→ **必须先 load 字体（所有 await 放最前），再同步遍历拿 fresh ref，再 set**。
  3. set 之后**不可读回**（`done = node.characters`）、**不可继续遍历**（ref 已死）→ 找到目标就 set 完立刻 return。
  4. 故 **一个文本一个 `use_figma` 脚本**（标题/描述/按钮各一）。字体先用同步 probe（`getRangeFontName`，一次 await 内）拿到，实测 = `Roboto SemiBold`(标题) / `Roboto Regular`(描述/按钮)。
  - 按钮 label 在嵌套 `Button/dark M` 实例内，同样走"遍历→set→return"。

#### Compare with
- `Popup Box` (2 variants Theme) —— 简单弹窗，纯 informational 场景。需 import sample 验证差异。

---

### Message  ⟨prompt / 提示消息 / status line / 顶部瞬时消息⟩
> **2026-06-12**：Figma component-set 从 "prompt message" 改名为 **"Message"** 并重发布（node `1408:17153` 未变）；代码侧公共组件 `PromptMessage` 同步改名为 **`Message`**。早期把它当 Notification 幻影别名（见下方 Notification 修正注）已纠正——`Message` 是独立 first-class 组件集，不是 Notification。
- **Figma node**: `1408:17153`（component-set）
- **Code export**: `Message`（canonical `src/canonical/Message.vue` → base `src/components/Message/Message.vue`）
- **Axes**: `status` (success / info / error / warning) × `size` (L / M)
- **Variants**: 8

#### Primary use
顶部瞬时消息：最轻量的非阻塞反馈，无操作按钮，只是会消失的状态行。L = 点击关闭，M = 自动消失。

#### Don't use for
- 需用户决策 / 阻塞流程 → 用 `Notification`（dialog / pop confirm）或 `Popup Box`。

---

### input box/filled
- **Library key**: `1f513914bde7e5e2844e785eefe427f0693f6d20`
- **Axes**: `dark theme` × `status` × `enable` × `UX` × `size` × `feature`
- **Variants**: 112
- **Properties**: `Content#4995:0` (SLOT)

#### Primary use
Dark theme 文本输入框，filled 风格。

#### Extension scenarios
- **Search field**（filter bar 搜索 PID/Object ID）：`dark theme=on, status=default, UX=default, size=M, feature=no`
- **Form 输入**：根据 size / feature 调整

#### Don't use for
- Light theme 页面（用 `dark theme=off`，但更推荐用 `input box/line` 在 light 下）

#### Used by
- Session Dashboard Filter Bar

---

### Tooltips
- **Library key**: `40c9daafd174d0f4d7005eacc566570ef381fde5`
- **Axes**: `dark theme` × `pointing` (left up / left down / right up / right down / Center up / Center down)
- **Variants**: 12
- **Properties**: `Content#4798:0` (SLOT)

#### Primary use
悬停提示。`pointing` variant 控制箭头方向。

#### Extension scenarios
- **Action button hint** ("Open Audio Remapping UI" 之类)：`dark theme=on, pointing=Center down`，悬于按钮上方
- **Disabled button explanation**（"Start Output 在 input previewing 之前不可用"）：`pointing=Center up`，贴于按钮下方

---

### APP Icons ⚠️ (file-local)
- **File-local key**: `fefd6aacdbb0a6e1acaf4106446e831fe3c5b8ff`
- **File-local nodeId**: `3:14402`
- **Scope**: 仅 `Micro-Apps-20250923` (fileKey `DtZcMkhNy6qh6jbQQnhreQ`)，跨文件不可用
- **Axes**: `Tag` × `Color` (Green / Black)
- **Variants**: 18

#### Available variants (Tag values)
- Audio remapping
- Audio Video Sync
- Media Analyzer
- Micro app
- Overlay APP
- SCTE App
- Standard Conversion
- Transcriber App
- TVU
- Video Sync

#### Missing (TODO: 加到既有 set，**不要**新建)
- Color Correction
- Graphics Insertion
- Test Pattern Generator

#### Don't use for
- 跨文件——这是 file-local，需要 cross-file 复用时要么入 library，要么在新文件里复制 set

---

### Table
- **Library key**: `TBD — import on next use`
- **Axes**: `Type` (Header / Tbody) × `Align` (Left / Center / Right)
- **Variants**: 6
- **Code mapping**: `Table` (status: approved)

#### Primary use
数据表格 (data-display)：列定义 + 数据驱动渲染的结构化行列。列走 `columns`、数据走 `data`，对齐走 `align`（列可用 `column.align` 覆盖），斑马纹走 `striped`，表头/表体形态走 `type`（`Tbody` 自动开 striped）。**别手写 `<table><thead><tbody>` 拼数据表。**

#### Extension scenarios
- **Operator console / session 列表表格**：`Type=Tbody, Align=Left, striped` —— 多行结构化数据，斑马纹增强行可读性
- **表头行**：`Type=Header` —— 列标题行，bold + tips 文本色，可带排序/下拉 affordance icon（column 的 `showRightIcon` + `arrow/sorting` / `arrow/dropdown`）
- **可复制字段单元格**（Event Name / Object ID / URL 列）：cell 走 **M29 Form 1** —— text hug content + 紧跟 `icon/Edit/Copy`（gap 4px，12×12），icon fill 绑 `Color Type/Icon/Default`
- **空值单元格**：cell 走 **M29 Form 2** —— 显示 "—" em dash，text fill 绑 `Color Type/Text/Placeholder & Button`，**不加** copy/action icon

#### Don't use for
- 分页 —— **不要 Table 内自实现**，下方另配 `Pagination`
- 可复制字段（ID / IP / MAC）强行 ellipsis 截断 —— 用 M29 Form 1 hug + copy icon，不走 M43 ellipsis
- 自由表单布局 / 卡片栅格 —— Table 是行列网格，非通用 layout 容器

---

### Pagination
- **Library key**: `TBD — import on next use`
- **Axes**: `Type` (Classic / Small / Simple)
- **Variants**: 3
- **Code mapping**: `Pagination` (status: approved)

#### Primary use
分页器 (navigation)：长列表 / 表格分页。页数由 `total` / `pageSize` 自动算，当前页用 v-model（`update:modelValue`）、页大小用 `v-model:pageSize`。**通常放 `Table` 下方。别用 button 列表自拼页码。**

#### Extension scenarios
- **表格下方分页**（默认）：`Type=Classic` —— 完整页码 + 总数 + 页大小选择 + 跳页，最常用
- **紧凑容器内分页**：`Type=Small` —— rimless 页码按钮 + 更窄间距，适合侧栏 / 卡片内嵌
- **极简前后翻页**：`Type=Simple` —— 隐藏页码列表，仅 prev/next 箭头

#### Don't use for
- tab / 步骤切换 —— 同数据集翻页才用分页；内容分段用 `Tab/Item` + `Tab List`，流程步骤用 `Step/Item`
- 手拼 button 页码列表 —— 页数交给 `total` / `pageSize` 自动算

---

### Form Item
- **Library key**: `TBD — import on next use`
- **Axes**: `Type` (Label & Input / Label & Selector / Label & Textarea / Label & Radio / Label & checkbox / Label & Switch) × `Layout` (2 lines / 1 line / 1 line & Right) × `Theme` (Dark / Light) × `Label Width` (Dynamic / 200 px / 120 px) × `Status` (Normal / Error)
- **Variants**: 64
- **Code mapping**: `FormItem` (status: approved)

#### Primary use
表单行容器 (form-input)：包裹任意表单控件（Input / Select / Textarea / Radio / CheckBox / Switch）并统一加 label、必填星号、错误/提示文案、标签宽度与单/双行对齐。控件放 default slot，label 走 `label`、必填走 `required`、报错走 `error`（或 `status=Error`）、提示走 `hint`、对齐走 `labelWidth` / `layout`。**别用 `<label>` + 控件 + 红字 `<div>` 手拼表单行。**

#### Extension scenarios
- **标准单行字段**：`Type=Label & Input | Label & Selector, Layout=1 line, Label Width=120 px | 200 px` —— label 左、控件右，固定标签宽对齐多行字段
- **双行字段**（label 上、控件下）：`Layout=2 lines, Label Width=Dynamic` —— 窄容器 / 长 label 场景
- **开关行右对齐**：`Type=Label & Switch, Layout=1 line & Right` —— 布尔控件靠右排
- **校验错误态**：`Status=Error`（或传 `error` 文案）—— 错误消息用 `--red`；**label 在错误态仍保持灰色**（CANONICAL-019）
- **富标签**（带 info icon）：用 `#label` 命名插槽替换纯文本 label

#### Don't use for
- 不需要 label / 校验的裸控件 —— 直接用对应控件组件，不必包 FormItem
- 整表布局 / 多列表单栅格 —— FormItem 只管单字段行，跨字段排版在外层 layout

---

### check box
- **Library key**: `TBD — import on next use`
- **Axes**: `dark theme` (on / off) × `status` (off / on / some) × `enable` (yes / no)
- **Variants**: 12
- **Code mapping**: `CheckBox` (status: approved)

#### Primary use
多选 toggle（一组选项里独立勾选 0..N 项）。`status` 三态含 `some`（半选/indeterminate），用于 select-all 父项反映子项部分勾选。

#### Extension scenarios
- **多选 checklist**：`status=on/off, enable=yes` —— 一组可独立勾选的项，每项 v-model 各自管理
- **Select-all 父项（半选）**：父 checkbox `status=some` —— 子项全选→`on`、全不选→`off`、部分→`some`，半选画 `action/minus` 横杠（不是对勾）
- **策略锁定项**：`enable=no`（可叠加 `status=some`）—— 不可改的项呈禁用，仍显示当前勾选/半选结果
- **只读嵌入**：canonical 有 `readonly` prop（CANONICAL-012），剥离 role/tabindex/pointer-events，把 checkbox 当更大点击目标里的纯视觉指示

#### Don't use for
- 互斥单选（一组只能选 1）—— 用 `radio`
- 二元 on/off 开关（启用某功能）—— 用 `switch`（即时生效，不是表单勾选项）
- 静态只读状态指示 —— 用 `Badge`（checkbox 是 interactive 输入控件）

---

### radio
- **Library key**: `TBD — import on next use`
- **Axes**: `dark theme` (on / off) × `status` (off / on) × `enable` (yes / no)
- **Variants**: 8
- **Code mapping**: `Radio` (status: approved)

#### Primary use
互斥单选（一组里只能选中 1 项）。单个 `Radio` 是独立控件，二态 `status`（off/on），无半选；互斥由消费方维护（base `select()` 只 emit `true`，radio 不能自取消）。

#### Extension scenarios
- **inline 决策组**：一组 radio 共享 parent state，选中项 `status=on` 其余 `off`（如角色选择 producer/...）
- **混合可用性选项**：组内某项 `enable=no` —— 被策略锁定的选项呈禁用，仍参与单选组排版
- **设置面板里的策略选择器**：radio 组嵌在 panel 内，选中 dot 用 brand green（mockup-conventions：选中 radio dot = brand）

#### Don't use for
- 多选（可同时选多项）—— 用 `check box`
- 单选导航 tab（切换内容面板）—— 用 `Tab/Item`（radio 用于表单值选择，不是导航）
- 二元 on/off 开关 —— 用 `switch`

---

### switch
- **Library key**: `TBD — import on next use`
- **Axes**: `dark theme` (on / off) × `status` (on / live / off) × `enable` (yes / no) × `loading` (no / yes)
- **Variants**: 18
- **Code mapping**: `Switch` (status: approved)

#### Primary use
二元开关（即时生效的 on/off toggle）。`status` 含第三态 `live`（广播 on-air），`loading` 态在切换异步生效时显示 thumb 内 spinner。base = native `<button role="switch">`。

#### Extension scenarios
- **Live / on-air 开关**：`status=live` —— track 染红（`--red`），遵循 M3 广播 ON AIR 惯例。区别于普通 `on`（开但非播出）
- **异步切换 loading**：`loading=yes` —— 切换需后端确认时显示 spinning `action/loading`，期间 toggle 被阻断
- **禁用开关**：`enable=no` —— 不可切换的固定态（权限锁定的功能位）

#### Don't use for
- 表单里的多选勾选项 —— 用 `check box`（switch 是即时 on/off，不是提交的勾选）
- 互斥单选 —— 用 `radio`
- 把 `status=live` 当普通"激活/选中"色用 —— `live`=红专表 output on-air；普通激活/品牌身份用 brand green（M3：不要按 SaaS 默认绿=活跃配色）

---

### InputNumber
- **Library key**: `TBD — import on next use`
- **Axes**: `Property 1` (Default / Only Add / Only Reduce / Readonly)
- **Variants**: 4
- **Code mapping**: `InputNumber` (status: approved)

#### Primary use
数字步进输入框（spinbox）：输入框 + 内置加减按钮 + 上下界约束。用于受约束的数值录入并提供加减微调（数量、并发数、时长）。连续区间拖动用 `Slider`。

#### Extension scenarios
- **受约束计数器**：`property1=Default` + `min`/`max`/`step` —— 到界自动禁用对应按钮
- **单向步进**：`property1=Only Add`（只增禁减）/ `Only Reduce`（只减禁增）
- **只读数值展示**：`property1=Readonly` —— 输入与两按钮全禁用，纯展示当前值

#### Don't use for
- 自拼步进器（InputBox + 两个 +/- Button，或裸 `<input type=number>`）—— 直接用 `InputNumber`，单向用 `property1=Only Add|Only Reduce`
- 连续区间拖动选值（音量/亮度/百分比）—— 用 `Slider`
- 单行文本/非数值录入 —— 用 `InputBoxLine` / `InputBoxFilled`

---

### select box/filled
- **Library key**: `TBD — import on next use`
- **Axes**: `dark theme` (on / off) × `status` (Placeholder / Value / multi select) × `enable` (on / off) × `UX` (default / error / hover / click / editable) × `size` (M / L) × `feature` (default / time / date)
- **Variants**: 144
- **Code mapping**: `SelectBoxFilled` (status: approved)

#### Primary use
填充（深底）风格的下拉选择器**容器**——输入框 + 触发箭头本体，承载单选/多选/可搜索的取值交互。透明线框风格用 `select box/line` (`SelectBoxLine`)。注意：这是"输入框那一格"，下拉展开后的选项列表面板是另一组件 `Drop down List/Select`。

#### Extension scenarios
- **Multi-select 过滤器**：`status=multi select`（代码 `multiple`）—— 多选 chip + 勾选已内置，不要外接 chip
- **可搜索 / 可输入筛选**：`UX=editable`（代码 `editable`）—— 选项多、需键入过滤时用
- **错误校验态**：`UX=error` —— 表单校验失败的边框警示，与 `FormItem` 配合
- **time / date 取值**：`feature=time` / `feature=date` —— select 外壳承载时间/日期取值变体

#### Don't use for
- 下拉里那一排可选行 —— 用 `Drop down List/Select`；本组件只是触发它的输入框容器
- 纯文本录入 —— 用 `input box/filled`（select 是"从既定 options 选值"，不是自由文本）
- 别用 `<input>` + 浮层 div + 自撸 chip 拼 select —— 用本组件 + `multiple` / `editable`

---

### Drop down List/Select
- **Library key**: `TBD — import on next use`
- **Axes**: `Dark Theme` (on / off) × `Type` (Radio / Multi / Operation List / Sort By)
- **Variants**: 8
- **Code mapping**: `DropDownListSelect` (status: approved)

#### Primary use
下拉展开后的**选项列表面板本体**——渲染一组可选行，支持单选/多选/操作/排序四种列表语义，内置键盘 roving focus 与 aria-activedescendant。被 `select box/filled` / `select box/line` 包裹；本组件是"下拉里的那张列表"，不是触发它的输入框。

#### Extension scenarios
- **单选列表**：`Type=Radio` —— 从一组互斥行选一项
- **多选列表**：`Type=Multi` —— 带勾选标记的多选（CANONICAL-012），禁用项走 `items[].disabled`
- **操作菜单**：`Type=Operation List` —— 行级动作下拉（Duplicate / Rename / Delete），即右键/更多菜单类命令列表
- **排序菜单**：`Type=Sort By` —— 列表/表格排序选项

#### Don't use for
- 整体"输入框 + 下拉"选择器 —— 用 `select box/line` / `select box/filled`；本组件只是它们展开后的面板
- 别用 `<ul><li>` + 自撸勾选拼下拉列表、给每行自管 tabindex —— 用 `DropDownListSelect`，多选走 `type=Multi`、禁用走 `items[].disabled`（roving focus 已内置）

---

### Chart
- **Library key**: `TBD — import on next use`
- **Axes**: `type` (pie / donut / line / bar / bar-horizontal / line-bar)
- **Variants**: 6
- **Code mapping**: `Chart` (status: approved)

#### Primary use
数据可视化组件——Chart.js（vue-chartjs）封装，按 `type` 渲染 6 种图，`datasets` 驱动 + 内置 12 色调色板与主题感知图例。展示统计数据时用，**禁止直接引 Chart.js 或自画 SVG**。

#### Extension scenarios
- **饼图 / 环形图**：`type=pie` / `type=donut` —— 占比/构成可视化
- **折线图**：`type=line` —— 趋势/时间序列（多系列）
- **柱状图 / 横向柱状图**：`type=bar` / `type=bar-horizontal` —— 分类对比，`bar-horizontal` 走 `indexAxis: 'y'`
- **折柱混合**：`type=line-bar` —— 同图叠加柱与线，每 dataset 用 `dataset.type='bar'|'line'` 指定

#### Don't use for
- 单一百分比进度 —— 用 `Progress`，不要为一个值开 Chart
- 别直接引 Chart.js 或自画 svg 图表 —— 用 `Chart`，类型走 `type`、数据走 `datasets`

---

### Progress
- **Library key**: `TBD — import on next use`
- **Axes**: `theme` (dark / light) × `status` (default / success / error / warning) × `size` (M / S)
- **Variants**: 16
- **Code mapping**: `Progress` (status: approved)

#### Primary use
只读进度条——百分比值（`value` 0–100）+ 状态填充色 + 可选百分比标签（`showLabel` 默认 true）。展示任务完成度时用；可拖动选值用 `Slider`。

#### Extension scenarios
- **任务完成度（中性）**：`status=default`（或 `success`）—— 填充色 `--brand`（绿）
- **失败 / 错误进度**：`status=error` —— 填充色 `--red`
- **告警进度**：`status=warning` —— 填充色 `--orange`
- **紧凑布局**：`size=S` —— 更细轨道，用于行内/卡片内空间紧张处；默认 `M`

#### Don't use for
- 可交互取值 / 滑动设值 —— 用 `Slider`（Progress 是只读 indicator）
- 多值/趋势可视化 —— 用 `Chart`
- 别用嵌套 div + width% 自画进度条 —— 用 `Progress`，值走 `value`、标签走 `showLabel`

> ⚠️ `status`（default/success/error/warning）是通用进度语义（错=红、警=橙、成功/默认=brand 绿），**不是** domain-tvu M3 的 broadcast Live/Preview 映射——复用同组 token 但语义轴不同。

---

## 🟡 Skeleton — Other Library Components

> **2026-06-15 批量回填**：11 个常用件（Table / Pagination / Form Item / check box / radio / switch / InputNumber / select box/filled / Drop down List/Select / Chart / Progress）已从本表升 ✅ Verified（见上）—— 变体/轴对**已同步库真源**（`components.manifest.json` / `docs-figma-members/*`，drift=0）核实，使用语义 grounded in 组件代码 + docs page + `component-affordances.json` + domain 规则。**Library key 按本节约定标 `TBD — import on next use`**（首次 mockup import 时回填；Claude Design 消费用指导+token、不依赖 key）。

下表列出其余尚未 verify 的 component_sets，按字母排序。**Library keys 留空**（用时 import 一次填回；优先 grep 这个表确认是否存在再 import）。其中 leak / 非组件 / 旧库残留（`After selecting R wi` / `auto recover` / `Home` / `Brand color` / `Neutral Color` / `Icon Guides 16*16` / `Dark·Light/*-btn` 系列）应 prune 或标 deprecated，不升 Verified。

| Component | Axes | Variants | Status | Notes |
|---|---|---|---|---|
| `After selecting R wi` | — | 1 | 🟡 | 名字像 file-internal 标记，可能是 leak，需验（prune 候选）|
| `auto recover` | — | 1 | 🟡 | 同上（prune 候选）|
| `Brand color` | — | 1 | 🟡 | 色板示例，**非组件**（prune 候选）|
| `Breadcrumb/Item` | state | 4 | 🟡 | navigation breadcrumb 单项 |
| `Button/dark L` | icon×style×color×status×radius×fixedWidth | 400 | 🟡 | Button/dark M（✅）的 large 版本 (40px)，用法同 M |
| `Button/dark S` | 同上 | 400 | 🟡 | small 版本 (28px)，用法同 Button/dark M（✅）|
| `Button/dark XS` | 同上 | 400 | 🟡 | ⚠️ operator console **不要用** (M7) |
| `Button/light L` | 同上 | 400 | 🟡 | light theme |
| `Button/light M` | 同上 | 400 | 🟡 | light theme |
| `Button/light S` | 同上 | 400 | 🟡 | light theme |
| `Button/light XS` | 同上 | 400 | 🟡 | light theme |
| `Button/url link` | dark theme×status | 4 | 🟡 | 链接样式按钮 |
| `Dark/filled btn` | Property 1 | 3 | 🟡 | **旧库残留**，优先用 `Button/dark M`（✅）（deprecate 候选）|
| `Dark/outlined btn` | Property 1 | 3 | 🟡 | 同上（deprecate 候选）|
| `Dark/text btn` | Property 1 | 3 | 🟡 | 同上（deprecate 候选）|
| `Drop down List/Cascading` | Dark Theme×Type | 4 | 🟡 | 级联下拉 |
| `Drop down List/Item` | Theme×Type×IsParent×Checked×Active×Disabled×Hover | 41 | 🟡 | 下拉单项（通常经 `Drop down List/Select`（✅）消费）|
| `Home` | — | 1 | 🟡 | 名字异常，可能 leak（prune 候选）|
| `Icon Guides 16*16` | — | 1 | 🟡 | 设计指引**非组件**（prune 候选）|
| `input box/line` | 同 input box/filled | 112 | 🟡 | line 风格（input box/filled 已 ✅）|
| `Light/filled btn` | Property 1 | 3 | 🟡 | **旧库残留**（deprecate 候选）|
| `Light/outlined btn` | Property 1 | 3 | 🟡 | 旧库残留（deprecate 候选）|
| `Light/text btn` | Property 1 | 3 | 🟡 | 旧库残留（deprecate 候选）|
| `Neutral Color` | — | 1 | 🟡 | 色板示例，**非组件**（prune 候选）|
| `Notification` | theme×status | 14 | 🟡 | inline message banner —— ⚠️ 疑为旧模型残留（Notification 已 ✅ form/type/closable 新模型），需 dedup-verify |
| `Popup Box` | Theme | 2 | 🟡 | modal 替代 Message? 需对比验证（dedup-verify）|
| `Rating` | theme×value | 10 | 🟡 | 评分 |
| `select box/line` | 同 select box/filled | 144 | 🟡 | line 版本（select box/filled 已 ✅）|
| `Slider` | theme×size | 4 | 🟡 | 滑块 |
| `Step/Item` | direction×style×state | 9 | 🟡 | 步骤条单项 |

---

## Icons (647 total · 28 namespaces)

**直接用，不要用 Unicode glyph 替代。** 命名清晰：`icon/Action/Concept`。

| Namespace | Count | 主要 icon | Notes |
|---|---|---|---|
| `icon/output` | 81 | — | 输出/视频/流 类 |
| `icon/Video` | 57 | `Video/go to` (跳转/外链) | broadcast 视频操作 |
| `icon/indicator` | 51 | — | 状态指示 dot/glow 等 |
| `icon/input` | 41 | `input/SRT` | 输入信号源类型 |
| `icon/file` | 40 | `file/log` | 文件操作 |
| `icon/Meeting` | 38 | — | 会议/通讯 |
| `icon/Edit` | 37 | `Edit/Add 1`, `Edit/Delete` (X 关闭/移除), `Edit/Edit`, `Edit/Copy` | 编辑/CRUD |
| `icon/Preview` | 31 | `Preview/Hide` | preview/眼睛切换 |
| `icon/user` | 29 | `user/ID` | 用户标识 |
| `icon/Picture` | 24 | — | 图片操作 |
| `icon/mark` | 23 | — | 标记/书签 |
| `icon/others` | 21 | `others/global control` | 杂项 |
| `icon/audio` | 17 | — | 音频操作 |
| `icon/Message` | 17 | `Message/Notification 2` | 消息提示 |
| `icon/Arrow` | 16 | `Arrow/Double up` (展开↑), `Arrow/Double down` (折叠↓), `Arrow/Dropdown`, `Arrow/Sorting` | 方向/箭头 |
| `icon/network` | 16 | — | 网络/连接 |
| `icon/Filter` | 15 | `MMA/filter` (待验证 namespace) | 过滤 |
| `icon/Setting` | 14 | `Setting/Setting 1`, `Setting/Switch` | 设置 |
| `icon/Time` | 13 | — | 时间/时钟 |
| `icon/Feature` | 11 | — | 功能特性标记 |
| `icon/share` | 11 | — | 分享/外发 |
| `icon/Cut` | 10 | `Cut/Hard cut`, `Cut/Dissolve` | 视频剪辑过渡 |
| `icon/Menu` | 9 | `menu/3` | 菜单触发 |
| `icon/pay` | 9 | — | 计费 |
| `icon/Search` | 5 | `MMA/search` | 搜索 |
| `icon/location` | 5 | — | 地理位置 |
| `icon/load` | 4 | — | loading 状态 |
| `icon/logo` | 2 | `logo/TVU` | 品牌 logo |

### 已知具体 icon (用过实证 key)

| Icon name | Key | 语义 |
|---|---|---|
| `icon/Arrow/Double up` | `2be13b82bf5bb8e32142e82d06bc20a14cfb79c2` | card 展开（点击折叠） |
| `icon/Arrow/Double down` | `9b7938b81ceba8cb1a55661a9fbbfaa5980a6493` | card 折叠（点击展开） |
| `icon/Arrow/Dropdown` | `eba15c0b438d16e88b86ffebe86423aabef212e9` | dropdown trigger |
| `icon/PP/play` | `260bf857862c7294aaaf3b8883efbc7a7d757e9f` | "Start" action（Start In / Start Out） |
| `icon/Edit/Delete` | `6379e02068f1cad59776d408d63cb9f4b416a594` | "Remove" / X close |
| `icon/Edit/Add 1` | `b55b65cce73c6dc552b44769025770d4025d6056` | 添加 |
| `icon/Video/go to` | `07b3d6414821094250313062d0d9977b09d0ed14` | 跳转外链/UI（Open GUI 用此 icon） |
| `icon/MMA/search` | `c9e2e51836547104114154c73bf10ce33e697386` | search field 内嵌 |
| `icon/MMA/filter` | `8cde6a706478268b9b42642809c65ed8913d4d4a` | filter trigger |
| `icon/menu/3` | `f5852eafa50b905e86dee2d20dd611dcdcf1b876` | top bar menu |
| `icon/message/notification 1` | `c05b1ead2bf860ada6d3c18170e5a24647b8658a` | top bar notification |
| `icon/Setting/Setting 1` | `3233ac2db519e7221673c4bd5e5f3c1e8bda4a53` | 设置入口 |
| `icon/Setting/Switch` | `9a6fdd6764d62d08a7a542e0bc3a229de8742503` | 设置切换 |
| `icon/file/log` | `70da3e2612f1c7c8f78ad83d380946986ba24f74` | 日志/记录 |
| `icon/user/ID` | `bddcef5f3dc2e868db753f0969d52174932ff22e` | 用户 ID |
| `icon/Preview/Hide` | `d969a9441f5e442b1fbee6eba42c403a4ecc55c1` | 预览隐藏切换 |
| `icon/Preview/4` | `b2cb6ce9757ffd2b91fd86ca78d6497890d3c2c9` | 2×2 grid / 4-tile layout —— **Overview / Dashboard / All Apps 入口的标准图标**（MicroApps Console Plan B 2026-05-14 实证：sidebar Overview row） |
| `icon/Preview/9` | `8f129b19b7eaf74bbae82c381df51a846310cb82` | 3×3 grid / 9-tile layout |
| `icon/Preview/6` | `fe01f4f75abacb88bcbc4ad6c593a2f9ccba1128` | 2×3 grid / 6-tile layout |
| `icon/Preview/1` | `3aa90987939670e1ca44de6edc7eee22ce3ea570` | single tile |
| `icon/Preview/25` | `93447a33188148bdf4debe1d78330fbab7627b9f` | 5×5 grid / 25-tile layout |
| `icon/Preview/grid view` | `301206fa43b380236df529891c60088446721f7d` | 通用 grid view 视图切换 |
| `icon/Preview/List` | `0ee7e3971009799b2b6666d78f9a95f971c626b9` | 列表视图切换（与 grid view 配对） |
| `icon/Preview/Layout` | `76f23233c100f9d2ffd941859ed2619ea3cc8b78` | 布局切换 |
| `icon/Preview/sidebar` | `2edf26729d98acafec5a981f73f2861e00662def` | 侧栏切换 |
| `icon/PL/more` | `c07fc7400241ef39ebef5ed0742bfec5f8cbd533` | 更多操作 (...) |
| `icon/Message/Success 2` | `f1381cc205f43a192403875eae357e0f520bbc74` | 成功 / 覆盖充足（绿）—— BM-1047 token 充足态 coverage 标识 |
| `icon/Message/warning 1` | `cefe48b9e79a32f8386939be5febb9c2c983e91d` | 警告（橙 `UX/Orange/Default` #f68512）—— BM-1047 余额不足 coverage 标识 |
| `icon/Message/Error 4` | `de34565e…`（severe）| 严重错误（红）—— `Notification status=warning` 变体内置 icon（库默认，勿 override；BM-1047 S5 减席位告警实证） |
| `icon/Arrow/Right_1` | `a135a5138dda4900963d0c6c69823c5523d96f80` | 右向箭头（feature line / CTA 指示） |

---

## Variables (color / spacing / radius / size)

参考 [`figma-data/normalized/variables.json`](../../figma-data/normalized/variables.json) 拿全集。**已知常用**：

### Status colors (broadcast convention M3)
- `UX/Red/Default` (key `a3f82a4b...`) — Live = on-air
- `UX/Brand/Brand` (key `ea8c2383...`) — Preview / standby / **primary brand identity (Active states' left border / badge primary fill)**
- `UX/Brand/Hover` (key `eab4ef3b...`) — **Hover affordance** for brand-colored interactive elements（sidebar item hover bg / button hover bg / etc.）。**禁止用 `UX/Brand/Brand` 给 hover 状态**——hover 有专门 token
- `UX/Brand/Disable` (key `9166c747...`) — disabled state of brand action
- `UX/Red/Hover 1` (key `fc189c23...`) — red hover variant
- `UX/Blue/Hover 1` (key `c4aedbd6...`) — blue hover variant
- `UX/Orange/Hover 1` (key `e3fe4750...`) — orange hover variant
- `UX/Grey/grey-7 #7B7B7B` (key `722ad30e...`) — Inactive
- `Color Type/Icon/Active & Hover` (key `f291aa2b...`) — icon-specific active/hover color（scope: FRAME_FILL / SHAPE_FILL / STROKE）
- `Color Type/Background/Hover Grey Button` (key `7d927a84...`) — grey button hover bg
- `Color Type/Text/Hover Grey button` (key `5cd07e8e...`) — grey button hover text

> **Hover ≠ Brand 实证**（MicroApps Console Plan B 2026-05-14）：Sidebar Item Hover variant 初版误用 `Color Type/Background/Layer_3` 灰 bg，缺乏品牌色 hover affordance；修正为 `UX/Brand/Hover @ 0.10`。Active 仍用 `UX/Brand/Brand` 作主品牌身份。规则：**hover = brand-hover @ low alpha / active = brand pure**。

### Surface (dark theme)
- `Color Type/Background/Layer_1` (`1c7389d2...`) — page bg
- `Color Type/Background/Layer_3` (`93476370...`) — card bg
- `Color Type/Background/Layer_4` (`f576bb4f...`) — elevated header
- `Color Type/Background/Top Bar` (`18e41d5d...`) — top bar bg

### Text
- `Color Type/Text/Heading & Button` (`232edb81...`) — primary
- `Color Type/Text/Text_1` (`422926b1...`) — body
- `Color Type/Text/Tips` (`b3b5983a...`) — secondary
- `Color Type/Text/Placeholder & Button` (`1fe2a119...`) — placeholder

### Border / divider
- `Color Type/Line/Deep Divider` (`8a6fbbc2...`)
- `Color Type/Line/Light Divider` (`51ef402a...`)

### Spacing / Radius
- `Spacing/XXS XS S M L XL XXL`
- `Radius/XS S M`

---

## Maintenance

### Variant-leak 问题
`figma-data/normalized/components.manifest.json` 含 4078 条 variant-leak entry（figmaName 像 `dark theme=off, status=default, ...`）。Filter `figmaName.includes('=')` 过滤即可。**根本原因在 extract 步骤**——`figma-sync/extract.mjs` 把某些 component_set 的 variants 拆成独立 .json 文件保存到 `components-tokenized/`。这是数据质量 bug，将来要修，但不阻塞 catalog 使用。

### 每个 entry 的演化路径
🟡 → ✅ 的方式：
1. 任务里实际用到 → import sample instance 看 variant properties
2. 写实 Primary use / Extension scenarios / Don't use（哪怕只填 1-2 行）
3. 把 Library key 填回（可从 instance 反推）
4. 加 `Used by` 段记录在哪个 mockup 用过
5. status 改为 ✅

### Bootstrap 重生成
将来如果要做自动 catalog 维护脚本，建议放在 `figma-sync/generate-component-catalog.mjs`：
- 输入：`components.manifest.json` + `figma-to-code-mapping.json`
- 输出：本文件的 🟡 表格部分（self-overwrite）
- 保留：✅ entry 的手填部分（用 HTML 注释 `<!-- BEGIN MANUAL: <name> -->...<!-- END MANUAL -->` 边界保护）

---

## 历史

- **2026-05-06** — 首次 bootstrap。来自 Session Dashboard mockup 阶段第三次 M2 库验证踩坑（Badge / Message（当时名 prompt message）/ Tab/Item 全在库但被错判"缺件"）的反思产物。把"AI 临场 brainstorm 库类比"升级为"AI 查表"。