Henji-AI 界面表面与层级规范

为什么需要这份规范

项目已将控件与表面收口到共享组件。过去出现过卡片套卡片、条带叠条带和默认控件过重；当前默认按钮静默，UiGroup 提供只分组不画框的入口。本规范约束骨架、语义与复用，防止这些问题再次出现。

参考文档（按需读，不要一次全读）

本文件只放每次改 UI 都要用的骨架规则。细分主题拆在 references/：

三条铁律（先记住这三句）

纵深：同一层视觉深度，只画一次边框/背景。 进入一个已经有边框或背景的容器后，内部分组必须改用留白 / 分隔线 / 更暗的底色，不得再叠一层 border + bg + rounded。

水平：一个视图只画一条命令带。 返回、标题、文件上下文、工具、导出动作全部进这一条；随工具变化的参数用紧贴其下的从属带，且与命令带共用同一块底色和同一条下边框。

内容：正式界面只展示用户需要据此行动、决策、理解结果或恢复失败的信息。 revision、schema/协议版本、请求 ID、哈希、缓存/Worker/渲染管线状态、调试计数等内部状态一律进入日志、诊断页或开发模式；不得通过改名、加 tooltip 或补充解释继续留在正式界面。

参考 Atlassian 的表述：能用边框或留白区分时，就不要用抬升（卡片）来分组。成熟设计系统普遍只保留 4~6 个层级并刻意克制。水平方向同理——桌面编辑器（VS Code、Figma、Photoshop）顶部一律是一条命令带加一条可选的上下文带，不会因为壳换了一层就多长一条。

“石墨”设计系统速览（界面重设计计划，重要记录 001–004、010、011）

设计稿与决策在 docs/task/界面重设计与主题引擎/（设计稿/*.dc.html 是本地源码副本，重要记录.md 是决策）。 核心一句话：背景只表达“这里是唯一主动作”或“这项被选中”；层次靠明暗不靠描边；强调色只给主动作、焦点、播放头与选中指示。

这些约束大多已进门禁：check:colors（调色板/黑白/rgba/命名色/旧别名/未定义颜色类）、check:surface:strict（规则 A–E 与 S1–S5/S7–S9，E = 调用点覆盖组件外观）、check:icons:strict（规则 A–D、同行静态 S6）、check:ui-residue（任意值类与内联尺寸口径、私有样式、零引用、旧文案）、check:ui-design（间距/动效/死令牌）、ESLint 令牌规则；对比度、条带数、折行、截断、选中态差异、浮层裁切由 check:ui-visual 在真实 DOM 上判。

五级容器词汇表（先背这张表）

写任何界面前，先确定"我在第几级"，然后只用那一级允许的东西。 从 Region 往下选，能停在哪级就停在哪级——不要一上来就用 Card。

<UiPanel>                  {/* 5 卡片：border + bg-panel + shadow-panel + rounded-xl */}
<UiPanel variant="glass">  {/* 5 玻璃浮层：只压在图片、视频、画布上 */}
<UiPanel variant="inset">  {/* 4 内嵌：仅 bg-window/40 + rounded-lg，无边框无阴影 */}
<UiPanel variant="bare">   {/* 4 纯容器：只有圆角 */}
<UiGroup title="基础设置">  {/* 2 分组：零装饰，标题 + 间距；窄停靠面板用 titleTone="compact" */}
<UiGroup divided>          {/* 3 分隔：上方一条线 */}

方向铁律：内层背景只能比外层更暗，不能更亮。 比父级亮 = 视觉上"浮起来" = 卡片。 表面令牌由主题引擎按“窗口 ± n 级”推导，深色下逐级变亮：bg-gap < bg-window < bg-panel < bg-raised < bg-hover < bg-selected （浅色模式按同一规则反向：面板比窗口亮，raised/hover/selected 逐级加深）。bg-control* 只给控件本身，bg-media 是不随主题的媒体底。 判断“比父级亮”时看的是层级而不是像素明暗：在面板里铺 raised 就是抬了一级。 在 bg-panel 的弹窗里用 bg-raised 做分区，就是在造卡片。

卡片准入条件（四条全中才允许）

1. 有独立交互或独立状态
2. 可被单独移动 / 关闭 / 拖拽
3. 与兄弟元素是并列实体（列表项、画布节点）
4. 脱离页面上下文仍能被理解

卡片嵌套上限：1 层。 卡片内部一律用 Group / Surface。

决策树：这个容器要不要边框背景？

我正在写的这个 div，它的父级链上已经有 border 或 表面 bg 了吗？
├─ 没有（我就是最外层浮层/弹窗/侧栏/画布节点）
│    → <UiPanel>。不要手写 border + bg-panel + rounded。
│
└─ 有（我在某个 panel 内部）
     ├─ 只是想把几个字段归成一组   → <UiGroup title="…">   ← 默认走这条
     ├─ 需要明确切分               → <UiGroup divided>
     ├─ 要让这块"沉下去"（代码块/只读预览/列表项）→ <UiPanel variant="inset">
     └─ 想不出理由，只是"看着空"    → 什么都不加。留白就是设计。

"想不出理由就不加" 是本规范最重要的执行细节 —— 绝大多数丑陋的套娃，都来自"这里看着空，加个卡片吧"。

页面骨架：横向条带（做整页/工具页之前先看这节）

上面几节全部在管纵深。这一节管水平：从窗口顶到内容区之间，横着切了几刀。

组件级审查（每个按钮用没用对 primitive）发现不了这类问题——每一条带单独看都合规，丑的是它们摞在一起。所以看整页时的第一个动作是数条带，不是看按钮。

三类条带与数量上限

连续操作条带上限 = 2（A + B）。 出现第三条就是骨架错了，不是间距问题。

决策树：这东西要不要新开一条带？

我要往页面顶部加一个东西，它是什么？
├─ 返回 / 标题 / 文件名 / 主动作 / 工具        → 进现有命令带（没有就建**一条**）
├─ 只随当前工具变化的参数                      → 从属带，紧贴命令带，不另画底色与边框
├─ 只读状态、进度、计数                        → 命令带右端 `ml-auto`，或页面底部状态带
└─ "它跟上面那些不是一类，单独放一行吧"        → 停。先问它是不是上面三类之一，
                                                 99% 的情况是，只是懒得往已有带里塞。

外层壳已有命令带时：注入，不要再嵌一层壳

功能组件被塞进一个已经有命令带的外壳里时，不能自己再长一条头带。正确做法是把内容作为 props 注入外层那一条带——项目里已经有这个出口，ImageEditor 的 toolbarActions 就是（复制 / 加入资产库 / 另存为三个按钮就是这么进到工具带右端的）。

// ❌ 外壳已经有一条命令带了，功能组件又开一条自己的行
<div className="p-4">
  <div className="flex items-center gap-2">   {/* 第二条带：只为了放一个按钮 */}
    <UiButton>打开图片</UiButton>
    <span>{fileName}</span>
  </div>
  <Editor />
</div>

// ✅ 注入到已有的那条命令带里
<Editor
  toolbarLeading={<><UiButton>打开图片</UiButton><span>{fileName}</span></>}
  toolbarActions={<UiButton variant="primary">另存为…</UiButton>}
/>

返回入口的三种形态（不要为返回单开一条带）

返回按钮的位置由这个页面长什么样决定，不由"哪个文件画的"决定：

禁止为"返回 + 页面名"单画一条 h-10 横带。 它会和应用标题栏叠成"双标题栏"， 而且页面名通常和下面的页面标题重复一遍。

实测踩过：ToolboxWorkspace 曾统一画一条「← 工具名」带，于是 3D 镜头参考列表页 纵向出现两遍"3D 镜头参考"；为了让编辑器形态只剩一条带，又加了 ownsCommandBar 与 view !== 'editor' 两个开关逐个工具关掉。判据换成"页面有没有标题/有没有命令带" 之后，那两个开关连同整条带一起删掉了。

同一批返回入口当时长成四种样子：外层条带图标、工具自绘条带图标、命令带左端图标、 画布上的玻璃文字按钮，以及资产库放在标题右侧动作区的文字按钮。用户在应用里 换一个页面就要重新找返回在哪——这是"每处各自决定"的必然结果，不是审美问题。

实测：同一个工具箱里，好例子和坏例子并存

更值得注意的是：ToolboxWorkspace 里曾有个 showToolHeader 开关，专门为 3D 镜头参考关掉外层标题带，好让它只剩一条。也就是说这个问题早就被撞见过，但当时是给单个工具开特例躲过去的，没有沉淀成规则——于是下一个工具（图片编辑）原样又撞了一次。现在外层标题带整条删除，那个开关也不复存在。

结论：特例是规则缺失的信号。 再看到"为某个页面单独关掉某段骨架"的开关时，先问它是不是该反过来变成默认。

横向 padding 必须对齐

图片编辑那 4 条带的横向 padding 分别是 px-2 / p-4 / px-3，于是返回箭头、"打开图片"、工具组的左端落在三个不同位置。同一视图内所有条带与其下的内容区用同一个横向 padding，改一处就该一起改。

全屏工作面不套卡片

画布、编辑区、预览区这类铺满剩余空间的工作面不是卡片——对照「卡片准入条件」四条：不能单独移动、不是并列实体、脱离上下文无意义，一条都不中。

// ❌ MarkCanvas 当时：工作面自带卡片外观，外层再给 p-4 空白，于是整个编辑器浮成一张卡
<div className="rounded-xl border border-line bg-gap/85">

// ✅ 铺满，边界由它和命令带之间的那条下边框表达；放图片/视频的视口用 bg-media（不随主题），其余用 bg-gap
<div className="bg-gap">

判据：这块区域会不会随窗口一起长大？ 会，就不是卡片。要给它一个更暗的底以便和 chrome 区分是可以的，但不要 rounded + border + 外层留白三件套——那三样凑齐就是卡片。

动作层级：视觉重量 = 动作的重要性

上面几节管容器和骨架，这一节管按钮本身该有多重。

主流设计系统都是同一个阶梯（Material 的 filled/outlined/text、Apple 的 prominent/bordered/plain、Fluent 的 primary/default/subtle）。本项目（重要记录 003，任务 2.1）：

尺寸：UiButton size sm/md/lg = 28/32/36（默认 md）；UiIconButton size 2xs/xs/sm/md/lg = 20/24/28/32/36（默认 md）， xl 40 只给全屏查看器、画面中央播放键。开关开启用 UiIconButton on（淡强调底 + 强调色图标）。 外观只由 variant / size / tone / on / shape 决定，className 只放布局；调用点改底色、边框、文字色、圆角、 阴影、高度或字号会被 check:surface 规则 E 拦截（确属非按钮外观的命中区，如拖动柄、时间轴记号，行级 ui-surface-allow 写明理由与接手任务）。

默认静默：不传 variant 就是 quiet，不传 tone 就是静默图标按钮——这是绝大多数按钮该有的样子。 需要“看得见”的只有三种：唯一主动作（primary / tone="accent"）、弹窗与表单里的普通动作（secondary）、 确认弹窗的破坏性确认（dangerSolid）。旧档位 ghost / muted / plain / glass、旧参数 appearance / showBorder / hoverVariant 已删除且不留兼容层（重要记录 011），不要再引入同义档位；确需新形态时给组件加有限枚举并登记到「必须复用」表。

两条硬规则

1. 一个表面只有一个主动作。 出现第二个实底按钮，用户就不知道该点哪个。
2. 同一组、同一层级的动作必须同档。 不能因为"这里太挤了"把其中一个降档——那是拿视觉语言解决布局问题， 用户读到的信息会变成"这个按钮没那么重要"，而事实不是。

实测踩过：图片编辑命令带右侧的「打开」和「复制 / 加入资产库」同属文件类次级动作， 为了给工具组腾 44px 宽度被降成了无边框图标，一眼就看出不对。宽度问题要用缩短文案、 图标化整组、或接受轻微偏移来解决，不能只降其中一个。

动作 ≠ 模式

工具栏里的工具（选择/标注/矩形…）不是按钮，是"我现在处于哪个模式"， 点它改变的是"接下来会发生什么"，不是"立刻发生一件事"。 它属于选中态语言，不属于动作层级：静息不描边，选中用淡强调底（重要记录 012）， 文字工具用 UiChipButton selectionRole="navigation"，图标工具与开关用 UiIconButton on，把实底强调色让给那个唯一的主动作。

同理，参数面板里的"当前值是什么"（形状、比例、档位）是单选， 用 UiOptionButton active（淡强调底 + 强调文字）——详见「选中态词汇表」。

分隔线：分组的第二手段，不是第一手段

分组有三级，按顺序往下选，能停在上一级就别用下一级：

1. 间距（格式塔邻近律）—— 首选，零视觉成本
2. 分隔线 —— 间距不够用或空间紧张时
3. 容器 / 边框 —— 最后手段（回到「五级容器词汇表」）

准入判据（只有一条）

两侧的交互语义根本不同，用户不会把它们当成一串连续操作。

数量上限

一条 bar 上最多一条分隔线。 第二条会把它切成三段，而右端的主动作实底本身 已经是"终点"标志，再加竖线的信息增量接近零。

选项集合的静息态：不描边

上面的决策树管容器，这一节管容器里那一堆并列的可点项（菜单项、模型网格、分辨率格子、列表行）。

边框表达的是"边界"，不是"可点击"。 一屏里几十个选项各自描边时，边框互相抵消、不再传递任何信息，只剩视觉重量。 可点击性由 hover 反馈 + 排布规律表达，不需要静息态的框。

UiOptionButton 的 variant="menu" 就是这条规则的落点：静息态无边框无底色，hover 出中性悬停底，选中态是淡强调底（selected-accent）+ 主要文字 + 强调色勾。

判据（两条都要满足才用 menu）

1. 是同质选项的集合：≥3 个由 map 渲染的并列 peer，（二选一分段走 UiSegmented，不按 menu 判）。孤立的单个按钮不算 —— 那种情况下框才真的在划定边界。
2. 去掉框之后形状还在。满足任一即可：
   • 已被可见容器圈住（浮层面板、弹窗左栏、下拉列表）——容器已经画过一次边界了
   • 每项自带足以撑出形状的内容（缩略图、图标块、多行文本、比例示意图）
   • 是二维网格 —— 用 variant="grid"：静息铺一层 raised 撑格子，但仍然不描边（底色已经表达过一次边界，边框是多余的第二次）；不要在调用点手写 bg-veil-faint

反例：这些要保留边框

选中态词汇表：先判断语义，再选强度

“选中”不是一种视觉，而是四种不同语义。业务层优先传递 active / checked 与 selectionRole，由 Ui* primitive 消费 styleTokens.ts 中的状态令牌，不要在调用点 复制蓝底、蓝框或强调文字。

默认态不是第五种选中态：它保持当前表面的中性视觉。不要用整行实底表达“已启用”， 也不要把多选语义画成单选项的样子（或反过来）。下拉当前项 = 淡强调底 + 主要文字 + 强调色勾；菜单宽度按选项内容自适应（含勾槽与竖向滚动条，上限 360 再截断；Dropdown 默认 panelWidthStrategy="options"，只有菜单必须与触发器等宽时才传 button）。

同一处的交互层级不得同色：悬停或选中的容器里，行内控件仍须与容器底可区分。字段触发器悬停取 control-hover（不是 hover）；悬停会换底的行容器里放取值触发器时，行悬停只加强描边（画布节点参数行）。选中项上悬停用 selected-accent-hover，不回落中性悬停。

状态与反馈统一入口

页面不要自己写空/加载/错误块（历史上因此出现同一状态在不同页面长得不一样）：

<UiEmpty title="还没有供应商" description="先添加一个吧。" />
<UiLoading message="生成中…"><ProgressBar progress={p} /></UiLoading>
<UiError message={err} onRetry={retry} />            {/* 不传 title 时缺省标题“操作未完成”；有更具体的说法就传 title */}
<UiEmpty size="node" icon={<ImageIcon className="h-7 w-7" />} title="等待结果" />  {/* 画布节点内容区的空占位 */}

状态块不画卡片——它已经在某个容器里了。失败必须一眼可辨：UiError 总有一行危险色标题（任务 5.8）， 标题已经是完整说法时传 title={…} message=""；不是失败的提示（“请先选择片段”）用 UiEmpty，不要借 UiError。

按钮悬停说明统一传 tooltip，内部复用 Tooltip 的 300ms 延迟与主题皮肤，键盘聚焦立即显示。UiIconButton 可用 label / aria-label 命名；无显式名称时回退 tooltip。原生 title 不作悬停说明，只允许不可见的无障碍名称场景。Tooltip asChild 保留触发器 DOM、布局和 ref。状态组件已登记规则 E；S8 阻断手写 spin/pulse 与按钮原生 title，非纯 busy/loading 的禁用缺少 disabledReason 时告警。

信息准入：先判断用户价值，再决定是否显示

界面不是运行状态转储，也不是开发文档。新增任何文字、数字、徽标、提示或状态前，必须确认它至少帮助用户完成一件事：

1. 知道下一步能做什么
2. 在结果、成本、时间或数据影响之间做决定
3. 理解当前进度、结果或产物的用户可感知属性
4. 从失败中恢复

全部不命中时直接删除。“代码里有这个字段”“测试需要观察”“看起来能体现状态”都不是展示理由。 删除后不影响用户完成任务的信息，不得仅换成更口语的名称继续保留。

禁止在正式界面展示：内部 revision、schema/协议/迁移版本、请求/任务/资源 ID、哈希、缓存命中、Worker/GPU/渲染管线、队列与重试代次、调试计数、风险分级，以及用架构术语解释实现的常驻正文。它们进入结构化日志、诊断页、开发模式或自动化测试。

确实影响用户的技术限制必须改写为用户能判断的影响与后果，例如“导出后将失去透明背景”，而不是解释内部降级管线。只有费用、数据丢失、权限、安全、长等待或不可逆操作等高影响信息才默认允许常驻；其余帮助说明仍按 tooltip 规则克制呈现。

已知反例：图片编辑器曾把 document.revision 放进命令带并显示为“版本 X”。这个数字只用于撤销、自动保存和淘汰过期渲染，用户不能选择或管理；正确处理是移除，而不是改名成“编辑次数”。

弹窗宽度按内容选档，不按“看起来大气”

UiModal size 的档位由内容实际需要的宽度决定：先估算最宽一行（标签 + 值 + 行内按钮），选能放下它的最小档。

• 不能为了让一行常驻说明不换行而加宽弹窗——那行说明多半本就不该存在（见上节）。
• 列表很长时靠弹窗内滚动，不靠把弹窗做宽做高。
• 弹窗顶部不放“这个弹窗怎么用”的常驻说明：可操作性由控件本身表达（录入中显示“请按下组合键…”、冲突时显示错误、恢复按钮写明“恢复 PR 默认”）。

实测踩过：剪辑快捷键弹窗用了 editor（最宽约 68rem），顶部还有一行说明键位来源、Esc 用法、作用范围的开发说明；内容实际只需约 26rem。

布局与表单

<UiRegion maxWidthClassName="max-w-3xl">
  <UiPageHeader title="生成历史" description="共 128 条" actions={<UiButton>清空</UiButton>} />
  <UiGroup title="基础设置">
    <UiFormRow label="语言" hint="影响界面与模型提示词">
      <Dropdown … />
    </UiFormRow>
    <UiFormRow label="启用快速下载" inline>
      <UiSwitch … />
    </UiFormRow>
  </UiGroup>
</UiRegion>

分区之间的间距用 UI_SECTION_STACK_CLASS，不要每处自己定 space-y-*。

窄停靠面板（剪辑效果控件、属性栏）里 16/600 的区块标题和 14/500 的行标签都太重：分组用 UiGroup titleTone="compact" （12/600 次要文字、间距收紧），行用 UiFormRow density="compact"（面板由 UiGroup labelWidth={72 | 96 | 120} 统一标签列，标签左对齐、12px 间隔、控件填满余宽）（标签 12 次要文字），两者成对使用，不要在调用点改字号。 UiFormRow 的 hint 只放“不看会选错”的常驻说明，背景知识放 info（标签文字本身悬停触发，见下文 tooltip 规则）。

字段（任务 2.2）：UiInput / UiSelect / UiFieldTrigger（Dropdown、PanelTrigger 的按钮）/ NumberInput 都是 raised 无边框表面、聚焦一圈强调色焦点环，高度只由 size 决定（sm 28 / md 32 默认 / lg 36）。NumberInput 自带数值拖动：在读数或标签上按住左右拖动改值（Shift 精细、Alt 粗调），单击进入编辑，读数不会被步进列裁掉。

字段排布（任务 3.2）：一行参数条（如生成输入区底栏）不要做成“标签在上 + 字段框”的表单。在容器上提供 UiFieldLayoutContext = toolbar：参数标签移到控件左侧（辅助文字 12），Dropdown / PanelTrigger 的触发器自动改静默皮肤，参数开关改胶囊；多行文本、单选卡片、上传类等大块控件仍按表单排布。两者打开的浮层内容一律重置回 form，不要在调用点逐个传 appearance 或手写行内标签。

设置页：新增或调整一项设置时

设置项按用户要做的事归类，不按程序模块归类。大类与分区的唯一清单是 src/core/types/settingsNavigation.ts 的 SETTINGS_TAB_SECTIONS：

新增设置先问"用户会在哪个页面遇到这件事"，放进对应分区；同一件事不得拆在两个大类。 新增分区要同时登记 SETTINGS_TAB_SECTIONS、surfaceCatalog.ts 的 Surface、文案 navSections， 助手可写属性的 target 指向新分区。新增一行设置还要在 src/components/Settings/settingsSearchIndex.ts 登记一条，设置搜索才搜得到。

页内写法统一：

• 单选：≤5 项且每项 ≤4 个汉字（英文 ≤12 字符） → UiSegmented（SettingsSegmented 只是它的重导出）；否则下拉。不要同一页两种写法表达同类选择。
• 从属项：用 SettingsDependentRows，主开关关闭时收起、打开时缩进；不要只加 opacity-50 变灰占位。
• 时长不让用户填毫秒：用带"秒"单位的滑块或"快 / 中 / 慢"。
• 行布局默认 UiFormRow inline（标签左、控件右）；只有路径、长输入框、列表才占整行。
• 分区内的小分组只用 UiGroup titleTone="overline" 一种样式。
• 不放只读状态或"跳到设置里另一处"的按钮；不显示无可操作内容的行（如没有已忽略版本时的"清除"）。

参数说明的受众：description 给助手，tooltip 给用户

本节只约束模型 / schema 参数的 ParamDef、ParamPresentation 等参数元数据， 不影响 UiPageHeader description、UiGroup description 这类明确属于页面内容的组件属性。

说明性文本只要是给用户看的，就必须进入 tooltip。 不要为了“让用户一定看到”把它 摊成控件下方的常驻正文；常驻说明会打断参数网格、扩大单个字段的视觉占位，并让一条局部约束 看起来像整个面板的主要内容。

参数存在 tooltip 时，必须由参数名称文本本身在 hover / focus 时触发：名称需要可聚焦，保证 鼠标与键盘均可访问，但不得在名称旁增加 Info、问号等额外提示图标。参数没有 tooltip 时保持普通、 不可聚焦的标签，不添加空触发器或伪交互。不要把整个输入框、上传区或参数容器包进 Tooltip， 否则移动到控件上会意外弹出，触发范围也会与“名称解释参数”的语义不符。

description 与 tooltip 可以同时存在，因为受众不同：前者可以写得更偏语义和能力边界， 后者应使用用户能直接理解的短文案。界面层不得在 tooltip 缺失时自动回退渲染 description。

界面语法：照着做就不会错（2026-10-12 起强制）

前面几节讲“为什么”，这一节是执行者逐条照做的语法。目标是让对审美没把握的执行者 只要照抄这里的结构就交得出合格界面。每条都来自真实返工：

1. 面板表单行（浮层面板、停靠面板、设置分区一律适用）

• 面板里每一个下拉、数值、滑杆、开关、分段选择都放进 UiFormRow，标签在左、控件在右； 同一个面板只用一种标签列宽（labelWidth 有限枚举），所有控件左缘对齐。
• 禁止：裸 Dropdown / NumberInput / UiRangeInput / UiSegmented 直接堆在 UiGroup 里； 禁止用 Dropdown label= 的行内标签在一行里塞两组“标签+控件”。
• 按钮行（开始、钉住、应用）与控件列左缘对齐，宽度占满控件列或按内容；不从标签列起头。
• 下拉没有可选项时显示占位（“不使用”“暂无标注”）并禁用；有选项但尚未选择时显示“未选择”类占位。任何时候都不出现空白下拉。
• 标签列宽按本面板最长标签取档（labelWidth 枚举里取能放下最长标签的最小档），不让长标签溢出把行挤歪； 控件一律占满控件列（下拉、数值框不按内容收缩）。
• 一个面板里可以有“成对数值网格”（X/Y、宽/高，标签在上），但它和单控件行的标签左缘必须对齐、 控件右缘必须对齐；同一面板不允许出现第三种排法。 返工现场：图片编辑属性面板“变换”是网格、“路径与组合”是 72px 行，“路径组合方式”溢出、下拉不占满、左缘不齐。
• UiGroup labelWidth={72 | 96 | 120} 统一提供面板列宽；内部与嵌套分组中的 UiFormRow 默认标签在左，普通表单上下文保持标签在上（记录 010）。成对网格或多行正文显式 labelColumn="auto"。面板行内的下拉、数值和分段由共享上下文填满控件列。尾部锁定等动作走 trailing；同组无动作的行传 null 保留 28px 尾槽，不手写栅格和 !important。

<UiGroup title="示范" titleTone="compact" labelWidth={96} divided>
  <UiFormRow label="方式" density="compact"><UiSegmented … /></UiFormRow>
  <UiFormRow label="属性" density="compact"><Dropdown … /></UiFormRow>
</UiGroup>

• 参数面板内的样张预览使用有限高度预算（剪辑风格样张图片采用 h-28）；宽面板可紧凑并排，增加宽度不得让样张同比长高、把参数和动作推走。预算只约束显示几何，不限制产品素材或样例数量。

2. 分段选择（2~5 个短选项的单选）

• 一律 UiSegmented（一个整体容器、选项等宽）。选中项用中性抬起底 + 强文字，不用强调色实底： 分段是“当前值”，一页常有多个，强调色实底只留给唯一主动作（记录 017，依据缺陷修复记录 014 修订 012）。禁止把几个 UiOptionButton variant="segment" 并排放在 flex 里冒充分段控件。
• 超过 5 项，或单项超过 4 个汉字（英文超过 12 字符） → 用 Dropdown（全应用统一口径，设置页不例外）。
• 设置页的 SettingsSegmented 是同一语义，必须合并为同一个实现，不得两套并存。

3. 记录列表（历史、任务、批注、版本等同质记录）

• 一律复用 UiRecordList / UiRecordItem；虚拟列表的 itemContent 可以直接返回 UiRecordItem，不另画列表边界。
• density="page" 每侧 20px、panel 每侧 12px、compact 每侧 4px；compact 只用于图片历史等高密度单行记录。不是“上下合计 20px”。块内统一 8px，页面相邻记录累计 40px。
• 插槽顺序为 title（14/500）→ meta（UI_TEXT_META_CLASS，数组自动以 · 分隔）→ children → status → actions。已存在完整领域记录组件或表格列的，放入 children，不拆业务状态。
• 分隔线统一 UI_DIVIDER_CLASS，由 item 根据完整列表 index > 0 画上边线，首条上方、末条下方不画；禁止 first: 判断虚拟窗口首项。测量 ref 指向含留白与边界的根节点。

4. 新元素先找同类结构，复用它

新增一种界面元素前，先问“它和现有哪种东西是同一类”，然后完全复用那一类的结构与交互：

禁止为了“快”把新元素塞进别的元素的空隙（标尺、标题栏、命令带边缘）。

复用同类结构还包括位置与列对齐：新轨道和同类轨道连成一组排布（不隔着空白区）， 头部按钮落在同类按钮的同一列上（同名按钮同列、缺的列留空），外观复用同一组件与 props。 返工现场：C1 字幕轨道第一版钉在标尺下、与 V1 隔着空白，按钮顺序“眼睛、锁”且与 V1 不对齐。

5. 不可用就不出现，出现就说明为什么

• 与当前模式无关的控件隐藏（如“速度”只在“录制轨迹”时出现），不要整排灰着。
• 暂时不可用但用户会找的唯一入口可以禁用，同时用 disabledReason 写清前置条件（“先示范一次运动”）。
• 一个区块里全部控件都不可用时，整块不显示。

6. 交付证据：按风险选择

• 以 docs/rules/testing.md 的 L0–L3 为准。局部样式、文案、事件或无视觉影响的属性，跑专项静态检查与精确测试。
• 共享布局、浮层、滚动、溢出或跨主题外观无法由精确测试证明时，才升级真实 Electron 样张页或受影响宿主；矩阵随实际风险选择。
• 本次运行过截图时，必须逐张目视，记录受影响状态与实际证据。一次 ui:tour --audit 已产出截图、DOM、像素对比度，不叠加同矩阵 check:ui-visual。
• 独占窗口验证受限时写明步骤并标待验证，禁止借用旧图或 DOM 测试冒充视觉通过。

硬性禁止清单

必须复用 vs 允许新增

先查表，再动手。已有实现的一律复用，不要另写一份：

新增组件的门槛（Agent 自行判断，不需要等用户确认；四条都要做到）：

1. 在 @/components/ui 与本表中确认没有可复用或可扩展的组件
2. 优先扩展现有组件的枚举变体（像 UiPanel variant / UiGroup titleTone）；只有当加变体会让现有组件的参数语义变乱（尺寸体系、状态、交互语义明显不同，如标题栏窗口控件）时，才新建一个职责单一的组件
3. 新组件放在 @/components/ui，参数是有限枚举，不开放 className 覆盖视觉，登记进上面的“必须复用”表，并纳入 check:surface 规则 E 的检查范围
4. 选型依据（比较过哪些现有组件/变体、为何新建）写进任务执行记录或提交正文

变体也要克制：新增变体必须是有限枚举，不要开放任意 className 覆盖视觉。

Agent 改 UI 的标准流程

1. 读需求 → 判断落在哪个工作区/页面
2. 整页体检（先横后纵，别直接进组件）：
   a. 数条带：从窗口顶到内容区横着切了几刀？> 2 条就是骨架问题，先合并再谈别的
   b. 顺着 JSX 往上找外层壳：它是不是已经有一条命令带了？有就注入，不要再嵌
   c. 数边框层数、看有没有全屏工作面被套成卡片
   d. 数实底按钮（应恰好 1 个）、看同组动作是否同档、数分隔线（一条 bar 最多 1 条）
   e. 逐项检查可见信息：它是否帮助行动、决策、理解结果或恢复失败？全部不命中就删除
3. 定级：这块内容属于 Region / Group / Divided / Surface / Card 的哪一级
4. 查复用表：需要的组件是否已存在 → 存在就复用
5. 先确认参数文案受众：助手语义写 `description` 但不渲染，用户说明写 `tooltip`；再用排版令牌建立标题/正文/元信息层级
6. 只在四条准入条件全中时才用 Card
7. 写代码：颜色用语义类，字号/圆角/阴影/层级用登记令牌
8. 跑自检清单；高影响 UI 再运行真实 Electron 视觉场景并由 Agent 逐张目视截图（判据与操作规范见 `references/review.md`；悬停、菜单打开、逐个模型等交互态与数据变体用 `ui:tour --steps` 截）
9. 仅命中 AGENTS.md 完成标准的环境维护条件时，检查并维护当前仓库开发实例

第 2 步不能跳。 审查界面时只做组件级检查（每个按钮用没用对 primitive）会漏掉所有骨架问题—— 条带叠条带、工作面套卡片、左边距三个位置，这些单看每一条都合规，丑的是它们摞在一起。 用户说"布局不合理""特别丑"而你只查出了几个 primitive 用错，那基本可以确定第 2 步跳了。

页面完成自检清单

• 按 testing.md 确定证据级别；若本次截了交互态或数据变体，是否按 references/review.md 第 2 节逐项看过吗？
• 从窗口顶到内容区横着切了几刀？ > 2 条（命令带 + 从属带）就是骨架错了
• 每一条新增文字、数字、徽标和状态是否至少服务于行动、决策、理解结果或恢复失败？否则删除
• 系统通知、成功提示与失败兜底是否进入 i18n，并在英文界面检查过？统一 Toast 保留消息键直到显示，不能把固定中文传到通知入口
• 有没有把 revision、schema/协议版本、ID、哈希、缓存/Worker/渲染管线状态或调试计数放进正式界面？全部移到日志、诊断页、开发模式或测试断言
• 有没有用专业术语解释实现，或给本来就能理解的控件添加常驻说明？删除；确有影响时改写为用户可感知的后果
• 外层壳是不是已经有命令带了？有的话内层不能再长一条，改成注入
• 有没有为一个按钮单独占的一整行？塞进命令带
• 返回入口放对形态了吗？有页面标题就进 UiPageHeader onBack，别为「← 页面名」单开一条带
• 各条带与其下内容区的横向 padding 是同一个值吗？
• 画布/编辑区/预览区被套成卡片了吗？会随窗口长大的区域不是卡片
• 这个页面有几层边框叠加？> 2 层就回到决策树
• 有没有"比父级更亮"的背景块？有就该是 inset 或 bare
• 有没有为了填空白而加的卡片/边框/阴影？删掉
• 容器里并列的可点项，静息态还在逐个描边吗？该是 UiOptionButton variant="menu"
• 这个表面有几个实底按钮？超过一个就不知道该点哪个
• 同一组里的同级动作是不是同档？有没有为了省宽度把其中一个降档
• 加分隔线了吗？两侧交互语义真的不同吗？一条 bar 最多一条
• 有手写 <svg> 吗？路径写死的就是图标，改用 lucide；路径算出来的才是图形
• 用到跨界面的业务概念图标了吗？走 @/core/theme/icons 的登记常量，别在调用点自己挑
• 有没有固定调色板、黑白类、rgba、命名色或旧别名类（bg-app、text-text-muted…）？换主题预设时它们不会跟着动，一律改语义令牌
• 用 accent 当文字色了吗？文字用 text-accent-text（UI_COLOR_ACCENT_TEXT_CLASS）；字压在强调实底上用 bg-accent text-on-accent（黑白由引擎按对比度决定）
• 分段是否中性抬起底 + 强文字，其他选中/当前值是否淡强调底且与悬停可辨？强调色实底只属于唯一主动作；悬停/选中的容器里行内控件仍可辨
• 本次涉及跨主题外观且升级截图时，至少看过“石墨”“纸白”吗？浅色模式下黑白类、媒体叠层令牌放错位置最容易露馅
• 破坏性动作（删除/清空）是不是 variant="primary"？那会抢走主动作的视觉权重，应该用 danger（静息中性、hover 才出危险色），确认弹窗里用 dangerSolid
• 改了 .css 文件吗？里面不能有 #hex 与 rgba(数字…)，只能 rgb(var(--xxx-rgb) / a)
• 新加的全局样式/变量放对文件了吗？懒加载的样式表里不能放全局主题变量
• 同一个 className 里有没有两个类抢同一个 CSS 属性？改成互斥三元
• 新面板有没有再叠一层自己的底色？表面应该由外壳统一提供
• 加了模糊吗？只有压在图片/视频/画布上才该加，且只能用 ui-glass / ui-glass-scrim / UiPanel variant="glass" / 浮层 surface="glass"
• 动效时长是否落在 120/180/240/500 四档？（缓动已是全局默认，不用每处写）
• 有 setTimeout 卸载动画组件吗？那个数字必须和 className 里的 duration-* 同档
• 过渡的是 opacity/transform 吗？别过渡宽高间距，也别用裸 transition
• 空/加载/错误三态是否都走了 UiEmpty/UiLoading/UiError
• 模型 / schema 参数的 description 是否没有进入正式界面？给用户看的说明是否全部进入参数名称的 tooltip？
• 有 tooltip 时参数名称是否可 hover / focus，且没有额外 Info 图标？无 tooltip 时是否仍是普通标签？
• 参数 tooltip 是否只由参数名称触发，而不是包住整个控件或上传区？
• 字号是否全部来自登记档位（无 text-[Npx]）
• 圆角是否只用了圆角令牌（rounded-control/field/overlay，或同一组变量的 rounded-md/lg/xl）与 rounded-full，且内层不大于外层
• 阴影是否只出现在浮层
• z-index 是否用了语义 token
• 同级元素间距是否统一（不要一行 mt-2 一行 mt-3）
• 高频状态（进度/hover/拖拽）是否放在独立 store 而非大列表 state
• 列表超过 ~50 项是否考虑了虚拟化
• 只有改动共享页面骨架、设计令牌或全局界面机制时才按 docs/rules/testing.md 运行相关 ui:tour -- --only ...；局部界面改动不默认跑全量场景

完成前按风险选择

npm run check:surface
npm run check:colors
npm run check:icons

只运行与本次改动直接相关的专项检查；验证级别和是否追加 lint、类型检查、构建由 docs/rules/testing.md 决定。 改了本 skill（.claude/skills 与 .codex/skills 任一侧）必须同步另一侧，并跑 npm run check:skill-sync（CI 门禁）。

改了动效档位或 motion.ts 再补一条（它保证 ms 数值与 duration-* 类不漂移）：

npx vitest run src/components/ui/motion.test.ts

公共组件先跑精确测试；主题求解变化才选相关主题测试（包括 themeCombination.test.ts）。只有公共布局、滚动、溢出或跨主题外观风险无法由精确测试证明时，升级 references/review.md 第 8 节的真实样张页或受影响宿主。升级后只运行一次 ui:tour --steps scripts/ui-review/ui-gallery.json --matrix review --audit --no-screenshots（只落盘有问题的截图；需要目视时去掉该参数，每轮抽看约 10 张以内）；矩阵仅在令牌/主题或明确布局矩阵风险时使用，其他情况选一个故障尺寸与受影响预设。

设计系统中心复用开发页 dev.ui_gallery，令牌、组件、模式与规范通过目录与搜索进入；正式构建裁掉入口，助手/MCP 不暴露。新增共享组件同时补真实样本与本复用表，覆盖由 uiGalleryCoverage.test.ts 保护。Windows 像素基线只在本机按 testing.md 的固定流程运行，不作为 CI 门禁。

真实 Electron 验证使用正式场景；本次产生的截图必须逐张目视。check:ui-visual 与 ui:tour --audit 共用审计循环并产出截图；同矩阵二选一。禁用控件、aria-hidden 和不可见区域不判；正文 ≥4.5:1，大字、图标与交互图形 ≥3:1。范围填充、边界、手柄分开测量各自邻接背景，现有通用候选收集仅覆盖文字/图标，图形须由对应场景像素断言。合理内容色例外按 review 第7节登记，界面色不达标修令牌。

开发实例维护只在 AGENTS.md 完成标准的触发条件成立时执行；规则、文档与无需真实窗口的局部逻辑任务不启动或重启环境。

条带数量已进自动检查（5.8）

「页面骨架：横向条带」那节的规则曾经全靠人看（4 条带的图片编辑页在 check:surface 与 check:ui-visual 下都是全绿）。 5.8 起 check:ui-visual 的 stackedBands 在真实 DOM 里数条带：不在滚动区里、几乎占满父容器宽、自己画了分隔线或底色 （或是命令带 / 从属带 / 工具条 / 页头）的 24–64 高块上下相接超过 2 条即命中；同批还有工具条折行、短文案截断、 选中态与静息态差异不足、浮层被裁切四条，判据与断牙样例见 references/review.md 第 7 节。 新工具页仍统一用 UiToolbar variant="command"，从源头避免条带问题；规则只在场景覆盖到的界面上生效，没有场景的新页面照样要人工数一遍。

代码残留同样进了门禁：npm run check:ui-residue（任意值类、内联尺寸与颜色、调用点覆盖、豁免理由、私有样式、零引用、旧文案）， 口径与登记方式见 references/review.md 第 3 节。

check:surface 默认严格，检查 A–E 与以下 S 规则；仅 S8 的禁用原因与手写 alert 建议为 warning。--report 只用于查看诊断，不冒充门禁通过。

A–E：

• [A] 手写面板表面 → 改用 <UiPanel>
• [B] 同文件多处卡片表面 → 疑似卡片套卡片，内层降级
• [C] 手写弹窗（fixed inset-0 + 黑色遮罩但没用 UiModal/AlertDialog）→ 改用 UiModal
• [D] .css 里手写毛玻璃（backdrop-filter）→ 元素上加 ui-glass
• [E] 按钮、选项、标签、导航、字段触发器的调用点用 className 覆盖外观（底色/边框/文字色/圆角/阴影/高度/字号）→ 用组件枚举

存量已全部清零，check:surface:strict 已接入 build / electron:build 与 CI，违规会直接让构建失败。改完必须跑一次确认通过。

静态语法 S 规则表

surface 规则行内或上一行真实注释可写 ui-surface-allow: S1 具体理由与接手任务（替换为对应编号）；不得文件级放行。S6 只按 icons 的已登记边界判，尺寸 D 不接受注释豁免。G6 是证据选择，没有静态规则能证明目视完成；实际覆盖见 frontend-ui.md 表。

确需例外时在该行上方加注释 ui-surface-allow 并写明理由与接手任务；只允许行级豁免，文件级 ui-surface-allow-file 出现即报违规（否则该文件将来真正的套娃也会被放行）。

全屏沉浸式媒体查看器统一用 UiViewerShell，不套用居中卡片语义的 UiModal。生命周期 hook 在宿主同层调用，淡出后只卸载壳内容，保留视频音量等宿主会话偏好；减少动效沿 useDialogTransition。scope="container" 只用于中心页静态预览，不接管模态、键盘与滚动。

npm run check:surface:report 是告警视图；check:surface 与 check:surface:strict 都是严格门禁，已接入 CI。

相关规范

• 组件复用与原生标签落点、颜色令牌三处入口：见 docs/rules/frontend-ui.md 与 docs/rules/architecture.md
• 画布节点的行组件拼装：见 skill canvas-node-builder
• 提示词编辑器、文件上传控件：必须复用 PromptEditor / FileUploader，不要重写

间距与尺寸复用补充（4.3）

纵横间距统一 UI_SPACING_SCALE 九档。工具条用 UiToolbar.gap，堆叠用 UI_STACK_CLASS；条带用 UI_BAND_HEIGHT_CLASS、UI_BAND_MIN_HEIGHT_CLASS、UI_BAND_PADDING_CLASS，表单行最小高度用 UI_FORM_ROW_MIN_HEIGHT_CLASS。PanelTrigger/Dropdown 用 panelSize 四档，正文高度用 UI_PANEL_BODY_HEIGHT_CLASS；可拖动侧栏共用 core/theme/panelSizes 的 UI_PANEL_WIDTH。UiTextArea/PromptEditor 用 height 三档。UiModal 用 contentPadding 与 contentScroll，不能靠 contentClassName 替换默认留白。完整像素、用途和迁移规则见 references/typography-and-tokens.md；新档必须同时补设计系统中心页真实样本与枚举覆盖。

5.2 自动语法与预算

S1–S5/S7–S9 的判据与正反例见 references/review.md 第 7 节；S6 仍由 check:icons:strict 负责。UiModal、UiToolbar 与工作区根在开发态按最近表面计算可见主动作，超过一个告警并标 data-primary-overflow，不静默改动业务动作。动态/互斥分支最终由 DOM 的 multiplePrimary 检查。

smallTargets 保持普通命中区 24px；唯一新增紧凑例外为正式 UiIconButton size="2xs"（20px），用于密集附属操作，需有 tooltip/可访问名称。只认 button.ui-btn + data-tone + data-size=2xs，低于 20px 仍报错；xs 已为 24px，不豁免。原生步进箭头、行内文本及画布缩放的既有边界不变。