| 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
- Inspect the component source to get the real API: props, types, defaults, variants (
tv config), and which theme CSS variables / theme--* classes it uses.
- 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.
- Register in ReactLiveScope (
src/theme/ReactLiveScope/index.ts): add the import and include the component in the ReactLiveScope object. Only needed once per component.
- Verify the site builds (catches broken live blocks and bad imports):
npm run build -w insomnia-component-docs
For interactive preview while writing: cd 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.
