--- name: tvu-design-system-rules description: 用 TVU 设计系统做设计稿 / 原型 / 前端代码时必须遵守的规则。Claude Design 每轮从本文件重新编译这套系统的"隐性规则"层——代码与 Figma 里推断不出来的那部分。 --- # TVU 设计系统 — 使用规则（Claude Design SKILL） > **这份文件是什么**：TVU 设计系统里**代码和 Figma 推断不出来的隐性规则**的浓缩。 > 视觉真源（颜色 / 间距 / 组件长相）在 `design-system/` 的编译样式 + `reference/` 的目录里； > 本文件只讲**怎么用才合规**。每条规则标了 `reference/` 里的出处,要核细节去查那里。 > **数值以 `tokens/variables.css` 与 `reference/icon-keys-*.md` 为准**（本文件给的是约数,会随版本变）。 --- ## 0. 两条铁律（高于一切） 1. **Figma 是真源**。组件的视觉（颜色 / 间距 / 尺寸 / 圆角 / 变体）以已发布库为准；设计稿用库组件,不自画形状拼凑已有组件。出处:`reference/03-mockup-conventions.md`、`reference/01-figma-component-catalog.md`。 2. **不按"行业惯例"自由发挥**。组件怎么用、什么场景用哪个、交付格式以本系统文档为准;没覆盖的向用户确认,不凭通用设计常识补全。出处:`reference/02-component-affordances.md`。 --- ## 1. 颜色与 token（最容易违规处） - **一律用 token,绝不硬编码 hex**。颜色 / 间距 / 圆角 / 字体都走 CSS 变量(`var(--brand)` / `var(--bg-layer1)`),不写 `#2fb54e` / `12px` 字面量。出处:`design-system/variables.css` 头注 + `reference/07-working-principles.md`。 - **品牌绿是强调色,克制使用**。`--brand`（dark `#2fb54e` / light `#299f45`）只用于主操作 / 关键强调,不要拿它染普通提示文字或大面积铺底。出处:`reference/03-mockup-conventions.md` §颜色规范。 - **背景分层 Layer 体系**:`--bg-layer1` → `--bg-layer4` 是从底到面的层级（dark `#141414`→`#353535`,light `#ffffff`→`#dbdbdb`）。按层级语义选,不要跳级乱用。出处:`design-system/variables.css`。 - **双主题**:dark 是默认(`:root`),light 用 `[data-theme="light"]` 切换。同一时刻只展示一个主题,**禁止 dark/light 并排对比展示**。出处:`design-system/variables.css` 头注。 - **字体只有两类,别引入第三种**:① 正文与**所有数据**(IP / MAC / 序列号 / dBm / 字节数 / 端口)一律用 `--font-family-base`(已区分中英文 `--font-family-en` / `--font-family-zh`);数字需列对齐时加 `font-variant-numeric: tabular-nums`(同字体,对齐数字),**不要引入单独的等宽字体**。② `--font-family-clock`(Digital Numbers 7-段 LED)**仅用于顶栏时钟读数**,且配 `--orange-tz` 琥珀色;**绝不**拿它染 IP / 序列号 / 表格数据。出处:`design-system/variables.css` 字体 token 头注。 - 写任何品牌色 / 视觉 hex 前,先到 `design-system/variables.css` 查真源 token 名,别凭记忆写值。 - **token 按分类分组展示**:`variables.css` 的 token 按语义分类分组（Neutrals / Brand & status / …）、组内有序;引用 / 展示 / 同步 token 时保持这个分类结构,不打散成任意序或字母序,便于理解和查找。出处:仓库 `meta-rules.md` §1「分类型真源 / 派生产物按分类分组展示」子规则。 --- ## 2. 图标（registry 纪律） - **所有图标从 registry 选,用 canonical 名**:``（如 `action/close`、`navigation/arrow-dropdown`）。目录见 `reference/icon-keys-index.md`（约 644 个 / 18 类）→ 对应 `icon-keys-<类>.md`。渲染矢量用 ``（sprite 的 symbol id 与目录名严格一致）。 - **绝不内联 / 手画 SVG**。找不到合适图标时**用占位 + 标注**,交给用户补,不要自己画一个。出处:`reference/07-working-principles.md`、`reference/icon-keys-*.md` 头注。 - **Logo 是 registry 资产,禁止手搓**:品牌标识只用 `brand/logo-tvu`(TVU 品牌主标)与 `brand/logo-ts`(TVU Streaming 产品标),按图标方式 `` 渲染——**直接渲染原 symbol,不要再套圆环 / 底色 / 方块**。**严禁**用"品牌绿方块 + 单字母(`T` / `TS` / `TVU`)"或任何 `div` / CSS / 手画 SVG 拼一个等价 logo(顶栏 leading 位最常踩);找不到对应产品标时用占位 + 标注交用户补,不要凑一个。出处:`reference/icon-keys-brand.md`、`reference/14-email-templates.md` §Header/§Logo、`preview/brand-logo.html`。 - 选图标先按 `icon-keys-*` 的"何时用 / 视觉特征 / 同义词"匹配语义,不要凭名字猜。 - **2.1 图标只用设计库既有资产、按 canonical 键名引用（禁造键名）**。图标必须取自 TVU UX Design System 库中**真实存在**的 icon，并用库的 canonical 键名——库按制播功能语义命名(如 `icon/Video/*`、`icon/audio/*`、`icon/indicator/*`、`icon/Menu/*`,约 644 个 / 18 类,以 `reference/icon-keys-index.md` 为准)。**禁止**:① 生成库外 sprite 键名(如 `media/score`、`media/audio`——库无 `media/` 前缀,那是另一套命名);② 用"内容题材词"当键名去猜(如 `gaming`/`sports`/`music`)。**注意——真瓶颈是命名映射,不是"库无题材图标"**(2026-07-01 初判"TVU 库无内容题材图标"已被证伪并纠正):这些题材图标**大多在库里,只是按功能命名**——体育=`icon/Video/Score`、音乐=`icon/audio/audio`、游戏=`icon/Video/Clip player`、新闻=`icon/Video/Live caption`、电竞=`icon/Video/Program`、户外=`icon/RC/location`…。**正解**:选图标时用**功能语义**匹配库目录(score/audio/clip-player/encoder/chat/location/program),别用题材词或 `media/*` 键名硬猜;根治需一张权威「题材键名↔库 canonical 名」映射表(Code Connect 的本职,TVU 现为 Professional plan、publish 401 用不了 → 暂靠功能语义 search 曲线救国)。库里确无对应图标时**显式标注缺口**(同上条占位规则),**不得静默引用外部 sprite / 编造键名**。依据:2026-07-01 设计流程还原 Live·Discover 实测 + 用户走查纠正。 - **↔ 图表色板 = 代码侧真源(已定,非缺口)**:`--chart-color-1..12` 是代码 token,Figma 库只有 1..4(别名 brand/red/blue/orange)有对应变量,5..12 是 HSL 派生的图表专用色(裸 hex)、**Figma 不建变量**。这**不是"库缺口"而是明确的真源方向划分**:图表/数据可视化色板真源在代码 `variables.css`(图表由 ECharts 运行时渲染、不进 Figma 像素模型),其余 token 真源在 Figma。详见 `meta-rules.md` §2「真源方向按 token 类别划分」。生成端应知悉:引用 `--chart-color-5..12` 时下游装配**无 Figma 变量可绑属正常**,按 `variables.css` 值上色并标注 token 名即可,不必等 Figma 建变量、也不判为漏绑。 - **↔ 装配端镜像**:本条约束**生成端**(只用库既有资产 / 不造键名);装配端(Figma `search_design_system` / swap)另有对应硬规则 `mockup-conventions.md` §M32.3——**只锁唯一权威库 `TVU UX Design System`**(search 必带 `includeLibraryKeys`)、库内找不到就报缺**不 fallback 到其它库**(如旧 `TVU UX Library`)。两端呼应:生成端不造库外资产,装配端不取库外资产。同一还原实测,IRL 位置图标即因装配没锁库、误取旧库 `icon/RC/location 1`。 - **2.2 导出 standalone HTML 时图标 / 背景装饰必须栅格化或内联**。导出独立 HTML 时,所有图标 / 背景装饰图必须**栅格化或内联**(inline `` path,或 base64 data-URI),**禁止**运行时 `fetch('assets/icons/sprite.svg')` 这类外部引用——该 sprite 不随 HTML 一起导出,下游 AI(`use_figma` / html.to.design 插件)拿不到图形,会导致图标全丢。目的:让下游能直接从导出的 HTML 提取图形还原。注:本条只约束**导出产物**;在系统内正常预览渲染仍走 sprite ``(见本节第 1 条),两者不冲突。依据:2026-07-01 设计流程还原实测——HTML 图标全是外部 sprite 引用、sprite 未导出→下游图标全丢。 --- ## 3. 组件（用库,不自搓） - **用 canonical 组件,不要手搓等价物**。系统有约 34 个 canonical 组件,每个的 props / 何时用 / "不要手搓什么"见 `reference/02-component-affordances.md` 的 `do_not_hand_compose` 字段。 - 代码场景:组件从 npm 包 canonical 入口导入(不是 base/components 实现层)。出处:`reference/02-component-affordances.md`。 - 组合规则(FormItem 包 Input、Table 包 Pagination 等)、状态完备性(hover/disabled/error/empty 都要给)见 `reference/04-design-process.md`。 - **品牌 logo 不算"组件场景"可自由发挥的部分**:任何顶栏 / header / splash 的 leading 标识一律用 registry 的 `brand/logo-tvu` / `brand/logo-ts`(见 §2 Logo 条),`TopBar` 的 `logo` prop 也必须传真实标识——绝不手搓等价物。 - **登录后顶栏必带 UserMenu(M 级硬规则)**:`tag="After Login"` 的 `TopBar`,右侧 `rightContent` 一律放 **`UserMenu`**——实心色头像(默认取 `name` 缩写 + 白字,如 Tim Wong → TW;也可传 `image` 用照片、`color` 改底色),点击在下方展开:账号头(名 + `role` 徽章 + 邮箱) + 自定义操作项(纯文字,如 Purchase Tokens / Manage Subscription Seats) + **行内语言切换** + **退出**。绝不用 `Button`/`div`+CSS 自画头像圆圈或自搓账号弹层。 - **"支持双语" = 语言切换,不是并排双语**:`UserMenu` 内一行 "Language … EN / 中文" 行内切换(选中品牌绿、其余 tips 灰),切换后整个应用以单一语言重渲染;**绝不同时并排显示两种语言文本**(与 §1 "禁止 dark/light 并排"同理)。语言切换入口只在 `UserMenu` 里,走 `languages`/`lang`/`onLanguageChange`。 - **增加 Menu 默认用 `MenuList`**:任何一组菜单项(顶栏导航 / 下拉 / 弹出 / 右键菜单)都用 **`MenuList`** 的规范样式——`TopBar` 的 menu slot 用 `orientation="horizontal"`(激活项品牌色下划线),下拉 / 弹层面板体用默认纵向(激活项品牌色 + 末尾 `action/selected` 勾选);`UserMenu` 面板体就是它。绝不用 ``/`
  • `+flex 手拼导航,也别为下拉另写一套行样式。 - **对话框/确认/提示用 `Notification form="dialog"`,不用 PopupBox 塞自定义页**:确认、提示、成功/失败反馈这类对话框,一律用 `Notification` 的 `form="dialog"`(标准化结构:类型图标 + 标题 + 描述 + 操作按钮,`type` 走 success/danger/error/info/warning)。**`PopupBox` 仅用于需遮罩(backdrop)的大型自定义内容模态**——表单 / 设置 / 向导等 `Notification` dialog 的固定结构装不下的场景。绝不在 `PopupBox` 里手搓一个"确认发布"这类本该由 `Notification form="dialog"` 承担的对话框(那就是"自创页面",违规)。两者边界:`Notification form="dialog"` = 内联标准对话框卡(无全屏遮罩);`PopupBox` = 全屏遮罩模态壳(`` + backdrop + title/footer + 任意 slot 内容)。选错的典型症状:一个只是"确认某操作"的弹窗却用了 PopupBox + 手写正文。 --- ## 4. 交付规范（做 mockup / 设计稿时） - mockup 硬规则(交付说明卡样式 M23、库优先 M32、字段三状态 M43、状态枚举等)全集在 `reference/03-mockup-conventions.md`;做交付物前通读。 - 业务领域规则(直播设备 / SaaS 视频流的术语、约束)见 `reference/05-domain-tvu.md`。 - 8 步交付流程 + 状态完备性枚举见 `reference/04-design-process.md`。 --- ## 5. 通用设计质量（⚠️ 非 TVU 仓库真源 — 通用补充,可按需删改） > 下面这节**不在 TVU 设计系统仓库的真源里**,是通用前端 / 视觉质量经验。保留是因为它对"生成不像 AI 套版的设计"有用,但它**不是 TVU 强制规则**——与上面 0-4 节冲突时,以 0-4 节(有真源)为准。 - 避免 "AI slop" 观感:无意义的渐变铺底、外发光 / 阴影堆叠、彩色左边框 callout 卡片、emoji 当图标。 - 留白与对齐优先于装饰;层级靠 typography scale + Layer 背景区分,不靠描边和阴影。 - 与上面 token / 组件 / 图标规则一致即可,不要为"更好看"引入系统外的视觉元素。 --- ## 来源与刷新 本文件由 TVU 设计系统仓库维护(`docs/CLAUDE_DESIGN_RULES.md`),随 `pnpm export:claude-design-bundle` 打进包。 仓库规则演化后重新导出 + 重新提供给 Claude Design。版本对照见包内 `MANIFEST.json` 的 `gitCommit`。