{
  "_meta": {
    "title": "Component Affordances — AI 组合组件语义层 (SoT)",
    "purpose": "让 AI 在设计产品（生成 Vue 代码 / 生成 Figma mockup）时，先知道每个 canonical 组件内置了什么能力，避免把已有组件（如 InputNumber 的 step / DropDownListSelect 的 multi）拆开自己用 primitive 拼。对标图标的 affordance-categories.json：图标解决「别自画 SVG」，本文件解决「别自拼组合组件」。",
    "is_source_of_truth": true,
    "generated_view": "docs/internal/component-affordances.md（由 `pnpm generate:component-affordances` 生成，勿手改）",
    "audited_by": "pnpm audit:component-affordances（校验 code_name 存在 + 双向覆盖 canonical/ + npm_export 与 canonical/index.ts 一致 + code_props 真实存在于 defineProps）",
    "source_refs": {
      "canonical_components": "src/canonical/*.vue",
      "npm_exports": "src/canonical/index.ts",
      "figma_manifest": "figma-data/normalized/components.manifest.json",
      "mockup_catalog": "docs/internal/figma-component-catalog.md（mockup 任务专属：library key / frame used-by / extension scenarios）"
    },
    "field_docs": {
      "code_name": "canonical 组件名 = src/canonical/<code_name>.vue",
      "npm_export": "npm 包公开导出名（消费方 `import { <npm_export> }`）；null = 内部 base 组件，不直接消费",
      "figma_name": "Figma 组件名（取自该 canonical 的 data-figma-component）",
      "category": "form-input | data-display | navigation | feedback | general",
      "built_in_features": "★ 核心。该组件已内置、AI 容易没看到而去自拼的能力 → controlled_by 指明用哪个 prop/轴开",
      "do_not_hand_compose": "★ 反模式：别用什么 primitive 自拼，应该用本组件的哪个能力",
      "composition": "组合关系：contained_by = 通常被谁包；contains = 内部用了哪些 canonical 组件",
      "code_props": "公开 props（实证自 defineProps）；audit 校验存在性",
      "status": "verified = 语义已填实并核对 props；skeleton = 仅基础信息"
    },
    "last_authored": "2026-06-01",
    "authored_by": "Claude Code (plan owner)"
  },

  "components": [
    {
      "code_name": "InputNumber",
      "npm_export": "InputNumber",
      "figma_name": "InputNumber",
      "category": "form-input",
      "summary": "数字步进输入框（spinbox）—— 输入框 + 内置加减按钮 + 上下界约束。",
      "synonyms_en": ["number input", "stepper", "spinbox", "spinner", "quantity input", "numeric field", "counter input"],
      "synonyms_zh": ["数字输入框", "步进器", "数量输入", "计数器", "数值输入"],
      "when_to_use": "需要受约束的整数/数值录入并希望提供加减微调时（如数量、并发数、时长）。需要连续区间拖动用 Slider。",
      "built_in_features": [
        { "feature": "加减步进按钮（+/-）", "controlled_by": "组件自带，无需外接按钮；步长用 prop:step（默认 1）" },
        { "feature": "上下界约束", "controlled_by": "prop:min（默认 0）/ prop:max（默认 10），到界自动禁用对应按钮" },
        { "feature": "只增 / 只减 / 只读形态", "controlled_by": "prop:property1 = Default | Only Add | Only Reduce | Readonly" },
        { "feature": "禁用态", "controlled_by": "prop:disabled" }
      ],
      "do_not_hand_compose": "别用 InputBox + 两个 Button(+/-) 自拼步进器，也别用裸 <input type=number>。直接用 InputNumber，步长/边界走 step/min/max，单向用 type=Only Add|Only Reduce。",
      "composition": { "contained_by": ["FormItem"], "contains": [] },
      "code_props": [
        { "name": "modelValue", "type": "number" },
        { "name": "type", "type": "Default | Only Add | Only Reduce | Readonly", "default": "Default" },
        { "name": "min", "type": "number", "default": 0 },
        { "name": "max", "type": "number", "default": 10 },
        { "name": "step", "type": "number", "default": 1 },
        { "name": "disabled", "type": "boolean", "default": false }
      ],
      "key_events": ["update:modelValue"],
      "code_import": "import { InputNumber } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Slider", "InputBoxLine"],
      "status": "verified"
    },

    {
      "code_name": "Slider",
      "npm_export": "Slider",
      "figma_name": "Slider",
      "category": "form-input",
      "summary": "连续数值滑块 —— 拖动选值 + 内置 step/min/max + 可选数值显示。",
      "synonyms_en": ["slider", "range", "range input", "track", "volume control", "seek bar"],
      "synonyms_zh": ["滑块", "滑动条", "区间选择", "音量条", "进度拖拽"],
      "when_to_use": "在连续区间内选一个值、且拖动比键入更自然时（音量、亮度、百分比）。需要精确键入用 InputNumber。",
      "built_in_features": [
        { "feature": "步进 / 区间", "controlled_by": "prop:step / prop:min / prop:max" },
        { "feature": "当前值显示", "controlled_by": "prop:showValue（默认 true）" },
        { "feature": "尺寸 / 主题", "controlled_by": "prop:size = M ... / prop:theme = dark|light" },
        { "feature": "禁用态", "controlled_by": "prop:disabled" }
      ],
      "do_not_hand_compose": "别用 <input type=range> 裸控件或自画轨道+滑块 div。用 Slider，值标签走 showValue 而非外接一个 <span>。",
      "composition": { "contained_by": ["FormItem"], "contains": [] },
      "code_props": [
        { "name": "modelValue", "type": "number", "default": 60 },
        { "name": "size", "type": "Size", "default": "M" },
        { "name": "theme", "type": "dark | light", "default": "dark" },
        { "name": "min", "type": "number", "default": 0 },
        { "name": "max", "type": "number", "default": 100 },
        { "name": "step", "type": "number", "default": 1 },
        { "name": "showValue", "type": "boolean", "default": true },
        { "name": "disabled", "type": "boolean", "default": false }
      ],
      "key_events": ["update:modelValue"],
      "code_import": "import { Slider } from '@nancyzeng0210/tvu-design-system'",
      "related": ["InputNumber", "Progress"],
      "status": "verified"
    },

    {
      "code_name": "DropDownListSelect",
      "npm_export": "DropDownListSelect",
      "figma_name": "Drop down List/Select",
      "category": "form-input",
      "summary": "下拉列表面板 —— 渲染 items 列表，支持单选/多选/操作列表/排序四种列表语义，内置键盘 roving focus。",
      "synonyms_en": ["dropdown", "dropdown list", "listbox", "option list", "menu list", "multi select list", "operation list"],
      "synonyms_zh": ["下拉列表", "下拉面板", "选项列表", "多选列表", "操作菜单", "排序菜单"],
      "when_to_use": "需要展示一组可选行（单选/多选/带勾选/操作项）。整体「输入框+下拉」选择器用 SelectBoxLine/Filled；本组件是下拉里的列表面板本体。",
      "built_in_features": [
        { "feature": "列表语义（单选/多选/操作/排序）", "controlled_by": "prop:type = Radio | Multi | Operation List | Sort By" },
        { "feature": "多选勾选标记", "controlled_by": "type=Multi 时内置勾选，无需手撸 <span class=check>（见 CANONICAL-012）" },
        { "feature": "禁用单项", "controlled_by": "items[].disabled" },
        { "feature": "键盘 roving focus + aria-activedescendant", "controlled_by": "组件内置（CANONICAL-016），无需自管 tabindex" }
      ],
      "do_not_hand_compose": "别用 <ul><li> + 自撸勾选 <span> 拼下拉列表，也别给每行自管 tabindex。用 DropDownListSelect，多选走 type=Multi（勾选已内置），禁用项走 items[].disabled。",
      "composition": { "contained_by": ["SelectBoxBase", "SelectBoxLine", "SelectBoxFilled"], "contains": ["CheckBox"] },
      "code_props": [
        { "name": "darkTheme", "type": "DarkTheme", "default": "on" },
        { "name": "type", "type": "Radio | Multi | Operation List | Sort By", "default": "Radio" },
        { "name": "items", "type": "readonly Item[]", "default": "[]" }
      ],
      "key_events": ["select", "close"],
      "code_import": "import { DropDownListSelect } from '@nancyzeng0210/tvu-design-system'",
      "related": ["SelectBoxLine", "SelectBoxFilled", "CheckBox"],
      "status": "verified"
    },

    {
      "code_name": "SelectBoxBase",
      "npm_export": null,
      "figma_name": "select box/{variant}",
      "category": "form-input",
      "summary": "下拉选择器底层实现（输入框 + 下拉面板）。内部 base，消费方请用 SelectBoxLine / SelectBoxFilled。",
      "synonyms_en": ["select", "select box", "combobox base"],
      "synonyms_zh": ["选择器底层", "下拉选择基类"],
      "when_to_use": "内部 base 组件，不直接消费。需要 select 时用 SelectBoxLine（线框）或 SelectBoxFilled（填充）。",
      "built_in_features": [
        { "feature": "单选/多选", "controlled_by": "prop:multiple 或 status=multi select" },
        { "feature": "可编辑（搜索/筛选）", "controlled_by": "prop:editable 或 ux=editable" },
        { "feature": "线框/填充形态", "controlled_by": "prop:variant = line | filled" }
      ],
      "do_not_hand_compose": "不要直接 import SelectBoxBase。用 SelectBoxLine / SelectBoxFilled。",
      "composition": { "contained_by": ["FormItem"], "contains": ["DropDownListSelect"] },
      "code_props": [
        { "name": "modelValue", "type": "string | number | Array<string|number>" },
        { "name": "options", "type": "Option[]", "default": "[]" },
        { "name": "variant", "type": "line | filled", "default": "line" },
        { "name": "multiple", "type": "boolean", "default": false },
        { "name": "editable", "type": "boolean", "default": false },
        { "name": "darkTheme", "type": "DarkTheme", "default": "on" },
        { "name": "status", "type": "Status", "default": "default" },
        { "name": "enable", "type": "Enable", "default": "on" },
        { "name": "ux", "type": "UX", "default": "default" },
        { "name": "size", "type": "Size", "default": "M" },
        { "name": "feature", "type": "Feature", "default": "default" },
        { "name": "placeholder", "type": "string", "default": "" }
      ],
      "key_events": ["update:modelValue"],
      "code_import": null,
      "related": ["SelectBoxLine", "SelectBoxFilled", "DropDownListSelect"],
      "status": "verified"
    },

    {
      "code_name": "SelectBoxLine",
      "npm_export": "SelectBoxLine",
      "figma_name": "select box/line",
      "category": "form-input",
      "summary": "线框下拉选择器（输入框 + 下拉面板，单选/多选/可搜索）。",
      "synonyms_en": ["select", "select box", "combobox", "dropdown select", "picker"],
      "synonyms_zh": ["选择器", "下拉框", "下拉选择", "选择框"],
      "when_to_use": "从选项中选一个或多个值，线框（透明底）风格。深底填充风格用 SelectBoxFilled。",
      "built_in_features": [
        { "feature": "多选", "controlled_by": "prop:multiple（内置多选 chip + 勾选）" },
        { "feature": "可编辑/搜索", "controlled_by": "prop:editable" },
        { "feature": "尺寸 / 状态 / 禁用", "controlled_by": "prop:size / prop:status / prop:enable" }
      ],
      "do_not_hand_compose": "别用 input + 浮层 div + 自撸 chip 拼 select。用 SelectBoxLine，多选走 multiple（chip 与勾选已内置），可搜索走 editable。",
      "composition": { "contained_by": ["FormItem"], "contains": ["DropDownListSelect"] },
      "code_props": [
        { "name": "modelValue", "type": "string | number | Array<string|number>" },
        { "name": "options", "type": "{label;value}[]", "default": "[]" },
        { "name": "multiple", "type": "boolean", "default": false },
        { "name": "editable", "type": "boolean", "default": false },
        { "name": "darkTheme", "type": "DarkTheme", "default": "on" },
        { "name": "status", "type": "Status", "default": "default" },
        { "name": "enable", "type": "Enable", "default": "on" },
        { "name": "ux", "type": "UX", "default": "default" },
        { "name": "size", "type": "Size", "default": "M" },
        { "name": "feature", "type": "Feature", "default": "default" },
        { "name": "placeholder", "type": "string", "default": "" }
      ],
      "key_events": ["update:modelValue"],
      "code_import": "import { SelectBoxLine } from '@nancyzeng0210/tvu-design-system'",
      "related": ["SelectBoxFilled", "DropDownListSelect", "InputBoxLine"],
      "status": "verified"
    },

    {
      "code_name": "SelectBoxFilled",
      "npm_export": "SelectBoxFilled",
      "figma_name": "select box/filled",
      "category": "form-input",
      "summary": "填充底下拉选择器（输入框 + 下拉面板，单选/多选/可搜索）。",
      "synonyms_en": ["select", "select box", "combobox", "dropdown select", "filled select"],
      "synonyms_zh": ["选择器", "下拉框", "填充选择框"],
      "when_to_use": "从选项中选值，填充（深底）风格。透明线框风格用 SelectBoxLine。",
      "built_in_features": [
        { "feature": "多选", "controlled_by": "prop:multiple" },
        { "feature": "可编辑/搜索", "controlled_by": "prop:editable" },
        { "feature": "尺寸 / 状态 / 禁用", "controlled_by": "prop:size / prop:status / prop:enable" }
      ],
      "do_not_hand_compose": "同 SelectBoxLine：别自拼 select，用本组件 + multiple/editable。",
      "composition": { "contained_by": ["FormItem"], "contains": ["DropDownListSelect"] },
      "code_props": [
        { "name": "modelValue", "type": "string | number | Array<string|number>" },
        { "name": "options", "type": "{label;value}[]", "default": "[]" },
        { "name": "multiple", "type": "boolean", "default": false },
        { "name": "editable", "type": "boolean", "default": false },
        { "name": "darkTheme", "type": "DarkTheme", "default": "on" },
        { "name": "status", "type": "Status", "default": "default" },
        { "name": "enable", "type": "Enable", "default": "on" },
        { "name": "ux", "type": "UX", "default": "default" },
        { "name": "size", "type": "Size", "default": "M" },
        { "name": "feature", "type": "Feature", "default": "default" },
        { "name": "placeholder", "type": "string", "default": "" }
      ],
      "key_events": ["update:modelValue"],
      "code_import": "import { SelectBoxFilled } from '@nancyzeng0210/tvu-design-system'",
      "related": ["SelectBoxLine", "DropDownListSelect", "InputBoxFilled"],
      "status": "verified"
    },

    {
      "code_name": "InputBoxBase",
      "npm_export": null,
      "figma_name": "input box/{variant}",
      "category": "form-input",
      "summary": "文本输入框底层实现。内部 base，消费方请用 InputBoxLine / InputBoxFilled。",
      "synonyms_en": ["input", "text input", "text field", "input base"],
      "synonyms_zh": ["输入框底层", "文本输入基类"],
      "when_to_use": "内部 base，不直接消费。需要文本输入用 InputBoxLine（线框）或 InputBoxFilled（填充）。",
      "built_in_features": [
        { "feature": "线框/填充", "controlled_by": "prop:variant = line | filled" },
        { "feature": "清除按钮 / feature 图标", "controlled_by": "prop:feature = yes（配合 ux=click 显示 clear）" },
        { "feature": "只读 / 禁用", "controlled_by": "prop:readonly / prop:enable" }
      ],
      "do_not_hand_compose": "不要直接 import InputBoxBase。用 InputBoxLine / InputBoxFilled。",
      "composition": { "contained_by": ["FormItem"], "contains": [] },
      "code_props": [
        { "name": "modelValue", "type": "string", "default": "" },
        { "name": "variant", "type": "line | filled", "default": "line" },
        { "name": "placeholder", "type": "string", "default": "" },
        { "name": "feature", "type": "Feature", "default": "no" },
        { "name": "readonly", "type": "boolean", "default": false },
        { "name": "darkTheme", "type": "DarkTheme", "default": "on" },
        { "name": "status", "type": "Status", "default": "default" },
        { "name": "enable", "type": "Enable", "default": "on" },
        { "name": "ux", "type": "UX", "default": "default" },
        { "name": "size", "type": "Size", "default": "M" }
      ],
      "key_events": ["update:modelValue"],
      "code_import": null,
      "related": ["InputBoxLine", "InputBoxFilled"],
      "status": "verified"
    },

    {
      "code_name": "InputBoxLine",
      "npm_export": "InputBoxLine",
      "figma_name": "input box/line",
      "category": "form-input",
      "summary": "线框文本输入框（透明底 + 下划线/边框）。",
      "synonyms_en": ["input", "text input", "text field", "line input", "underline input"],
      "synonyms_zh": ["输入框", "文本框", "线框输入框"],
      "when_to_use": "单行文本录入，线框风格。深底填充风格用 InputBoxFilled；数值用 InputNumber。",
      "built_in_features": [
        { "feature": "清除按钮", "controlled_by": "prop:feature=yes + ux=click（有值时显示 clear）" },
        { "feature": "尺寸 / 状态 / 只读 / 禁用", "controlled_by": "prop:size / prop:status / prop:readonly / prop:enable" }
      ],
      "do_not_hand_compose": "别用裸 <input> + 自定义边框样式。用 InputBoxLine，清除图标走 feature=yes 而非外接一个 close icon。",
      "composition": { "contained_by": ["FormItem"], "contains": [] },
      "code_props": [
        { "name": "modelValue", "type": "string", "default": "" },
        { "name": "placeholder", "type": "string", "default": "" },
        { "name": "feature", "type": "Feature", "default": "no" },
        { "name": "readonly", "type": "boolean", "default": false },
        { "name": "darkTheme", "type": "DarkTheme", "default": "on" },
        { "name": "status", "type": "Status", "default": "default" },
        { "name": "enable", "type": "Enable", "default": "on" },
        { "name": "ux", "type": "UX", "default": "default" },
        { "name": "size", "type": "Size", "default": "M" }
      ],
      "key_events": ["update:modelValue"],
      "code_import": "import { InputBoxLine } from '@nancyzeng0210/tvu-design-system'",
      "related": ["InputBoxFilled", "InputNumber", "SelectBoxLine"],
      "status": "verified"
    },

    {
      "code_name": "InputBoxFilled",
      "npm_export": "InputBoxFilled",
      "figma_name": "input box/filled",
      "category": "form-input",
      "summary": "填充底文本输入框（深底）。",
      "synonyms_en": ["input", "text input", "text field", "filled input"],
      "synonyms_zh": ["输入框", "文本框", "填充输入框"],
      "when_to_use": "单行文本录入，填充风格。透明线框风格用 InputBoxLine。",
      "built_in_features": [
        { "feature": "清除按钮", "controlled_by": "prop:feature=yes + ux=click" },
        { "feature": "尺寸 / 状态 / 只读 / 禁用", "controlled_by": "prop:size / prop:status / prop:readonly / prop:enable" }
      ],
      "do_not_hand_compose": "同 InputBoxLine：别自拼输入框，用本组件。",
      "composition": { "contained_by": ["FormItem"], "contains": [] },
      "code_props": [
        { "name": "modelValue", "type": "string", "default": "" },
        { "name": "placeholder", "type": "string", "default": "" },
        { "name": "feature", "type": "Feature", "default": "no" },
        { "name": "readonly", "type": "boolean", "default": false },
        { "name": "darkTheme", "type": "DarkTheme", "default": "on" },
        { "name": "status", "type": "Status", "default": "default" },
        { "name": "enable", "type": "Enable", "default": "on" },
        { "name": "ux", "type": "UX", "default": "default" },
        { "name": "size", "type": "Size", "default": "M" }
      ],
      "key_events": ["update:modelValue"],
      "code_import": "import { InputBoxFilled } from '@nancyzeng0210/tvu-design-system'",
      "related": ["InputBoxLine", "InputNumber", "SelectBoxFilled"],
      "status": "verified"
    },

    {
      "code_name": "FormItem",
      "npm_export": "FormItem",
      "figma_name": "FormItem",
      "category": "form-input",
      "summary": "表单行容器 —— label + 控件插槽 + required 星号 + error/hint 文案 + 布局对齐。",
      "synonyms_en": ["form item", "form field", "form row", "field wrapper", "label input group"],
      "synonyms_zh": ["表单项", "表单行", "字段", "标签输入组", "表单字段"],
      "when_to_use": "给任意表单控件加标签、必填标记、错误/提示文案并统一对齐。包裹 InputBox / SelectBox / InputNumber 等。",
      "built_in_features": [
        { "feature": "标签 + 必填星号", "controlled_by": "prop:label / prop:required" },
        { "feature": "错误 / 提示文案", "controlled_by": "prop:error / prop:hint（无需自己加一行红字 <span>）" },
        { "feature": "标签宽度 + 单/双行布局", "controlled_by": "prop:labelWidth / prop:layout" },
        { "feature": "label 命名插槽（富标签）", "controlled_by": "#label slot（v0.4.0 dual-form）" }
      ],
      "do_not_hand_compose": "别用 <label> + 控件 + 红字 <div> 手拼表单行。用 FormItem 包控件，必填走 required，报错走 error，对齐走 labelWidth/layout。",
      "composition": { "contained_by": [], "contains": ["InputBoxLine", "InputBoxFilled", "InputNumber", "SelectBoxLine", "SelectBoxFilled", "CheckBox", "Radio", "Switch"] },
      "code_props": [
        { "name": "label", "type": "string", "default": "Form Label" },
        { "name": "required", "type": "boolean", "default": false },
        { "name": "error", "type": "string" },
        { "name": "hint", "type": "string", "default": "" },
        { "name": "labelWidth", "type": "LabelWidth", "default": "120 px" },
        { "name": "layout", "type": "Layout", "default": "1 line" },
        { "name": "status", "type": "Status", "default": "Normal" },
        { "name": "theme", "type": "Theme", "default": "Dark" },
        { "name": "type", "type": "Type", "default": "Label & Input" }
      ],
      "key_events": [],
      "code_import": "import { FormItem } from '@nancyzeng0210/tvu-design-system'",
      "related": ["InputBoxLine", "SelectBoxLine", "InputNumber"],
      "status": "verified"
    },

    {
      "code_name": "CheckBox",
      "npm_export": "CheckBox",
      "figma_name": "check box",
      "category": "form-input",
      "summary": "复选框 —— 勾选/未勾选/半选三态，支持只读展示态。",
      "synonyms_en": ["checkbox", "check", "tick box", "multi select toggle", "indeterminate"],
      "synonyms_zh": ["复选框", "勾选框", "多选", "半选"],
      "when_to_use": "布尔多选 / 三态勾选。下拉列表里的勾选请用 DropDownListSelect type=Multi（已内置 CheckBox）。",
      "built_in_features": [
        { "feature": "三态（勾/未勾/半选）", "controlled_by": "prop:status = on | off | some" },
        { "feature": "只读展示态", "controlled_by": "prop:readonly（行本身是点击目标时用，CANONICAL-012）" },
        { "feature": "禁用态", "controlled_by": "prop:enable = no" }
      ],
      "do_not_hand_compose": "别用裸 <input type=checkbox> 或自画方块+对勾。用 CheckBox，半选走 status=some，纯展示走 readonly。",
      "composition": { "contained_by": ["FormItem", "DropDownListSelect", "Table"], "contains": [] },
      "code_props": [
        { "name": "status", "type": "on | off | some", "default": "off" },
        { "name": "darkTheme", "type": "DarkTheme", "default": "on" },
        { "name": "enable", "type": "Enable", "default": "yes" },
        { "name": "readonly", "type": "boolean", "default": false }
      ],
      "key_events": ["update:status"],
      "code_import": "import { CheckBox } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Radio", "Switch", "DropDownListSelect"],
      "status": "verified"
    },

    {
      "code_name": "Radio",
      "npm_export": "Radio",
      "figma_name": "radio",
      "category": "form-input",
      "summary": "单选按钮 —— 选中/未选中两态。",
      "synonyms_en": ["radio", "radio button", "option button", "single select"],
      "synonyms_zh": ["单选按钮", "单选框", "单选"],
      "when_to_use": "一组互斥选项里选一个。下拉里的单选用 DropDownListSelect type=Radio。",
      "built_in_features": [
        { "feature": "选中态", "controlled_by": "prop:status = on | off" },
        { "feature": "禁用态", "controlled_by": "prop:enable = no" }
      ],
      "do_not_hand_compose": "别用裸 <input type=radio> 或自画圆圈。用 Radio，选中走 status=on。",
      "composition": { "contained_by": ["FormItem", "DropDownListSelect"], "contains": [] },
      "code_props": [
        { "name": "status", "type": "on | off", "default": "off" },
        { "name": "darkTheme", "type": "DarkTheme", "default": "on" },
        { "name": "enable", "type": "Enable", "default": "yes" }
      ],
      "key_events": ["update:status"],
      "code_import": "import { Radio } from '@nancyzeng0210/tvu-design-system'",
      "related": ["CheckBox", "Switch"],
      "status": "verified"
    },

    {
      "code_name": "Switch",
      "npm_export": "Switch",
      "figma_name": "switch",
      "category": "form-input",
      "summary": "开关 —— 开/关/直播(live) 态 + 内置 loading。",
      "synonyms_en": ["switch", "toggle", "on off", "toggle switch"],
      "synonyms_zh": ["开关", "切换", "拨动开关", "切换开关"],
      "when_to_use": "即时生效的布尔开关（启用/停用某功能）。需要确认后才生效的多选用 CheckBox。",
      "built_in_features": [
        { "feature": "开/关/直播态", "controlled_by": "prop:status = on | off | live" },
        { "feature": "加载中（异步切换）", "controlled_by": "prop:loading = yes（无需外接 spinner）" },
        { "feature": "禁用态", "controlled_by": "prop:enable = no" }
      ],
      "do_not_hand_compose": "别用 div + transition 自画拨钮，也别在切换时外接一个 spinner。用 Switch，异步等待走 loading=yes。",
      "composition": { "contained_by": ["FormItem", "Table"], "contains": [] },
      "code_props": [
        { "name": "status", "type": "on | off | live", "default": "off" },
        { "name": "loading", "type": "yes | no", "default": "no" },
        { "name": "darkTheme", "type": "DarkTheme", "default": "on" },
        { "name": "enable", "type": "Enable", "default": "yes" }
      ],
      "key_events": ["update:status"],
      "code_import": "import { Switch } from '@nancyzeng0210/tvu-design-system'",
      "related": ["CheckBox", "Radio"],
      "status": "verified"
    },

    {
      "code_name": "Rating",
      "npm_export": "Rating",
      "figma_name": "Rating",
      "category": "form-input",
      "summary": "星级评分 —— 显示/选择 1-5 星，默认只读。",
      "synonyms_en": ["rating", "stars", "star rating", "score"],
      "synonyms_zh": ["评分", "星级", "打分", "星星"],
      "when_to_use": "展示或采集星级评分。",
      "built_in_features": [
        { "feature": "星值", "controlled_by": "prop:value（'1'..'5'）" },
        { "feature": "只读/可选", "controlled_by": "prop:readonly（默认 true 只读）" }
      ],
      "do_not_hand_compose": "别用循环画 star 图标拼评分。用 Rating，值走 value，可交互走 readonly=false。",
      "composition": { "contained_by": ["Table", "FormItem"], "contains": [] },
      "code_props": [
        { "name": "value", "type": "'1' | '2' | '3' | '4' | '5'", "default": "1" },
        { "name": "readonly", "type": "boolean", "default": true }
      ],
      "key_events": ["update:value"],
      "code_import": "import { Rating } from '@nancyzeng0210/tvu-design-system'",
      "related": [],
      "status": "verified"
    },

    {
      "code_name": "Table",
      "npm_export": "Table",
      "figma_name": "Table",
      "category": "data-display",
      "summary": "数据表格 —— 列定义 + 数据驱动渲染 + 对齐 + 斑马纹；分页请配 Pagination。",
      "synonyms_en": ["table", "data table", "grid", "datagrid", "list table"],
      "synonyms_zh": ["表格", "数据表", "列表表格", "数据网格"],
      "when_to_use": "结构化行列数据展示。分页用 Pagination 配合（不要 Table 内自实现）。",
      "built_in_features": [
        { "feature": "列定义 + 数据驱动", "controlled_by": "prop:columns / prop:data（无需手写 <tr><td>）" },
        { "feature": "对齐", "controlled_by": "prop:align（列可单独 column.align 覆盖）" },
        { "feature": "斑马纹", "controlled_by": "prop:striped" },
        { "feature": "表头形态", "controlled_by": "prop:type" }
      ],
      "do_not_hand_compose": "别手写 <table><thead><tbody> 拼数据表。用 Table，列走 columns、数据走 data；分页另配 Pagination。",
      "composition": { "contained_by": [], "contains": ["Pagination", "Badge", "Switch", "CheckBox", "Rating"] },
      "code_props": [
        { "name": "columns", "type": "readonly TableColumn[]", "default": "[]" },
        { "name": "data", "type": "Record<string,unknown>[]", "default": "[]" },
        { "name": "align", "type": "Align", "default": "Center" },
        { "name": "type", "type": "Type", "default": "Header" },
        { "name": "striped", "type": "boolean", "default": false }
      ],
      "key_events": [],
      "code_import": "import { Table } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Pagination"],
      "status": "verified"
    },

    {
      "code_name": "Pagination",
      "npm_export": "Pagination",
      "figma_name": "Pagination",
      "category": "navigation",
      "summary": "分页器 —— 页码导航 + 总数/页大小驱动，支持经典/其它形态。",
      "synonyms_en": ["pagination", "pager", "page nav", "page navigation"],
      "synonyms_zh": ["分页", "分页器", "翻页", "页码"],
      "when_to_use": "长列表 / 表格分页。通常放 Table 下方。",
      "built_in_features": [
        { "feature": "页码计算", "controlled_by": "prop:total / prop:pageSize（自动算页数）" },
        { "feature": "当前页双向绑定", "controlled_by": "v-model（update:modelValue）" },
        { "feature": "形态", "controlled_by": "prop:type = Classic | ..." }
      ],
      "do_not_hand_compose": "别用 button 列表自拼页码。用 Pagination，页数由 total/pageSize 自动算，当前页 v-model。",
      "composition": { "contained_by": ["Table"], "contains": [] },
      "code_props": [
        { "name": "modelValue", "type": "number", "default": 3 },
        { "name": "total", "type": "number", "default": 120 },
        { "name": "pageSize", "type": "number", "default": 10 },
        { "name": "type", "type": "Type", "default": "Classic" }
      ],
      "key_events": ["update:modelValue", "update:pageSize"],
      "code_import": "import { Pagination } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Table"],
      "status": "verified"
    },

    {
      "code_name": "Tab",
      "npm_export": "Tab",
      "figma_name": "Tab",
      "category": "navigation",
      "summary": "单个 Tab 触发器（单标签）。多标签用 TabList 一次给一组。",
      "synonyms_en": ["tab", "tab trigger"],
      "synonyms_zh": ["标签页", "选项卡", "单个标签"],
      "when_to_use": "需要单独一个标签时。整组标签优先用 TabList（数据驱动）。",
      "built_in_features": [
        { "feature": "线框/文字/填充形态", "controlled_by": "prop:fill = Line | Text | Filled" },
        { "feature": "白/绿配色", "controlled_by": "prop:color = White | Green" }
      ],
      "do_not_hand_compose": "整组标签别用一排 button 自拼；用 TabList。单个用 Tab。",
      "composition": { "contained_by": ["TabList"], "contains": [] },
      "code_props": [
        { "name": "modelValue", "type": "string | number", "default": "overview" },
        { "name": "fill", "type": "Line | Text | Filled", "default": "Line" },
        { "name": "color", "type": "White | Green", "default": "White" }
      ],
      "key_events": ["update:modelValue"],
      "code_import": "import { Tab } from '@nancyzeng0210/tvu-design-system'",
      "related": ["TabList", "TabItem"],
      "status": "verified"
    },

    {
      "code_name": "TabList",
      "npm_export": "TabList",
      "figma_name": "TabList",
      "category": "navigation",
      "summary": "标签组 —— items 数组驱动整组 tab，内置当前选中 v-model。",
      "synonyms_en": ["tabs", "tab list", "tab bar", "tab group", "segmented"],
      "synonyms_zh": ["标签组", "选项卡组", "标签栏", "分段切换"],
      "when_to_use": "一组互斥视图切换。这是 tab 的首选入口（数据驱动整组）。",
      "built_in_features": [
        { "feature": "整组渲染", "controlled_by": "prop:items（[{label,value,disabled?}]）" },
        { "feature": "当前选中双向绑定", "controlled_by": "v-model（update:modelValue）" },
        { "feature": "形态", "controlled_by": "prop:fill = Line | Text | Filled" }
      ],
      "do_not_hand_compose": "别用一排 button + 自管 active class 拼 tab。用 TabList，整组走 items，当前页 v-model。",
      "composition": { "contained_by": [], "contains": ["TabItem"] },
      "code_props": [
        { "name": "items", "type": "{label;value;disabled?}[]" },
        { "name": "modelValue", "type": "string | number", "default": "overview" },
        { "name": "fill", "type": "Line | Text | Filled", "default": "Line" }
      ],
      "key_events": ["update:modelValue"],
      "code_import": "import { TabList } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Tab", "TabItem"],
      "status": "verified"
    },

    {
      "code_name": "TabItem",
      "npm_export": "TabItem",
      "figma_name": "TabItem",
      "category": "navigation",
      "summary": "TabList 内的单个标签项（通常由 TabList 内部渲染）。",
      "synonyms_en": ["tab item", "tab"],
      "synonyms_zh": ["标签项", "单个选项卡"],
      "when_to_use": "一般不直接用，由 TabList 渲染；需要细粒度控制单项时用。",
      "built_in_features": [
        { "feature": "普通/激活态", "controlled_by": "prop:state = Normal | Active" },
        { "feature": "禁用", "controlled_by": "prop:disabled" },
        { "feature": "形态 / 配色", "controlled_by": "prop:fill / prop:color" }
      ],
      "do_not_hand_compose": "优先用 TabList 整组；单项才用 TabItem，激活走 state=Active。",
      "composition": { "contained_by": ["TabList"], "contains": [] },
      "code_props": [
        { "name": "value", "type": "string | number", "default": "overview" },
        { "name": "state", "type": "Normal | Active", "default": "Normal" },
        { "name": "color", "type": "White | Green", "default": "White" },
        { "name": "fill", "type": "Line | Text | Filled", "default": "Line" },
        { "name": "disabled", "type": "boolean", "default": false }
      ],
      "key_events": [],
      "code_import": "import { TabItem } from '@nancyzeng0210/tvu-design-system'",
      "related": ["TabList", "Tab"],
      "status": "verified"
    },

    {
      "code_name": "Breadcrumb",
      "npm_export": "Breadcrumb",
      "figma_name": "Breadcrumb/Item",
      "category": "navigation",
      "summary": "面包屑容器 —— slot 放一组 BreadcrumbItem，分隔符内置。",
      "synonyms_en": ["breadcrumb", "breadcrumbs", "path nav", "trail"],
      "synonyms_zh": ["面包屑", "路径导航", "层级导航"],
      "when_to_use": "展示当前页在层级结构中的位置路径。",
      "built_in_features": [
        { "feature": "分隔符", "controlled_by": "BreadcrumbItem.showSeparator（容器自动串联）" }
      ],
      "do_not_hand_compose": "别用 <a> + '/' 字符自拼路径。用 Breadcrumb 包 BreadcrumbItem，分隔符内置。",
      "composition": { "contained_by": ["TopBar"], "contains": ["BreadcrumbItem"] },
      "code_props": [],
      "key_events": [],
      "code_import": "import { Breadcrumb } from '@nancyzeng0210/tvu-design-system'",
      "related": ["BreadcrumbItem"],
      "status": "verified"
    },

    {
      "code_name": "BreadcrumbItem",
      "npm_export": "BreadcrumbItem",
      "figma_name": "Breadcrumb/Item",
      "category": "navigation",
      "summary": "面包屑单项 —— 链接 + 状态（当前/hover/disabled）+ 分隔符开关。",
      "synonyms_en": ["breadcrumb item", "crumb", "path segment"],
      "synonyms_zh": ["面包屑项", "路径段"],
      "when_to_use": "Breadcrumb 内的每一级。最后一级通常 state=current。",
      "built_in_features": [
        { "feature": "状态", "controlled_by": "prop:state = Default | hover | current | disabled" },
        { "feature": "链接", "controlled_by": "prop:href" },
        { "feature": "分隔符显隐", "controlled_by": "prop:showSeparator（最后一项设 false）" }
      ],
      "do_not_hand_compose": "用 BreadcrumbItem，当前页走 state=current（不要用纯文本 + 手动去掉链接）。",
      "composition": { "contained_by": ["Breadcrumb"], "contains": [] },
      "code_props": [
        { "name": "href", "type": "string" },
        { "name": "state", "type": "Default | hover | current | disabled", "default": "current" },
        { "name": "showSeparator", "type": "boolean", "default": true }
      ],
      "key_events": [],
      "code_import": "import { BreadcrumbItem } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Breadcrumb"],
      "status": "verified"
    },

    {
      "code_name": "Steps",
      "npm_export": "Steps",
      "figma_name": "Step/Item",
      "category": "navigation",
      "summary": "步骤条容器 —— 横/竖方向 + 当前步 + 数字/图标样式，内部串联 StepItem。",
      "synonyms_en": ["steps", "stepper", "wizard", "progress steps", "stepline"],
      "synonyms_zh": ["步骤条", "步骤", "向导", "流程步骤"],
      "when_to_use": "多步流程/向导的进度指示。注意区别 InputNumber 的「步进」——那是数值不是流程。",
      "built_in_features": [
        { "feature": "当前步高亮 + 连接线", "controlled_by": "prop:current（连接线由容器自动算）" },
        { "feature": "横/竖方向", "controlled_by": "prop:direction = horizontal | vertical" },
        { "feature": "数字/图标样式", "controlled_by": "prop:type = number | icon" }
      ],
      "do_not_hand_compose": "别用 circle + 连线 div 自拼步骤条。用 Steps，当前步走 current，方向走 direction。",
      "composition": { "contained_by": [], "contains": ["StepItem"] },
      "code_props": [
        { "name": "current", "type": "number", "default": 0 },
        { "name": "active", "type": "number" },
        { "name": "direction", "type": "horizontal | vertical", "default": "horizontal" },
        { "name": "type", "type": "number | icon", "default": "number" }
      ],
      "key_events": [],
      "code_import": "import { Steps } from '@nancyzeng0210/tvu-design-system'",
      "related": ["StepItem"],
      "status": "verified"
    },

    {
      "code_name": "StepItem",
      "npm_export": "StepItem",
      "figma_name": "Step/Item",
      "category": "navigation",
      "summary": "步骤条单步 —— 标题/描述 + 状态 + 前后连接线 + 数字/图标。",
      "synonyms_en": ["step item", "step", "wizard step"],
      "synonyms_zh": ["步骤项", "单步"],
      "when_to_use": "Steps 内的每一步；一般由 Steps 串联，需要细控时单用。",
      "built_in_features": [
        { "feature": "状态", "controlled_by": "prop:state" },
        { "feature": "前后连接线显隐", "controlled_by": "prop:showLeadingConnector / prop:showTrailingConnector" },
        { "feature": "图标 / 数字", "controlled_by": "prop:iconName / prop:type" }
      ],
      "do_not_hand_compose": "优先用 Steps 串联；单步才用 StepItem。",
      "composition": { "contained_by": ["Steps"], "contains": [] },
      "code_props": [
        { "name": "title", "type": "string", "default": "Step Title" },
        { "name": "description", "type": "string", "default": "" },
        { "name": "index", "type": "number", "default": 0 },
        { "name": "state", "type": "State" },
        { "name": "direction", "type": "Direction" },
        { "name": "type", "type": "StepStyle" },
        { "name": "iconName", "type": "string" },
        { "name": "showLeadingConnector", "type": "boolean", "default": true },
        { "name": "showTrailingConnector", "type": "boolean", "default": true }
      ],
      "key_events": [],
      "code_import": "import { StepItem } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Steps"],
      "status": "verified"
    },

    {
      "code_name": "TopBar",
      "npm_export": "TopBar",
      "figma_name": "TopBar",
      "category": "navigation",
      "summary": "顶部应用栏 —— 标题 + 可选菜单按钮 + 可选搜索框 + 登录前/后形态。",
      "synonyms_en": ["top bar", "app bar", "header bar", "navbar", "title bar"],
      "synonyms_zh": ["顶栏", "顶部栏", "应用栏", "导航栏", "标题栏"],
      "when_to_use": "页面/应用顶部全局栏。",
      "built_in_features": [
        { "feature": "菜单按钮显隐", "controlled_by": "prop:showMenu" },
        { "feature": "搜索框显隐", "controlled_by": "prop:showSearchBox" },
        { "feature": "登录前/后形态", "controlled_by": "prop:tag = After Login | ..." }
      ],
      "do_not_hand_compose": "别用 header + flex 自拼顶栏。用 TopBar，菜单/搜索走 showMenu/showSearchBox。",
      "composition": { "contained_by": [], "contains": ["Breadcrumb"] },
      "code_props": [
        { "name": "title", "type": "string", "default": "Product Name" },
        { "name": "tag", "type": "Tag", "default": "After Login" },
        { "name": "showMenu", "type": "boolean", "default": true },
        { "name": "showSearchBox", "type": "boolean", "default": false }
      ],
      "key_events": [],
      "code_import": "import { TopBar } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Breadcrumb"],
      "status": "verified"
    },

    {
      "code_name": "Notification",
      "npm_export": "Notification",
      "figma_name": "Notification",
      "category": "feedback",
      "summary": "通知 —— 双轴 form×type：dialog/alert/pop confirm 居中模态（按钮按 form 固定）、slide 侧边被动 toast；分类图标随 type 内置。",
      "synonyms_en": ["notification", "alert", "toast", "banner", "callout", "confirm dialog"],
      "synonyms_zh": ["通知", "提示卡", "告警", "横幅", "消息卡", "确认弹窗"],
      "when_to_use": "状态反馈/告警/轻确认：被动告知用 form=slide；需决策用 form=dialog 或 pop confirm；单一确认用 form=alert。轻量行内提示用 Message；表单类模态用 PopupBox。",
      "built_in_features": [
        { "feature": "交互形态", "controlled_by": "prop:form = dialog | alert | pop confirm | slide（按钮按 form 固定：dialog/pop confirm=Cancel+Confirm、alert=单 OK、slide=无）" },
        { "feature": "严重度图标", "controlled_by": "prop:type = warning | secondary warning | error | info | success | none（图标随 type 内置）" },
        { "feature": "关闭按钮", "controlled_by": "prop:closable（默认 true，无需外接 close icon）" },
        { "feature": "按钮文案", "controlled_by": "prop:cancelText / prop:confirmText / prop:okText（仅改文案，按钮有无由 form 决定）" }
      ],
      "do_not_hand_compose": "别用带图标的 div + close × + button 自拼通知/确认框。用 Notification，形态走 form、严重度走 type，按钮是 form 固定的不要外拼。",
      "composition": { "contained_by": [], "contains": [] },
      "code_props": [
        { "name": "form", "type": "Form", "default": "dialog" },
        { "name": "type", "type": "Type", "default": "none" },
        { "name": "theme", "type": "Theme", "default": "dark" },
        { "name": "title", "type": "string" },
        { "name": "description", "type": "string" },
        { "name": "closable", "type": "boolean", "default": true },
        { "name": "cancelText", "type": "string" },
        { "name": "confirmText", "type": "string" },
        { "name": "okText", "type": "string" }
      ],
      "key_events": [],
      "code_import": "import { Notification } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Message", "PopupBox"],
      "status": "verified"
    },

    {
      "code_name": "Message",
      "npm_export": "Message",
      "figma_name": "Message",
      "category": "feedback",
      "summary": "行内提示条 —— 状态色 + 尺寸 + 可关闭，比 Notification 轻。",
      "synonyms_en": ["prompt", "inline message", "hint message", "alert inline", "tip", "toast"],
      "synonyms_zh": ["提示信息", "行内提示", "消息条", "提示条"],
      "when_to_use": "轻量行内状态提示（表单上方一行提示、页面内联反馈）。成块带操作用 Notification。",
      "built_in_features": [
        { "feature": "状态色 + 图标", "controlled_by": "prop:status = info | ..." },
        { "feature": "尺寸", "controlled_by": "prop:size = L | ..." },
        { "feature": "关闭", "controlled_by": "prop:closable（默认 true）" }
      ],
      "do_not_hand_compose": "别用 icon + 文本 div 自拼行内提示。用 Message。",
      "composition": { "contained_by": [], "contains": [] },
      "code_props": [
        { "name": "status", "type": "MessageStatus", "default": "info" },
        { "name": "size", "type": "MessageSize", "default": "L" },
        { "name": "closable", "type": "boolean", "default": true }
      ],
      "key_events": [],
      "code_import": "import { Message } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Notification", "Tooltip"],
      "status": "verified"
    },

    {
      "code_name": "PopupBox",
      "npm_export": "PopupBox",
      "figma_name": "Popup Box",
      "category": "feedback",
      "summary": "模态弹窗 —— 标题 + 内容插槽 + footer(取消/确认) + 背板/Esc 关闭控制。",
      "synonyms_en": ["modal", "dialog", "popup", "popup box", "overlay dialog"],
      "synonyms_zh": ["弹窗", "对话框", "模态框", "模态弹窗"],
      "when_to_use": "需要打断流程的模态对话（确认、表单、详情）。非模态轻提示用 Notification/Message。",
      "built_in_features": [
        { "feature": "显隐双向绑定", "controlled_by": "prop:visible + v-model:visible" },
        { "feature": "关闭手段", "controlled_by": "prop:closable / prop:closeOnBackdrop / prop:closeOnEscape" },
        { "feature": "footer 取消/确认", "controlled_by": "prop:showFooter + cancelText/confirmText，或 #footer slot" },
        { "feature": "宽度", "controlled_by": "prop:width（默认 680）" }
      ],
      "do_not_hand_compose": "别用 fixed 遮罩 div + 自管 z-index/Esc 拼模态。用 PopupBox，显隐 v-model:visible，关闭走 closeOnBackdrop/closeOnEscape，按钮走 footer。",
      "composition": { "contained_by": [], "contains": [] },
      "code_props": [
        { "name": "visible", "type": "boolean", "default": false },
        { "name": "title", "type": "string" },
        { "name": "width", "type": "string | number", "default": 680 },
        { "name": "theme", "type": "Theme", "default": "dark" },
        { "name": "closable", "type": "boolean", "default": true },
        { "name": "closeOnBackdrop", "type": "boolean", "default": false },
        { "name": "closeOnEscape", "type": "boolean", "default": true },
        { "name": "showFooter", "type": "boolean", "default": true },
        { "name": "cancelText", "type": "string" },
        { "name": "confirmText", "type": "string" }
      ],
      "key_events": ["update:visible", "close", "cancel", "confirm"],
      "code_import": "import { PopupBox } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Notification"],
      "status": "verified"
    },

    {
      "code_name": "Tooltip",
      "npm_export": "Tooltip",
      "figma_name": "Tooltip",
      "category": "data-display",
      "summary": "气泡提示 —— 悬浮文案 + 6 个指向方位，内置定位。",
      "synonyms_en": ["tooltip", "hint", "popover", "hover hint", "bubble"],
      "synonyms_zh": ["气泡提示", "悬浮提示", "工具提示", "提示气泡"],
      "when_to_use": "hover/focus 时补充说明。常驻行内提示用 Message。",
      "built_in_features": [
        { "feature": "指向方位", "controlled_by": "prop:pointing（6 向，内部映射到 placement）" },
        { "feature": "文案", "controlled_by": "prop:content 或 #content slot（v0.4.0 dual-form）" },
        { "feature": "受控显隐 / 禁用", "controlled_by": "prop:open / prop:disabled" }
      ],
      "do_not_hand_compose": "别用 title 属性或自管绝对定位 div 拼 tooltip。用 Tooltip，方位走 pointing。",
      "composition": { "contained_by": [], "contains": [] },
      "code_props": [
        { "name": "content", "type": "string", "default": "Description" },
        { "name": "pointing", "type": "Pointing", "default": "Center down" },
        { "name": "darkTheme", "type": "DarkTheme", "default": "off" },
        { "name": "open", "type": "boolean", "default": false },
        { "name": "disabled", "type": "boolean", "default": false }
      ],
      "key_events": [],
      "code_import": "import { Tooltip } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Message"],
      "status": "verified"
    },

    {
      "code_name": "Badge",
      "npm_export": "Badge",
      "figma_name": "Badge",
      "category": "data-display",
      "summary": "状态/计数标记 —— 圆形/矩形 × 5 色 × 填充/线框，只读指示。",
      "synonyms_en": ["badge", "tag", "pill", "status dot", "count badge", "label"],
      "synonyms_zh": ["徽标", "标签", "状态点", "计数标记", "角标"],
      "when_to_use": "只读的状态/计数指示（行内状态、计数角标）。可点击的 chip/选择用 Tab；运行态会话指示用 PillStatus。",
      "built_in_features": [
        { "feature": "形状", "controlled_by": "prop:type = Circle | Rectangle" },
        { "feature": "状态色", "controlled_by": "prop:color = Green | Blue | Orange | Red | Neutral" },
        { "feature": "填充/线框", "controlled_by": "prop:fill = Filled | Line" }
      ],
      "do_not_hand_compose": "别用带背景色的 <span> 自拼状态标。用 Badge，色走 color、形态走 type/fill。",
      "composition": { "contained_by": ["Table", "TopBar"], "contains": [] },
      "code_props": [
        { "name": "type", "type": "Circle | Rectangle", "default": "Circle" },
        { "name": "color", "type": "Green | Blue | Orange | Red | Neutral", "default": "Green" },
        { "name": "fill", "type": "Filled | Line", "default": "Filled" }
      ],
      "key_events": [],
      "code_import": "import { Badge } from '@nancyzeng0210/tvu-design-system'",
      "related": ["PillStatus", "PillCounter"],
      "status": "verified"
    },

    {
      "code_name": "PillStatus",
      "npm_export": "PillStatus",
      "figma_name": "Pill Status",
      "category": "data-display",
      "summary": "会话运行状态药丸 —— On-air/Preview/Analyzing/Inactive + active 态 + 可选计数。",
      "synonyms_en": ["status pill", "session status", "live pill", "state badge"],
      "synonyms_zh": ["状态药丸", "会话状态", "直播状态", "运行状态"],
      "when_to_use": "TVU 会话/流的运行状态指示（直播/预览/分析中/未激活）。通用状态/计数用 Badge。",
      "built_in_features": [
        { "feature": "状态语义色", "controlled_by": "prop:status = On-air(red) | Preview(brand) | Analyzing(blue) | Inactive(grey)" },
        { "feature": "激活/未激活态", "controlled_by": "prop:active（false 时统一灰态）" },
        { "feature": "计数", "controlled_by": "prop:count" }
      ],
      "do_not_hand_compose": "别自拼带圆点的状态药丸。用 PillStatus，运行语义走 status，未激活走 active=false。",
      "composition": { "contained_by": ["Table", "TopBar"], "contains": [] },
      "code_props": [
        { "name": "status", "type": "On-air | Preview | Analyzing | Inactive", "default": "On-air" },
        { "name": "active", "type": "boolean", "default": true },
        { "name": "count", "type": "number | string" }
      ],
      "key_events": [],
      "code_import": "import { PillStatus } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Badge", "PillCounter"],
      "status": "verified"
    },

    {
      "code_name": "PillCounter",
      "npm_export": null,
      "figma_name": "Pill/Counter",
      "category": "data-display",
      "summary": "计数药丸（neutral/success/warning/info 配色）。内部组件，未在 npm 公开导出。",
      "synonyms_en": ["counter pill", "count badge"],
      "synonyms_zh": ["计数药丸", "计数标记"],
      "when_to_use": "内部组件，当前未公开导出。通用计数标记请用 Badge。",
      "built_in_features": [
        { "feature": "配色语义", "controlled_by": "prop:kind = neutral | success | warning | info" }
      ],
      "do_not_hand_compose": "当前不在 npm 公开 API；通用计数用 Badge。",
      "composition": { "contained_by": [], "contains": [] },
      "code_props": [
        { "name": "kind", "type": "neutral | success | warning | info", "default": "neutral" }
      ],
      "key_events": [],
      "code_import": null,
      "related": ["Badge", "PillStatus"],
      "status": "verified"
    },

    {
      "code_name": "Progress",
      "npm_export": "Progress",
      "figma_name": "Progress",
      "category": "data-display",
      "summary": "进度条 —— 百分比值 + 状态色 + 可选标签。",
      "synonyms_en": ["progress", "progress bar", "loading bar", "percentage bar"],
      "synonyms_zh": ["进度条", "进度", "百分比条", "加载条"],
      "when_to_use": "展示任务完成百分比（只读）。可拖动选值用 Slider。",
      "built_in_features": [
        { "feature": "进度值", "controlled_by": "prop:value（0-100）" },
        { "feature": "状态色", "controlled_by": "prop:status" },
        { "feature": "百分比标签", "controlled_by": "prop:showLabel（默认 true）" }
      ],
      "do_not_hand_compose": "别用嵌套 div + width% 自画进度条。用 Progress，值走 value，标签走 showLabel。",
      "composition": { "contained_by": [], "contains": [] },
      "code_props": [
        { "name": "value", "type": "number", "default": 60 },
        { "name": "size", "type": "Size", "default": "M" },
        { "name": "status", "type": "Status", "default": "default" },
        { "name": "theme", "type": "Theme", "default": "dark" },
        { "name": "showLabel", "type": "boolean", "default": true }
      ],
      "key_events": [],
      "code_import": "import { Progress } from '@nancyzeng0210/tvu-design-system'",
      "related": ["Slider"],
      "status": "verified"
    },

    {
      "code_name": "Chart",
      "npm_export": "Chart",
      "figma_name": "Chart",
      "category": "data-display",
      "summary": "图表 —— Chart.js 封装，按 type 渲染多种图，datasets 驱动 + 12 色调色板。",
      "synonyms_en": ["chart", "graph", "plot", "bar chart", "line chart", "pie chart"],
      "synonyms_zh": ["图表", "图形", "统计图", "柱状图", "折线图", "饼图"],
      "when_to_use": "数据可视化（柱/线/饼等，按 type）。",
      "built_in_features": [
        { "feature": "图表类型", "controlled_by": "prop:type" },
        { "feature": "数据集 + 标签", "controlled_by": "prop:datasets / prop:labels" },
        { "feature": "尺寸", "controlled_by": "prop:width / prop:height" }
      ],
      "do_not_hand_compose": "别直接引 Chart.js 或自画 svg 图表。用 Chart，类型走 type、数据走 datasets（内置 12 色 palette）。",
      "composition": { "contained_by": [], "contains": [] },
      "code_props": [
        { "name": "type", "type": "ChartType" },
        { "name": "datasets", "type": "ChartDatasetInput[]" },
        { "name": "labels", "type": "string[]", "default": "[]" },
        { "name": "height", "type": "number", "default": 200 },
        { "name": "width", "type": "number", "default": 320 }
      ],
      "key_events": [],
      "code_import": "import { Chart } from '@nancyzeng0210/tvu-design-system'",
      "related": [],
      "status": "verified"
    },

    {
      "code_name": "ButtonBridge",
      "npm_export": "Button",
      "figma_name": "Button",
      "category": "general",
      "summary": "按钮 —— 8 轴覆盖 Figma 全部 Button sets（色/尺寸/形态/图标/状态/圆角/定宽/主题）。npm 导出名为 Button。",
      "synonyms_en": ["button", "btn", "cta", "action button"],
      "synonyms_zh": ["按钮", "操作按钮", "主按钮"],
      "when_to_use": "任何点击操作。导出名是 Button（不是 ButtonBridge）。",
      "built_in_features": [
        { "feature": "配色", "controlled_by": "prop:color = green | red | orange | gray 1" },
        { "feature": "形态", "controlled_by": "prop:fill = filling | ghost | rimless" },
        { "feature": "图标位", "controlled_by": "prop:icon = no | left | right | loading" },
        { "feature": "尺寸/圆角/定宽/状态", "controlled_by": "prop:size / prop:radius / prop:fixedWidth / prop:status" },
        { "feature": "主题（跟随 docs 或显式）", "controlled_by": "prop:theme（缺省 inject docsTheme）" }
      ],
      "do_not_hand_compose": "别用裸 <button> + 自定义样式。用 Button（`import { Button }`），loading 走 icon=loading 而非外接 spinner。",
      "composition": { "contained_by": ["Notification", "PopupBox", "Pagination"], "contains": [] },
      "code_props": [
        { "name": "color", "type": "green | red | orange | gray 1", "default": "gray 1" },
        { "name": "fill", "type": "filling | ghost | rimless", "default": "filling" },
        { "name": "icon", "type": "no | left | right | loading", "default": "no" },
        { "name": "size", "type": "Size", "default": "M" },
        { "name": "radius", "type": "square | round", "default": "square" },
        { "name": "fixedWidth", "type": "yes | no", "default": "no" },
        { "name": "status", "type": "default | hover | disable | loading", "default": "default" },
        { "name": "theme", "type": "dark | light" }
      ],
      "key_events": [],
      "code_import": "import { Button } from '@nancyzeng0210/tvu-design-system'",
      "related": [],
      "status": "verified"
    },
    {
      "code_name": "Logo",
      "npm_export": null,
      "figma_name": "—（无独立 Figma 组件；等价物 = TopBar 内部 logo 图层 + 品牌图标资产 icon/logo/TVU · icon/logo/ts；见 divergence logo-menulist-usermenu-code-first-2026-07-02）",
      "category": "general",
      "summary": "品牌 Logo —— 渲染 registry 品牌 SVG（tvu 全称 / ts 简写）。双框架库 code-first 组件（tvu-logo），不经 src/index.ts（已发布 Vue 包未含）。",
      "synonyms_en": ["logo", "brand", "brand mark", "wordmark"],
      "synonyms_zh": ["标志", "品牌标识", "商标", "logo"],
      "when_to_use": "顶栏或页面品牌标识。别手搓 SVG——用 Logo，type 切换 tvu/ts。",
      "built_in_features": [
        { "feature": "品牌变体", "controlled_by": "prop:type = tvu | ts" },
        { "feature": "尺寸", "controlled_by": "prop:size（px）" }
      ],
      "do_not_hand_compose": "别内联/自画品牌 SVG。用 Logo，图形走 icon registry（icon/logo/TVU · icon/logo/ts）。",
      "composition": { "contained_by": ["TopBar", "UserMenu"], "contains": [] },
      "code_props": [
        { "name": "type", "type": "tvu | ts", "default": "tvu" },
        { "name": "size", "type": "number", "default": "16" }
      ],
      "key_events": [],
      "related": ["TopBar", "UserMenu"],
      "status": "verified"
    },
    {
      "code_name": "MenuList",
      "npm_export": null,
      "figma_name": "—（无独立 Figma 组件；等价物 = TopBar 内部 \"Menu List\" 图层；见 divergence logo-menulist-usermenu-code-first-2026-07-02）",
      "category": "navigation",
      "summary": "菜单列表 —— topbar 菜单模式抽取。horizontal（品牌下划线）/ vertical（品牌色 + 末尾 action/selected 勾选）。双框架 code-first 组件（tvu-menu-list），不经 src/index.ts。",
      "synonyms_en": ["menu", "menu list", "nav list", "menu items"],
      "synonyms_zh": ["菜单", "菜单列表", "导航列表", "菜单项"],
      "when_to_use": "顶栏/下拉面板里的菜单项分组。别用 ul+li 自拼——用 MenuList，items 驱动，选中态走 item.selected。",
      "built_in_features": [
        { "feature": "方向", "controlled_by": "prop:orientation = horizontal | vertical" },
        { "feature": "菜单项（含 action/selected 勾选）", "controlled_by": "prop:items[]" }
      ],
      "do_not_hand_compose": "别用 ul/li + flex 自拼菜单。用 MenuList，图标走 registry，勾选态走 item.selected。",
      "composition": { "contained_by": ["TopBar", "UserMenu"], "contains": [] },
      "code_props": [
        { "name": "items", "type": "MenuListItem[]", "default": "[]" },
        { "name": "orientation", "type": "horizontal | vertical", "default": "vertical" }
      ],
      "key_events": [],
      "related": ["TopBar", "UserMenu"],
      "status": "verified"
    },
    {
      "code_name": "UserMenu",
      "npm_export": null,
      "figma_name": "—（无独立 Figma 组件；等价物 = TopBar 内部账号区 PM 头像 + Account Name；下拉壳 code-first；见 divergence logo-menulist-usermenu-code-first-2026-07-02）",
      "category": "navigation",
      "summary": "用户菜单 —— 实心首字母/图片头像 → 下拉面板（账号头 name+role+email · custom actions[MenuList] · 行内语言切换 · 退出）。双框架 code-first 组件（tvu-user-menu），不经 src/index.ts。",
      "synonyms_en": ["user menu", "account menu", "avatar menu", "profile menu"],
      "synonyms_zh": ["用户菜单", "账号菜单", "头像菜单", "个人菜单"],
      "when_to_use": "登录后顶栏右侧账号入口（§3：after-login TopBar rightContent 必须是 UserMenu，别手搓头像+菜单）。",
      "built_in_features": [
        { "feature": "头像（首字母底色或图片）", "controlled_by": "prop:name / prop:image / prop:color" },
        { "feature": "账号头（name+role+email）", "controlled_by": "prop:name / prop:role / prop:email" },
        { "feature": "自定义操作", "controlled_by": "prop:actions[]（渲染为 MenuList 面板体）" },
        { "feature": "行内语言切换", "controlled_by": "prop:languages[] / prop:lang" }
      ],
      "do_not_hand_compose": "别手搓头像+下拉菜单。登录后顶栏右区用 UserMenu，操作走 actions（MenuList），语言切换走内建 languages/lang（别外接切换器）。",
      "composition": { "contained_by": ["TopBar"], "contains": ["Logo", "MenuList"] },
      "code_props": [
        { "name": "name", "type": "string", "default": "''" },
        { "name": "email", "type": "string" },
        { "name": "role", "type": "string" },
        { "name": "image", "type": "string" },
        { "name": "color", "type": "string" },
        { "name": "actions", "type": "MenuListItem[]", "default": "[]" },
        { "name": "languages", "type": "UserMenuLanguage[]", "default": "[]" },
        { "name": "lang", "type": "string" }
      ],
      "key_events": [],
      "related": ["TopBar", "MenuList", "Logo"],
      "status": "verified"
    }
  ]
}