React Component Documentation

Component Documentation (MDX Stories)

Create a .mdx file for a Sentry component following the conventions in static/app/components/core/.

Step 0: Gather Editorial Content

Before writing, collect the information that makes documentation useful beyond mechanical structure. Ask the user these questions — or, if they aren't available, search existing usages in the codebase (Grep for the component name across static/app/views/) to infer answers.

You don't need answers to all questions for every component. Skip ones that don't apply. The goal is to not write docs that only describe _how_ to use the API — write docs that tell developers _when and why_.

Prop triage

Not every prop needs a demo section. Ask the user: "Which props should I document, and are there any variants or values with specific intended uses?"

If the user isn't available, read the component's TypeScript props and classify each:

For enum props specifically, always ask: "Does each value have a distinct intended meaning, or are they purely visual?" If distinct (e.g., danger means destructive, not just red), document the semantics — not just the visual difference.

Step 1: Locate the Component

Find the component source file:

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

Read the component file to understand:

• Props and their types
• Exported named variants and sub-components (e.g., Component.SubComponent, export {TabList, TabPanels})
• Available values for enum/union props
• Default prop values

The MDX file goes next to the component: <component-dir>/<component>.mdx.

If the file already exists, read it first and update rather than overwrite.

Determining the import path:

• Components in static/app/components/core/ are published as @sentry/scraps/<name>
• All other components use the sentry-internal path: sentry/components/<path>

To confirm the exact @sentry/scraps package name and type-loader path, check an existing import in the component directory or a neighboring .mdx file — the type-loader path can be @sentry/scraps/<name> or @sentry/scraps/<name>/<name> depending on the package structure.

Step 2: Determine 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>/
---

Category values:

For principle/pattern docs (no interactive component), use layout: document instead of category, and replace a11y: with reference: under resources.

Step 3: Write Imports

Follow this import order exactly:

// 1. External packages (react, etc.) — only if needed for examples
import {useState} from 'react';
// 5. Type-loader for auto-generated API docs (@sentry/scraps components only)
import documentation from '!!type-loader!@sentry/scraps/<component>';

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

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

export {documentation};

Omit any group that isn't needed. For product components (not in @sentry/scraps), omit the type-loader lines and document props manually in a table (see Step 5).

Complex export: If the component exports need filtering (e.g., to hide internal exports), use the explicit form instead of export {documentation}:

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

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

Step 4: Write Content

Section structure

Organize content by feature or user-facing variant, not by prop name:

1. Introduction — 1-2 sentences, then a minimal usage code block (no demo wrapper) 2. When to use _(if the component has meaningful alternatives or misuse risk)_ — prose guidance, optionally a do/don't <Storybook.SideBySide> 3. Feature sections — one ## per major feature: ## Sizes, ## Priorities, ## States, ## Composition 4. Accessibility — WCAG claims and developer responsibilities 5. See Also — links to related components with one-line guidance (optional)

Prefer titles like ## Sizes, ## Variants, ## States over ## The size prop.

When to use / See Also patterns:

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

Introduction pattern

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

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

````

````

Sub-components

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

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

<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:

## Sizes

<brief description>

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

<Component size="sm">Small</Component> <Component size="md">Medium</Component> <Component size="lg">Large</Component> ````

````

Demo layout helpers:

Accessibility section

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

Callout syntax

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

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

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

Step 5: Props Table (product components only)

For components not in @sentry/scraps, list props manually instead of using the type-loader:

## Props

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

Complete Example

````mdx --- 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.

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

````

Types

Alerts come in five types: muted, info, warning, success, and danger.

<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> </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>

Accessibility

This component meets WCAG 2.2 AA standards:

• Color contrast: All variants meet 4.5:1 ratio (WCAG 1.4.3)
• Keyboard accessible: Fully operable via keyboard (WCAG 2.1.1)

Checklist

Before completing, verify:

• [ ] MDX file is colocated next to the component source file (named <component>.mdx)
• [ ] Frontmatter has title, description, and source
• [ ] Imports follow the correct order (external → icons/utils → @sentry/scraps → Storybook → type-loader)
• [ ] Type-loader import is included for @sentry/scraps components
• [ ] Every <Storybook.Demo> is immediately followed by a matching code block
• [ ] Sections are organized by feature/variant, not by prop name
• [ ] Sub-components are documented with compound usage examples
• [ ] Accessibility section covers WCAG compliance and developer responsibilities
• [ ] No raw <img> tags (use <Image>), no inline SVGs, no styled components