Component Docs

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):

   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.