component-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Component docs

组件文档

A draft entry for one component, built only from what its sources say. Gaps are marked, not filled. It does not judge the design and it publishes nothing. The heading order and a worked example are in

references/doc-format.md

为单个组件起草文档条目时，只能依据其来源明确说明的内容。缺失内容会被标记，而不会自行补全。它不评判设计，也不发布任何内容。标题顺序和完整示例见

references/doc-format.md

。

Steps

步骤

Paste the nine headings from
```
references/doc-format.md
```
into the draft, empty.
Find the component. Read its code, props type, styles and stories, and record each as a Sources line.
Find two real uses, by call-site search or from the ask. One real use or none changes the stop table below.
Trace which source gave each example, variant, prop, state and token. Every disagreement between sources is a line under Conflicts, with the quoted rule that settles it, or "no rule, not chosen".
Fill each section from sourced facts, copying token names and example code character for character.
Write Usage rules last. Each rule is
```
rule/<component>-<slug>
```
, a condition, an action, a reason, its evidence (two call sites, a measurement with its path, a named principle, or the person's words), and a
```
Don't:
```
line with real code that breaks it. A rule you cannot break with a snippet is cut.
Fill Guessed at, one line per judgement call. Reread the draft against the Done list below.

将
```
references/doc-format.md
```
中的九个标题粘贴到草稿中，各节内容保持为空。
找到该组件。阅读其代码、props 类型、样式和 stories，并将每一项记录为一行
```
Sources
```
。
通过调用点搜索或根据请求，找到两个真实用例。如果只有一个真实用例或没有真实用例，则按下方的停止表处理。
追踪每个示例、variant、prop、状态和 token 分别来自哪个来源。来源之间的每处不一致都应在
```
Conflicts
```
下单独占一行，并附上能够解决该冲突的规则原文；如果没有相应规则，则写明
```
no rule, not chosen
```
。
仅使用有来源依据的事实填写每个章节，逐字复制 token 名称和示例代码。
最后编写
```
Usage rules
```
。每条规则都采用
```
rule/<component>-<slug>
```
格式，并包含条件、操作、原因、证据（两个调用点、一项测量及其路径、一项命名原则，或请求者的原话），以及一行
```
Don't:
```
，其中应包含违反该规则的真实代码。如果无法用代码片段展示违反规则的情况，则删除该规则。
填写
```
Guessed at
```
，每项判断占一行。根据下方的
```
Done
```
列表重新核对草稿。

Output

输出

The entry, then Sources, Conflicts, Guessed at, and Gates (a question with its default) only where a rule adds one. Run on its own, it saves to

docs/system/<name>.md

with a draft comment on line 1 and writes each missing example file. The reply opens with the path, what the entry covers and its status, then up to three questions with defaults and one prompt the person can paste to take the next step.

先输出文档条目，然后输出

Sources

、

Conflicts

和

Guessed at

；仅当某条规则新增问题时，才输出

Gates

（一个问题及其默认值）。独立运行时，它会将文件保存到

docs/system/<name>.md

，在第 1 行添加草稿注释，并写入每个缺失的示例文件。回复开头应包含文件路径、条目涵盖的内容及其状态，随后最多提出三个附带默认值的问题，并提供一个用户可以直接粘贴以推进下一步的提示词。

Stops

停止条件

Missing after searching	Why it stops
The code	Nothing else sources the variants, props or behaviour
The variant list (props type or stories)	A guessed list documents a different component
Any use, real or planned	Invented uses read like real ones and readers copy them first

A props type with no variant prop is an empty list. Variants reads "None" and the run goes on. One real use, planned uses and a deprecated predecessor are marked as such, not stopped on. A stopped run returns the stop, the facts sourced so far by section, and the smallest reply that unblocks it ("one screen name, what put the component there, and which variant showed").

搜索后仍缺失	停止原因
组件代码	其他任何来源都无法说明 variant、prop 或行为
variant 列表（props 类型或 stories）	猜测出的清单会记录成另一个组件
任何用例（无论真实存在还是计划中）	虚构的用例看起来与真实用例无异，读者会首先照搬

如果 props 类型中没有 variant prop，则变体列表为空。

Variants

写作

None

，运行继续。只有一个真实用例、计划中的用例和已弃用的前代组件，都应按其实际状态标记，而不因此停止。运行停止时，应返回停止原因、目前按各章节整理出的已溯源事实，以及能够解除阻塞的最小回复（“提供一个界面名称、是什么将该组件放到该界面中，以及显示的是哪个 variant”）。

Rules

规则

Never write a variant, prop, token name, example or use that has no listed source. A planned use says planned.
Never invent a state or a precedence order to make a section look complete.
A behaviour that looks like a bug is written as it is, followed by a
```
Defect:
```
line to the owner with what goes wrong for the user and the smallest fix.
A part also used on its own gets a
```
### Parts
```
subsection under Description. A compound component (
```
Tabs
```
with
```
Tab
```
) is one entry.
Do not edit the code, stories or spec being documented.
Counts in the reply come from
```
grep -o
```
on the saved file, below the draft comment.

绝不记录没有列出来源的 variant、prop、token 名称、示例或用例。对于计划中的用例，必须明确写为
```
planned
```
。
绝不为使章节看起来完整而虚构状态或优先级顺序。
如果某项行为看起来像 bug，就按实际情况记录，随后添加一行
```
Defect:
```
，写给负责人，说明它会给用户带来什么问题以及最小修复方案。
如果某个组成部分也可以单独使用，则在
```
Description
```
下添加
```
### Parts
```
小节。复合组件（由
```
Tab
```
构成的
```
Tabs
```
）只记录为一个条目。
不编辑正在编写文档的代码、stories 或 spec。
回复中的计数必须来自对已保存文件执行
```
grep -o
```
的结果；这些计数位于草稿注释下方。

Done

完成标准

Every variant, prop, token and example has a Sources line. Every Usage rule has evidence and a

Don't:

line. Every conflict is shown. The nine headings are present in order, and a section with nothing sourced reads

Not applicable: <reason>

每个 variant、prop、token 和示例都有一行
```
Sources
```
。
每条
```
Usage rule
```
都有证据和一行
```
Don't:
```
。
每个冲突都已展示。
九个标题按既定顺序出现；没有任何已溯源内容的章节写为
```
Not applicable: <reason>
```
。