agentleFS
Sign inStart free
arla6kaarla6ka/design.how/skills/component-docs/SKILL.md

component-docs

Skill281 starsChanged 27 days agoMITView on GitHub

Use to write one component's documentation entry from its code, stories and real call sites, such as "document the button", "write docs for Select", "what states does Toast have", or usage rules for a new or changed component. Not for foundations or pages that span components, which no skill here writes, nor for changing the component, which is build-design-system.

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 1

    1. arla6ka/skills★ 281100% same

    Edited · 0

    None found.

    Wrote their own version · 2

    1. Kong/insomnia★ 40ksame name
    2. dylantarre/design-system-skills★ 50same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository5 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never write a variant, prop, token name, example or use that has no listed source.

    line 36
  2. Distinctive:

    Never invent a state or a precedence order to make a section look complete.

    line 37
  3. Distinctive:

    Do not edit the code, stories or spec being documented.

    line 40
  4. Very specific:

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

    line 45

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Steps

  1. Paste the nine headings from references/doc-format.md into the draft, empty.
  2. Find the component. Read its code, props type, styles and stories, and record each as a Sources line.
  3. Find two real uses, by call-site search or from the ask. One real use or none changes the stop table below.
  4. 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".
  5. Fill each section from sourced facts, copying token names and example code character for character.
  6. 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.
  7. Fill Guessed at, one line per judgement call. Reread the draft against the Done list below.

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.

Stops

Missing after searchingWhy it stops
The codeNothing 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 plannedInvented 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").

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.

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>.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free