extract-saas-design

提取 SaaS 设计

以取证方式记录已实现的 SaaS 仪表板、管理面板或内部工具的视觉系统，并整理为结构化 Markdown。输出应为文档和解析后的设计令牌，而不是生成的 UI 代码。

何时使用此技能

当请求符合以下任一意图时使用：

• “从这个仪表板 URL 提取设计系统”——在线 SaaS 应用、管理面板或内部工具。
• 从代码库、仓库或 HTML 快照中“记录设计令牌” / “提取视觉系统” / “提取视觉 DNA”。
• 从 globals.css、@theme、tailwind.config.* 或令牌文件中“记录颜色、字体、间距、圆角、阴影令牌”。
• “记录侧边栏 / 表格 / 命令面板 / 表单布局”——来自真实实现的指定组件。
• 根据已实现的系统，审查颜色、间距或无障碍的一致性，并以证据为依据。
• 从正在运行的仪表板中“提取深色模式令牌” / “记录模式切换”。
• “交接设计系统”，以便其他团队或代码库复现现有外观。
• “提取仪表板的图表配色 / 密度分区 / 侧边栏覆盖样式”。

以下情况请勿使用此技能：

• 用户要求构建、移植、克隆、恢复、转换或交付可运行的 UI。请转交给 convert-url-to-nextjs。
• 用户要求重新设计、重设样式、“让它更好”，或征求推测性的 UX 建议。此技能绝不提出改进建议——只记录现状。
• 来源只有 Figma、截图或视觉参考，没有可检查的实现（没有 DOM、CSS 或代码）。
• 目标是营销 / 宣传网站，而不是 SaaS / 仪表板 / 管理产品。

硬性规则（关键要求）

规则	重要原因
记录，不要重建。 仅在 .design-soul/ 中输出 .md 文档。	生成 UI 代码就偏离了此技能的用途。
将每条令牌链解析到最终值。 bg-primary → var(--primary) → oklch(0.205 0 0)。只在字面值处停止。	类名和别名对复现者毫无用处。
遵守范围。 如果用户要求记录侧边栏，就不要记录整个应用。	扩大范围会损害交付成果。
缺失也是证据。 写明 Hover: not implemented、Loading: not implemented、Dark mode: not implemented。	承认缺失总好过凭空编造状态。
区分规范与噪声。 记录主要模式，再列出不一致之处及文件引用。	掩盖不一致会隐藏 Bug。
源码优先于截图。 组件源码和 CSS 令牌是主要依据。DOM / 计算样式为次要依据。截图仅用于验证布局。	截图无法如实呈现伪状态。

输出约定

所有成果都放在目标代码库根目录下的 .design-soul/ 中（而非此技能仓库中）。默认交付内容按范围划分如下：

范围	文件
完整提取 / “视觉 DNA”	system.md、编号基础文档、每个组件各一份编号文档、INDEX.md、_summary.md
仅基础 / 令牌	仅 system.md 和基础文档
指定组件	最少的基础背景 + 每个指定组件各一份编号文档
一致性 / 无障碍审查	基于证据的发现文档，以提取的令牌为依据——不进行重新设计

默认格式为包含 CSS 复现代码块的 Markdown。除非明确要求，否则不要生成 .tokens.json、Style Dictionary 或 Tokens Studio 文件。

准确的模板和文件夹结构：references/documentation/output-format.md、references/system-template.md、references/component-template.md。

工作流程

1. 明确任务

用一行重述范围：包含哪些内容、不包含哪些内容，以及哪些内容视为事实依据。默认采用满足请求的最小提取范围。

2. 检测样式技术栈（这是所有后续工作的前置条件）

先对目标根目录执行以下检查：

• Tailwind v4 — CSS 中有 @import "tailwindcss" 和 @theme {} 块。没有 tailwind.config.*。
• Tailwind v3 — 存在带有 theme.extend 的 tailwind.config.ts/js。
• shadcn/ui — 存在 components/ui/ 目录、来自 @/lib/utils 的 cn()，且通常使用 oklch() 颜色。
• CVA — class-variance-authority 定义变体／尺寸矩阵；cva() 调用本身就是规范。
• CSS 入口点 — 设计令牌位于 globals.css 或 app.css 中。
• 离线快照模式 — 纯 HTML+CSS，没有 package.json/src/。以 CSS 文件为唯一事实来源；针对特定框架的系统填写 not implemented / N/A。

目标根目录解析以及快照与仓库支持模式的处理方式：references/extraction/target-modes.md。

3. 收集证据

对于在线 URL 或可交互的本地应用，使用 run-agent-browser 捕获 DOM、计算样式、截图和状态覆盖情况。浏览器工具仅用于收集证据，切勿让它们偏离到重建工作。

将浏览器产物存放在目标代码库根目录下的 .design-soul/evidence/ 中：路由或页面名称、视口、截图路径、DOM／源文件路径、观察到的状态。

如需确定性的设计令牌清单，请对目标根目录运行辅助脚本：

• scripts/capture-css-tokens.md — 枚举 CSS 自定义属性。
• scripts/audit-spacing-scale.md — 统计间距尺度的使用情况。

4. 提取基础规范（适用时）

涵盖间距、颜色、字体、阴影／层级、圆角、动画和共享状态约定。对于仪表盘，还需涵盖侧边栏覆盖样式、图表调色板、密度区域以及表格／等宽字体的使用。

基础规范	参考资料
颜色（包括 oklch() 的读取方式、暗色模式链）	references/extraction/color-extraction.md
字体（字体栈、字号阶梯、行高）	references/extraction/typography-extraction.md
间距（尺度检测、密度区域）	references/extraction/spacing-extraction.md
图标和资源清单	references/extraction/icons-and-assets.md
基础规范提取提示词（子流程）	references/foundations-agent.md
仪表盘专属模式（侧边栏覆盖样式、图表调色板、密度）	references/dashboard-patterns.md
布局网格 + 响应式断点	references/layout/grid-and-responsive.md

5. 提取组件和模式（适用时）

记录每个组件的结构、变体、尺寸、状态、状态转换、暗色模式差异和组合方式。侧边栏、表格、命令面板和表单布局都是大型组件，应拆解为子部分和模式，不要将其扁平化。

在离线快照模式下，将重复的 DOM 片段及其选择器视为组件证据。仅记录快照能够证实的内容，并明确指出缺失的信息。

需求	参考资料
组件提取提示词（子流程）	references/components-agent.md
组件输出模板	references/component-template.md

6. 转换设计令牌

需求	参考资料
W3C DTCG、CSS 自定义属性、oklch() 格式	references/tokens/token-formats.md
shadcn 命名模式、语义层与原始层	references/tokens/naming-conventions.md

7. 交接前验证

宣布完成前，先运行验证清单。验收标准：重建者无需猜测任何值或状态。

需求	参考资料
交接前验证清单	references/quality-checklist.md
一致性审查清单	references/audit/consistency-checklist.md
无障碍／WCAG 对比度审查	references/audit/accessibility-review.md

特别留意：禁用、焦点可见、加载、错误／无效、空状态、暗色模式、不透明度语义、动画组合。

8. 打包输出

根据 references/documentation/output-format.md 中的结构，将所有产物放在目标代码库根目录下的 .design-soul/ 中。基础规范使用 references/system-template.md，组件使用 references/component-template.md。不要自创格式。

护栏

应该这样做	不要这样做
将 bg-primary、rounded-md、p-3 解析为实际值	停留在类名或别名层面
如果未实现，写明 Hover: not implemented	臆造“最佳实践”状态
将侧边栏／表格／表单拆解为子部分	把大型组件压成一整块
根据文件证据标记不一致之处	将其粉饰成更整洁的系统
让审计以证据为依据	偏离到重新设计或批评
记录组合方式和上下文	只孤立地描述组件

恢复规则

• 证据不完整： 查找相邻的事实依据（全局 CSS、主题文件、配置、Storybook、截图）。如果仍无法确认，请明确记录这一缺口。
• 代码库过大： 按基础规范 + 指定类别或组件拆分。不要悄然扩大范围。
• 不同文件中的值冲突： 记录主要模式，并列出带有来源引用的例外。
• 不存在深色模式／状态： 直白说明。缺失本身也是提取结果的一部分。
• 偏向实现： 停止生成构建说明；回到文档交付物。

面向 Agent 的指导说明

这些说明可以避免最常见的提取问题。

检测 Tailwind v4。 在 CSS 文件中搜索 @import "tailwindcss" 或 @theme——如果找到，项目使用原生 CSS 配置（没有 tailwind.config.js）。如果存在带有 theme.extend 的 tailwind.config.ts，则使用的是 v3。提取 Token 前务必先检查。检测命令：references/foundations-agent.md。

oklch 色彩空间。 现代 shadcn/ui（2024 年及以后）使用 oklch(L C H)。L = 亮度（0–1），C = 色度（0–0.4），H = 色相（0–360）。灰色的 C < 0.01。务必注明亮度，以区分深色和浅色。阅读指南：references/extraction/color-extraction.md、references/tokens/token-formats.md。

CVA 和 cn()。 cva() 调用本身就是组件的视觉规范——提取每个变体／尺寸的键值对。cn() 工具通过 tailwind-merge 合并类名，后面的类名优先。CVA 提取检查清单和 cn() 合并指南：references/component-template.md。

解析 Token 链。 不要停留在 Tailwind 类名层面。解析完整链路：bg-primary → var(--primary) → oklch(0.205 ...)。有些 Token 会经过多个变量链接——务必一直解析到字面值：references/extraction/color-extraction.md。

事实来源优先级

1. 组件源码 + CSS Token——首要来源。
2. 实时 DOM／计算样式 + Storybook——次要来源。
3. 截图——用于验证布局和状态覆盖；不要用它覆盖源码值。
4. Figma Token 同步——仅当已实现的代码库中包含 Token 同步产物时才记录。

与 convert-url-to-nextjs 的边界

此技能产出的是文档。convert-url-to-nextjs 根据快照产出可构建的 Next.js 应用。如果用户想交付可用的 UI，请转到该技能。如果他们想要一份供其他团队参考、以复现外观的交接文档，请留在这里。

最后提醒

此技能是一个编排器，而不是模板集合。保持主流程精简，详细内容交由参考资料说明，并以已实现的 UI 为依据，而不是重建或重新设计它。