界面组件图鉴 liuke101/dsh-UIUX

UIUX — DeepSeek Harness 界面组件目录

这个目录是对 DeepSeek Harness Web 客户端全部 React UI 组件的调研产物：把每个组件的名称、导出变量名、外观示例与代码来源整理成 HTML 目录，可以直接在浏览器里查阅，同时保留生成它所需的脚本与结构化数据。

产物是静态 HTML，双击即可打开，不需要服务器，也不需要联网。

产出物

| 文件 | 内容 |
| index.html | 总览：调研方法、覆盖统计、组件分层、包分布、复现命令。 |
| primitives.html | 基础组件库 ui-primitives 的图鉴：共享原子的实时重绘、Props 表与设计变量。 |
| product.html | 产品组件图鉴 · 会话流：消息、思考块、工具行、输入编辑器与回合操作。 |
| product-shell.html | 产品组件图鉴 · 外壳与预览：应用框架、侧边栏、文件动作，以及文本 / Office / 图片 / 网页预览与附件。 |
| product-dock.html | 产品组件图鉴 · 停靠与工具：停靠面板与标签页、终端与右侧栏，以及工具调用卡片与渲染绑定。 |
| product-panels.html | 产品组件图鉴 · 面板与浮层：任务计划、目标、交付物、插件市场、日程、工作区，以及对话框与菜单。 |
| product-settings.html | 产品组件图鉴 · 设置与运行视图：设置页骨架与各行控件、账户与引导，以及轨迹、子代理、工作流。 |
| tokens.html | 设计变量参考：--dsw- 静态色板、语义别名、圆角、字体排印、浮层描边与投影，含浅色/深色取值与引用计数。 |
| inventory.html | 全量清单：扫描到的每个组件的导出变量名、源码位置、Props 类型、CSS 类名与设计变量，可过滤。 |
| data/components.json | 组件清单的机器可读版本（抽取脚本的产物）。 |
| data/tokens.json | 设计变量的机器可读版本（含每个变量的声明位置与组件引用）。 |
| data/parts/ | 组件条目（外观示例的 HTML 与元数据），按批次分文件，共 388 条 / 967 个示例。 |
| data/ENTRY-SCHEMA.md | 条目写入规范：字段含义与硬性规则。 |
| assets/ | 嵌入用的中文子集字体（cjk-400.woff2 / cjk-500.woff2，OFL 授权的 Noto Sans SC 子集）。 |
| tools/ | 生成与校验脚本：extract.mjs、extract-tokens.mjs、build.mjs、font.mjs、validate.mjs、check.mjs。 |

外观示例是怎么画出来的

示例不是截图，也不是照着截图重写的近似样式，而是直接加载组件自己的样式表源码渲染出来的：

1. 每个组件的 .module.css 原文被内联进一个声明式 Shadow DOM（），因此组件 CSS 逐字生效，且不会泄漏到目录页自身。
2. 页面的 <body> 内联了 packages/client/ui-theme/src/styles/ 下的真实主题样式表，所以示例消费的是真实的 --dsw- 变量。自定义属性会继承穿过 shadow 边界，点右上角的主题按钮（太阳 / 月亮图标）即可让所有示例在浅色与深色取值之间切换；选择写进 localStorage 的 dsh-uiux-theme，在 <body> 的第一个子节点里读回，因此翻到别的页面仍是同一个主题，也不会先闪一下浅色。组件 CSS 里针对 body[data-ds-dark-theme] 的规则在 shadow root 里改写成 :host(...)，因此切换时预览宿主也会带上同一个属性。
3. 示例里的 HTML 使用组件 .tsx 里实际 clsx 的类名，由抽取到的源码结构决定；构建脚本只做三件机械改写：去掉 :global(...) 包装、把 :root / html / body 选择器改成 :host（shadow root 里没有文档级选择器），以及在组件 CSS 之前插入一条预览重置 button, input, select, textarea { font-family: inherit }——浏览器给表单控件的默认字体不含中文，真实产品靠操作系统字体补上，目录页改用内嵌子集。
4. 需要 JavaScript 才能产生的状态（悬停、展开、打开、焦点）以静态近似呈现：条目自带一小段附加 CSS 复刻真实规则的视觉效果，并在示例标题旁标注。

依赖布局父级的组件（侧边栏、设置页、面板）在示例里补一层只声明 width / display 的无类名容器。示例框 .stage 自身是 position: relative 加 isolation: isolate：组件里 inset: 0 的绝对定位层（例如 MenuSurface 的 .material）本由调用方提供的定位父级兜住，少了这一层就会以初始包含块为参照铺满整个视口——而铺满视口的 backdrop-filter 会让 Chromium 干脆不画这一页。同样地，条目里的静态快照把浮层拉回文档流时要用 position: relative 加 inset: auto，不要用 position: static：relative 既回到文档流，又留住子层需要的包含块。

覆盖范围

清单页收录 packages/client/、packages/experimental/、packages/extensions/ 下全部 .tsx 里的每个 React 组件导出，共 601 个；其中 388 个有图鉴条目、967 个实时重绘示例：

- 产品层全覆盖：313 个 product 组件、18 个实验包组件、5 个扩展包组件，每个导出都有独立条目（含 experimental/ 的语音输入、会话检查器，extensions/ui-cordis 的插件面板）。
- 基础组件库：ui-primitives 的可视导出全部有条目，另有 tokens 页逐个列出它消费的 --dsw- 变量。
- 图标与美术按族合并：199 个图标与 10 个品牌美术合并成若干族条目（例如 8 个权限图标一条、5 个插件美术一条），字形在一个示例里并排渲染、逐个标注。

产品组件因为示例逐条内联样式表源码，单页会到十几兆，所以按区域拆成五页（会话流 / 外壳与预览 / 停靠与工具 / 面板与浮层 / 设置与运行视图）；左侧目录的「产品组件」分支下就是这五页。

判定规则：primitive 为 ui-primitives 的共享原子；icon、artwork 为字形与品牌美术；product 为功能包组件；experimental、extension 为实验包与扩展包。packages/client/AGENTS.md 规定功能包之间不能互相导入组件，ui-primitives 是唯一可以跨包复用的组件来源——图鉴因此把基础组件库与产品组件分开成两组页面。

重新生成

cd <本目录>
node tools/extract.mjs # 扫描 .tsx → data/components.json
node tools/extract-tokens.mjs # 解析 ui-theme 样式表 → data/tokens.json
node tools/build.mjs # 组装九张页面
node tools/check.mjs # 条目校验 + 仓库引用规则 + 页面产物体积

前两个脚本要读 packages/client/ 下的源码，因此必须把本目录放在 deepseek-harness 检出的 UIUX/ 位置再运行；build.mjs 与 check.mjs 只需要本目录自己的数据。发布副本（本仓库根目录，上方没有检出）要加 --root <检出> 才能读到组件样式表，否则条目校验会把每个类名都报成未声明：

node tools/build.mjs --root ~/deepseek-harness
node tools/check.mjs --root ~/deepseek-harness

源码链接默认指向上游仓库（https://github.com/deepseek-ai/deepseek-harness/blob/master/<路径>#L<行号>），这样发布出去的副本点得开；加 --source-base local 则改回相对路径，供在检出内离线查阅。check.mjs 会核对这些链接目标是否都属于当前检出的已跟踪文件——发布副本因此不会带着失效链接出门。

check.mjs 会做三件事：校验每个条目的必填字段、类名归属、设计变量与源码行号；按 scripts/verify-repository-references.ts 的规则确认目录内没有提交号或组织 URL；统计九张页面的体积与预览数量。

页面是中文的，而生成机器上不一定装了中文字体。构建脚本会统计页面用到的全部汉字写入 data/cjk-charset.txt，并在缺少覆盖时提示；此时先跑字体子集再重新构建：

mkdir -p /tmp/dsh-uiux-font && cd /tmp/dsh-uiux-font
npm install --cache ./.npm-cache subset-font
cd - && node <本目录>/tools/font.mjs --tools /tmp/dsh-uiux-font
node <本目录>/tools/build.mjs

subset-font 只是构建期工具，刻意不写进仓库依赖。字体源文件在首次运行时从 notofonts/noto-cjk 下载到 --cache 目录；assets/.woff2 是产物，可以随目录一起提交。

同名类的处理

真实构建会给每个 CSS Module 的类名加哈希，所以 ReasoningRow.module.css 与 DisclosureRow.module.css 里的 .root 是两个互不相干的选择器。目录页把样式表逐字内联进同一个 Shadow DOM，必须自己还原这层隔离：当条目列出两张以上样式表时，构建脚本按文件把类名改写成 c<下标>-<原名>（下标是 css 数组的下标），HTML 里的类名同步改写。

类名归属的判定顺序是「与组件源文件同名的那张样式表」→「css 中第一张声明了该类的表」。当元素属于非主样式表、而类名在主表里也存在时，条目直接写带前缀的类名，构建脚本原样保留；规则见 data/ENTRY-SCHEMA.md 的「多张样式表与同名类」。

发布副本

目录同时发布在 <https://github.com/liuke101/dsh-UIUX>，并开启 GitHub Pages 在线浏览：<https://liuke101.github.io/dsh-UIUX/>。仓库根目录的 .nojekyll 关闭 Jekyll 处理，页面按字节原样提供。每张页面右上角有两个入口：GitHub 小猫图标指向本仓库，太阳 / 月亮图标切换浅色与深色。

左侧目录是一棵站点树：九张页面各带自己的页内小节，当前页的分支高亮，读到哪一节就在树里标出哪一节（滚动时用 scrollIntoView({ block: 'nearest' }) 把它带进侧栏自己的滚动区）。这棵树由 build.mjs 的 SITE 一次算出、原样写进九张页面，所以翻页时侧栏不会变形状，只有高亮的分支在移动。页内小节在所属页面里是纯锚点链接，在别的页面里带上文件名跨页跳转——原来单独一栏「页面内」因此取消。

数据字段

data/components.json 的每条组件记录包含：name（组件名）、exportName（导出变量名）、kind（分层判定）、package、file 与 line（代码来源）、propsType、doc（源码 JSDoc）、cssModule、cssClasses、tokens（该组件 CSS 引用的设计变量）、publicExport（是否在包的 src/index.ts 中公开导出）。

data/parts/.json 的每条记录包含：id、name、exportName、zh、group、summary、source、css、tokens、specimens、props、notes，字段含义见 data/ENTRY-SCHEMA.md。

说明

页面在 内嵌了中文字体子集，因此单个 HTML 文件可以独立分发；代价是每页约 760 KiB 的字体数据（base64），九张页面合计约 22 MiB。清单页与变量页的数据规模较大，用浏览器搜索或页面自带的过滤框定位比滚动更快。

目录数据取自工作区源码快照，页面顶部记录了快照日期；重新生成即可与当前源码对齐。

许可

本仓库的目录页面、生成脚本与结构化数据以 MIT 协议开源，全文见 LICENSE。

Copyright (c) 2026 LiuKe

两处内嵌内容保留各自的上游授权：示例里逐字内联的组件样式表与源码片段来自 DeepSeek Harness（MIT），assets/ 下的中文字体子集来自 Noto Sans SC（SIL Open Font License 1.1）。