write-api-reference

# API reference Treat TypeScript source and the builder E2E test as the specification. Generated JSON is diagnostic output, not an editable source. ## Workflow 1. Identify the export and read its implementation, public export path, tests, and any matching design record. 2. Read `site/scripts/api-docs-builder/src/tests/e2e.test.ts` to confirm the builder contract involved in the change. 3. Load only the needed reference: - Component discovery or naming failure: `references/builder-conventions.md` - Hook, controller, mixin, factory, or other utility: `references/util-conventions.md` - New MDX reference page: `references/mdx-structure.md` - New interactive example: `references/demo-patterns.md` 4. Run `pnpm -F site api-docs` and inspect the corresponding file under `site/src/content/generated-*-reference/`. 5. Fix missing metadata at the TypeScript/JSDoc source or in the builder. Do not hand-edit generated JSON. 6. Create or update the page and the matching `site/src/docs.config.ts` entry when a page is required: `site/src/content/docs/reference/components/<slug>.mdx` for components, skins, media, extensions, and the icon sets; `site/src/content/docs/reference/api/<slug>.mdx` for hooks, features, controllers, factories, utilities, and presets (`preset-<name>.mdx`, in the API tab's Presets group). Keep each page in its sidebar tab's directory, because each tab's llms files are written where its pages share a directory. 7. Give extra exports a code heading or an `## Exports` table row, or list them in `apis` when neither fits, then run `pnpm -F site check:api-stability` (see the frontmatter section of `site/src/content/docs/writing-style/write-references.mdx`). 8. Verify the page for every supported framework/style combination it targets. ## Component pages - Derive props, state, data attributes, parts, tag names, and behavior from source. - Add prose only for non-obvious behavior, styling contracts, accessibility, or platform constraints. - Keep reference prose neutral and descriptive: state facts, let examples illustrate without teaching, and link how-to guides for tasks and concept pages for rationale (see `.agents/skills/write-docs/references/diataxis.md`). - Include basic HTML and React demos when both platforms expose the component; follow existing neighboring demos when the reference guide leaves room for judgment. ## Utility pages - Confirm the export is reachable from a builder-scanned public entry point. - Add `@public` only when the export intentionally belongs in reference docs and naming-based discovery does not include it. - Verify generated overloads, parameters, and return data before authoring prose. ## Validation Run the builder E2E test for builder changes, `pnpm -F site api-docs`, and the narrowest site check that renders the affected page. ## Example Input: “Add the Menu component API reference.” Output: Source JSDoc and builder-compatible metadata, verified generated output, MDX examples, navigation config, and site checks.