--- name: DSH Visual Acceptance description: 继承 DSH 宿主语义、用于声明检查范围并阅读确定性验收证据的紧凑工作台。 colors: brand: "var(--dsw-alias-brand-primary, #3d68d8)" background: "var(--dsw-alias-bg-base, #f7f8fa)" layer: "var(--dsw-alias-bg-layer-1, #ffffff)" layer-2: "var(--dsw-alias-bg-layer-2, #f4f5f7)" border: "var(--dsw-alias-border-l2, rgba(20, 24, 32, 0.14))" border-soft: "var(--dsw-alias-border-l3, rgba(20, 24, 32, 0.09))" text: "var(--dsw-alias-label-primary, #15171a)" text-muted: "var(--dsw-alias-label-secondary, #616771)" text-faint: "var(--dsw-alias-label-tertiary, #8a9099)" text-inverted: "var(--dsw-alias-label-primary-inverted, #ffffff)" success: "var(--dsw-alias-state-success-primary, #17824d)" warning: "var(--dsw-alias-state-warn-primary, #a55d00)" error: "var(--dsw-alias-state-error-primary, #c43b43)" typography: headline: fontFamily: inherit fontSize: 16px fontWeight: 650 lineHeight: 1.35 letterSpacing: "-0.01em" title: fontFamily: inherit fontSize: 15px fontWeight: 650 lineHeight: 1.35 letterSpacing: "-0.01em" body: fontFamily: inherit fontSize: 13px fontWeight: 400 lineHeight: 1.45 label: fontFamily: inherit fontSize: 11px fontWeight: 400 lineHeight: 1.45 section-title: fontFamily: inherit fontSize: 12px fontWeight: 650 lineHeight: 1.35 metric: fontFamily: inherit fontSize: 18px fontWeight: 650 lineHeight: 1.2 rounded: skeleton: 4px icon: 5px control: 6px container: 7px pill: 999px spacing: compact-1: 4px compact-2: 8px control: 9px panel: 16px section: 19px components: button-primary: backgroundColor: "{colors.brand}" textColor: "{colors.text-inverted}" typography: "{typography.body}" rounded: "{rounded.control}" padding: "0 11px" height: 34px button-secondary: backgroundColor: "{colors.layer}" textColor: "{colors.text}" typography: "{typography.body}" rounded: "{rounded.control}" padding: "0 11px" height: 34px field: backgroundColor: "{colors.layer}" textColor: "{colors.text}" typography: "{typography.body}" rounded: "{rounded.control}" padding: "0 9px" height: 34px status-pill: backgroundColor: "{colors.layer}" textColor: "{colors.text-muted}" typography: "{typography.label}" rounded: "{rounded.pill}" padding: "0 8px" height: 24px result-card: backgroundColor: "{colors.layer}" textColor: "{colors.text}" rounded: "{rounded.container}" --- # Design System: DSH Visual Acceptance > English companion: [DESIGN.en.md](DESIGN.en.md). Update both documents when design constraints change. ## Overview **Creative North Star: “安静的验收账本”** 当前 `0.1.2-responsive-acceptance` 源码候选是 DSH 会话内的 Operate 工作台，不是营销页。它在人工闭环上增加覆盖计划、响应式证据总览、基础质量事实、Retest Diff 与受控状态配方。表达必须忠于当前实现，不能暗示参考设计图比较、Provider 推理、自动 Agent 注入或真实项目 Gate 已完成。 视觉系统不建立独立品牌皮肤，而是通过 DSH alias token 继承宿主的深浅色、文字层级与状态色。识别度来自一条贯穿配置区的“对象 → 覆盖 → 证据”验收轨道、严谨的信息分层和对“不确定性”的准确命名，而不是大标题、渐变、插画或装饰性卡片。 **关键特征：** - 宿主优先：DSH alias 是颜色权威，本地值只作为隔离运行时 fallback。 - 左侧声明、右侧核验；桌面并行，窄屏顺序执行。 - 1px 边线与轻微层色承担分组，默认不使用悬浮阴影。 - 数值、状态文案、原始事实与截图共同构成证据，不使用综合评分。 - 当前 UI 只呈现确定性执行底座，候选判断与人工决定不得伪装成已实现能力。 ## Colors 配色安静且语义化：大面积只使用宿主背景和两级 layer，品牌色用于主操作、焦点和运行中状态，警告与错误色只标记对应事实，不负责表达“整体是否通过”。 ### DSH token 映射 | 本地角色 | DSH 权威 token | 隔离 fallback | 使用范围 | |---|---|---|---| | `--va-brand` | `--dsw-alias-brand-primary` | `#3d68d8` | 主按钮、焦点、排队/检查中 | | `--va-bg` | `--dsw-alias-bg-base` | `#f7f8fa` | 工作台结果区底色 | | `--va-layer` | `--dsw-alias-bg-layer-1` | `#fff` | 顶栏、配置区、卡片、控件 | | `--va-layer-2` | `--dsw-alias-bg-layer-2` | `#f4f5f7` | Checkpoint、事实条、骨架屏 | | `--va-border` | `--dsw-alias-border-l2` | `rgba(20,24,32,.14)` | 主分隔与容器边界 | | `--va-border-soft` | `--dsw-alias-border-l3` | `rgba(20,24,32,.09)` | 容器内部层级 | | `--va-text` | `--dsw-alias-label-primary` | `#15171a` | 标题、输入值、关键事实 | | `--va-muted` | `--dsw-alias-label-secondary` | `#616771` | 标签、元数据、说明 | | `--va-faint` | `--dsw-alias-label-tertiary` | `#8a9099` | 次级符号与弱提示 | | `--va-success` | `--dsw-alias-state-success-primary` | `#17824d` | 已预留；当前结果未用绿色宣告“通过” | | `--va-warn` | `--dsw-alias-state-warn-primary` | `#a55d00` | 异常信号数量与详情入口 | | `--va-error` | `--dsw-alias-state-error-primary` | `#c43b43` | Ready 未满足、运行失败、取消、错误信息 | **状态色不越权规则。** 颜色只加强文字已经说明的语义。`warning` 不等于 Issue，`error` 不代表产品整体不合格，`completed` 也不得改成绿色“通过”。 ## Typography **字体：** 完全继承 DSH 宿主字体栈；插件不加载 Web Font，也不建立独立 Display Font。 **性格：** 小字号、短行距、以扫描效率为中心。层级主要依靠字号、字重、留白和边线，而不是全大写、彩色标题或夸张尺度。 ### 层级 - **结果标题**：16px / 650 / `letter-spacing: -.01em`，仅用于选中 Run 名称。 - **工作台标题与空态标题**：15px / 650，用于“视觉验收”和空态结论。 - **正文与控件**：13px / 1.45，继承宿主字体，承载输入、操作和主要内容。 - **区块标题**：12px / 650，用于“验收对象”“状态矩阵”等局部分组。 - **标签与元数据**：11px，用于字段标签、路径、时间、事实条和说明；关键数值使用等宽数字特性 `tabular-nums`。 - **摘要数字**：18px / 650，只显示计数，不制造分数感。 **可读性规则。** 11px 只用于辅助信息，不承载唯一结论；状态必须同时出现可读文字，长路径和 Run ID 允许换行或省略但保留可查看的上下文。 ## Layout ### 当前信息架构 1. **工作台顶栏**：产品名、当前会话工作区、刷新入口和“对象 → 覆盖 → 证据”心智模型。 2. **验收轨道**：按真实任务顺序完成“确定验收对象 → 选择覆盖计划 → 确认验收指令”，Target 默认留空，不再用开发 Fixture 冒充用户应填对象。 3. **自定义页面与状态**：在覆盖步骤中按需进入 1–8 个 Checkpoint，声明路径、状态、视口、主题和 Ready 条件；运行名称下沉至“更多设置”。 4. **历史 Run**：按时间列出已创建的 Run，点击切换当前结果。 5. **当前 Run 结果**：生命周期状态、四项摘要、Checkpoint 事实、Finding Candidate 和截图证据。 6. **问题与决定**：项目级 Issue 以折叠账本呈现；展开后追加 Decision、复制获批修改包，合并/拆分入口继续按需展开。 7. **复验关系**：Retest 完成后在证据前展示候选关系和人工确认操作；新 Candidate 仍须明确立项。 参考设计图比较、Provider 推理、自动 Agent 注入与第二套 Harness UI 不属于当前信息架构；Retest 的像素 Diff 只在原 Matrix 下作为证据。 ### 桌面布局 - 插件根节点高度为 `calc(100dvh - 76px)`，适配 DSH 会话壳层；顶栏最小高度 54px。 - 主体采用两栏 Grid：配置栏 `minmax(310px, 352px)`，结果区占剩余宽度。 - 两栏各自滚动，配置区右侧使用 1px 主边线；结果区水平 padding 为 `clamp(16px, 2.2vw, 28px)`。 - 摘要为四等分单行；结果卡按 10px 间距纵向排列；截图宽度占满卡片并限制为 440px 高，顶部对齐、完整包含。 ### 响应式行为 - **≤900px**：主体改为单列，配置在前、结果在后；根节点和两区改用页面级滚动；摘要变为 2×2；历史 Run 隐藏时间列。创建 Run 后自动滚动到结果区。 - **≤460px**：水平 padding 收紧为 12px；双列字段改为单列；结果头允许换行；头部操作占满宽度；输入、选择、按钮和图标按钮统一到 40px 触控高度。 - 390px 验收截图证明结果区能在 DSH 窄屏壳层中单列展示；这不是原生移动设备适配声明。 ## Elevation & Depth 系统默认平面化，不使用卡片阴影制造层级。深度由宿主 `background / layer / layer-2` 三层色、1px 边线、局部留白和滚动边界表达。截图证据区使用轻微棋盘底纹区分透明或空白区域。 输入聚焦时使用 2px 品牌色混合外环；这是键盘焦点反馈，不是悬浮 elevation。骨架屏的水平渐变仅表达加载，且在 `prefers-reduced-motion: reduce` 下停止动画。 **平面优先规则。** 不给普通 Checkpoint、摘要或结果卡添加投影；只有宿主壳层可以保留其自身 elevation 体系。 ## Shapes 形态克制、接近 DSH 原生控件：图标按钮 5px、输入与普通按钮 6px、卡片与摘要容器 7px、状态胶囊 999px。边框统一为 1px；状态胶囊的小尺寸用于元数据，不应扩展成大面积彩色 Badge 云。 图标使用 16px 左右的圆角描边 SVG（`stroke-width: 1.8`），不依赖图标字体或外部图片。空态图标容器是 42px 圆形，属于当前唯一的装饰性几何，用于建立空态焦点。 ## Components ### 覆盖计划与 Matrix - 配置区使用连续的三步验收轨道；编号表示真实执行顺序，不是装饰性章节编号。 - Target 占位示例直接使用工作区相对 HTML 路径，并同时解释“本机 URL / 工作区 HTML”两种合法输入，避免用户误以为必须自己搭建公网链接。 - 覆盖计划用 2×2 紧凑选择器表达“快速 / 标准 / 页面断点 / 自定义”，不堆叠六个独立设备按钮。 - 快速计划固定为 `390×844 + 1280×800`；标准计划固定为六个布局视口并在手机/桌面增加副主题锚点，共 8 项。 - 页面断点显示读取完整性和不可访问样式表数量；CSS 视口不得命名为具体手机型号。 - 主按钮常驻工作台顶栏，并以“检查 N”复述即将执行的范围；Target 未填写时禁用，避免发起无对象 Run。DSH 输入区遮挡配置区底部时，主操作仍然可见。 - 自定义计划承载页面、空/错误等业务状态；状态复现步骤和运行名称继续按需展开。 - 首次进入自定义模式时使用当前 Quick 组合初始化；往返模式保留用户已编辑的自定义草稿，不静默覆盖。 - 自定义模式在提交前重新汇总 ID、路径、状态、视口和主题；自动 Run 名称追加本地时间，窄屏历史仍可区分多次运行。 - 输入和选择框为 34px 高、9px 水平内边距、6px 圆角；hover 加深边线，focus 使用品牌色边线与 2px 外环。 - 字段标签在控件上方；视口宽高输入使用 `×` 分隔，并分别提供可读的 `aria-label`。 - Checkpoint 是 `layer-2` 背景的 7px 圆角容器；删除操作始终保留文字化无障碍名称，只有一个 Checkpoint 时禁用。 - 添加上限为 8；禁用状态用透明度与 `not-allowed` 光标共同表达。 ### Buttons 与图标操作 - 主按钮用于“开始验收”，品牌底色、反色文字；提交中改为“正在创建…”并禁用重复提交。 - 次按钮为 layer 背景加 1px 边线；危险操作只将文字/图标改为错误色，不使用高饱和整块红底。 - 所有按钮均有 hover、active 和 `focus-visible`；active 仅下移 1px。窄屏触控高度提升至 40px。 ### Run 历史与结果摘要 - 历史 Run 是整行按钮，当前项通过 `aria-current="true"` 与品牌色 7% 混合背景表达。 - 当前 Run 头部显示名称、Run ID、Target 和生命周期胶囊；仅 `queued / running` 显示“取消”。 - 四项摘要固定为“已检查 / Ready 满足 / Ready 未满足 / 异常信号”，不得合并为总分或单一通过率。 ### Checkpoint 结果与证据 - 每个结果卡同时显示 Checkpoint ID、视口、主题、声明状态、Ready 结果和六类确定性事实计数。 - 结果区使用“验收账本”作为内容类型提示；空态以“对象 → 覆盖 → 证据”三段轨迹解释首次价值，不创建脱离真实任务的教程模式。 - 每张截图前显示“浏览器截图证据”，避免图片与上方事实条之间缺少证据归属。 - 有异常信号时显示警告色数量胶囊，并通过原生 `details` 展开原始值；截图使用明确 `alt`，延迟加载。 - 每条确定性信号同时生成可审核 Candidate；只有用户点击“立为 Issue”并补充影响后才进入项目级 Issue。 - 每张截图提供“新增手工 Issue”，用于没有确定性规则的视觉问题；这类 Issue 的 Retest 默认进入 `needs-human-review`。 - 三个及以上 Checkpoint 先显示响应式 Contact Sheet 与跨范围 Candidate 归并；它只用于定位，不合并底层证据或 Issue。 - Retest 显示基线、当前、Diff 三联证据和变化像素/比例；变化仍标记 Candidate，不使用“视觉通过”。 - 基础无障碍信号必须附带“不是完整 WCAG 审计”的说明。 - 受控状态配方折叠在 Checkpoint 内，只允许点击、填写、选择、按键、等待和确认已出现；界面提醒不得录入凭据。 - 加载使用骨架条；无 Run 时使用任务导向空态；API 或会话错误使用 `role="alert"` 的可读错误块。 ### Issue、Decision 与修改包 - “问题与决定”沿用验收账本的边线与折叠层级，不新建页面或弹窗；默认只显示 Issue ID、标题、lifecycle 与最新 Decision。 - Decision 必须填写原因；保存行为追加事件，不覆盖历史。`approved-fix` 只控制修改包资格，不自动改变 lifecycle。 - “复制修改包”仅在 `approved-fix` 后出现；成功文案必须写明“尚未发送给 Agent”。浏览器拒绝剪贴板时保留本地文件路径。 - 合并与拆分归入二级治理区，避免干扰主路径；合并保留来源证据，拆分创建新 Issue。 ### Retest 候选关系 - “按原条件复验”从基线 Run 复制 Target 与 Matrix，Client 不提供编辑入口。 - 关系状态使用完整文字：`新候选 / 仍检出 / 疑似已解决 / 疑似回归 / 无法验证 / 需人工复核`；颜色只辅助扫描。 - `possibly-resolved` 必须显示“确认已解决 / 仍未解决”；`still-detected`、`regressed` 与不确定关联支持人工确认或否决。 - Retest 运行中只显示“等待比较”，不得在关系尚未生成时显示成功或解决。 ### 状态语义：四者不可混淆 | 概念 | 当前 UI 表达 | 它只证明什么 | 绝不代表什么 | |---|---|---|---| | **运行完成** | Run 生命周期胶囊 `completed`，中文“运行完成” | Runner 已结束并产出本次可用结果 | 不代表所有 Ready 满足、不代表零异常、不代表验收通过 | | **Ready 满足** | Checkpoint 的 `reached`，中文“Ready 已满足” | 用户声明的 Selector / Text 已满足；状态声明、页面观测值与复现方式另存为 `reproduction` 证据 | 不代表页面无浏览器异常，也不代表视觉或产品质量合格 | | **异常信号** | `signalCount`、警告胶囊、事实条和可展开原始值 | 浏览器确定性检查观察到 console、请求、HTTP、坏图、字体或溢出信号 | 不等于正式 Issue；同一问题可能产生多个信号，也可能被规则或人工判定无需立项 | | **Issue** | 项目级折叠账本、人工创建、Decision 与 verification 历史 | 用户明确建立并持续跟踪的问题记录 | 不能由信号数量直接替代，不能因 Run 完成或 Candidate 消失而自动关闭 | 允许组合出现：一个 Run 可以“运行完成”，所有 Checkpoint 都“Ready 满足”，同时仍有多个 Candidate 和未解决 Issue。只有人工确认后，Issue 才能写为 `resolved`。 ### 可访问性 - 键盘焦点使用 2px `focus-visible` 轮廓；图标按钮都有 `aria-label`，纯装饰 SVG 为 `aria-hidden`。 - 结果主区通过 `aria-busy` 暴露加载/运行状态；隐藏的 `aria-live="polite"` 区域播报错误、生命周期、已检查数和信号数。 - 错误使用 `role="alert"`；历史当前项使用 `aria-current`；状态同时使用图标、文字和颜色。 - `prefers-reduced-motion` 下关闭旋转和 shimmer；窄屏主要控件达到 40px 高。 - 当前实现只滚动到窄屏结果区，没有在提交后主动移动键盘焦点；后续若调整焦点管理，应避免打断屏幕阅读器用户的输入上下文。 ## Do's and Don'ts ### Do - **Do** 继承 DSH alias token；新增颜色角色前先确认宿主已有语义，不创建平行主题系统。 - **Do** 将事实来源、覆盖对象和原始值放在结论附近，使每个数字可追溯到 Run 与 Checkpoint。 - **Do** 保留紧凑但可扫描的 Operate 密度；优先边线、对齐和短文案，避免增加无任务价值的视觉层级。 - **Do** 为加载、空、错误、禁用、运行中、取消、Ready 未满足分别提供可读文案。 - **Do** 在扩展 Issue 或复验 UI 时继续分开 lifecycle、finding、decision 与 verification。 ### Don't - **Don't** 把“运行完成”改写成“验收通过”，或用绿色对勾暗示质量结论。 - **Don't** 把“Ready 满足”当作零异常、视觉合格或业务状态完整的证据。 - **Don't** 把异常信号直接命名为 Issue；Candidate 必须经过人工“立为 Issue”。 - **Don't** 添加综合评分、百分比置信度、排行榜式指标或大面积红绿灯，它们会隐藏具体证据和人工决策边界。 - **Don't** 使用 landing page 式大标题、渐变光效、玻璃卡片、装饰插画、悬浮阴影或营销口吻；这个表面属于宿主内的操作工具。 - **Don't** 为展示未来能力而放置不可用入口；参考设计图比较、Provider 推理和自动 Agent 注入在实现前只能作为文档目标。 ### 已知兼容与实现限制 - 当前入口依赖 DSH `conversation.view`；空白会话不会挂载该 View，需要先产生非空会话。 - 工作台深浅色由 DSH alias 继承；Checkpoint 的“主题”字段控制被验收目标，不切换工作台自身主题。Desktop 壳层深浅色重开仍是 README 标记的发布前 Gate。 - CSS 使用 `color-mix()` 与 `100dvh`，当前面向 DSH 内置的现代 Web Client，不承诺旧版浏览器兼容。 - 390px 证据来自 DSH Web 壳层中的 CSS 窄屏视口，不等于真实移动设备或原生 App 验证。 - 当前截图只校验 PNG 格式与非零尺寸；内容级空白检测尚未实现，不能将“有截图 URL”解释为证据内容一定有效。 - Provider 图片推理、参考设计图比较、自动 Agent 注入和真实项目 Gate 均未完成；当前只允许复制本地修改包，不得呈现“已发送给 Agent”。