Shade component decision

Shade — pick the right layer (and decide whether to add to Shade at all)

Before adding anything to Shade, walk the decision flow and the promotion checklist. The default is keep code local first — premature design system additions lock in the wrong API.

The five layers

Layer	Lives in	Examples
Token	theme-variables.css, tailwind.theme.css	--background, --text-base, --radius-md
Primitive	src/components/primitives/	Stack, Inline, Box, Grid, Container, Text
Component	src/components/ui/	Button, Input, Dialog, Tabs, Card
Recipe	src/components/ui/<name>.ts (no JSX)	inputSurface
Pattern	src/components/patterns/	PageHeader, KpiCard, Filters, GhAreaChart

Plus one additional barrel:

• page-templates/ (@tryghost/shade/page-templates) — top-level page wrappers (ListPage today). Composes Patterns + Components + Primitives. If you're building a new shape that wraps a whole admin page, this is where it goes. See shade-page-templates.

Decision flow (top-to-bottom, stop at first match)

1. Just a colour, size, radius, duration? → Token. Add to theme-variables.css (semantic) or tailwind.theme.css (raw @theme).
2. Layout-only (spacing, alignment, structure)? → Primitive. Reuse an existing one; only add a new one if the structural shape is genuinely novel.
3. Generic, accessible UI control with no Ghost-specific knowledge? → Component. Reuse first; only add if it doesn't exist and the promotion checklist below passes.
4. The same chrome / focus / density rule shared across ≥ 2 components? → Recipe. A class-string function (no JSX, no React) next to the components in src/components/ui/.
5. Knows about Ghost (KPIs, members, posts, newsletters, analytics)? → Pattern.

Quick gut check: generic name → Component; Ghost-shaped name → Pattern. Button is web-y; KpiCard is Ghost-y.

Allowed dependencies (one-way)

Each layer can use anything below it. The reverse is forbidden.

• A Button can't reach into a Pattern.
• A Primitive can't import a Component.
• A Recipe is pure CSS classes — no React, no JSX.

Promotion checklist — add to Shade only if ALL are true

1. Reused at least twice in different surfaces. Actual second use, not "we might reuse this."
2. It's generic. A <MembersTable> that's just <Table> with three preset columns belongs in the app, not Shade.
3. The shape has settled. Slots and composition have been stable across both local copies for at least one iteration.
4. It has a generic name. PageHeader, KpiCard, Filters — not MembersFilterBar or PostAnalyticsHero.
5. The API is slots, not props. 3–6 named subcomponents (.Title, .Actions, .Body) — not <ListPage title="..." onAdd={...} columns={...} />.
6. State stays with the consumer. No useQuery, no routing, no app-context reads inside Shade.

Fail any of these? Keep it local. Build it again somewhere else first, then promote.

Common misclassifications

Tempting	Actually	Why
Add a variant="kpi" to Card	New Pattern KpiCard	Product-specific shape, generic Component shouldn't know about it
Add <MembersFilterBar> to patterns	Keep local in apps/admin/src/settings	Single-surface name
Add a one-off class string as a recipe	Inline it in the one component	Recipes are for shared rules across ≥ 2 components
Add a useQuery-driven <MembersList> to patterns	Keep local — patterns are state-free	Bring-your-own state
Wrap a <div className="flex gap-3"> as a new primitive	Use Inline gap="md"	Already covered

When you've decided

• New Component or Pattern → also see the shade-new-component skill for the file/story/state checklist.
• New Recipe → no JSX, follow the recipeClasses + recipe() shape (see apps/shade/src/components/ui/input-surface.ts).
• New Token → add to apps/shade/theme-variables.css (semantic + dark-mode override) or apps/shade/tailwind.theme.css (raw @theme). Never an ad-hoc CSS variable in a component file.

Source of truth

Storybook → Overview / Layers owns the layer model and promotion rules. Overview / Contributing owns the implementation requirements.