React Component DocumentationCAUTION

Developer-first error tracking and performance monitoring

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: react-component-documentation
description: Create or update component documentation in Sentry's MDX stories format. Use when asked to "document a component", "add stories", "write component docs", "create an mdx file", "add a stories.mdx", or document a design system component. Generates structured MDX with live demos, accessibility guidance, and auto-generated API docs from TypeScript types.
allowed-tools: Read, Grep, Glob, Write, Edit
---

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

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

.claude/skills

api-docs/.node-version

Gates applied: no_behavioural_pass.