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.
| 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.
More from getsentry/sentry
design-system
Guide for using Sentry's layout and text primitives. Use when implementing UI components, layouts, or typography. Enforces use of core components over styled components.
84sentry-security
Sentry-specific security review based on real vulnerability history. Use when reviewing Sentry endpoints, serializers, or views for security issues. Trigger keywords: "sentry security review", "check for IDOR", "access control review", "org scoping", "cross-org", "security audit endpoint".
67generate-migration
Generate Django database migrations for Sentry. Use when creating migrations, adding/removing columns or tables, adding indexes, or resolving migration conflicts.
67sentry-javascript-bugs
Review Sentry React and TypeScript changes for bug patterns drawn from real production issues. Use when reviewing a frontend diff or PR, checking Warden findings, auditing the current branch, reviewing production-error patterns, or looking for common regressions in `static/`.
61generate-frontend-forms
Guide for creating forms using Sentry's new form system. Use when implementing forms, form fields, validation, or auto-save functionality.
61migrate-frontend-forms
Guide for migrating forms from the legacy JsonForm/FormModel system to the new TanStack-based form system.
57