Design SystemCAUTION

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: design-system
description: 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.
---

# Layout and Text Primitives at Sentry

## Core Principle

**ALWAYS use core components from `@sentry/scraps` instead of creating styled components with Emotion.**

Core components provide consistent styling, responsive design, and better maintainability across the codebase.

## Component Implementation Reference

For the complete list of supported props and their types, refer to the implementation files:

- **Layout Components**: `/static/app/components/core/layout/`
  - `container.tsx` - Base container with all layout props
  - `flex.tsx` - Flex layout primitive
  - `grid.tsx` - Grid layout primitive
  - `stack.tsx` - Stack layout primitive (Flex with column direction by default)
- **Typography Components**: `/static/app/components/core/text/`
  - `text.tsx` - Text primitive
  - `heading.tsx` - Heading primitive

## Layout Primitives

> **Important**: `Flex`, `Grid`, and `Stack` all extend `Container`. This means **every prop available on Container is also available on Flex, Grid, and Stack**. When you use `<Flex>`, you get all Container props (position, padding, border, overflow, etc.) PLUS the flex-specific props. The same applies to Grid and Stack.

### Container

Base layout component that supports all common layout properties. Flex, Grid, and Stack extend Container, inheriting all of its props.

**Key Props** (see `container.tsx` for complete list):

- `position`: "static" | "relative" | "absolute" | "fixed" | "sticky"
- `padding`, `paddingTop`, `paddingBottom`, `paddingLeft`, `paddingRight`: SpaceSize tokens
- `margin`, `marginTop`, etc.: SpaceSize tokens (deprecated, prefer gap)
- `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`
- `border`, `borderTop`, `borderBottom`, `borderLeft`, `borderRight`: BorderVariant tokens
- `radius`: RadiusSize tokens
- `overflow`, `overflowX`, `overflowY`: "visible" | "hidden" | "scroll" | "auto"
- `background`: SurfaceVariant ("primary" | "secondary" | "tertiary")
- `display`: Various display types
- Flex item props: `flex`, `flexGrow`, `flexShrink`, `flexBasis`, `alignSelf`, `order`
- Grid item props: `area`, `row`, `column`

```tsx
import {Container} from '@sentry/scraps/layout';

// ❌ Don't create styled components
const Component = styled('div')`
  padding: ${p => p.theme.space.md};
  border: 1px solid ${p => p.theme.tokens.border.primary};
`;

// ✅ Use Container primitive
<Container padding="md" border="primary">
  Content
</Container>;
```

### Flex

Use `<Flex>` for flex layouts. Extends `Container`, inheriting all Container props plus flex-specific props.

**Flex-Specific Props** (see `flex.tsx` for complete list):

- `direction`: "row" | "row-reverse" | "column" | "column-reverse"
- `align`: "start" | "end" | "center" | "baseline" | "stretch"
- `justify`: "start" | "end" | "center" | "between" | "around" | "evenly" | "left" | "right"
- `gap`: SpaceSize or `"${SpaceSize} ${SpaceSize}"` for row/column gap
- `wrap`: "nowrap" | "wrap" | "wrap-reverse"
- `display`: "flex" | "inline-flex" | "none"

**Plus ALL Container props**: `position`, `padding`, `margin`, `width`, `height`, `border`, `radius`, `overflow`, `background`, flex/grid item props, and more (see Container section above).

```tsx
import {Flex} from '@sentry/scraps/layout';

// ❌ Don't create styled components
const Component = styled('div')`
  display: flex;
  flex-direction: column;
  position: relative;
`;

// ✅ Use Flex primitive with props
<Flex direction="column" position="relative" gap="md">
  <Child1 />
  <Child2 />
</Flex>;
```

### Grid

Use `<Grid>` for grid layouts. Extends `Container`, inheriting all Container props plus grid-specific props.

**Grid-Specific Props** (see `grid.tsx` for complete list):

- `columns`: Grid template columns (number or CSS value)
- `rows`: Grid template rows
- `areas`: Named grid areas
- `gap`: SpaceSize or `"${SpaceSize} ${SpaceSize}"` for row/column gap
- `align`: "start" | "end" | "center" | "baseline" | "stretch" (align-items)
- `alignContent`: "start" | "end" | "center" | "between" | "around" | "evenly" | "stretch"
- `justify`: "start" | "end" | "center" | "between" | "around" | "evenly" | "stretch" (justify-content)
- `justifyItems`: "start" | "end" | "center" | "stretch"
- `flow`: "row" | "column" | "row dense" | "column dense"
- `autoColumns`, `autoRows`: Size of auto-generated tracks

**Plus ALL Container props**: `position`, `padding`, `margin`, `width`, `height`, `border`, `radius`, `overflow`, `background`, flex/grid item props, and more (see Container section above).

```tsx
import {Grid} from '@sentry/scraps/layout';

// ❌ Don't create styled components
const Component = styled('div')`
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: ${p => p.theme.space.md};
`;

// ✅ Use Grid primitive
<Grid columns="repeat(3, 1fr)" gap="md">
  <Item1 />
  <Item2 />
  <Item3 />
</Grid>;
```

### Stack

Use `<Stack>` for vertical layouts. Stack is essentially `Flex` with `direction="column"` by default. It also provides `Stack.Separator` for adding separators between items.

**Props** (see `stack.tsx` for complete list):

- Same as Flex props (inherits all Flex and Container props)
- `direction` defaults to "column" (but can be overridden)
- `Stack.Separator` component for adding dividers between stack items

```tsx
import {Stack} from '@sentry/scraps/layout';

// ❌ Don't create styled components for vertical layouts
const Component = styled('div')`
  display: flex;
  flex-direction: column;
  gap: ${p => p.theme.space.md};
`;

// ✅ Use Stack primitive (automatically column direction)
<Stack gap="md">
  <Item1 />
  <Item2 />
  <Item3 />
</Stack>;

// ✅ With separators between items
<Stack gap="md">
  <Item1 />
  <Stack.Separator />
  <Item2 />
  <Stack.Separator />
  <Item3 />
</Stack>;

// ✅ Stack sup

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.