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)
- Just a colour, size, radius, duration? → Token. Add to
theme-variables.css (semantic) or tailwind.theme.css (raw @theme).
- Layout-only (spacing, alignment, structure)? → Primitive. Reuse an existing one; only add a new one if the structural shape is genuinely novel.
- 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.
- 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/.
- 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
- Reused at least twice in different surfaces. Actual second use, not "we might reuse this."
- It's generic. A
<MembersTable> that's just <Table> with three preset columns belongs in the app, not Shade.
- The shape has settled. Slots and composition have been stable across both local copies for at least one iteration.
- It has a generic name.
PageHeader, KpiCard, Filters — not MembersFilterBar or PostAnalyticsHero.
- The API is slots, not props. 3–6 named subcomponents (
.Title, .Actions, .Body) — not <ListPage title="..." columns={...} />.
- 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.
1---2name: shade-component-decision3description: Decide which Shade layer (Token, Primitive, Component, Recipe, Pattern) a new piece of UI belongs in — and whether it should be added to Shade at all. Trigger when creating new files in apps/shade/src/components, or proposing to add a new Shade component.4---56# Shade — pick the right layer (and decide whether to add to Shade at all)78Before 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.910## The five layers1112| Layer | Lives in | Examples |13| ------------- | ------------------------------------------- | ----------------------------------------------------- |14| **Token** | `theme-variables.css`, `tailwind.theme.css` | `--background`, `--text-base`, `--radius-md` |15| **Primitive** | `src/components/primitives/` | `Stack`, `Inline`, `Box`, `Grid`, `Container`, `Text` |16| **Component** | `src/components/ui/` | `Button`, `Input`, `Dialog`, `Tabs`, `Card` |17| **Recipe** | `src/components/ui/<name>.ts` (no JSX) | `inputSurface` |18| **Pattern** | `src/components/patterns/` | `PageHeader`, `KpiCard`, `Filters`, `GhAreaChart` |1920Plus one additional barrel:2122- **`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`.2324## Decision flow (top-to-bottom, stop at first match)25261. **Just a colour, size, radius, duration?** → **Token**. Add to `theme-variables.css` (semantic) or `tailwind.theme.css` (raw `@theme`).272. **Layout-only (spacing, alignment, structure)?** → **Primitive**. Reuse an existing one; only add a new one if the structural shape is genuinely novel.283. **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.294. **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/`.305. **Knows about Ghost (KPIs, members, posts, newsletters, analytics)?** → **Pattern**.3132**Quick gut check: generic name → Component; Ghost-shaped name → Pattern.** `Button` is web-y; `KpiCard` is Ghost-y.3334## Allowed dependencies (one-way)3536Each layer can use anything **below** it. The reverse is forbidden.3738- A Button can't reach into a Pattern.39- A Primitive can't import a Component.40- A Recipe is pure CSS classes — no React, no JSX.4142## Promotion checklist — add to Shade only if ALL are true43441. **Reused at least twice in different surfaces.** Actual second use, not "we might reuse this."452. **It's generic.** A `<MembersTable>` that's just `<Table>` with three preset columns belongs in the app, not Shade.463. **The shape has settled.** Slots and composition have been stable across both local copies for at least one iteration.474. **It has a generic name.** `PageHeader`, `KpiCard`, `Filters` — not `MembersFilterBar` or `PostAnalyticsHero`.485. **The API is slots, not props.** 3–6 named subcomponents (`.Title`, `.Actions`, `.Body`) — not `<ListPage title="..." onAdd={...} columns={...} />`.496. **State stays with the consumer.** No `useQuery`, no routing, no app-context reads inside Shade.5051**Fail any of these? Keep it local.** Build it again somewhere else first, then promote.5253## Common misclassifications5455| Tempting | Actually | Why |56| -------------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------- |57| Add a `variant="kpi"` to `Card` | New Pattern `KpiCard` | Product-specific shape, generic Component shouldn't know about it |58| Add `<MembersFilterBar>` to patterns | Keep local in `apps/admin/src/settings` | Single-surface name |59| Add a one-off class string as a recipe | Inline it in the one component | Recipes are for shared rules across ≥ 2 components |60| Add a `useQuery`-driven `<MembersList>` to patterns | Keep local — patterns are state-free | Bring-your-own state |61| Wrap a `<div className="flex gap-3">` as a new primitive | Use `Inline gap="md"` | Already covered |6263## When you've decided6465- New **Component** or **Pattern** → also see the `shade-new-component` skill for the file/story/state checklist.66- New **Recipe** → no JSX, follow the `recipeClasses` + `recipe()` shape (see `apps/shade/src/components/ui/input-surface.ts`).67- 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.6869## Source of truth7071Storybook → Overview / Layers owns the layer model and promotion rules.72Overview / Contributing owns the implementation requirements.
TryGhost