SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscomponent-docs

component-docs

Frontend & websites

View repository

Updated 10-15 23:47

About this skill

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.