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.

Question	Where it surfaces in the docs
When should a developer reach for this component?	Introduction or a `## When to use` section
When should they NOT use it — and what should they use instead?	`> [!WARNING]` callout or `## See Also` with guidance
What does each variant/priority mean semantically?	Description in each variant's section (e.g., " `danger` = destructive and irreversible")
What do developers commonly get wrong?	`> [!WARNING]` callouts, icon-only accessibility notes, required prop reminders
Does this component require a specific parent, peer, or provider to work correctly?	Noted in the introduction or a `> [!NOTE]` callout
Are there related components that overlap in purpose?	`## See Also` with one-line guidance on when to prefer each
Which props and variants are worth documenting with a demo?	See prop triage below

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:

Tier	Document how	Examples
Core — defines the component's primary behavior or appearance	Full `##` section with live demo and semantic description of each value	`priority` , `variant` , `size`
Modifier — adjusts a single aspect; values are self-explanatory	Brief mention with a demo, or a single combined demo with other modifiers	`disabled` , `busy` , `icon` , `showIcon`
Structural — controls layout or composition	Demo showing the before/after or compound usage	`system` , `expand` , `trailingItems`
Internal / pass-through — not user-facing	Skip entirely	`className` , `style` , `ref` , `data-test-id`

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>

@sentry/scraps/<name>/<name>

depending on the package structure.

Step 2: Determine Frontmatter

yaml

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

Category	Components
`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`	design patterns, principles

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:

jsx

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

jsx

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:

Introduction — 1-2 sentences, then a minimal usage code block (no demo wrapper)
When to use (if the component has meaningful alternatives or misuse risk) — prose guidance, optionally a do/don't
```
<Storybook.SideBySide>
```

Feature sections — one

##

per major feature:

## Sizes

## Priorities

## States

## Composition

Accessibility — WCAG claims and developer responsibilities
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:

mdx

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

mdx

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

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

Callout syntax

mdx

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

mdx

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

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

jsx

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

undefined

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

react-component-documentation

NPX Install

Tags

SKILL.md Content