frontend-docs

前端文档

根据代码证据，为前端应用编写客观的 Markdown 文档。只生成用户选择的文档类型；除非用户明确要求，否则不要创建完整的文档集。

文档选择

如果用户未指定文档类型，请让他们选择一种或多种：

用户需求	模板
前端架构与设计	templates/architecture-design.md
开发者入门	templates/developer-onboarding.md
差距分析与改进机会	templates/gap-analysis.md
路由、数据与状态契约	templates/route-data-contracts.md
组件系统与设计系统概览	templates/component-system-map.md

如果用户要求编写“前端文档”但未指定目标路径，请使用模板名称作为文件名，将选定的文件创建在 docs/frontend/ 下。如果仓库有更明确的文档规范，则遵循该规范。

参数规则：

• 将 --mode 视为选定的文档类型。
• 将 --frontendPath 视为要检查的前端路径、应用、路由组、领域系统、组件树或范围。
• 将 --outputPath 视为指定的 Markdown 目标路径。
• 如果未提供 --mode，则根据用户的措辞推断文档类型，或请用户选择。

选择规则：

• 如果请求提及组件、UI 系统、设计系统、组件清单、屏幕、状态、无障碍或视觉模式，则选择 component-system-map.md。
• 如果请求提及路由、导航、加载器、查询键、变更、适配器、API 调用、表单、状态契约或前后端集成行为，则选择 route-data-contracts.md。
• 如果主要目标是分析风险、代码异味、违规项、技术债务、无障碍问题、设计系统偏差、测试缺口或改进机会，则选择 gap-analysis.md。
• 如果主要目标是说明前端的组织方式或这样设计的原因，则选择 architecture-design.md。
• 只有在两种文档类型会产生实质不同的输出，且提示未明确体现更重要的读者需求时，才提出澄清问题。

工作流

第 1 步：确认范围

确定目标前端应用、包、路由组、领域系统、组件集、状态层或设计系统领域。如果请求范围较广，则先记录价值最高的部分，并注明其余未涵盖的范围。

记录：

• 文档类型和目标读者。
• 目标路径或文档规范。
• 可查明的前端技术栈和运行时。
• 文档应描述当前状态、拟议设计，还是两者都要描述。

步骤 2：了解规则和现有文档

阅读 references/discovery-workflow.md，然后先检查项目规则，再查看实现细节。

优先检查：

1. 项目说明：AGENTS.md、CLAUDE.md、DESIGN.md、.cursor/rules/、.windsurf/rules/、CONTRIBUTING.md。
2. 现有文档：docs/、架构说明、设计系统文档、入门文档、Storybook 文档、ADR/RFC。
3. 代码契约：路由定义、加载器、查询选项、API 适配器、模式、存储、上下文、组件、测试、故事、生成的路由树和令牌文件。

如果项目规则与此技能冲突，以项目规则为准。

在两个位置查找 DESIGN.md：仓库根目录和 docs/references/DESIGN.md。都要检查；如果两者都存在，则以根目录中的文件为准，并将内容不一致列为发现项。记录最终采用的路径，并在文档提及设计规则时引用该路径。

如果 DESIGN.md 在任一位置存在，则将其视为规范性的前端契约。在评估 UI、TSX、CSS、Tailwind、令牌、图标、间距、排版、动效、文案、无障碍性或组件模式之前，先加载该文件。

如果仓库使用 systems/<domain>/，则在编写文档前加载 references/feature-system-contracts.md。对于功能/领域文档，将 app-renderer-systems 视为主要的本地架构视角。

如果选择了 --mode gap-analysis，则将捆绑的 UI 质量参考资料以及 baseline-ui、frontend-design、interface-design、interaction-design 和 web-design-guidelines 视为可见产品界面的默认资料来源。使用这些资料识别可用性、组件状态、令牌规范、无障碍性、视觉层级、微文案、动效、深色模式、响应式行为和反默认模式方面的差距。除非用户要求，否则不要另行生成 UI 审查报告。

步骤 3：从代码中收集证据

从入口点追踪前端，直到用户可见的行为。使用文件引用，而不是粘贴大段代码。

检查：

• 应用引导、路由器设置、提供程序、布局外壳、主题/设计系统集成和全局样式。
• Vite 配置、React 插件、Tailwind 插件、TanStack Router 插件顺序、生成的路由树处理、别名、环境变量公开方式，以及构建/预览脚本。
• 路由、加载器、路由守卫、搜索参数、导航、懒加载路由、错误和加载中组件。
• 领域系统、systems/<domain>/ 边界、适配器、查询键、查询选项、钩子、变更、表单、模式、存储、上下文、守卫和公共导出入口。
• 组件、基础组件、变体、状态矩阵、无障碍模式、设计令牌、响应式行为和深色模式。
• TSX/CSS 是否符合 DESIGN.md：原始十六进制/RGB/HSL 颜色、硬编码的 Tailwind 颜色、内联样式、魔法间距/圆角/尺寸值、图标系列用法、排版工具类/类名、令牌文件、CSS 变量和文档记录的例外情况。
• 面向用户界面的 UI 质量差距：界面职责不清、缺少状态矩阵、层级薄弱、文本溢出、虚假交互、通用 CTA、占位文案、用表情符号充当图标、默认 SaaS/AI 视觉风格、未经验证的对比度、缺少 focus-visible 行为、缺少减少动态效果的处理、未经测试的深色模式，以及对性能敏感的视觉模式。
• 测试、故事、视觉验证、Playwright 覆盖范围、模拟/伪造实现，以及已知的测试缺口。
• 对性能敏感的区域：大型表格、图表、虚拟列表、图像、包边界、Suspense/懒加载，以及不必要的客户端状态。

将事实标记为“观察结果”；对于代码或文档未直接说明的结论，将其标记为“推断”。

第 4 步：仅加载相关参考资料

采用渐进式披露：

• 若要了解文档结构和简洁性，请阅读 references/documentation-principles.md。
• 若要了解前端证据收集和源技能路由，请阅读 references/source-skill-map.md。
• 若要了解 systems/<domain>/ 的功能架构、适配器、查询选项、钩子、存储、上下文、守卫和导出入口，请阅读 references/feature-system-contracts.md。
• 如果任一位置存在 DESIGN.md，请阅读 references/design-system-compliance.md。
• 如果选择了 --mode gap-analysis，且范围包含可见 UI，请阅读 references/ui-quality-gap-lens.md。
• 若要了解 React、系统、路由/数据、UI、无障碍、设计系统、测试和质量检查，请阅读 references/frontend-quality-lenses.md。
• 若要了解 React、TanStack Router/Query、Zustand、Storybook、shadcn/Radix、Tailwind、无障碍或设计系统的具体内容，请阅读 references/framework-contract-notes.md。
• 如果 UI 质量问题需要确定性证据，请从此技能根目录运行只读辅助工具：node scripts/detect-token-drift.mjs <source-dir> 用于检测原始颜色偏差，或运行 node scripts/check-contrast.mjs --fg <color> --bg <color> / --json <file> 检查对比度。
• 根据所选文档类型，只阅读 templates/ 中匹配的模板。

第 5 步：编写 Markdown 文档

以所选模板为结构依据。文档应简洁实用，符合目标读者的需求。

每份生成的文档都应：

• 以范围、受众和最近审阅日期开篇。
• 在可能的情况下，引用具体代码或文档证据，并注明文件路径和行号。
• 将当前状态与建议分开。
• 清单、路由、契约、状态、差距和后续行动优先使用表格呈现。
• 仅在图示有助于说明所有权、路由、数据流或组件关系时加入图示。
• 标明未知信息和假设，不得臆造缺失细节。
• 以简短的维护说明收尾，解释何时应更新文档。

第 6 步：完成前进行验证

提交最终回复前：

• 重新阅读生成或编辑的文档。
• 检查是否遵循了所选模板。
• 检查每项不明显的说法是否有证据支持，或是否标注为推断。
• 检查是否未生成无关模板。
• 检查链接和文件路径。
• 检查 systems/<domain>/ 代码库是否依据功能系统契约评估，而非依据通用 React 文件夹建议评估。
• 检查仓库根目录或 docs/references/ 中存在 DESIGN.md 时，是否已结合前端 TSX、CSS、令牌文件和已记录的例外进行评估。差距分析文档必须报告此项扫描的发现，或明确列出“未发现问题”。
• 检查包含可见 UI 的差距分析文档是否包含 UI 质量通过/未通过项，或涵盖状态矩阵、无障碍底线、令牌使用规范、微文案、动效/深色模式/响应式行为和反默认模式的发现。
• 检查有关 React、Vite、TanStack Router、TanStack Query、Tailwind CSS 和项目设计系统的说法是否来自项目证据、本地技能或当前文档。
• 如果存在用于文档格式检查或 Markdown lint 的验证命令，请运行项目首选命令。

输出规则

• 除非仓库中有明确记录的文档语言，否则使用用户所用的语言。
• 使用简洁的技术性文字。避免宣传性语言和泛泛而谈的说法。
• 不要重复粘贴大段源代码。应链接到源文件路径。
• 除非用户选择了相应文档形式，或仓库惯例要求，否则不要擅自创建 ADR、RFC、PRD 或设计规范。
• 编写文档时不要实现前端改动。如果发现缺漏，应将其记录为建议。
• 如果有代码证据，不要仅凭截图描述 UI 质量；请引用代码、文档、故事文件或渲染验证来源。
• 不要把输出写成 React、Vite、Tailwind 或 TanStack 教程。只有当框架行为会影响项目特定发现、契约或入门步骤时，才予以说明。
• 不要建议违反仓库本地 systems/<domain>/ 或路由惯例的目录迁移。
• 除非已根据 TSX 和 CSS 证据（包括令牌用法和例外情况）核对 DESIGN.md 规则，否则不要声称前端遵循了设计系统。
• 除非已根据源代码证据、测试／故事文件、渲染验证检查 UI 质量风险，或明确将其列为未知项，否则不要将差距分析中的 UI 部分标记为健康。

示例

架构与设计

用户说：“为仪表板应用编写前端架构文档。”

操作：选择 templates/architecture-design.md，检查项目规则和前端应用代码，梳理应用引导、路由、系统、状态、设计系统集成、测试和风险。

入门指南

用户说：“编写入门文档，让新的前端开发人员了解这个应用。”

操作：选择 templates/developer-onboarding.md，确定设置命令、应用入口、路由／数据流、组件约定、设计系统规则和安全的首次修改路径。

差距分析

用户说：“找出这个系统中的前端架构问题和文档缺漏。”

操作：选择 templates/gap-analysis.md，结合项目规则，从 React、路由、服务端状态、客户端状态、组件、设计系统、UI 质量、无障碍、性能和测试等角度进行评估。

路由与数据契约

用户说：“为账单 UI 编写路由加载器、查询键、变更操作和 API 适配器的文档。”

操作：选择 templates/route-data-contracts.md，追踪路由归属、加载器／查询契约、适配器调用、表单、变更操作、缓存失效、错误和副作用。

功能系统文档

用户说：“记录 accounts 系统，并告诉我们它是否遵循前端系统模式。”

操作：根据所需结果选择 templates/architecture-design.md 或 templates/gap-analysis.md，加载 references/feature-system-contracts.md，并根据目录布局、依赖流、查询选项、适配器契约、钩子、存储、上下文、守卫和公共导出入口评估 systems/accounts/。

组件系统图谱

用户说：“梳理账户设置组件及其对设计系统的依赖。”

操作：选择 templates/component-system-map.md，盘点组件、变体、状态、基础组件、令牌、无障碍行为、故事文件／测试和建议补充的文档。