update-doc

name	update-doc
description	Add or update ink-ui component documentation pages in content/docs/components/. Triggered when the user says "add/update documentation for <component>".

Adding/updating component documentation

This skill describes the full procedure for documenting a UI component on the ink-ui docs site.

Overview

A component doc page has these pieces:

1. Wrapper component at registry/default/ui/<component>.tsx - styled wrapper around Base UI primitives
2. Demo examples at registry/default/examples/<component>-<example-name>-example.tsx - one exported React function per file
3. Registry entry in registry.json - shadcn registry metadata for the component and each atomic example
4. Doc page at content/docs/components/<component>.mdx - MDX page with frontmatter, examples, installation, and API reference
5. Props registry at src/lib/props-registry.ts - entries for <PropsTable>
6. Docs navigation in content/docs/components/meta.json - add the page slug to pages

Generated output:

• public/r/ is generated by pnpm registry:build; do not edit files there by hand.
• .source/ is generated by pnpm typegen; do not edit files there by hand.
• src/routeTree.gen.ts is generated by TanStack Router; do not edit it by hand.

1. Check the wrapper component exists

The wrapper at registry/default/ui/<component>.tsx must exist and export named components. Read it to understand which sub-components are exported.

2. Create/update demo examples

Create or update atomic files in registry/default/examples/. Each file must contain exactly one exported example function.

Rules:

• File naming convention: <component>-<example-name>-example.tsx, e.g. button-loading-example.tsx, menu-with-icons-example.tsx
• Use default as the example name for the primary/basic example, e.g. button-default-example.tsx
• Export one function per file: export function ComponentExample() { ... }
• Name convention: <Feature><Component>Example, e.g. LoadingButtonExample, MenuWithIconsExample
• Import from registry/default/ui/<component> and @phosphor-icons/react for icons
• Wrap multiple items in <div className="flex flex-wrap items-center gap-4">
• Keep examples self-contained and client-safe; MDX renders React components directly, without Astro client:* directives.

Docs pages import each atomic example file with ?raw and pass that file's source to the matching <ComponentSource>, so each code snippet shows only the example being previewed.

3. Update registry.json

Add or update two registry items:

1. A registry:ui item named <component> that points at registry/default/ui/<component>.tsx.
2. A registry:component item for each atomic example, named <component>-<example-name>-example, that points at registry/default/examples/<component>-<example-name>-example.tsx.

Example:

{
  "name": "component-name",
  "type": "registry:ui",
  "title": "Component Name",
  "description": "Ink UI Component Name component.",
  "files": [
    {
      "path": "registry/default/ui/component-name.tsx",
      "type": "registry:ui",
      "target": "components/ui/component-name.tsx"
    }
  ],
  "registryDependencies": ["utils", "theme"],
  "dependencies": ["@base-ui/react"]
}

Add any actual runtime dependencies and registry dependencies the component uses. After changing registry.json, run pnpm registry:build to regenerate public/r/.

4. Create the MDX doc page

Create content/docs/components/<component>.mdx with this structure:

---
title: ComponentName
description: Short description of what this component does.
component: ComponentName
registry: component-name
---

import { Component, SubComponent } from "registry/default/ui/component-name";
import { ComponentExample } from "registry/default/examples/component-name-default-example";
import componentExampleSource from "registry/default/examples/component-name-default-example.tsx?raw";
import { VariantExample } from "registry/default/examples/component-name-variant-example";
import variantExampleSource from "registry/default/examples/component-name-variant-example.tsx?raw";
import componentSource from "registry/default/ui/component-name.tsx?raw";

<ComponentSection>
  <ComponentTabs>
    <ComponentPreview name="ComponentExample">
      <ComponentExample />
    </ComponentPreview>
    <ComponentSource
      code={componentExampleSource}
      language="tsx"
      title="component-name-default-example.tsx"
    />
  </ComponentTabs>
</ComponentSection>

## Examples

### Variant name

Brief description of what this example demonstrates.

<ComponentSection>
  <ComponentTabs>
    <ComponentPreview name="VariantExample">
      <VariantExample />
    </ComponentPreview>
    <ComponentSource
      code={variantExampleSource}
      language="tsx"
      title="component-name-variant-example.tsx"
    />
  </ComponentTabs>
</ComponentSection>

## Installation

Copy the source code below into your project:

<CodeBlock code={componentSource} language="tsx" />

## API Reference

### Component

<PropsTable component="Component" />

### SubComponent

<PropsTable component="SubComponent" />

Key notes:

• MDX helper components are globally registered in src/components/mdx/mdx-components.tsx; do not import ComponentSection, ComponentTabs, ComponentPreview, ComponentSource, CodeBlock, or PropsTable in each page.
• Use component and registry frontmatter to connect the doc page to the component and registry item.
• Use <ComponentTabs> with <ComponentPreview> and <ComponentSource> for examples.
• Import each example component and ?raw source from its own atomic example file.
• The installation section uses a ?raw import to show the full wrapper source.
• Keep component doc pages under content/docs/components/, not src/pages/.

5. Add props to the registry

Add entries to src/lib/props-registry.ts for each exported sub-component.

Registry rules:

• Only list wrapper-specific props (like variant, size, positionerProps) - NOT inherited Base UI props.
• Use extends to link to the Base UI API reference for inherited props. Check the Base UI docs for primitive props. The docs link is usually https://base-ui.com/react/components/{componentName}.
• If extends is set but props is empty, the table shows a link to Base UI docs instead of an empty table
• Use the same component names as the exports from the wrapper

Example entry:

MenuItem: {
  extends: {
    name: "Base UI Menu.Item",
    href: "https://base-ui.com/react/components/menu#api-reference",
  },
  props: [
    {
      name: "variant",
      type: '"default" | "destructive"',
      defaultValue: '"default"',
      description: "Visual style of the menu item.",
    },
  ],
},

6. Add to docs navigation

Add the new component slug to content/docs/components/meta.json:

{
  "title": "Components",
  "pages": ["button", "component-name", "menu"]
}

Keep the list alphabetically sorted.

7. Verify

Run these commands to check the build:

pnpm typegen      # Regenerate fumadocs-mdx types if docs content changed
pnpm registry:build
pnpm typecheck   # TypeScript validation
pnpm lint
pnpm build

Check the dev server at http://localhost:3000/docs/components/component-name to verify:

• All examples render correctly
• Code snippets show the expected example and wrapper source
• Props tables show the right data
• Docs navigation works