IronClaw WebUI 设计系统完成清单（CHECKLIST）深度解析：五阶段治理路线图与验收标准

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本文基于 IronClaw 仓库docs/internal/reborn/design-system/设计系统提案包中的 CHECKLIST.md 展开完整解读这套受治理governed、面向 Agentagentic-first的 WebUI 设计系统的完成定义Definition of Done。你将看到为什么完成清单以每个勾选框都必须真正落在main分支上为唯一验收口径WS1–WS7 七个工作流分别解决什么问题、各自有哪些阻塞性前置依赖⚠、哪些决策必须由指定人类拍板[decision]以及如何用 README 中的 Epic 归属表做单点治理。适合 WebUI 前端工程师、设计系统负责人与关注 AI Agent 交互体验的开发者阅读。文档定位一份完成定义而非执行计划在 docs/internal/reborn/design-system/ 这一提案包中四份文档分工明确README.md —— 总览、五阶段速览与Epic 归属表canonicalPROPOSAL.md —— 决策记录、不可妥协的不变量invariants与依赖治理规则PLAN.md —— 何时、如何执行的分阶段计划CHECKLIST.md本文主角—— 完成什么的验收清单即整个设计系统的Definition of Done。CHECKLIST 开篇即给出一句可操作的定义当下方每一个勾选框都被勾选时这套受治理、面向 Agent 的 WebUI 设计系统才算真正落地。而且勾选有硬性含义——一个勾选框被勾选意味着该内容已经合入main分支且合入的 PR 需在清单内点名。文档还约定两种特殊标记⚠阻塞性前置依赖必须先满足才能推进后续项[decision]需要指定人类named human拍板决策的项决策记录必须挂到对应 Epic 上。整个文档基于origin/maind3791e0f8编写状态为 Proposal提案评审中跨三个 Epic 跟踪#7038、#7781、#7782。Epic 归属表单点治理的关键机制CHECKLIST 反复强调一个设计原则Epic 归属只存在一处——即 README 中的 canonical 表README.md#epic-ownership-canonical。CHECKLIST 与 PLAN 中出现的每一个Epic #NNNN标签都是指向该表的链接而非对该映射的重复陈述。好处是当归属关系发生变化时只需要在 README 中改一处不会出现多份拷贝互相漂移。Epic阶段范围#70381Storybook 集成与设计系统目录PR #7750#77812–3DESIGN.md 治理与文档#7042· 主题更新与 UI reskin取代已关闭的 #7733#77824–5Agent 化交互与组件 · 信息架构三个 Epic 的由来最初的 #7038 被拆分Phase 2 与 Phase 3 合并进 #7781。这套一表定归属、他处只引用的做法与仓库内另一套治理基准包docs/internal/reborn/target-architecture/PR #6918的文档形态一致。WS1 — Storybook 集成阶段 1Epic #7038搭起工作台与目录WS1 的目标是把 Storybook 立起来作为设计系统的工作台、测试基座和 Agent 访问入口四项验收全部由 PR #7750 承载Storybook 10storybook/react-vitepnpm 管理接入真实app.css并提供 light/dark 双主题工具栏约 33 个 story分布在五个侧边栏分类Primitives / Components / Composites / Icons / TokensVitest 拆分pnpm test只跑 node 环境pnpm test:storybook跑 headless Chromium渲染层测试与纯逻辑测试互不阻塞storybook/addon-mcp把组件目录暴露成 Agent 可查询的 MCP 资源让 Agent 在调用组件前先读文档。在 PROPOSAL §2.3 中有明确的当前状态说明Phase 1 处于 IN REVIEW尚未合入main——当前main上既没有.storybook/目录也没有任何 story。这一点也解释了为什么 CHECKLIST 要求每个勾选都点名合入 PR清单描述的是落定之后的目标状态而不是今天的代码树。从源码结构看Storybook 的故事文件与组件**同目录共存colocated**的模式在仓库中已经成形例如 button.stories.tsx、command-palette.stories.tsx、gateway-layout.stories.tsx。这正是 PROPOSAL 不变量 3每个有意义的组件都有 story在文件布局上的体现。WS2 — DESIGN.md 治理阶段 2Epic #7781让设计系统有宪法WS2 的任务是把设计系统变成有治理文档管辖的对象四项验收DESIGN.md落在crates/product/ironclaw_webui/frontend/DESIGN.md内容是 M3X 规格 IronClaw 治理附录原 #7043 的 changeset 被完整保留将基于main开新 PR 合入StorybookDesign/Guidelines文档页Design分类排序最前Agent 治理文件.claude/rules/design-system.md加上CLAUDE.md中的 Module Specs 指针与 DS README 链接——但三者都只能作为AGENTS.md的补充。AGENTS.md是工具中立tool-neutral的规范契约入口Claude 专属文件不得新增任何它未承载的规则⚠ 阻塞项必须先合入 #7750再以main为基线开新 PR 落地 Phase-2 changesetPROPOSAL §7.6。这一文档即真相docs-are-source-of-truth的取向直接对标 APDD 治理套件也与 PROPOSAL §5 的五层分类映射呼应Tokens →styles/app.css、Elements原语→design-system/、Components →primitives.tsx与components/、Patterns →pages/**、Layouts →layout/。WS3 — 主题基础与 reskin阶段 3Epic #7781换肤最容易失控也最需要护栏WS3 是风险最集中的阶段验收项也最多深色面板值推导为每个 token 在:root[data-themedark]下推导深色值PROPOSAL §7.3 明确要求色调位移tonal shift而非字面反转WCAG AA 对比度验证所有文本/token 配对通过 AATokens/Colorsstory 负责断言——这是常驻不变量PROPOSAL §3.4内嵌在深色面板依赖里不作为独立项另管字体厂商化Roboto Flex Roboto MonoOFL 协议放到/vendor/fonts下[decision]Google Sans 的替代方案需人类拍板Google Sans 不可自由再分发M3 →--v2-*token 值落地app.csslight dark 双主题⚠ token 值必须先于任何组件 restyle 落地原语/复合组件按新 token 重做外观每个变化都要过 story CssCheck a11y 验证。Invariant 2 的缺口一次被量化而不是被回避的治理WS3 明确点名要闭合 Invariant 2 缺口PROPOSAL §3.1 有完整测量数据当前crates/product/ironclaw_webui/frontend/src/下的生产组件排除*.test.*中存在违规类型文件数出现次数任意像素 class如text-[13px]、rounded-[13px]91345—— 其中在design-system/原语层内部838.tsx中硬编码的 6 位十六进制色值310迁移顺序design-system/8 个文件 38 处与 OOBE 试点卡片先行随后是其余同时需要一个 lint 或 grep 门禁防止计数回潮。文档还给出了一个具体例子suggested-task-card.tsx 携带 5 处任意像素 classrounded-[13px]、rounded-[6px]、text-[13px]、text-[11px]、text-[10.5px]——但它颜色维度已经合规所有颜色都是var(--v2-*)引用缺口是维度性的间距/字号/圆角不是色度性的因此由 Phase 3 的 type/space/radius 刻度来闭合。这个案例展示了一个诚实的治理姿态试点组件是被治理的对象而非已合规的样板。WS3 的护栏PROPOSAL §7.0token名称不变只改值保证消费者无需改动字体自托管 经过测试的系统回退栈 font-display: swap字体加载失败退化为可读文本而非不可见文本整个阶段可由单个 PR 回退不留残余状态。WS4 — Agent 化组件与交互阶段 4Epic #7782从界面走向代理工作台WS4 是 IronClawagentic-first定位最直观的落点验收项动画方案选定并接入prefers-reduced-motion门禁PROPOSAL §7.5MSW用于网络依赖型 story 的 happy-pathPairingWebCodePanel、TeeShield 两个组件目前因联网/宿主门控只能渲染 limited/error 状态§7.2Agent 化组件建设 编目composer 工具栏、FAB 快捷拨号、聊天气泡、agent 活动/推理卡片、品牌化进度、连接按钮组——每个都要带 story 与 play coverage护栏生产产物被断言既不包含mockServiceWorker.js也不包含mswchunkworker 生成进 Storybook 专属静态目录而绝不进入frontend/public/缺失 handler 时退化为现有的 limited/error 状态运动总开关kill switch一个共享的禁用运动信号同时被prefers-reduced-motion与应用开关解析CSS 和每个 JS 调用方都读它运行中的 spring 要取消自己的 RAF 循环并写出静态终态动态加载的 motion chunk 被拒时渲染静态基线断言级别在**调用方caller**而非 helper⚠ 依赖 WS3 的 token。PROPOSAL §7.2 解释了为什么 MSW worker 不能进public/vite.config.ts将publicDir设为public其中的一切都会被复制进dist/而crates/product/ironclaw_webui/build.rs会递归遍历dist/并把每个文件嵌入最终二进制。一旦 worker 落入public/即使它是devDependency也会被编译进生产并随真实 WebUI 分发——这正是隔离护栏要证明dev-only 依赖在生产 bundle 中可证明地缺席的原因。为什么共享信号而不是一行 CSSPROPOSAL §7.5 给了一个非常关键的工程理由* { animation: none !important }能停掉 CSS 动画与过渡却停不掉 JS spring 的requestAnimationFrame循环以及它写入的内联transform/style。所以把app.css那条规则当作关闭开关是一条代码并未兑现的保证。当前仓库 app.css 的静态运动策略正是如此全局animation: none !important外加五条例外.v2-marquee…-track、.v2-spin、.near-process-icon、.near-comet、.oobe-card-reveal每条例外都带!important以压过全局规则并在media (prefers-reduced-motion: reduce)块内逐一重新抑制可参见 app.css 第 397 行与第 500–508 行。Phase 4 要做的是扩展这条纪律而不是替换它运动按组件 opt-inprefers-reduced-motion下回到当前静态基线。WS5 — 信息架构阶段 5Epic #7782让导航为 Agent 工作流让路WS5 聚焦 IA 重塑验收项重构导航/路由/页面结构——src/app/routes.ts、src/pages/、侧边栏、src/layout/gateway-layout.tsx路径均相对crates/product/ironclaw_webui/frontend/在合适处采用M3X navigation-rail 导航轨道模式并保持多通道multi-channel体验对等关键用户旅程CUJ验证不破chat、approvals、projects、settings 四条主链路逐一验证。从源码结构看上述被点名的文件均已存在routes.ts、gateway-layout.tsx以及src/pages/下的 chat、admin、automations 等特性视图——IA 阶段的任务是在这套既有骨架上重排而不是推倒重来。WS6 — 强制与 CI横切让治理可持续WS6 是不属于任何单一阶段、却贯穿始终的治理项.claude/rules/design-system.md随每个阶段保持更新且每次更新都维持优先级AGENTS.md是规范且工具中立Claude 规则只是补充[decision]可选 CI 任务playwright install chromiumpnpm test:storybook只有稳定后才提升为 required 门禁PROPOSAL §7.1。护栏按 WebUI 路径过滤触发、非阻塞、可一键删除且不影响其他 lanepnpm typecheckpnpm lint:conventionspnpm build-storybook每个阶段保持绿色每个 gating 阶段开启前先点名负责人PROPOSAL §7 问责规则在所属 Epic 上切出依赖子 issue 并指派给 §7.1–§7.6 的每一项每个[decision]连同拍板人记录到该 Epic 上设计治理单一归属禁止在本包之外再提出第二个DESIGN.md、token 集或 Storybook 工作台PROPOSAL §9。PROPOSAL §7 的问责规则值得单独强调依赖的负责人是承载其 gating 阶段的那个 Epic而具体负责人是该 Epic 依赖子 issue 的 assignee——子 issue 必须在 gating 阶段第一个 PR 打开前切出并指派带[decision]的项还需要把拍板人记录到 Epic 上。没有 assignee 的依赖、没有拍板人的 decision其阶段门禁保持关闭不会默认打开——这是把治理从意愿变成可执行状态机的关键机制。WS7 — 最终验收门禁100% 门WS7 是整个清单的收口每个有意义的 primitive/composite/component 都有 storypnpm test:storybook全绿light dark 对等与WCAG AA 对比度在 reskin 后依然成立WebUI 的主题、资产、交互与 IA 全面反映DESIGN.md中的 agentic-first 原则DESIGN.md Storybook 目录被证明是事实上的真相来源新 UI 必须经由它们构建每个阶段都在其所属 Epic 下落地链接回 canonical 表。六个依赖与它们的门禁状态PROPOSAL §7 把 Phases 3–5 的依赖整理成表每一项都标了 gating 阶段、所属 Epic、子 issue 与 assignee。截至该提案撰写时没有任何依赖有具名负责人因此所有门禁均为 closed——这是程序当前的真实状态而非表格疏漏。六项依赖速览#依赖Gating所属 Epic门禁7.1CI Playwright/Chromium 跑test:storybook横切#7038 closed ·[decision]提升为 required 需拍板7.2MSW 服务网络型 storyPhase 4 happy-path#7782 closed7.3深色面板推导含 §3.4 对比度不变量Phase 3#7781 closed7.4字体与许可证Phase 3#7781 closed ·[decision]Google Sans 替代需拍板7.5表现型运动Phase 4#7782 closed ·[decision]动画机制需拍板7.6合入顺序 / 堆叠 PRPhase 1→2 落地#7038 → #7781 closed注意WCAG AA 对比度验证不是第七行——它是常驻不变量§3.4由 7.3 的同一负责人在深色面板工作内部强制执行不可被拆成独立依赖。四条不变量从今天起的新增代码标准PROPOSAL §3 的五条不可妥协不变量是 WS 各阶段验收的共同底层其中两条1、5目前已经满足一条2存在已量化的缺口见上文 WS3 表格原生 M3X—— 用 React Tailwind --v2-*实现绝不引入md-*Lit Web 组件或并行框架当前已满足Token 驱动—— 组件中零硬编码 hex/px新增 tokenlight dark进app.css当前未满足缺口见 §3.1对新代码立即生效存量迁移在 Phase 3一组件一 story—— 每个有意义的组件有 colocated*.stories.tsx变更在 Storybook 中评审并由pnpm test:storybook覆盖可访问性基线—— WCAG AA 对比度、保留aria-*、键盘/焦点、lightdark 对等运动策略—— 表现型运动 opt-in 且prefers-reduced-motion门禁当前已满足五条例外各被 reduced-motion 抑制。当前状态与下一步截至该提案Phase 1#7750IN REVIEW未合入main原 #7039 已关闭并重建为非堆叠的 #7750Phase 2#7042PREPARED无公开 PR原 #7043 关闭changeset 保留等待 #7750 合入后基于main开新 PRPhase 3–5PLANNED依赖门禁全部 closed等待切子 issue、点名负责人、处理三个[decision]。建议的下一步 PR 顺序PLAN.md 给出先合 #7750 关掉 Phase 1在 Phase 3a 开启前点名负责人并切出 #7781 上的依赖子 issue深色面板对比度、字体/许可随后依次是 Phase 3a token 地基app.css 更新的Tokens/*stories不做组件 restyle、Phase 3b 原语 reskin、Phase 4a 运动地基reduced-motion 门禁 MSW、Phase 4b 首批 Agent 化组件composer 工具栏或 agent 活动卡片。结语一份可执行状态机式的完成清单CHECKLIST.md 的价值不在于罗列待办而在于它把设计系统做完这件事变成了可验证、可回退、有归属、有门禁的状态机每个勾选都必须点名合入 PR每个⚠都讲清先决条件每个 [decision] 都要求具名拍板人每个依赖都锚定到 Epic 归属表且未指派即关门。对任何想把设计系统治理从口号落成工程实践的前端团队来说这份清单本身就是一份可复用的模板——先量化缺口345 处像素 class、10 处硬编码 hex再定顺序token 先于 restyle再上护栏单 PR 可回退、dev-only 依赖可证明地不进生产 bundle最后用 CI 与归属表让治理自我持续。相关文档继续深入PROPOSAL.md决策与依赖详情· PLAN.md分阶段执行· README.mdEpic 归属表与层图· 前端 token 真相来源 app.css。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐stable-diffusion-webui-docker用户体验改进路线图分阶段实施计划stable diffusion webui docker用户体验改进路线图分阶段实施计划 一、现状分析与痛点诊断 1.1 当前架构评估 mermaid cl人工智能媒体生成本地部署容器编排IronClaw 前端治理体系APDD Governance Kit 分阶段集成计划全解Phase 0–4、CI 门禁与回滚IronClaw 前端治理体系APDD Governance Kit 分阶段集成计划全解Phase 0–4、CI 门禁与回滚 导读 本文以 docs/in人工智能AI 应用交互助手AI Agent干净状态检查清单Clean State Checklist为 Agent 会话收尾建立可验证的完成标准干净状态检查清单Clean State Checklist为 Agent 会话收尾建立可验证的完成标准 导读 本文围绕 learn harness eng上一篇ChatGLM3-6B vs 同类模型10项关键指标全面对比分析下一篇如何优化gte-base性能7个提升文本嵌入质量的关键策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考