shade-use-primitives

name	Shade use primitives
description	Replace bare divs that only carry flex/grid/gap utilities with Shade primitives (Stack, Inline, Box, Grid, Container, Text). Use semantic gap="md" instead of gap-4. Trigger when editing TSX in Shade-consuming apps.
autoTrigger	[{"fileEdit":"apps/{shade,admin,admin-x-framework,activitypub}/**/*.tsx"}]

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

<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

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