component-docs

コンポーネントのドキュメント作成スキル

コンポーネントのドキュメントは、apps/web/src/components 内、または該当するルートセグメント内のローカルコンポーネントの隣に配置します。HeroUI のコンポーネントについては、サードパーティの内部仕様をドキュメント化するのではなく、HeroUI v3 の公式ドキュメントにリンクしてください。

コンポーネントのドキュメントテンプレート

# Button

A reusable local component or wrapper used by MotorMetrics.

## Usage

\`\`\`tsx
import { Button } from "@heroui/react";

<Button variant="primary">Click me</Button>
\`\`\`

## Variants

\`\`\`tsx
<Button variant="primary">Primary</Button>
<Button variant="danger">Delete</Button>
<Button variant="outline">Outline</Button>
\`\`\`

## Sizes

\`\`\`tsx
<Button size="sm">Small</Button>
<Button size="default">Default</Button>
<Button size="lg">Large</Button>
<Button size="icon"><Icon /></Button>
\`\`\`

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | `"primary" \| "danger" \| "outline"` | `"primary"` | Visual style |
| size | `"default" \| "sm" \| "lg" \| "icon"` | `"default"` | Button size |
| asChild | `boolean` | `false` | Render as child element |

## Accessibility

- Uses semantic `<button>` element
- Supports keyboard navigation (Enter, Space)
- Proper focus states

JSDoc コメント

/**
 * A customizable button component.
 *
 * @example
  * <Button variant="primary">Click me</Button>
 */
export interface ButtonProps {
  /** Visual style variant @default "primary" */
  variant?: "primary" | "danger" | "outline";
  /** Button size @default "default" */
  size?: "default" | "sm" | "lg" | "icon";
}

Storybook ストーリー

// apps/web/src/components/button.stories.tsx
import type { Meta, StoryObj } from "@storybook/react";
import { Button } from "./button";

const meta = {
  title: "Components/Button",
  component: Button,
  tags: ["autodocs"],
  argTypes: {
    variant: { control: "select", options: ["primary", "danger", "outline"] },
    size: { control: "select", options: ["default", "sm", "lg", "icon"] },
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

export const Default: Story = { args: { children: "Button" } };
export const Danger: Story = { args: { variant: "danger", children: "Delete" } };

ドキュメントのチェックリスト

• コンポーネントと props に JSDoc コメントがある
• 使用例を含む Markdown ドキュメントがある
• props の表が含まれている
• バリアントがドキュメント化されている
• アクセシビリティに関する注記がある
• Storybook ストーリーがある（Storybook を使用する場合）

ベストプラクティス

1. 明確な例：完全に動作するコードを記載します
2. Props のドキュメント化：すべての prop について、型と説明を記載します
3. アクセシビリティ：アクセシビリティに関する注記を含めます
4. 最新の状態を維持：コンポーネントを変更した際は、ドキュメントも更新します

参考資料

• HeroUI v3 のドキュメント：https://www.heroui.com/docs/react