Build Product And Tool Interfaces

构建产品与工具界面

成功定义

让目标角色把真实输入或对象推进到可核验结果；需要持久化、权限、批量或协作时，这些能力也必须形成真实闭环。完成态不是“页面已经画完”，而是适用于当前子型的输入、命令、状态变化、反馈、恢复与输出成立；不适用的能力应明确记为 N/A，不能用假数据或假控件补齐产品外观。

本 Skill 拥有产品领域判断，并保留介质中立的真实标杆、视觉理由、素材来源与许可和目标环境验收。 最终消费者或合同交付确为 Web 时，再与 $build-polished-visual-frontends 组合；对象模型、迁移报告或 内部状态检查器本身不触发组合。组件系统风格合同和代表性非空方向帧只适用于含可视界面的 Create/Edit；纯对象建模和 Diagnose 记为 N/A + 原因。Diagnose 可只读检查组件语言与渲染证据， 不得借检查改写视觉方向。详细状态矩阵、批量作用域、恢复策略和环境转换模式见 references/patterns.md。

组合时以对象模型、命令关系、任务密度和状态风险决定视觉优先级，不套用“简单、干净、中性”的 默认皮肤。主题材料与标志性表达不得压过主工作对象，除非用户要求、已接受参考或品牌系统明确授权。

选择主要产品循环

按用户反复完成的工作选择主型，不按“有侧栏”“像后台”或采用的框架分类。混合产品只保留一个主要循环，其他能力围绕它服务。

页面主要用于发现和阅读内容时，路由到内容网站；交付物主要是跨产品复用的组件、状态与 token 时，路由到 UI 组件与设计系统。单张图的重点是解释数据时属于数据可视化；只有当查询、筛选、告警和处置组成持续工作时，完整界面才属于本领域。操纵变量只为理解规律时属于交互解释器，不要套用业务工作流。

登录、侧栏、搜索、图表或 AI 摘要不自动构成产品工具。混合站点按任务面拆分：发现与阅读仍按内容网站设计；只有反复操作稳定对象、推进持久生命周期或生成可继续使用结果的工作区才应用本 Skill，不把整个站点强行包装成 dashboard。

先定工作模式与适用能力

先根据请求选择工作模式，不能把 Create 的流程机械套到 Edit 或 Diagnose：

再按产品子型建立适用性表，并为每项写 required / optional / N/A + 原因：

所有子型只共享不变量，不共享固定字段：真实输入进入一个权威任务模型；同一命令的不同入口产生相同效果；可见承诺能追溯到真实状态或输出；失败保留仍可恢复的工作；界面不伪造未实现的后端、权限、协作、版本或持久化。

先写产品契约

编码前用一页以内写清以下内容，并让界面结构从契约产生：

• 模式与适用性：Create、Edit 或 Diagnose；产品主型；选择、批量、持久化、权限、协作、异步和环境转换分别是必需、可选还是 N/A。
• 角色与责任（适用时）：谁可以看、改、批准、撤回或导出；受限动作如何解释原因。单用户本地工具不虚构角色体系。
• 对象/任务模型：记录完成任务所需的身份、字段、关系、原始值与派生值；只有跨对象引用、持久化、版本或协作需要时才增加稳定 id、所有者与版本。
• 生命周期：记录当前子型实际存在的业务或工具状态，以及允许的命令转换；一次性同步工具不强造审批生命周期。
• 任务主线：入口、当前步骤、下一步、适用的交接点、完成定义，以及承诺持久化时的重新打开路径。
• 共视依赖：完成每个高频判断时必须同时看到的当前对象、主要证据、判断输入、可执行命令与完成证据。
• 命令契约：目标、适用作用域、前置条件、状态转换、成功证据、失败恢复，以及风险需要时的撤销或确认。
• 输入输出：输入的真实来源与格式；输出是保存记录、交接、配置、下载文件还是发布结果。
• 状态层次：把适用的业务状态、界面交互状态、异步作业状态和视图上下文分别建模，不用一个 status 混装；不存在的层次标为 N/A。
• 组件系统风格合同（仅可视产品界面的 Create/Edit）：选定组件系统的实际样张；它拥有的字体、密度、间距、圆角、边界、阴影、表面、图标、反馈与动效；项目 token 的一一映射、专属工作面的扩展规则和有证据的例外。纯非可视交付和 Diagnose 记为 N/A；Diagnose 只记录现状证据，不建立新合同。
• 持续性（适用时）：需要保留的草稿、筛选、选中范围、滚动位置、历史、冲突与未完成作业如何恢复。
• 持久化契约（适用时）：权威存储、schema 版本、hydrate/commit 边界、草稿、作业幂等、迁移，以及配额、损坏或重开失败时如何恢复。无持久化工具明确内存边界和离开后丢失什么。

按能力保留语义不变量，不照抄字段名。多对象产品必须区分当前上下文、显式选择、筛选结果和命令作用域；单对象工具只需一个权威文档/输入及其派生结果，不应为了“像产品”引入空的 selection 或 collection。专业引擎输入、标注/选区、检查器、计数、禁用条件和导出内容必须从同一权威对象或任务状态派生，不能只换标题而继续展示旧对象或全局演示数据。

从共视依赖生成工作空间

产品布局必须由高频判断的依赖关系产生，不能由需求列表、组件目录或“一个需求一个 section”产生。编码前为每个高频判断或命令写一行：current object / primary evidence / decision input / available command / completion evidence。

据此建立当前合同环境的工作区拓扑：

• 同一次高频判断需要相互参照的对象，在允许并列的合同视口默认同时可见；
• 主工作对象成为最大的连续区域，强连接对象形成稳定相邻 pane；高频直接呈现、次要一层展开、低频进入次级面板；
• 比较关系可以并列，顺序关系采用步骤，不因“三栏看起来专业”强造并列；
• 空间或输入方式不足以保留并列关系时，转换为明确的列表—详情、任务模式或分步流，并保留对象、 游标、选区和草稿，不机械纵向堆叠全部 pane。

交付范围包含可视产品界面的 Create 与大改先渲染代表性非空工作区；方向检查只看用户请求、外部参考、共视关系与像素，模型解释不能证明布局成立。纯非可视交付和 Diagnose 将方向帧记为 N/A。

用命令组织工作流

不要先列页面和卡片，先写一条对象动词路径，例如“受理 → 定位 → 操作 → 校验 → 交接 → 完成或重开”。每个高频动作都实现为统一命令，让按钮、菜单、快捷键和触摸入口调用同一逻辑。

为每项可见承诺建立硬映射：控件 → 命令 → 权威状态变化 → 成功证据 → 重开恢复或导出证据。缺少任一环的主流程控件不得启用；暂不实现的次要能力应禁用并说明边界。能点击、打开弹层、改变按钮文案或出现 toast 都不等于命令完成。

1. 首屏说明当前范围、当前对象、业务状态和最合理的下一步。
2. 有可视产品界面的 Create/Edit 先用代表性非空状态完成主工作区与核心判断，渲染并修正方向；此时只实现决定视觉方向所需的真实领域引擎和最小交互。纯非可视交付和 Diagnose 跳过本步并记录 N/A + 原因。
3. Create/Edit 在适用的方向检查无 blocker 后完成一个纵向闭环：取得真实输入，操作一个对象或任务状态，再产生可检查的即时结果、下载、保存记录或提交结果。Diagnose 只读复现现有路径并收集状态、行为和渲染证据，不执行写命令。
4. 再扩展当前子型确实需要的搜索、筛选、比较、多选、批量、历史、协作与低频设置；适用性表为 N/A 的能力不扩展。
5. 为每个异步阶段显示精确语义；读取、校验、保存、提交和导出不能共用模糊的“处理中”。
6. 高影响命令显示目标和作用域；不可逆动作确认，可逆动作优先提供撤销。

让专业能力真实成立

• Web 产品若没有质量合格的既有设计系统，采用稳定现代应用栈，并按 $build-polished-visual-frontends 的设计系统路由，从环境实际可用的成熟候选中，以产品气质、任务密度、平台传统、能力覆盖、可访问性、许可与交付证据选择一套主系统。候选清单及其技术边界只由前端路由维护；预装只表示可用，不能自动决定风格。
• 选定一套成熟系统后，把它当作整件产品的视觉语言，而不是按钮和输入框仓库。先观察真实组件样张和关键状态，再让导航、列表、面板、工作画布、空态、通知及自定义组合组件继承其字体、密度、间距、圆角、边界、阴影、图标、反馈与动效；项目只能使用从系统派生或明确映射的 token，不得平行创造另一套 chrome。
• 不要把“单页”“离线”或“交付一个 index.html”误判成简单静态产物：只要存在多个相互关联的控件、持久状态、导入/编辑/导出闭环或专业工作面，就应使用框架、组件系统和适用的领域引擎。离线是部署方式，不是放弃成熟能力的理由。
• 文件导入要读取并解析真实 File；查询要由用户输入或明确、可追溯的数据源计算；编辑要改变对象模型；导出要从当前状态生成可打开、可下载或可继续使用的结果。文件链路的唯一有效验收是从用户可见入口触发真实 file chooser、选择文件并观察权威状态与输出；测试代码直接给隐藏 input 注入文件只能作为下层单测，不能证明入口可用。确定性 synthetic fixture 只能进入自动化测试，或用户明确要求的 demo/mockup；后者必须在画面内和随附 metadata 显著标为 synthetic/demo，不能作为生产事实。
• 浏览器工具必须按最终交付 origin 与容器复验主路径，记录 isSecureContext、存储可用性、沙箱和权限边界。局域网 HTTP、iframe 与 localhost 不是等价环境；randomUUID、Web Crypto、Clipboard、File System Access、下载、IndexedDB 或媒体解码等能力若依赖安全上下文或顶层文档，必须提供真实兼容路径、明确要求 HTTPS，或在入口前阻止并解释，不能在用户动作后静默失败。
• 用户未提供数据、权威数据源或明确 demo 合同时，最终界面从真实空态、导入或创建入口开始，不预置看似生产的记录、队列、历史、用户、权限、指标或成功结果。离线交付可以使用浏览器存储和客户端生成文件实现真实本地状态，但不得虚构服务器同步、权限校验或后台作业成功。无持久化单对象工具可以只维护内存状态，只要清楚说明离开边界并交付真实即时结果或可用文件；不要为了通过“刷新恢复”而假造存储。无法实现的次要能力应禁用并说明边界。
• 未被需求要求时不要添加 AI 助手、洞察卡或聊天入口。确需 AI 或自动化时，把它建模为真实命令：显示输入范围、来源、执行状态、输出版本与限制，允许接受、拒绝或编辑；接受后的变化进入同一权威任务状态，并在适用时进入持久化、版本和审计链。没有真实推理或自动化能力时禁用并说明，不伪造评分、建议或成功状态。
• 数据表格、树、组合框、日期范围、可调分栏、对话框、菜单和复杂表单优先复用项目已有或新选定的主设计系统，不用临时 div 拼出近似行为，也不在同一产品混用多套组件语言。
• 成熟系统没有覆盖的专业工作面可以由领域引擎与自定义组合组件完成，但其容器、工具条、选区、浮层、状态和运动仍遵循同一组件系统风格合同。领域特异性来自真实对象与操作，不来自第二套皮肤。
• 富文本、代码与差异比较、图形画布、图表、地图、时间线、媒体处理或其他专业工作面，优先接入成熟领域引擎。领域引擎的输入、选择、游标、缩放、坐标和标注必须与产品对象共享状态，不能成为独立演示层；图形同时说明适用的单位、尺度、变换/归一化、参数与不确定性。采用成熟库只证明实现起点，不能自动证明数据真实或专业语义成立。
• 成功 toast 只能提示，不能代替当前子型真正承诺的状态变化、即时结果、下载入口、持久化版本或审计条目。

让工作空间服从任务关系

密度来自单位时间内必须比较和操作的信息，不来自堆满控件。使用共视依赖决定并列、分步或按需展开，不从需求清单直接生成页面 section。

• 基底、前景与边界关系来自选定设计系统、用户、品牌或实际参考；没有这些证据时使用职责清楚、 对比稳定的克制关系，不从题材提取全局配色，也不为“视觉个性”增加色彩。
• 用尺度、字重、对齐、留白和必要分隔建立层级。当前工作面优先，导航只保留跨任务入口；不把每组内容包成圆角卡片，更不要卡片套卡片。
• 次要信息仍须清楚可读，不通过低对比和缩小字号隐藏。浏览器内持续辅助文字默认不低于 14 CSS px；12–13px 仅限刻度、单位、时间戳和少量高对比 metadata。操作、字段名、状态、错误、说明和下一步不属于例外；没有明确控件、状态、风险或判断 owner 的辅助文案直接删除。
• 设计系统默认拥有基础控件的 anatomy、内部尺寸、字体角色、状态和焦点视觉。项目通过宏观构图、领域工作面和少量全局 token 组合产品，不逐组件重画。
• 设计系统同样约束页面外壳与自定义组合组件。执行“去控件检查”：临时遮住按钮、输入框、选择器和菜单，只看导航、面板、列表、工作面与状态反馈；若剩余部分不像组件库自然扩展出的同一产品，先统一字体、密度、灰阶、圆角、边界、图标和反馈，再继续润色。
• 一个表面只使用完成职责所需的最少视觉信号。不要把细描边、浅色填充和圆角同时铺满容器、选中行、通知与状态条；瞬时成功优先使用组件系统的轻量反馈，只有持续影响任务的状态才占据持久区域。
• 视觉面积、对比和位置按主工作对象、命令风险与判断频率分配。来源、限制和恢复说明贴近受影响的 对象或动作；除非风险本身就是主任务，不把它做成全宽巨幅告示或在多个面板重复。
• 未建立真实品牌身份时使用清楚、克制的文字标识；不要把通用线性图标装进彩色圆角方块冒充 logo，也不要给每个标题机械配图标。
• 有主要专业工作对象时，选择一处任务原生的精致高点，例如可精确操纵的主工作面、可信的数据视图、时间/版本导航或状态转换。它必须直接改善判断或操作，并延续组件系统的字体、颜色、几何与反馈；其余区域保持安静，不用装饰制造“惊喜”。
• 遇到“不够精致”先删除重复标签、容器、颜色、阴影和解释文字，再调整关系；不通过增加装饰修补。
• 装饰轨、强调条、局部 border-left、角括号、图标外框、伪元素线段和标题旁竖线，只有在组件或 状态合同中稳定编码选择、状态、进度、尺度、真实分组或身份语法时保留。删除后不影响理解或操作 就删除；“强调重点”和 CSS 属性名都不能自证职责。CSS 只承担布局、排印、必要分隔、真实反馈， 以及真实图像的裁切、遮罩和可读性处理，不另造装饰资产。
• 公开开场页若使用大背景，按 Web 主视觉合同建立世界；进入工作区后以对象、结构和交互延续身份， 不重复铺图或退化成“背景图 + 半透明面板”。

执行 skin-stripping test：临时中和产品名、行业标题、题材色、行业图标、章节眉题和装饰素材，再判断领域用户能否从对象模型、专业工作面、命令关系、状态转换与输出产物认出任务。至少两个层面必须具有领域特异性；颜色、图标和题材文案不计为通过证据。若去除 skin 后只剩可任意换行业的 SaaS 壳，先重建对象与工作区，不增加更多装饰。

以下均为不能由功能完成度抵消的产品视觉 blocker：

• 主工作对象不是最大连续区域，互依对象被滚动/路由/弹层分隔，或页面只是需求 section 堆叠；
• 信息层级依赖灰色微文案、眉题和重复标签，关键文字违反字号/对比规则，或存在无职责装饰线；
• 颜色职责冲突、领域特异性依赖题材 skin，或基础组件被无证据地系统性重画；
• 只有现成控件符合组件库，导航、面板、列表、工作面或通知却使用另一套字体、密度、灰阶、圆角、描边、阴影、图标或动效；
• 细描边、浅填充和圆角在多数表面机械成套出现，或通用图标方块被当作品牌与标题装饰；
• 受约束环境机械堆叠原布局并丢失任务上下文。

把恢复设计成主流程

只实现正常态不算产品。按适用性和实际风险覆盖加载、空、无权限、未保存、保存中、冲突、离线、校验失败、作业失败、部分成功和禁用等状态；不存在的权限、网络、批量或持久化状态记为 N/A，不要模拟出来。

• 错误靠近失败动作，说明原因、影响对象、已保留内容和下一步；不要只发全局 toast。
• 重试、修正输入、撤销、恢复草稿、载入其他版本或联系有权限角色，至少提供一种真实出口。
• 切换对象、筛选、视图或合同环境时保留草稿与必要上下文；恢复后回到出错位置，而不是首页。
• 冲突同时保留本地内容和外部版本信息；批量部分失败分别报告成功、跳过和失败对象。
• 输出失败保留原作用域与输入；成功显示持久标识、版本、文件名、下载入口或可追踪记录。

承诺多个目标环境时分别成立

本节只在适用性表要求多个目标环境或布局转换时使用，以结果等价而不是像素或功能入口完全相同为 目标。明确限定单一环境的专业工作面将本节标为 N/A，只验证合同声明的尺寸与输入方式。

• 空间允许时，可用并列比较、稳定上下文、多选、精确输入和可调工作面；避免让全局 chrome 抢走主任务空间。
• 空间受限时，决定哪些面板折叠、停靠、转场或成为覆盖层，并提供明确的打开与关闭入口；核心结果 仍须可完成，不能直接隐藏后失去任务路径。
• 输入方式变化时，关键动作仍须可发现，不依赖未承诺的 hover、硬件键盘或精细指针。
• 跨布局切换后保留当前对象、草稿、筛选、选择范围和异步作业状态；不适合重型创作的合同环境只 承诺真实可完成的查看、记录、审批或稍后继续路径，不用残缺界面伪装功能等价。

实施与验收

1. 选择 Create、Edit 或 Diagnose，审计现有对象、后端契约、适用的组件系统、领域引擎和不可破坏行为；Diagnose 保持零写入。
2. 写适用性表、产品契约、最小状态图和共视依赖，再由关系选择自然工作空间；所有 N/A 必须有可核对理由。
3. 有可视产品界面的 Create/Edit 先构建代表性非空工作态，在契约承诺的目标环境与尺寸渲染；对照组件系统样张执行风格合同与“去控件检查”，再修复所有产品视觉 blocker。纯非可视交付和 Diagnose 将本步记为 N/A + 原因。无独立 review 时仅将 assurance metadata 标记为 SELF_REVIEW_ONLY，不得写 PASS，也不得把它当作完成、生命周期、release 或 promotion 状态。
4. 方向无 blocker 后实现一条真实输入到真实输出的纵向闭环；只在契约要求持久化时验证刷新恢复。Diagnose 则用只读复现、状态轨迹和对照证据定位问题，不把观察变成修复。
5. 只扩展适用的异常、权限、冲突、批量、协作和撤销，并逐项核对命令作用域。
6. 用真实长度、最高适用密度和最空数据测试承诺的环境与尺寸；文件、媒体或数据处理还要覆盖契约中的现实格式与尺寸，微型 fixture 不能代替容量、解码、进度、配额和失败恢复验证。未承诺的环境不虚报完整支持。
7. 在最终消费上下文自动沿可见承诺映射验证命令、权威状态、输出及适用的重开恢复；Web 交付还要在最终 URL、origin 和实际嵌入/顶层打开方式下复验，其他介质使用其真实消费者。人工验证适用的首屏任务、信息扫描、焦点、触控与恢复路径。不得绕过可见入口，不得以 click 成功、弹层出现或 toast 文案代替结果，只报告与当前构建匹配的证据。

交付前确认：用户能说出当前任务、输入/对象、状态和下一步；Create/Edit 的主动作改变真实状态并产生可核验结果，Diagnose 只有只读复现、证据和零写入；失败保留适用的工作；专业能力不是静态道具；承诺设备都能完成结果。有可视产品界面时，还要确认组件、自定义工作面与页面外壳遵循同一设计系统，界面没有假导航、灰色微文案、无职责装饰、随意配色或卡片套卡片。视觉审查来源明确为独立 PASS/REVISE/BLOCKED 或 SELF_REVIEW_ONLY；后者仅是 assurance metadata，不代表 PASS、完成、release 或 promotion。