react-component-documentation

コンポーネントドキュメント (MDX ストーリー)

static/app/components/core/ の規約に従って、Sentry コンポーネントの .mdx ファイルを作成します。

ステップ 0: 編集コンテンツを収集する

執筆を始める前に、機械的な構造を超えてドキュメントを有用にする情報を集めます。ユーザーに以下の質問をしてください。あるいは、ユーザーが対応できない場合は、コードベース内の既存の使用箇所を検索して (static/app/views/ 全体でコンポーネント名を Grep して) 回答を推測してください。

質問	ドキュメント内で表れる場所
開発者はどのようなときにこのコンポーネントを使うべきですか?	はじめに、または ## When to use セクション
どのようなときに使うべきではありませんか — そして代わりに何を使うべきですか?	> [!WARNING] コールアウト、またはガイダンス付きの ## See Also
各バリアント/優先度は意味的に何を表しますか?	各バリアントのセクション内の説明 (例: 「danger = 破壊的かつ不可逆」)
開発者がよく間違えることは何ですか?	> [!WARNING] コールアウト、アイコンのみのアクセシビリティに関する注意、必須 prop のリマインダー
このコンポーネントが正しく動作するために、特定の親、ピア、またはプロバイダーが必要ですか?	はじめに、または > [!NOTE] コールアウトに記載
目的が重複する関連コンポーネントはありますか?	## See Also に、それぞれをいつ優先すべきかの一行ガイダンス
デモ付きでドキュメント化する価値のある prop とバリアントはどれですか?	以下の prop トリアージを参照

すべてのコンポーネントについて、すべての質問に回答がある必要はありません。該当しないものはスキップしてください。目標は、API の 使い方 だけを説明するドキュメントを書くことではなく、開発者に いつ、なぜ を使うべきかを伝えるドキュメントを書くことです。

prop トリアージ

すべての prop にデモセクションが必要なわけではありません。ユーザーに尋ねてください: 「どの prop をドキュメント化すべきですか、また特定の意図された用途を持つバリアントや値はありますか?」

ユーザーが対応できない場合は、コンポーネントの TypeScript の props を読み、それぞれを分類してください:

層	ドキュメント化の方法	例
コア — コンポーネントの主要な動作や外観を定義する	ライブデモと各値の意味的な説明を含む完全な ## セクション	priority、variant、size
修飾 — 単一の側面を調整する。値は自明である	デモ付きの簡単な言及、または他の修飾子と組み合わせた単一のデモ	disabled、busy、icon、showIcon
構造 — レイアウトや構成を制御する	before/after または複合的な使用方法を示すデモ	system、expand、trailingItems
内部 / パススルー — ユーザー向けではない	完全にスキップする	className、style、ref、data-test-id

特に enum prop については、常に尋ねてください: 「各値に明確に意図された意味がありますか、それとも純粋に見た目だけですか?」 明確な意味がある場合 (例: danger は単に赤いだけでなく破壊的を意味する)、視覚的な違いだけでなく意味をドキュメント化してください。

ステップ 1：コンポーネントを特定する

コンポーネントのソースファイルを探します。

static/app/components/core/<category>/<component>/index.tsx
static/app/components/core/<category>/<component>/<component>.tsx

コンポーネントファイルを読み、以下を確認します。

• Props とその型
• エクスポートされている名前付きのバリアントとサブコンポーネント（例：Component.SubComponent、export {TabList, TabPanels}）
• enum／union 型の prop で使用できる値
• prop のデフォルト値

MDX ファイルはコンポーネントと同じディレクトリに配置します：<component-dir>/<component>.mdx。

ファイルがすでに存在する場合は、まず内容を読み、上書きせずに更新してください。

インポートパスの決定方法：

• static/app/components/core/ 内のコンポーネントは、@sentry/scraps/<name> として公開されています
• それ以外のコンポーネントには、sentry 内部のパス sentry/components/<path> を使用します

正確な @sentry/scraps のパッケージ名と型ローダーのパスを確認するには、コンポーネントディレクトリ内または近くの .mdx ファイルにある既存のインポートを確認してください。パッケージ構成によって、型ローダーのパスは @sentry/scraps/<name> または @sentry/scraps/<name>/<name> になります。

ステップ 2：フロントマターを決める

---
title: <ComponentName>
description: <One sentence describing what it is and its primary purpose.>
category: <category> # See category table below; omit for principle docs
source: '@sentry/scraps/<component>' # or 'sentry/<path>' for product components
resources:
  figma: <figma-url> # Include if known
  js: https://github.com/getsentry/sentry/blob/master/static/app/components/core/<path>
  a11y: # Include for interactive components
    WCAG 1.4.3: https://www.w3.org/TR/WCAG22/#contrast-minimum
    WAI-ARIA <Pattern> Practices: https://www.w3.org/WAI/ARIA/apg/patterns/<pattern>/
---

カテゴリの値：

カテゴリ	コンポーネント
buttons	Button、ButtonBar、LinkButton
forms	Input、Select、Checkbox、Radio、Slider、Switch
navigation	Tabs、SegmentedControl、Disclosure
status	Alert、Badge、Tag、Toast
layout	Flex、Grid、Stack、Container、Surface
typography	Text、Heading、Prose
patterns	デザインパターン、原則

原則やパターンのドキュメント（インタラクティブなコンポーネントがない場合）では、category の代わりに layout: document を使用し、リソース内の a11y: を reference: に置き換えます。

ステップ 3：インポートを記述する

以下のインポート順を厳守します。

// 1. External packages (react, etc.) — only if needed for examples
import {useState} from 'react';

// 2. @sentry/scraps component(s)
import {ComponentName} from '@sentry/scraps/<component>';

// 3. Sentry internals used in examples (icons, utils)
import {IconAdd} from '@sentry/icons/add';
import {IconEdit} from '@sentry/icons/edit';
// 4. Stories namespace (always last before type-loader)
import * as Storybook from 'sentry/stories';

// 5. Type-loader for auto-generated API docs (@sentry/scraps components only)
import documentation from '!!type-loader!@sentry/scraps/<component>';

export {documentation};

不要なグループは省略します。プロダクトのコンポーネント（@sentry/scraps に含まれないもの）では、型ローダーの行を省略し、props を手動で表にまとめます（ステップ 5 を参照）。

複雑なエクスポート： コンポーネントのエクスポートをフィルタリングする必要がある場合（例：内部エクスポートを非表示にする場合）は、export {documentation} ではなく、明示的な形式を使用します。

import RawDocumentation from '!!type-loader!@sentry/scraps/<component>';

export const documentation = {
  exports: RawDocumentation.exports,
  props: {
    ...RawDocumentation?.props,
    // Remove internal props if needed
  },
};

ステップ 4：内容を記述する

セクション構成

prop 名ではなく、機能またはユーザー向けのバリアントごとに内容を整理します。

1. 概要 — 1～2 文の説明の後に、最小限の使用例コードブロックを記述します（デモ用ラッパーは不要です）
2. 使用する場面 (コンポーネントに意味のある代替手段がある場合、または誤用のリスクがある場合) — 文章で説明し、必要に応じて <Storybook.SideBySide> でよい例と悪い例を並べます
3. 機能のセクション — 主な機能ごとに ## 見出しを付けます：## Sizes、## Priorities、## States、## Composition
4. アクセシビリティ — WCAG への適合に関する説明と開発者の責任
5. 関連項目 — 関連コンポーネントへのリンクと、1 行の説明（任意）

## The size prop よりも、## Sizes、## Variants、## States のような見出しを優先します。

「使用する場面」／「関連項目」のパターン：

## When to use

Use `<Alert>` for inline feedback within a page. For application-level banners that span the full viewport, use the `system` prop or reach for `<Toast>` if the message is transient.

> [!WARNING]
> Do not use `<Alert variant="danger">` for confirmation dialogs. Use a modal instead.

## See Also

- [LinkButton](/stories/core/linkbutton/) — use when the action navigates to a new URL
- [Link](/stories/core/link/) — use for inline text navigation, not standalone CTAs

概要のパターン

To create a basic <component>, wrap content in `<ComponentName>`.

```jsx
<ComponentName prop="value">Content</ComponentName>
```

### Sub-components

When a component exposes sub-components, show the full compound usage early:

```mdx
`<Tabs>` is a compound component. Use `<TabList>` and `<TabPanels>` together:

```jsx
<Tabs>
  <TabList>
    <TabList.Item key="tab1">Tab 1</TabList.Item>
  </TabList>
  <TabPanels>
    <TabPanels.Item key="tab1">Content 1</TabPanels.Item>
  </TabPanels>
</Tabs>

### Demo pattern

Every feature section must have a `<Storybook.Demo>` followed **immediately** by the matching code block:

```mdx
## Sizes

<brief description>

<Storybook.Demo>
  <Component size="sm">Small</Component>
  <Component size="md">Medium</Component>
  <Component size="lg">Large</Component>
</Storybook.Demo>
```jsx
<Component size="sm">Small</Component>
<Component size="md">Medium</Component>
<Component size="lg">Large</Component>

**Demo layout helpers:**

| Component | Use when |
|-----------|----------|
| `<Storybook.Demo>` | Default; horizontally arranges examples |
| `<Storybook.Grid>` | Grid layout for many variants |
| `<Storybook.SideBySide>` | Two-column comparisons (do/don't) |
| `<Storybook.TokenReference>` | Displaying design tokens (spacing, color, etc.) |
| `<Storybook.ColorReference>` | Displaying color tokens specifically |

### Accessibility section

```mdx
## Accessibility

This component meets [WCAG 2.2 AA](https://www.w3.org/TR/WCAG22/) standards:

- **Color contrast**: Meets 4.5:1 ratio (WCAG 1.4.3)
- **Keyboard navigation**: <what interactions are supported>
- **Screen reader support**: <ARIA role and labeling behavior>

### Developer responsibilities

- Always provide <required accessible prop> (e.g., `aria-label` or visible label text)
- <other requirement>

コールアウトの構文

> [!TIP]
> Use the `<prop>` prop when you need <use case>.

> [!WARNING]
> Avoid <pattern> because <reason>.

> [!NOTE]
>
> <Additional context.>

ステップ 5：Props の表（プロダクトのコンポーネントのみ）

@sentry/scraps に含まれないコンポーネントでは、型ローダーを使わずに props を手動で一覧にします。

## Props

| Prop      | Type                              | Default  | Description               |
| --------- | --------------------------------- | -------- | ------------------------- |
| `variant` | `'info' \| 'warning' \| 'danger'` | `'info'` | Controls the visual style |
| `size`    | `'sm' \| 'md' \| 'lg'`            | `'md'`   | Controls the size         |

完全な例

---
title: Alert
description: Alerts provide contextual feedback messages with different severity levels.
category: status
source: '@sentry/scraps/alert'
resources:
  js: https://github.com/getsentry/sentry/blob/master/static/app/components/core/alert/index.tsx
  a11y:
    WCAG 1.4.3: https://www.w3.org/TR/WCAG22/#contrast-minimum
    WCAG 2.1.1: https://www.w3.org/TR/WCAG22/#keyboard
    WAI-ARIA Alert Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/alert/
---

import {Alert} from '@sentry/scraps/alert';

import * as Storybook from 'sentry/stories';

import documentation from '!!type-loader!@sentry/scraps/alert';

export {documentation};

To create a basic alert, wrap a message in `<Alert>` and specify the appropriate type.

```jsx
<Alert variant="info">This is an informational message</Alert>
```

Types

アラートには、muted、info、warning、success、danger の 5 つのタイプがあります。

<Storybook.Demo> <Alert.Container> 控えめ 情報 警告 成功 危険 </Alert.Container> </Storybook.Demo>

<Alert.Container>
  <Alert variant="muted">Muted</Alert>
  <Alert variant="info">Info</Alert>
  <Alert variant="warning">Warning</Alert>
  <Alert variant="success">Success</Alert>
  <Alert variant="danger">Danger</Alert>
</Alert.Container>

アクセシビリティ

このコンポーネントは WCAG 2.2 AA の基準を満たしています。

• 色のコントラスト：すべてのバリアントが 4.5:1 の比率を満たしています（WCAG 1.4.3）
• キーボード操作への対応：キーボードですべての操作を実行できます（WCAG 2.1.1）

チェックリスト

完了する前に、以下を確認してください。

• MDX ファイルはコンポーネントのソースファイルの隣に配置されている（名前は <component>.mdx）
• フロントマターに title、description、source が含まれている
• インポートが正しい順序に従っている（外部 → icons/utils → @sentry/scraps → Storybook → type-loader）
• @sentry/scraps コンポーネントに type-loader のインポートが含まれている
• すべての <Storybook.Demo> の直後に対応するコードブロックが続いている
• セクションは prop 名ではなく機能/バリアントごとに整理されている
• サブコンポーネントが複合的な使用例とともにドキュメント化されている
• アクセシビリティのセクションで WCAG 準拠と開発者の責任について説明している
• 生の <img> タグ（<Image> を使用）、インライン SVG、styled components が含まれていない