# UniDesk Web 设计默认规范

本文件记录 UniDesk/HWLAB Web 工具页的长期设计默认。`SKILL.md` 只保留入口索引；实际做前端布局、Workbench/Project Management 页面或视觉验收时读取本文件。

## 用户图片输入门禁

- 用户上传截图、设计稿或其他图片并要求分析或修改时，必须先完成视觉读图，
  并在修改前准确复述图片中可见内容、标注和用户指出的问题。
- 图像工具没有返回可见像素、图片损坏、分辨率不足或无法可靠识别时，必须立即
  停止并向用户说明阻塞；禁止在没有看清图片的情况下继续修改。
- OCR、文件名、源码、DOM、CSS 和历史上下文只能用于视觉读图后的交叉验证，
  不能替代视觉读图，不能据此猜测图片内容。
- 未完成视觉读图与问题复述前，禁止创建补丁、调整样式、改数据或启动发布；
  用户确认复述不符时，必须撤销基于错误理解产生的未验收改动，再重新读图。

- UniDesk/HWLAB 的工具页默认是工作界面，不是营销页：首屏直接呈现可操作对象、状态和主要任务流，避免 hero、装饰卡片和说明性大段文案。
- 信息密度优先但要稳定：header 保持窄，source/file/project 等上下文选择放在顶部工具栏或状态栏下拉；计数、来源、taskRef、更新时间等元信息收敛到详情/感叹号弹窗，不长期占主版面。
- 工具页页头默认采用紧凑命令栏：
  - 页面身份、短说明和高频操作在桌面端保持同一行或同一紧凑区域；
  - 操作按钮靠右对齐，不得为了少量按钮单独占据一整行；
  - 标题使用工具页尺度，不得使用 hero 尺度；
  - 说明默认限制为一行，空间不足时隐藏次要说明，不得持续撑高页头；
  - 禁止用大面积留白、背景纹理或装饰区域扩充页头。
- 状态摘要默认作为页头底栏：
  - 紧贴命令栏下方，不在命令栏与主体之间增加大段空白；
  - 桌面端优先使用单行、等高、可扫描的状态分栏，不使用高大的独立状态卡片；
  - 单项只保留短标签、主值和必要状态点，详细解释进入主体或检查器；
  - 状态数量超过可用宽度时优先内部横向滚动或收敛次要字段，不换成多行高卡片墙。
- 页头必须服从主体工作区高度预算：
  - 在 `1920x1080` 桌面视口中，页面命令栏与状态底栏合计高度默认不超过主内容可用高度的 `18%`；
  - 主体工作区使用 `minmax(0, 1fr)` 或等价布局占满全部剩余高度；
  - 页面不得为了展示品牌、说明或空白而压缩列表、时间线、正文和证据检查器；
  - 紧凑桌面优先隐藏次要说明、缩小垂直 padding 和收敛状态字段，再考虑改变主体分栏。
- 主内容区必须占优：树、大纲、列表和导航只作为左侧辅助视图，默认约 30% 或更小，并支持折叠或调整宽度；正文、报告、trace、消息或表格等主工作内容应占页面主要空间。
- Workbench 类三栏/双栏工作区优先复用通用受限布局组件或抽取通用组件后再接入新页面；不要为每个页面重新堆叠一套 `aside + main + report` CSS。
- HWLAB 页面滚动边界：
  - AppShell、主内容区和页面根容器保持视口内稳定高度，使用 `min-height: 0` 和 `overflow: hidden`；
  - document 和主内容区不得承担工具页面的全局纵向或横向滚动；
  - 页面头、命令栏、状态摘要和主要操作保持稳定可见；
  - 树、列表、正文、事件流、时间线、日志和证据检查器在各自 pane 内滚动，并使用 `overscroll-behavior: contain`；
  - 窄桌面可把次要 pane 移到工作区下一行，移动端可改为工作区内部纵向布局，但滚动容器仍是 workspace 或 pane；
  - 新页面和重设计页面必须遵守；历史页面通过 AppShell 路由元数据逐步迁移，禁止一次全局切换造成回归。
- 页面可见文案默认使用中文；协议字段、实体名、命令、路径、`runId`、`traceId`、`SHA256`、`HWPOD` 等机器或领域标识可保留原文，状态码旁应提供中文含义，禁止整块工作区只显示英文标题和状态。
- 新建、配置、probe、reindex 等低频表单用对话框或抽屉承载；默认版面不要常驻新建框、配置表或调试面板。高频命令保留为稳定按钮或图标按钮，并配清晰状态。
- 文档/任务类页面优先就地阅读和就地编辑：标题和正文双击或显式编辑态切换，不为常规查看单独铺满输入框；正文渲染态必须可见，不能只显示 taskRef、文件名或更新时间。
- 树和大纲中的结构化编号、层级控件与标题内容必须职责分离：
  - `R1`、`R1.2` 等结构化编号使用独立稳定列，不嵌入 Markdown 标题流，
    不因编号长度或层级深度改变同级标题起点；
  - 展开按钮、树导线和缩进只表达层级，不重复推动编号列；
  - 状态点属于标题内容列，不能夹在展开控件与编号之间制造视觉噪声；
  - 导入标题已带旧结构编号时，只在展示层去重，禁止修改原始标题或破坏
    Markdown 链接；
  - 不使用逐行断开的硬分隔线模拟列边界，优先依靠稳定对齐、字重和留白表达
    信息层次。
- 报告、Markdown、日志和 JSON 片段要用成熟 Markdown/代码块渲染，代码块采用浅色 Workbench 风格、可滚动且不撑破布局；不要把裸 JSON 或长日志直接挤爆页面。
- 页面状态要可深链：重要 source/file/task/report/session 选择进入 RESTful URL，并能刷新后恢复；联动其他功能只通过公共 API、稳定 id 和 URL，不把两个功能互相嵌入成强依赖。
- 设计验收必须用截图或 web-probe 样本检查真实版面：
  - 检查正文是否可见、主区域是否足够、弹窗是否遮挡流程、长文本是否溢出、移动或窄屏是否仍可操作；
  - 桌面默认视口是 `1920x1080`；
  - 记录命令栏、状态底栏和主体工作区的实际高度及占比；
  - 确认页头未超过默认高度预算，主体工作区占据全部剩余高度；
  - TaskTree、遗留 MDTODO 和报告类页面按风险覆盖紧凑桌面视口，例如 960x600；遗留任务迁移见 `$unidesk-tasktree`；
  - 紧凑桌面覆盖深链默认态、左侧树折叠态和右侧报告关闭态；
  - 涉及报告渲染或布局重写时覆盖右侧报告栏和报告全屏态；
  - 记录 document overflow 为零、主内容区不滚动、pane 宽高和滚动范围、正文或报告可见性、按钮遮挡情况及截图 SHA。
