write-component-docs

name	write-component-docs
description	Author component documentation in this project. Docs live inside the component's *.stories.tsx (Storybook autodocs), translated from the HTML reference's MDX structure into JSX, in Japanese.

Where docs live

This project does not use standalone MDX files for component docs (yet). Instead, documentation is rendered by Storybook autodocs, configured inside <Name>.stories.tsx:

• Simple components → parameters.docs.description.component with a short Markdown string.
• Complex components → parameters.docs.page with a JSX page that mirrors the HTML version's MDX structure.

Reference implementations:

• Simple: src/components/Divider/Divider.stories.tsx
• Complex: src/components/ProgressIndicator/ProgressIndicator.stories.tsx

Note: Migrating to standalone MDX (matching the HTML version's setup) is on the roadmap. Until that migration happens, write new docs in the JSX form described here. Do not introduce a one-off MDX file for a single component ahead of the project-wide switch.

When to use which form

Form	Use when
description.component only	The component has minimal API surface (1–2 props), no notable variants, no specific usage notes.
Full docs.page JSX	The component has multiple sub-components, multiple variants worth tabling, JS-driven behavior, accessibility caveats, or paired hooks/utils.

If in doubt, start with description.component and expand later.

Source of structure: the HTML version's MDX

Use the HTML version's .mdx for the same component (https://github.com/digital-go-jp/design-system-example-components-html) as the content source — variant tables, behavior descriptions, usage recipes. Translate it into Japanese suitable for a React API surface (drop CSS class names, data-* attributes that don't exist on the React side, raw HTML markup, etc.).

The section order is different from the HTML MDX, because the React version uses Storybook autodocs (live components) rather than <details> source-code blocks. Match the React layout below, not the HTML one.

Section order (React)

1. <Title /> / <Subtitle /> / <Description /> (autodocs metadata)
2. <Primary /> + <Controls /> (the leading interactive Story)
3. <Stories includePrimary={false} /> (remaining Stories — placed before spec/usage in this project)
4. 仕様 (Spec)
   • コンポーネント構成 — list each exported component / hook with one-line role
   • Props — one table per exported component, columns: Props / 説明 / デフォルト
   • 機能仕様 — variants, modes, screen-reader behavior, motion handling
5. 使い方 (Usage)
   • 基本的な使い方 — minimum working snippet
   • 〜する — recipe-style snippets for common patterns (control state, customize messages, etc.)
   • Customization sub-sections (e.g. メッセージのカスタマイズ, 通知間隔のカスタマイズ) live as <h3> inside 使い方 — not as a separate top-level section.
6. 参考情報 (References) — external links (WAI, WCAG, etc.) when relevant

What to omit from the HTML MDX

• ソースコード section (<details> with HTML/CSS/JS source) — the React version exposes live components instead; do not include raw source dumps.
• CSS class names and data-* attributes that do not exist on the React API.
• Raw HTML markup blocks showing internal SVG / element structure — replace with the React component name.
• JavaScript API tables (HTML version's start(), stop(), value) — replaced by props and hooks; describe the React equivalents.

HTML MDX → React docs mapping

HTML MDX	React equivalent
<Canvas of={...Playground} withToolbar />	<Primary />
<Controls of={...Playground} />	<Controls />
<Stories title="デモ" includePrimary={false} /> (placed at end)	<Stories includePrimary={false} /> (placed near top, after Primary/Controls)
## ソースコード <details> blocks	omit
## カスタマイズ (top-level)	### 〜のカスタマイズ (under 使い方)
data-foo attribute table	Props table per exported component
HTML element JS API table	Hook signature + options table

Skeleton for docs.page (complex components)

import {
  Controls,
  Description,
  Primary,
  Stories,
  Subtitle,
  Title,
  Unstyled,
} from '@storybook/addon-docs/blocks';
import type { Meta, StoryObj } from '@storybook/react-vite';
import { Foo } from './Foo';

const meta = {
  id: 'Component/DADS v2/Foo',
  title: 'Component/フー',
  component: Foo,
  tags: ['autodocs'],
  parameters: {
    docs: {
      page: () => (
        <Unstyled>
          <div className='prose'>
            <Title />
            <Subtitle />
            <Description />
            <Primary />
            <Controls />
            <Stories includePrimary={false} />

            <h2>仕様</h2>
            {/* ... */}

            <h2>使い方</h2>
            {/* ... */}
          </div>
        </Unstyled>
      ),
    },
  },
} satisfies Meta<typeof Foo>;

Required wrapper: <Unstyled> + <div className='prose'>. Without these, autodocs styles bleed into the documentation content.

Conventions

Language

• All prose: Japanese.
• Identifier names, type signatures, code samples: as in code (English).
• Keep prose concise and noun-ending where natural (〜の追加, 〜を実装 style).

Props tables

Three columns: Props / 説明 / デフォルト. The 説明 cell starts with the type in <code>, then a one-line description.

<table aria-labelledby='foo-props' className='w-full'>
  <thead>
    <tr>
      <th scope='col' className='text-nowrap'>Props</th>
      <th scope='col'>説明</th>
      <th scope='col' className='text-nowrap'>デフォルト</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td className='whitespace-nowrap'><code>size</code></td>
      <td>
        <div><code>'lg' | 'sm'</code></div>
        インジケーターのサイズ
      </td>
      <td><code>'lg'</code></td>
    </tr>
  </tbody>
</table>

Use aria-labelledby to tie the table to a preceding <h4 id='...'>. When the table sits under an inline heading (no preceding labeled heading), fall back to a regular table caption or omit aria-labelledby rather than inventing IDs.

Code samples

Use <pre><code> with template literals for multi-line samples. No syntax highlighting (Storybook autodocs renders as-is).

<pre>
  <code>
    {`import { Foo } from './Foo';

<Foo size='lg' />`}
  </code>
</pre>

Headings

• <h2> for top-level sections (仕様, 使い方, 参考情報).
• <h3> for sub-sections (Props, バリエーション, 基本的な使い方).
• <h4> for nested entries (e.g. each exported component's Props block).

Markuplint enforces no heading-level skips — verify with npm run lint:markup.

Skeleton for simple components

parameters: {
  docs: {
    description: {
      component: `<コンポーネント名>の概要を1〜2文で。

詳細な使い分けは別段落で書いてもよい。`,
    },
  },
},

This renders into the autodocs <Description /> slot. No JSX page needed.

Pre-flight

• Section order matches the HTML version's MDX (where the HTML version exists).
• Wrapped in <Unstyled> + <div className='prose'> for JSX page form.
• All prose is in Japanese; identifiers/types remain English.
• Each table has a header row with the right column count and uses <th scope='col'>.
• Heading levels are sequential (no skips). npm run lint:markup passes.
• Code samples are runnable (correct imports, props that actually exist).
• npm run storybook renders the docs tab without runtime errors.