ln-114-frontend-docs-creator

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

前端文档创建器

类型： L3 Worker

用于创建 design_guidelines.md 的 L3 Worker。有条件调用——仅在项目包含前端时调用。

目的与范围

• 创建 design_guidelines.md（如果 hasFrontend）
• 接收来自 ln-110-project-docs-coordinator 的 Context Store
• 符合 WCAG 2.1 AA 级无障碍标准
• 编写设计系统文档
• 下游使用方： ln-401（Frontend Guard）和 ln-402（Frontend Review Checks）会加载 design_guidelines.md，根据实现进行运行时设计验证
• 不自行收集上下文；使用协调器提供的输入

调用（谁／何时）

• ln-110-project-docs-coordinator： 在以下情况下有条件调用：
  • hasFrontend=true（检测到 react、vue、angular、svelte）
• 绝不由用户直接调用

输入

来自协调器：

• contextStore：包含前端专属数据的 Context Store
  • DESIGN_SYSTEM（Material-UI、Ant Design、自定义）
  • COLOR_PALETTE（主色、辅助色、强调色）
  • TYPOGRAPHY（字体系列、字号、字重）
  • COMPONENT_LIBRARY（检测到的组件）
• targetDir：项目根目录
• flags：{ hasFrontend }

必须阅读： 加载 references/docs_quality_contract.md 和 references/markdown_read_protocol.md。 可选规则目录：仅在需要精确规则 ID、路径矩阵或允许的占位符例外时，加载 references/docs_quality_rules.json。

创建的文档（1 个，有条件）

文件	条件	问题	自动发现
docs/project/design_guidelines.md	hasFrontend	Q43-Q45	低

工作流

阶段 1：检查条件

1. 解析协调器传入的 flags
2. 如果 !hasFrontend：提前返回空结果

阶段 2：创建文档

1. 检查文件是否存在（幂等）
2. 如果存在：记录日志并跳过
3. 如果不存在：
   • 复制模板
   • 使用 Context Store 中的值替换占位符
   • 保留模板中的共享开篇约定和标准顶部章节
   • 填充设计系统章节
   • 发布的前端文档中绝不保留模板标记
   • 如果数据缺失：省略相关描述或使用简洁、中性的兜底文本，但不要输出 [TBD: ...]

阶段 3：自我验证

1. 检查 SCOPE 标签和元数据标记
2. 检查必需的顶部章节（Quick Navigation、Agent Entry、Maintenance）
3. 验证以下章节：
   • 设计系统（组件库）
   • 字体排版（字体系列、字号）
   • 颜色（十六进制代码、语义颜色）
4. 检查 WCAG 2.1 相关引用
5. 检查是否符合文档质量约定（无禁用占位符、无泄露的模板元数据、文档类型／角色有效）

阶段 4：返回状态

{
  "created_files": ["docs/project/design_guidelines.md"],
  "skipped_files": [],
  "quality_inputs": {
    "doc_paths": ["docs/project/design_guidelines.md"],
    "owners": {
      "docs/project/design_guidelines.md": "ln-114-frontend-docs-creator"
    }
  },
  "validation_status": "passed"
}

重要说明

核心规则

• 有条件调用： 如果未检测到前端，则完全跳过
• 符合 WCAG： 文档必须引用无障碍标准
• 设计令牌： 从 CSS 变量、tailwind 配置或主题文件中提取
• 幂等： 绝不覆盖现有文件
• 可发布输出： 前端文档中不得包含 [TBD: ...]、TODO 或泄露的模板元数据

NO_CODE_EXAMPLES 规则（必须遵守）

设计指南文档描述的是视觉标准，而非代码：

• 禁止： CSS 代码块、组件实现
• 允许： 表格（颜色、字体排版）、设计令牌、Figma 链接
• 替代代码的写法： “参见 组件库”或“参见 src/components/Button.tsx”

技术栈适配规则（必须遵守）

• 链接到正确的组件库文档（React 使用 MUI，Vue 使用 Vuetify）
• 引用框架专属模式（React hooks、Vue composition API）
• 绝不混用技术栈引用（Vue 项目中不得出现 React 示例）

格式优先级（必须遵守）

表格（颜色、字体排版、间距）> 列表（组件清单）> 文本

运行时摘要产物

**必须阅读：**加载 references/docs_generation_summary_contract.md

接受可选的 summaryArtifactPath。

摘要类型：

• docs-generation

必需的载荷语义：

• worker = "ln-114"
• status
• created_files
• skipped_files
• quality_inputs
• validation_status
• warnings

将摘要写入提供的产物路径，或在结构化输出中返回相同的信封。

完成定义

• 已检查条件（hasFrontend）
• 如适用，已创建文档
• 已记录设计系统、排版、颜色
• 已包含 WCAG 参考
• **已验证时效性：**文档中的所有事实均与当前代码一致（路径、函数、API、配置均存在且准确）
• 已返回状态

参考文件

• 模板：references/templates/design_guidelines_template.md
• 问题：references/questions_frontend.md（Q43-Q45）

---

**版本：**1.1.0 **最后更新：**2025-01-12