Design systems
How to document components
Component documentation states the API, the states and the limits of one component. Here is the structure that survives review, with catalogue numbers.
Key points
- A useful page answers five questions: purpose, props, states, keyboard, limits.
- react-docgen (MIT) extracts types and defaults, not the intent behind the component.
- In the EneUI catalogue 403 of 1,556 blocks carry both a description and a category.
Documenting a component means writing its API, its states and its limits in a format another developer can read without opening the code. It is not a comment in the file, not a screenshot and not a catalogue page.
The five parts of a component page
A useful page answers five questions, always in the same order. If one is missing, the reader goes back to reading the code.
- Purpose: one sentence, no adjectives.
- Props: name, type, default value, whether it is required.
- States: default, hover, focus, disabled, loading, error.
- Keyboard and ARIA contract: which keys, which role, which label.
- Limits: what the component does not do and what is not supported.
The command: extract the types
npx react-docgen src/components/Button.tsxreact-docgen is an MIT project: it reads TypeScript types and default values and returns JSON. It builds the props table for you; it does not write the sentence that explains what the component is for, and that sentence stays your job.
A record that documents well
In the catalogue, Fumadocs zoomable image shows the description, the dependencies, the upstream licence and the install command in one place. The library is Fumadocs under the MIT licence, and you can also reach the record from the index of 111,985 components.
The limitation
No tool checks that the documentation is true. react-docgen extracts types, not behaviour: a badly documented component passes every test and every lint rule, and the wrong page stays online.
Where to continue
The shape of an installable record is in what a registry is. For the sections of a documentation page read blocks for documentation; the comparison between copied code and a library is in copy-paste or headless.
Frequently asked questions
What should component documentation contain?
Purpose in one sentence, props with type and default, visual states, the keyboard and ARIA contract, and the declared limits. If one part is missing, the reader has to open the code.
Is a comment in the source enough?
No. A comment explains a choice to someone who already knows the file; documentation serves someone who does not. The comment still helps, but it does not replace the page.
Do I need Storybook to document components?
No. Storybook is an MIT tool that helps with interactive states, but a static page with props and state screenshots covers most cases.
How do I document the states of a component?
One example per state, with the same content: default, hover, focus, disabled, loading, error. Only the state should change between examples.
Who writes the documentation?
Whoever writes the component, before opening the pull request. Documentation written afterwards by someone else describes what the code does, not what it should do.