react-component-documentation

组件文档（MDX Stories）

按照 static/app/components/core/ 中的约定，为 Sentry 组件创建一个 .mdx 文件。

第 0 步：收集编辑内容

在撰写之前，先收集那些能让文档超越机械结构、真正有用的信息。向用户询问以下问题——如果用户不在，则在代码库中搜索现有用法（在 static/app/views/ 中对该组件名执行 Grep）来推断答案。

问题	它在文档中出现的位置
开发者应该在什么时候使用这个组件？	引言或 ## When to use 章节
开发者不应该在什么时候使用它——以及应该改用什​​么？	> [!WARNING] 提示框，或带指导说明的 ## See Also
每个 variant/priority 在语义上分别意味着什么？	每个 variant 章节中的描述（例如，“danger = 破坏性且不可逆”）
开发者常见的错误是什么？	> [!WARNING] 提示框、仅图标情况下的无障碍说明、必填 prop 提醒
这个组件是否需要特定的父组件、同级组件或 provider 才能正常工作？	在引言或 > [!NOTE] 提示框中注明
是否存在用途重叠的相关组件？	## See Also，并用一行说明何时应优先选择哪一个
哪些 props 和 variants 值得用演示来记录？	参见下方的 prop 分类

并非每个组件都需要回答所有问题。跳过不适用的即可。目标是不要只写那些只描述 API 如何 使用的文档——而要写告诉开发者_何时以及为何_使用它的文档。

Prop 分类

并非每个 prop 都需要一个演示章节。询问用户：“我应该记录哪些 props，是否有任何 variants 或取值具有特定的预期用途？”

如果用户不在，阅读组件的 TypeScript props 并逐一分类：

层级	如何记录	示例
核心 — 定义组件的主要行为或外观	完整的 ## 章节，包含实时演示以及每个取值的语义描述	priority、variant、size
修饰 — 调整单个方面；取值本身不言自明	简要提及并配一个演示，或与其他修饰项合并为单个演示	disabled、busy、icon、showIcon
结构 — 控制布局或组合	展示前后对比或复合用法的演示	system、expand、trailingItems
内部 / 透传 — 不面向用户	完全跳过	className、style、ref、data-test-id

对于 enum props 尤其要问：“每个取值是否有截然不同的预期含义，还是纯粹只是视觉差异？”如果含义截然不同（例如，danger 意味着破坏性，而不仅仅是红色），就要记录其语义——而不仅仅是视觉差异。

步骤 1：定位组件

查找组件源文件：

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

阅读组件文件，了解：

• Props 及其类型
• 导出的命名变体和子组件（例如，Component.SubComponent、export {TabList, TabPanels}）
• 枚举/联合类型 props 的可用值
• Props 的默认值

MDX 文件应与组件放在同一目录下：<component-dir>/<component>.mdx。

如果文件已存在，请先阅读，并在其基础上更新，而不是覆盖。

确定导入路径：

• static/app/components/core/ 中的组件以 @sentry/scraps/<name> 发布
• 其他所有组件都使用 sentry-internal 路径：sentry/components/<path>

如需确认确切的 @sentry/scraps 包名和类型加载器路径，请检查组件目录中已有的导入语句或相邻的 .mdx 文件——根据包结构，类型加载器路径可能是 @sentry/scraps/<name> 或 @sentry/scraps/<name>/<name>。

步骤 2：确定 Frontmatter

---
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	设计模式、原则

对于原则/模式文档（没有交互式组件），使用 layout: document 代替 category，并在 resources 下用 reference: 替换 a11y:。

步骤 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. 适用场景（如果组件有明显的替代方案或存在误用风险）——提供文字说明，可选用 do/don't <Storybook.SideBySide>
3. 功能章节——每项主要功能使用一个 ## 标题：## Sizes、## Priorities、## States、## Composition
4. 无障碍——说明 WCAG 符合情况和开发者的责任
5. 另请参阅——链接到相关组件，并附上一行说明（可选）

优先使用 ## Sizes、## Variants、## States 等标题，而非 ## The size prop。

适用场景 / 另请参阅模式：

## 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>
```

类型

Alert 有五种类型：muted、info、warning、success 和 danger。

<Storybook.Demo> <Alert.Container> Muted Info Warning Success Danger </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）
• Frontmatter 包含 title、description 和 source
• import 顺序正确（外部 → icons/utils → @sentry/scraps → Storybook → type-loader）
• 为 @sentry/scraps 组件包含了 type-loader import
• 每个 <Storybook.Demo> 后面紧跟一个匹配的代码块
• 各部分按功能/变体组织，而不是按 prop 名称组织
• 子组件使用复合用法示例进行文档化
• 无障碍部分涵盖 WCAG 合规性和开发者职责
• 没有原始 <img> 标签（使用 <Image>），没有内联 SVG，没有 styled components