component-docs

---
name: component-docs
description: "Author or update a component doc in the Docusaurus site (packages/insomnia-component-docs) for a component in the shared library. Use when adding a new component to src/basic-components, changing a component's props/variants, or when asked to document/update docs for a component."
argument-hint: 'The component name and its source path, e.g. "Select (packages/insomnia/src/basic-components/select.tsx)"'
---

# Component Docs (Docusaurus + MDX)

Author/maintain docs for the shared component library on the Docusaurus site at
`packages/insomnia-component-docs`. Docs are one MDX file per component with live,
editable examples.

## When to Use

- A new component was added to `packages/insomnia/src/basic-components/` (or migrated in).
- A component's props/variants/styling changed and its doc needs updating.
- Asked to "document" / "write docs for" / "update docs for" a component.

## Key Facts (read before editing)

- **One file per component**: `packages/insomnia-component-docs/docs/Components/<name>.mdx` (kebab-case filename).
- **Sidebar is autogenerated** from the folder — do NOT edit `sidebars.ts`. Just set `sidebar_position` in frontmatter for ordering.
- **Live examples** use ` ```tsx live ` fenced blocks (via `@docusaurus/theme-live-codeblock`). Component names in those blocks resolve from a shared scope, NOT from imports in the MDX.
- **⚠️ The easy-to-forget step**: any component used in a `tsx live` block MUST be imported and registered in `packages/insomnia-component-docs/src/theme/ReactLiveScope/index.ts`. If it isn't, the live block fails to compile. Library components import as `insomnia/src/basic-components/<name>`.

## Procedure

1. **Inspect the component source** to get the real API: props, types, defaults, variants (`tv` config), and which theme CSS variables / `theme--*` classes it uses.
2. **Create/update the MDX** at `docs/Components/<name>.mdx` using `template.mdx` in this skill folder as the starting point. Fill:
   - Frontmatter: `id`, `sidebar_label`, `sidebar_position` (next free integer, or logical grouping).
   - Title + one-line description.
   - `## Props` table (prop / type / default / description). End with a link to the underlying React Aria props page when it extends an RA component.
   - `## Usage Examples` — at least 2–3 ` ```tsx live ` blocks covering the main variants/states. Keep examples small and self-contained; wrap multiple elements in a `function` component.
   - `## Styling` → `### CSS Variables` list (only the color vars the component consumes) and, if applicable, a note on the `theme--*` scope class it carries.
3. **Register in ReactLiveScope** (`src/theme/ReactLiveScope/index.ts`): add the `import` and include the component in the `ReactLiveScope` object. Only needed once per component.
4. **Verify the site builds** (catches broken live blocks and bad imports):
   ```bash
   cd packages/insomnia-component-docs && npm run build
   ```
   For interactive preview while writing: `cd packages/insomnia-component-docs && npm run start`.

## Conventions

- Match the existing docs' tone and section order (see `docs/Components/button.mdx` as the reference).
- Document colors via CSS variables (`--color-*` / `--hl-*`); sizes/spacing are native Tailwind utilities — mirror the component's actual source, not an idealized version. (Library styling conventions live in `packages/insomnia/src/basic-components/AGENTS.md`.)
- Keep live examples free of business/data dependencies so they render in isolation.
- If the component is multi-part (e.g. `Modal.Header/Body/Footer`), document the sub-components together in one file.

More agent context in Kong/insomnia

4 other files this repository gives its agents.