Communitygithub.com

UX.md 生成器与结构审计器 (v1)

生成、提取、审计、预览、差异对比并验证 UX.md v1 结构化 UI/UX 规范。作为 DESIGN.md 和 AGENTS.md 的结构化伴侣,定义应用骨架(应用外壳、空间预算数学、滚动与 z-index 所有权、页面原型、路由可达性图、URL 状态持久化、覆盖层决策矩阵、4 状态视图契约以及强制性布局原语)。在初始化前端/UI 项目、从参考产品提取 UX 模式、审计现有代码库的布局漂移或添加新路由和视图时使用。

UX.md 生成器与结构审计器 (v1) 是什么?

UX.md 生成器与结构审计器是一个专门用于创建和维护规范化的 UX.md 文件的 AI 技能,该文件定义了应用的结构骨架和交互规则。它与 DESIGN.md(负责视觉标记)相辅相成,通过强制约束空间预算、滚动规则、z-index 所有权、路由可达性、视图状态契约和布局原语,防止 AI 编码智能体在跨会话中产生设计漂移。该技能基于六个零依赖的 Node.js 脚本,提供四种操作模式:绿地的合成模式、提取参考产品模式、审计现有代码库的逆向工程模式,以及功能添加时的迭代模式。它生成一个包含 12 个强制性部分的 UX.md 文件,并严格执行没有模糊形容词、没有死胡同路由的规定,同时强制执行布局原语,并可通过内置的 16 条规则检查器进行自动验证。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SolidStateNetwork/ux.md/tree/main/skills/ux-md-generator

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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

操作模式

  1. 合成(绿地 / init): 运行 extract-ux.mjs + generate-ux.mjs,根据项目上下文和 DESIGN.md 搭建初始的 UX.md,然后自定义路由、原型和领域规则。
  2. 从参考产品提取(参考产品或 URL): 从命名的参考产品(例如 Linear、ChatGPT Canvas、Stripe Dashboard、Shopify 或 Supabase)中提取空间外壳、交互规则、键盘快捷键和页面原型。
  3. 审计和逆向工程(现有代码库): 运行 extract-ux.mjs 以发现现有路由(src/app/**、src/pages/**、src/routes/**),检测结构漂移,并生成统一的 UX.md。
  4. 演进(功能添加 / 路由同步): 每当添加新页面或工作流时,更新第 3 节(页面原型)和第 4 节(导航、路由图与 URL 持久化),并通过 validate-ux.mjs UX.md --check-code 验证奇偶性。

三阶段生成管道

阶段 1:确定性提取和原型分类

  1. 运行 node .agents/skills/ux-md-generator/scripts/extract-ux.mjs .(或直接检查 package.json、AGENTS.md 和 DESIGN.md)以检测目标运行时、认证边界、现有路由和 DESIGN.md 断点。
  2. 加载 resources/archetype-taxonomy.md 并确认:
    • platform_profile:web-app | mobile-native | desktop-app | terminal-tui
    • archetype:b2b-saas-workspace | ai-chat-canvas | analytics-dashboard | ecommerce-storefront | developer-tool
  3. 可选地通过以下方式播种 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 持久化(Mermaid flowchart 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:交叉审计与机器验证

  1. 根据 resources/quality-checklist.md([UX-01] 至 [UX-16])审计生成的 UX.md。
  2. 运行自动化检查器脚本:
    node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code
    
  3. 解决所有报告的 error 或 warning 发现,并重新运行直到验证器以 0 errors 退出。

相关技能