component-docs

组件文档

1. 将 references/doc-format.md 中的标题列表粘贴到草稿中，留空。
2. 查找组件并阅读其代码、props 类型、样式和 stories，并分别按 references/sources.md 的格式记录为 Sources 行。
3. 找到两个真实用例，粘贴或通过调用点搜索找到；或者应用 sources.md 中的规则（少于两个用例）。
4. 检查下面的停止条件。如果符合其中一项，则返回停止格式并结束运行。
5. 追溯每个示例、变体、prop、状态和 token 分别来自哪个来源。每处不一致都在 Conflicts 下列为一行。
6. 按 doc-format.md 的顺序，根据来源事实填写各个部分。逐字复制 token 名称和示例代码。
7. 最后按照 doc-format.md（Usage）中的规则方法编写 Usage rules：每项都要有一个形态、一条依据、一项检查，以及一组 Don't 和 Do，并经过测试或删除。
8. 填写 Guessed at，并通过审查清单。
9. 如果条目属于规范，运行 doc-format.md（When the entry is a spec）中指定的检查，并将其最后一行放入状态块。

绝不提交：

• 没有列出来源的变体、prop、token 名称、示例或真实用例。计划中的用例要标明为计划用例。
• 为了通过规范检查而编造的状态或优先级规则。
• 没有引用规则却裁定的不一致。否则，双方的说法都要保留。
• 对正在记录的代码、stories 或规范所做的编辑。
• 由此技能发布的条目。它只是草稿，由协调器决定放在哪里，发布工作由其他人负责。

单个组件的草稿条目，只根据其来源所述内容编写。缺失信息要标明，不要补充；每项判断都要列出，供他人检查。不对设计作评价。同级条目链接相对于此技能的文件夹。

从请求提供的任何信息开始

只提供组件名称也足够。自行查找代码、stories 和调用点，只询问任何工具都无法获取的信息。如果指定了多个组件，只记录第一个，并列出其余组件。复合组件（Tabs 和 Tab）作为一个条目处理。若某个部分也被单独使用，则在 Description 下添加一个 ### Parts 小节。

协调器调用时

协调器会提供代码、变体列表以及真实或计划中的用例。将这些信息视为既定内容，不要提问，直接执行到底。Conflicts 和 Guessed at 应涵盖所有未决问题，调用方会将它们和 Gates 块转换为门槛，每项都附带默认值。

输出以状态行开头：Status: complete、Status: complete with NEEDS REVIEW (n)、Status: ready-with-gaps (<n> real uses) 或 Status: stopped: <condition>，接着是 Commit: none。直接运行时也使用相同的状态行。以文本形式返回包含各块的条目，或停止格式，不要写入其他文件。协调器负责保存条目，除非任务说明中的 SCOPE 指定了其路径。

输出

一条可直接粘贴的 Markdown 条目，然后在条目外附上以下块：

• Sources：每个来源一行，格式与 sources.md 中的记录一致。
• Conflicts：每处不一致一行，列出事实、各来源的说法，以及应用的引用规则；如果没有规则，则写 "no rule, not chosen"。
• Guessed at：每项判断一行，说明依据；若没有，则写 "Nothing guessed"。
• Gates：仅在规则要求时添加，并列出问题及其默认值。

直接运行时，将条目及其各块保存到 docs/system/<name>.md，并在第 1 行添加草稿注释，同时写入每个缺失的示例文件（doc-format.md，Examples）。回复以该路径开头，说明条目涵盖的内容及其状态。然后列出运行的每条命令及其退出代码、所有 Defect 行、最多三个带默认值的未决问题，以及包含一条待粘贴提示词的 Next:。回复中的所有计数都必须通过对草稿注释下方保存的文件运行 grep -o 得出。

条目通过审查清单后即可就绪；若为规范，则还需满足 check-spec.mjs 以 0 退出，或者所有剩余失败均在 Guessed at 下列出，并说明为何没有来源能够解决这些问题。

停止条件

搜索后仍缺少	停止原因	协调器接下来会做什么
代码	没有其他来源能说明变体、属性或行为	提供代码路径并重新运行，或者移除该组件并将其记录为缺口
变体列表（来自代码或故事）	猜测的变体列表记录的是另一个组件	提供属性类型或故事并重新运行，或者将其搁置为需要负责人处理的门槛
任何实际或计划中的用例	虚构的用例看起来像真的，读者会优先照搬	构建试点屏幕，或者提供简介中的一个屏幕作为计划用例，然后重新运行。绝不要自己编写条目

如果属性类型中没有变体属性，则变体列表为空，因此 Variants 显示为“None”，流程会继续。停止的流程会返回停止原因、按章节列出的迄今为止已找到的事实、下一步，以及解除阻塞所需的最简回复。对于缺少用例的情况，回复应为“一个屏幕名称、是什么让该组件出现在屏幕上，以及显示了哪个变体”。

其他情况都会继续。一个实际用例、计划用例和已弃用的前代组件均遵循 sources.md（用例少于两个）。冲突遵循 sources.md（来源之间的冲突）；看起来像 Bug 的行为则添加一行 Defect:（doc-format.md，状态）。缺少属性类型、令牌列表、规范、备注或无障碍指引时，标记为 NOT SUPPLIED、NEEDS REVIEW，或添加一行“猜测”。