Interactive examples

Put examples in the JSDoc block above the component class. The docs renderer extracts fenced snippets and shows their previews beside the source.

Existing component comments use fenced HTML with an optional <script>. Start with that pattern:

/**
 * ```html
 * <esp-button label="Save"></esp-button>
 * <script>
 *   const button = findByTagName("esp-button")[0];
 *   button.addEventListener("esp-clicked", () => {
 *     showToast({ message: "Saved", duration: 2 });
 *   });
 * </script>
 * ```
 */

findByTagName and showToast are helpers available in the documentation preview. In application code, find the element using your own DOM reference and import the public toast helper when needed.

Choose useful examples

Start with the smallest example that shows a normal use. Add separate examples for important states such as disabled, loading, validation errors, or intent. Keep each snippet focused so readers can see which option changes the result.

Include the required labels and semantic markup. Check keyboard interaction as well as appearance. An example that looks correct can still be inaccessible.

Use theme tokens for color, spacing, and type. Explain any preview-only helper or setup that readers need when copying the snippet into their application.

Check the result

Follow the build pipeline to regenerate the site. Try the example, check its source, and confirm that event handling works. Keep automated coverage for the promised behavior; see documentation and verification.