跳至内容
Web UI 样式参考

Web UI 样式参考

版本依据: DSH 0.2.1-rc.5 · 核对日期: · 官方来源。 DSH 仍处于公开预览阶段,升级后请重新核对版本敏感步骤。

本参考面向 DSH Web GUI 组件开发者,说明主题、组件和页面各自控制什么。样式约定固定于页首版本;适用于 Harness 浏览器客户端,不是 dshx.dev 文档站的样式配置。

先确定修改归属

  • ui-theme 拥有 --dsw-* 静态色阶、语义别名、字体、动效、阴影、滚动条及主题偏好。全局样式放在 ui-theme/src/styles/,不要在功能包重建另一套主题。
  • ui-layout 的 ThemePresenter 将已解析快照投射到文档:html 的 color-scheme、body 的 data-ds-dark-theme、主题 tokens、文字 / 代码 / 终端字号与字体,以及 theme-color 元数据。
  • 功能包复用 ui-primitives 控件目录,再用相邻 CSS Modules 和 clsx 组合状态。跨功能包有意的视觉差异放进共享控件的 prop,避免复制第二套按钮或菜单。
  • 组件可用局部自定义属性表达自身尺寸或呈现约定;共享色彩、字体、层级与动效仍由主题包负责。React 内联样式只传局部变量,不编码明暗主题分支。

主题设置保存到 Host 的 ui-theme namespace,本地 provider 默认写入 $DSH_HOME/cordis.patch.yml。选择 system 时由主题运行时解析 prefers-color-scheme,组件只消费结果。不要靠 feature CSS 手动改 body 属性来替代设置;首屏也由 Host bootstrap 应用保存值,避免先闪默认主题。

组件规则

使用语义别名,不在功能组件写颜色字面量、复制静态色板或加主题选择器。字体大小与行高配对;有匹配角色时用主题排版变量。保留列结构的源码、终端和 diff 不强行折行,使用共享滚动条。不要新增组件库或 Tailwind。

圆角和设置卡片

共享档位为 R4 / R8 / R12 / R16 / R20 / R28,对应 radius-xs / sm / md / lg / xl / panel。按控件用途选档,普通组件不要另造 10 / 14 / 18 / 24px 档位;已有精确例外按所属包保留。设置卡片通常用 R20,外层面板 / 对话框用 R28,代码块 / diff / 预览卡片用 R16,具体映射见圆角规范。

支持 corner-shape 的引擎由主题统一应用 superellipse(1.5),不支持时保留普通圆角。50%、100% 或 pill 半径必须在同一规则配 corner-shape: round;头像容器和 img 都要保持圆形。hover / selected / focus 不改变轮廓。贴边子区域由外壳裁切或继承外露圆角,独立内卡按用途选档,不机械减去全部 padding。

阴影、细线与菜单

悬浮面、菜单、弹层、面板和浮动按钮用 border: 0,再按用途选 --dsw-elevation-panel、--dsw-elevation-prominent;输入区用 --dsw-elevation-soft。第一层阴影已包含 0.5px hairline,不叠加中性 alias-border 边框;警告等状态色边框仍是真实边框。平面中性边框与分隔线用 0.5px,虚线和状态色保留 1px,spinner 轨道按精确例外。

下拉、右键、子菜单和选择菜单复用 Menu,或用 MenuSurface 包装自定义内容。菜单材质由 --dsw-menu-surface-fill 与 --dsw-menu-backdrop-filter 提供,功能和平台 CSS 不覆写;schedule 的 TaskMenu / ClockPicker 是已有明确例外。模态遮罩保持半透明暗色,--dsw-mask-blur 为 none,不模糊背后的整页。

背景滤镜放在独立层,不能破坏嵌套菜单和 fixed overlay 定位。macOS 的 MenuSurface 在菜单范围内增加不透明 backing,卸载时清理;没有 backing 的 overlay 消费主题的 --dsw-specific-menu(macOS 为 94% 不透明),不要在功能包复制或覆盖其值。

链接、焦点与动效

产出物链接、文件提及、Web 来源、生成文件和 workflow 成员链接使用 --dsw-alias-link、font-weight 500;静止无下划线,hover / focus 用偏移 3px 的点线下划线。紧凑 Thinking Markdown 保留三级文字色和静止点线。文字前导链接复用 LinkIconMedium 类别图标;workflow 成员和纯图片链接不加该图标,工具行文件链接保留既有灰色点线。

控件增加动效或仅 hover 可见操作时,同时检查键盘 focus-visible 和 prefers-reduced-motion;不要通过移除 outline 或只靠颜色表达选中来隐藏交互状态。

一次样式修改如何落地

  1. 先找所属组件及 ui-primitives 中是否已有控件。局部布局改组件旁的 .module.css;共享 token 改主题所属样式表及文档,消费端只引用别名。
  2. 在真实组合中检查 light / dark / system,文本 / 代码 / 终端字号、字体回退,以及窄屏长内容。菜单还要检查子菜单、滚动容器和 fixed 定位;圆角要检查内外 hover 是否留下缝隙。
  3. 执行所属包相关测试。主题有 corner-shape-styles、elevation-styles、menu-surfaces 等源码规则测试;它们不能代替实际浏览。影响可见行为时按测试策略跑 pnpm run test:web,逐个查看差异,不靠全量刷新期望图掩盖回归。
  4. 修改后失效时,检查 token 声明 / 导入顺序、主题快照与 DOM 写入,再检查组件层叠。回退所属修改并复验;不要靠 !important、复制全局主题或改另一包来压住错误。

常见故障

症状先检查
light 正常、dark 不正常组件是否写了色值或主题分支;别名是否在主题所有方同时解析
设置已改,首屏仍闪默认值Host bootstrap 的保存值、主题加载顺序和 ThemePresenter;不要只改后加载的 CSS
悬浮面有双边框是否把中性 border 与 elevation 阴影叠加;先确认状态色是否属于例外
子菜单偏移或被截断背景滤镜层、portal / 裁切父级与 MenuSurface backing,而不是任意加 z-index
圆头像变方或 hover 轮廓不齐容器和图片的 corner-shape: round、等宽高,以及裁切 / 继承边界
鼠标正常、键盘无法定位focus-visible、hover-only 控件可达性及 reduced-motion 行为

来源与相关阅读

本文据固定版本的 样式参考 整理,遵循 MIT 许可;已归档样式笔记 只解释历史框架依据,其中旧 --bg-* / global.css 清单已被替代,不能当作本版本 token 表。