Documenting components so the next engineer does not guess

Component documentation is the note that stops the next engineer from guessing. It records the states the component can be in, and the things you must not do with it. A picture of the happy path is not documentation. The happy path is the one screen everyone already understands. The bugs live in the states nobody drew.

Write the note for a person who was not in the critique. They have the file open, a ticket, and an hour. They will invent a hover style, an error message, and a disabled look if you do not hand them one. Those inventions will be reasonable and wrong. The note is how the team stays one product.

What every note should answer

Four questions are enough.

1. What is this for? One sentence. A button submits or confirms. A field collects a single value. If you need three sentences, you may have two components.
2. What can it contain? The label, the icon, the optional hint. Say what happens when the label is long. Say whether the icon is decorative.
3. Which states exist? Name them. Default, hover, focus, disabled, error, loading. Omit the ones you do not support, and say they are omitted so nobody adds them "to be complete."
4. What should people refuse? The don'ts. Do not put two primary buttons in one row. Do not use the danger color for a neutral confirmation. Do not detach the text style.

That is a useful note. A gallery of every size on a colored background is a poster. Posters help a sales deck. Notes help a pull request.

Keep the words next to an example that uses real-looking content. "Submit" and "Email" teach more than "Button label" and "Lorem ipsum." Placeholder copy hides overflow, wrapping, and the awkward case where the error is longer than the field. Use a slightly too-long label in the note so the next person sees the wrap on purpose.

States are the document

Draw or build each state you claim. A list that says "includes error" and shows only the default field will be implemented as a red border with no message, because that is the fastest reading of an undescribed word.

For a text field, the states that matter are ordinary and easy to skip. Empty. Filled. Focused, with a visible ring. Error, with a message that says what to fix. Disabled, if something upstream locked it. Read-only, if that is different from disabled, which it usually is: the person can still select the value. Write the difference down. Teams conflate them, and then a disabled field swallows text nobody can copy.

For a button, specify loading if the click can take time. A button that stays in its idle label while the request runs will be clicked twice. Say whether the label changes, whether the width should stay stable, and what the focus does. Say that a disabled button still needs an explanation nearby if the person cannot tell why it is dead. The control's silence is not an explanation.

The W3C's Web Content Accessibility Guidelines are the right parent for two of these states in particular. Content should be perceivable and operable. A focus state that only changes color by a hair will be missed. An icon button with no accessible name will be announced as nothing. Put both in the note: where the focus ring sits, and what the accessible name is when the visible label is not text. The next engineer should not have to remember a guideline number. They should see the requirement beside the component they are editing.

Don'ts earn their space

A don't is a decision you already paid for in a critique. Write it down or you will pay again. The useful don'ts are specific.

• Do not use the primary button for navigation that could be a link.
• Do not stack a hint, an error, and a character count under one field unless the layout was designed for all three.
• Do not recolor the card to mean "selected" if selection is already shown by a checkbox. Two signals for one idea will drift apart.
• Do not add a drop shadow on this component to make it feel more important. Elevation, if you use it, is a token, not a local effect.

Vague don'ts waste the line. "Don't make it ugly" is not a note. "Don't set the label in a second typeface" is a note. Tie the refusal to the decision it protects.

Also write the don't that protects neighboring components. A menu item is not a button with different padding. If people restyle one into the other, both lose their meaning. Say which component to use for a command, and which to use for a choice. That single paragraph prevents a month of almost-menus.

An example, labeled as an exercise

Here is a note for a button, written as an exercise so the shape is clear. It is not a Hanabi client component. It is a pattern you can copy.

The button confirms the action named on its label. The label is a verb. It may include one icon, placed before the verb, and the icon is hidden from assistive tech because the verb is the name. States: default, hover, focus, disabled, loading. Loading keeps the same width, swaps the label for "Saving," and ignores further clicks. Do not use it for going to another page. Do not put two of the primary variety in the same cluster. The quiet variety is for the secondary action in that cluster.

An engineer can implement that without a meeting. A designer can review the result against it. If your real button needs a destructive variety, add four lines. Do not add a framework.

Notice what the exercise leaves out. It does not specify a marketing slogan, a shadow recipe, or a philosophy of clicks. Those belong in the brand, if anywhere. The note stays at the level of a decision the next commit can obey.

Where the note has to live

Put the note where the work already happens. The best place on a small team is the top of the component file, in plain language above the code, plus the Figma component description if designers live there. A documentation site is justified when people outside the repo need the notes. Until then, a site becomes another surface to forget.

Engineers open files. They open the pull request. They do not open a brand guideline deck during a sprint. The companion to this piece is about that habit: brand guidelines your engineers will actually open. The same rule applies here. Short, next to the code, with the values and the refusals.

Review the note when you change the component. A state you removed, left in the note, will be rebuilt by someone who trusted the note. A state you added, missing from the note, will be "fixed" back out. The note is part of the change. In review, ask for it the way you ask for a test of the empty case.

When you want those notes written as part of the build, see Hanabi's services. The studio designs and ships the components with the states named, so the next person in the repo does not have to guess.