Documentation and verification

Write documentation while designing a component's API. Explaining what a property does and showing a small example can reveal awkward defaults or unnecessary options before consumers depend on them.

Describe the public contract

Document when to use each property, slot, event, and styling hook. Types already tell readers whether a value is a string or number; prose should explain its meaning, units, defaults, and effects that are easy to miss.

The Custom Elements Manifest extracts API metadata from source and feeds the reference pages. This reduces duplicated API lists, but descriptions and examples still need review when behavior changes.

Use examples and tests together

Live examples let people try a component and see it alongside other elements. Check the documented states, keyboard interaction, labels, and theme behavior. A working example covers only the situation it demonstrates.

The repository also uses automated checks:

• Vitest covers markup, properties, events, controller state, and form behavior.
• Browser fixtures cover layout, focus, scrolling, and pointer interaction.
• Driver fixtures exercise role and label locators through real browser input.
• Visual baselines catch unexpected rendering changes.

Choose a check that can observe the behavior being promised. A CSS declaration alone does not prove that a pane scrolls or a focus trap works. Consumer-facing automation expectations are documented in browser automation.

Keep docs current

Update API descriptions and examples in the same change as the component. Follow component authoring for source comments and example authoring for runnable snippets. The build pipeline explains how to regenerate the site.