# AGENTS.md — Component Docs Site (Docusaurus + MDX)

Docs for Insomnia's shared component library. Prefer the **`component-docs` skill** for authoring —
it carries the template and full procedure. This file is the quick reference for direct edits.

## Structure

- One MDX file per component: `docs/Components/<name>.mdx` (kebab-case).
- **Sidebar is autogenerated** from the folder — do NOT edit `sidebars.ts`. Order via
  `sidebar_position` in frontmatter.
- Reference doc for format/tone: `docs/Components/button.mdx`.

## Doc format (per file)

1. Frontmatter: `id`, `sidebar_label`, `sidebar_position`.
2. `# Title` + one-line description.
3. `## Props` table (prop / type / default / description) + link to the underlying React Aria props page.
4. `## Usage Examples` — ` ```tsx live ` blocks (live-editable). Wrap multiple elements in a `function`.
5. `## Styling` → `### CSS Variables` (color vars consumed) + any `theme--*` scope class note.

## ⚠️ Live examples need ReactLiveScope registration

` ```tsx live ` blocks resolve component names from `src/theme/ReactLiveScope/index.ts`, NOT from
MDX imports. Any component used in a live block must be imported there and added to the
`ReactLiveScope` object. Library components import from the barrel as `insomnia/src/basic-components`.

## Commands

```bash
cd packages/insomnia-component-docs
npm run start   # local preview while writing
npm run build   # verify (catches broken live blocks / bad imports)
```