component-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Component documentation

组件文档

A draft entry for one component, built only from what its sources say. Gaps are marked, not filled, and every judgement call is listed for a person to check. It does not judge the design and does not publish. The format and checklist are in

references/doc-format.md

, finding and recording sources in

references/sources.md

. Sibling links are relative to this skill's folder.

单个组件的文档条目草稿，仅基于来源资料生成。缺口会被标记而非补全，所有判断决策都会列出供人工核查。本技能不评判设计，也不负责发布。格式和检查清单见

references/doc-format.md

，来源的查找与记录规则见

references/sources.md

。同级链接均相对于本技能的文件夹。

Start from whatever the ask gives

从需求提供的任意信息开始

A component name is enough. Find the code, stories and call sites yourself, and ask only for what no tool can reach. Of several named components, document the first and list the rest. A compound component (

Tabs

with

Tab

) is one entry. A part also used on its own gets a

### Parts

subsection under Description.

只需提供组件名即可。你可以自行查找代码、stories 和调用点，仅在工具无法获取信息时才发起询问。若需求指定了多个组件，仅为第一个编写文档，其余的列出即可。复合组件（包含

Tab

的

Tabs

）算作一个条目。若组件的某个部分也可独立使用，需在描述章节下添加

### Parts

子小节。

When a coordinator calls it

当协调器调用本技能时

A coordinator passes the code, the variant list and real or planned uses. Take them as given and run to the end without asking. Conflicts and Guessed at carry every open question, and the caller turns them and the Gates block into gates.

Start the output with a status line,

Status: complete

Status: complete with NEEDS REVIEW (n)

Status: ready-with-gaps (<n> real uses)

Status: stopped: <condition>

, then

Commit: none

. A direct run uses the same status line. Return the entry with its blocks, or the stop shape, as text, and write no other file. The coordinator saves the entry, unless the brief's SCOPE names its path.

协调器会传入代码、变体列表以及实际或计划的使用场景。直接使用传入的信息运行至结束，无需额外询问。所有未解决的问题都会记录在 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 中指定了路径，否则由协调器负责保存文档条目。

Steps

步骤

Paste the skeleton. Copy the heading list from
```
doc-format.md
```
into the draft, empty.
Find the component and read its code, props type, styles and stories. Done when each has a Sources line, recorded as
```
sources.md
```
says.
Find real uses, pasted or found by searching call sites. Done when two uses meet the definition in
```
sources.md
```
, or its Fewer than two uses applies.
Check the stops. If one applies, return the stop shape and end the run.
Trace and compare. Note which source supplied each example, variant, prop, state and token. Done when every difference between sources that state the same fact is a line under Conflicts.
Fill each section from sourced facts, in order, per
```
doc-format.md
```
. Copy token names and example code character for character. Done when every section is filled or marked.
Write Usage rules last, by the rule method in
```
doc-format.md
```
(Usage). Done when each rule has a shape, a ground, a check and a Don't and Do pair, and passed its tests or was cut.
Close out. Fill Guessed at. Done when the review checklist passes.
Spec check. When the entry is a spec, run the check
```
doc-format.md
```
(When the entry is a spec) names. Fix each failure from a source or mark the gap, and never invent a state or a precedence to pass. Done when the check's last line is in the status block.

粘贴骨架。 将
```
doc-format.md
```
中的标题列表复制到草稿中，保持内容为空。
定位组件，阅读其代码、props 类型、样式和 stories。当每一项都有对应的 Sources 行（按
```
sources.md
```
要求记录）时，本步骤完成。
查找实际使用场景，可直接粘贴或通过搜索调用点获取。当找到2个符合
```
sources.md
```
定义的使用场景，或符合「少于2个使用场景」的规则时，本步骤完成。
检查停止条件。 如果满足任一停止条件，返回停止状态结构并结束运行。
追溯与比对。 记录每个示例、变体、prop、状态和 token 的来源。当表述同一事实的不同来源之间的所有差异都在 Conflicts 区块中记录为一行时，本步骤完成。
填充每个章节，按照
```
doc-format.md
```
的要求，依序使用有来源的事实内容。token 名称和示例代码需逐字复制。当所有章节都已填充或标记状态时，本步骤完成。
最后编写使用规则，按照
```
doc-format.md
```
（Usage 章节）中的规则方法编写。当每条规则都包含结构、依据、检查方式，以及一组 Do/Dont't 示例，且通过测试或被裁撤时，本步骤完成。
收尾。 填充 Guessed at 区块。当评审检查清单通过时，本步骤完成。
规范检查。 若该条目是规范文档，运行
```
doc-format.md
```
（「当条目为规范时」小节）中指定的检查项。对于每个未通过项，要么从来源中找到依据修复，要么标记为缺口，绝不能为了通过而虚构状态或优先级。当检查的最后一行出现在状态块中时，本步骤完成。

Output

输出

One Markdown entry, ready to paste, then these blocks outside it:

Sources, one line per source, as
```
sources.md
```
records it.
Conflicts, one line per disagreement: the fact, each source's version, and the quoted rule applied or "no rule, not chosen".
Guessed at, one line per judgement call with what it rests on, or "Nothing guessed".
Gates, only when a rule adds one: the question and its default.

On a direct run, save the entry with its blocks to

docs/system/<name>.md

with a draft comment on line 1, and write each missing example file (

doc-format.md

, Examples). The reply opens with that path, what the entry covers and its status. Then each command run with its exit code, any Defect lines, up to three open questions with defaults, and

Next:

with one prompt to paste. Every count in the reply comes from

grep -o

on the saved file below the draft comment.

The entry is ready when it passes the review checklist, and for a spec when

check-spec.mjs

exits 0 or every remaining failure is under Guessed at with why no source settles it.

一份可直接粘贴的 Markdown 文档条目，其外包含以下区块：

Sources：每个来源占一行，按
```
sources.md
```
的要求记录。
Conflicts：每个分歧占一行，内容包括：事实描述、各来源的版本、所引用的判定规则，或是「无规则，未选择」。
Guessed at：每个判断决策占一行，说明其依据；若无推测则写「Nothing guessed」。
Gates：仅当规则添加了门槛时存在，内容包括问题及其默认值。

直接运行时，将带所有区块的文档条目保存到

docs/system/<name>.md

，并在第一行添加草稿注释，同时补全所有缺失的示例文件（参考

doc-format.md

的 Examples 章节）。回复开头需包含该路径、条目覆盖范围及其状态。随后列出每个运行的命令及其退出码、所有 Defect 行、最多3个带默认值的未解决问题，以及

Next:

后跟一个可粘贴的提示。回复中的所有统计数据均来自对保存文件（草稿注释以下部分）执行

grep -o

的结果。

当文档条目通过评审检查清单时即为就绪；若为规范文档，则需

check-spec.mjs

退出码为0，或所有剩余未通过项都已记录在 Guessed at 中，并说明无来源可判定的原因。

Stops

停止条件

Missing after searching	Why it stops	The coordinator does next
Code	Nothing else sources the variants, props or behavior	Pass the code path and rerun, or drop the component and log it as a gap
Variant list, from code or stories	A guessed variant list documents a different component	Pass the props type or stories and rerun, or park it as a gate for the owner
Any use, real or planned	Invented uses read like real ones, and readers copy them first	Build the pilot screen, or pass one screen from the brief as a planned use, then rerun. Never write the entry itself

A props type with no variant prop is an empty list, so Variants reads "None" and the run continues. A stopped run returns the stop, the facts sourced so far by section, the next step, and the smallest reply that unblocks it. For missing uses, that is "one screen name, what put the component there, and which variant showed".

Everything else continues. One real use, planned uses and a deprecated predecessor follow

sources.md

(Fewer than two uses). Conflicts follow

sources.md

(Conflicts between sources), and a behavior that looks like a bug gets a

Defect:

line (

doc-format.md

, States). A missing props type, token list, spec, notes or accessibility guidance becomes

NOT SUPPLIED

NEEDS REVIEW

or a Guessed at line.

搜索后仍缺失的内容	停止原因	协调器后续操作
代码	没有其他来源可以提供变体、props 或行为信息	传入代码路径后重新运行，或舍弃该组件并记录为缺口
变体列表（来自代码或 stories）	推测的变体列表会导致文档描述的并非实际组件	传入 props 类型或 stories 后重新运行，或将其作为门槛留给组件负责人处理
任何使用场景（实际或计划的）	虚构的使用场景看起来会像真实的，读者会优先照搬	构建试点页面，或从需求中选取一个页面作为计划使用场景，然后重新运行。绝不要直接编写文档条目

如果 props 类型中没有变体相关的 prop，变体列表即为空，因此 Variants 章节会显示「None」，流程继续运行。停止的运行会返回停止原因、目前按章节整理的有来源事实、下一步操作，以及能解除阻塞的最简短回复要求。对于缺失使用场景的情况，要求是「提供一个页面名称、该组件被放置在页面上的原因，以及展示的是哪个变体」。

其他情况都继续运行。单个实际使用场景、计划使用场景以及已废弃的前置版本，均遵循

sources.md

中的「少于2个使用场景」规则。冲突处理遵循

sources.md

中的「来源间冲突」规则；看起来像 bug 的行为会添加一行

Defect:

标记（参考

doc-format.md

的 States 章节）。缺失的 props 类型、token 列表、规范、说明或无障碍指南，会标记为

NOT SUPPLIED

、

NEEDS REVIEW

或添加到 Guessed at 区块中。

Hard limits

硬性限制

Every variant, prop, token name, example and real use comes from a listed source. A planned use says planned.
A conflict stays open with both sides shown, or is settled by a quoted rule.
The skill never edits the code, stories or spec it documents.
The entry is a draft. A coordinator decides where it goes, and publishing belongs to the person.

所有变体、prop、token 名称、示例和实际使用场景都必须来自列出的来源。计划使用场景需标注为 planned。
冲突要么保持开放并展示双方观点，要么通过引用的规则判定。
本技能绝不会编辑它所记录的代码、stories 或规范。
文档条目是草稿。由协调器决定其存放位置，发布权归人工所有。