UX.md 生成器与结构审计器 (v1) 是做什么的?
概述
虽然 DESIGN.md 指定视觉标记(颜色、字体、圆角、阴影、间距比例),但 UX.md 则指定应用的结构骨架和交互规则。
没有 UX.md,AI 编码智能体会在会话间出现漂移:混合容器宽度、移动主要 CTA、在模态框和抽屉之间随意切换、遗漏空状态或错误状态、在 F5 刷新后丢失过滤器状态以及引入死胡同路由。
此技能通过一个三阶段管道跨四种模式运行,该管道由 scripts/ 中的六个零依赖 Node.js 脚本提供支持。
附带的 CLI 脚本
| 脚本 | 用途 | 示例用法 |
|---|---|---|
scripts/extract-ux.mjs | 将 package.json、AGENTS.md、DESIGN.md 以及源路由(src/app、src/pages)扫描为结构化 JSON。 | node .agents/skills/ux-md-generator/scripts/extract-ux.mjs . --output ux-scan.json |
scripts/generate-ux.mjs | 根据原型、产品预设(--preset linear)或 ux-scan.json 搭建一个 12 个章节的 UX.md。 | node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --preset linear --project "Acme" --output UX.md |
scripts/validate-ux.mjs | 运行 16 条确定性结构规则和 --check-code 检查器规则(路由奇偶性、原语、死处理程序、异常 z-index)。 | node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code |
scripts/scaffold-ux.mjs | 从 UX.md 生成 ux-contract.css 自定义属性和 React/TypeScript 布局原语(AppShell.tsx、PageHeader.tsx、PageSection.tsx、DataStateBoundary.tsx)。 | node .agents/skills/ux-md-generator/scripts/scaffold-ux.mjs UX.md --out-dir src/components/ux |
scripts/preview-ux.mjs | 生成一个独立的、响应式的 ux-preview.html 交互式线框模拟器。 | node .agents/skills/ux-md-generator/scripts/preview-ux.mjs UX.md --output ux-preview.html |
scripts/diff-ux.mjs | 比较两个 UX.md 文件的路由、原型、预算或阈值回归。 | node .agents/skills/ux-md-generator/scripts/diff-ux.mjs UX.old.md UX.md --json |
操作模式
- 合成(绿地 /
init): 运行extract-ux.mjs+generate-ux.mjs,根据项目上下文和DESIGN.md搭建初始的UX.md,然后自定义路由、原型和领域规则。 - 从参考产品提取(参考产品或 URL): 从命名的参考产品(例如 Linear、ChatGPT Canvas、Stripe Dashboard、Shopify 或 Supabase)中提取空间外壳、交互规则、键盘快捷键和页面原型。
- 审计和逆向工程(现有代码库):
运行
extract-ux.mjs以发现现有路由(src/app/**、src/pages/**、src/routes/**),检测结构漂移,并生成统一的UX.md。 - 演进(功能添加 / 路由同步):
每当添加新页面或工作流时,更新第 3 节(页面原型)和第 4 节(导航、路由图与 URL 持久化),并通过
validate-ux.mjs UX.md --check-code验证奇偶性。
三阶段生成管道
阶段 1:确定性提取和原型分类
- 运行
node .agents/skills/ux-md-generator/scripts/extract-ux.mjs .(或直接检查package.json、AGENTS.md和DESIGN.md)以检测目标运行时、认证边界、现有路由和DESIGN.md断点。 - 加载 resources/archetype-taxonomy.md 并确认:
platform_profile:web-app|mobile-native|desktop-app|terminal-tuiarchetype:b2b-saas-workspace|ai-chat-canvas|analytics-dashboard|ecommerce-storefront|developer-tool
- 可选地通过以下方式播种
UX.md:node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --archetype <archetype> --project "<Project Name>" --output UX.md
阶段 2:特定领域的 12 章节合成
加载 resources/ux-md-format.md、resources/layout-primitives.md 和 resources/writing-style-guide.md。在仓库根目录定制 UX.md,包括:
- YAML frontmatter: 完整配置(
spec_version: "1.0"、shell_budget、z_index_scale、thresholds、layout_primitives)。 - 按顺序的章节
0到11:## 0. 产品与领域拓扑## 1. 空间架构与应用外壳(ASCII 线框和视口预算表)## 2. 滚动、视口与 Z-Index 契约## 3. 核心页面原型(蓝图)(使用### 原型:<ArchetypeID>标题)## 4. 导航、路由图与 URL 持久化(Mermaidflowchart LR、路由可达性表以及状态持久化矩阵)## 5. 覆盖层与反馈决策矩阵(字段计数和px阈值)## 6. 强制视图状态(4 状态矩阵)(加载、空、错误、已填充)## 7. 变更、表单与权限人体工程学(isDirty守卫、2 层破坏性规则、3 路权限门)## 8. 真实数据压力、密度与截断(单一列表缩放模式、min-w-0 truncate、-空单元格占位符令牌、tabular-nums)## 9. 响应式重排与输入编排(折叠顺序、>= 44x44px触控目标及其>= 8px间距、悬停交互的点击等效项、安全区域滚动内边距)## 10. 强制布局原语(代码契约)(<AppShell>、<PageHeader>、<PageSection>、<DataStateBoundary>)## 11. 项目注意事项与智能体提示指南
编写约束:
- 零模糊形容词: 不要编写 "小表单"、"整洁布局"、"慢请求" 或 "直观导航" 而不给出明确数字(
<= 4 fields、1280px、>= 150ms)。参见 resources/anti-patterns.md。 - 零死胡同: 第 4 节中的每条路由都引用第 3 节中的一个有效
<ArchetypeID>,并同时定义进入触发器和退出/取消回退。 - 强制执行布局原语: 确保所有路由都包含第 10 节中定义的 4 个强制布局原语(
<AppShell>、<PageHeader>、<PageSection>、<DataStateBoundary>)。
阶段 3:交叉审计与机器验证
- 根据 resources/quality-checklist.md(
[UX-01]至[UX-16])审计生成的UX.md。 - 运行自动化检查器脚本:
node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code - 解决所有报告的
error或warning发现,并重新运行直到验证器以0 errors退出。