pikasTech-unidesk/.agents/skills/unidesk-webdev/references/design.md

UniDesk Web 设计默认规范

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

• UniDesk/HWLAB 的工具页默认是工作界面，不是营销页：首屏直接呈现可操作对象、状态和主要任务流，避免 hero、装饰卡片和说明性大段文案。
• 信息密度优先但要稳定：header 保持窄，source/file/project 等上下文选择放在顶部工具栏或状态栏下拉；计数、来源、taskRef、更新时间等元信息收敛到详情/感叹号弹窗，不长期占主版面。
• 主内容区必须占优：树、大纲、列表和导航只作为左侧辅助视图，默认约 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、文件名或更新时间。
• 报告、Markdown、日志和 JSON 片段要用成熟 Markdown/代码块渲染，代码块采用浅色 Workbench 风格、可滚动且不撑破布局；不要把裸 JSON 或长日志直接挤爆页面。
• 页面状态要可深链：重要 source/file/task/report/session 选择进入 RESTful URL，并能刷新后恢复；联动其他功能只通过公共 API、稳定 id 和 URL，不把两个功能互相嵌入成强依赖。
• 设计验收必须用截图或 web-probe 样本检查真实版面：正文是否可见、主区域是否足够、弹窗是否遮挡流程、长文本是否溢出、移动/窄屏是否仍可操作。桌面默认视口是 1920x1080；项目/MDTODO/报告类页面还应按风险覆盖紧凑桌面视口（例如 960x600）的深链默认态、左侧树折叠态、右侧报告关闭态。涉及报告渲染或布局重写时还必须覆盖右侧报告栏和报告全屏态。记录 document overflow 必须为零、主内容区不得滚动、pane 宽高和滚动范围、正文/报告可见性、按钮是否被遮挡，以及截图 SHA。