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
, finding and recording sources in
. Sibling links are relative to this skill's folder.
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 (
with
) is one entry. A part also used on its own gets a
subsection under Description.
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 with NEEDS REVIEW (n)
,
Status: ready-with-gaps (<n> real uses)
or
Status: stopped: <condition>
, then
. 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.
Steps
- Paste the skeleton. Copy the heading list from 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 says.
- Find real uses, pasted or found by searching call sites. Done when two uses meet the definition in , 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 . 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 (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 (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.
Output
One Markdown entry, ready to paste, then these blocks outside it:
- Sources, one line per source, as 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
with a draft comment on line 1, and write each missing example file (
, 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
with one prompt to paste. Every count in the reply comes from
on the saved file below the draft comment.
The entry is ready when it passes the review checklist, and for a spec when
exits 0 or every remaining failure is under Guessed at with why no source settles it.
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
(Fewer than two uses). Conflicts follow
(Conflicts between sources), and a behavior that looks like a bug gets a
line (
, States). A missing props type, token list, spec, notes or accessibility guidance becomes
,
or a Guessed at line.
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.