Shade — use primitives, not flex divs

A <div> whose className is only flex / grid / gap / items-* / justify-* utilities is a primitive call site. Use a Shade primitive instead so layouts read by intent, not by class string.

import {Stack, Inline, Box, Grid, Container, Text} from '@tryghost/shade/primitives';

Picking the primitive

You need	Use	Element
Column of children	`Stack`	flex-col
Row of children	`Inline`	flex-row (with optional `wrap`, `as`)
Padding / radius around content	`Box`	div with `padding`, `radius` props
Two-dimensional layout	`Grid`	display: grid
Width-constrained shell	`Container`	max-width wrapper
Text with size/tone/weight	`Text`	`as`, `size`, `tone`, `weight`

Use the semantic gap scale, not raw numbers

gap="md" reads as intent and resolves to the shared spacing scale. Mapping:

Step	Tailwind	Use for
`none`	`gap-0`	flush
`xs`	`gap-1`	inline icons-to-text
`sm`	`gap-2`	dense lists, badges
`md`	`gap-3`	default row/column spacing
`lg`	`gap-5`	section spacing
`xl`	`gap-6`	between major blocks
`2xl`	`gap-8`	page-level rhythm

The same scale applies to Box padding (padding="md" → p-3).

Correct

tsx

<Box padding="lg" radius="md" className="border border-border-default">
    <Inline align="center" gap="md" justify="between">
        <Stack gap="xs">
            <Text weight="semibold">Email notifications</Text>
            <Text size="sm" tone="secondary">Get notified about engagement.</Text>
        </Stack>
        <Switch />
    </Inline>
</Box>

Incorrect

tsx

// BAD — bare div doing flex layout
<div className="flex flex-col gap-2">
    <div className="font-semibold">Title</div>
    <div className="text-sm text-gray-600">Hint</div>
</div>

// BAD — raw gap-4 instead of gap="md"
<Stack className="gap-4">

When NOT to reach for a primitive

A pattern already exists for the shape (page header → PageHeader, list page → ListPage).
The wrapper is starting to know about Ghost data — that's a Pattern, not a primitive composition.
You're inside a Shade primitive's own implementation.

className still works

Primitives forward className and merge with cn(). Use it for one-offs the prop API doesn't cover (e.g. className="border border-border-default"). Don't reach for className to set flex, gap, align, or justify — that's what the props are for.