import { Meta } from '@storybook/addon-docs/blocks';

<Meta title="Overview / Layers" /> <div className="sb-doc">

Layers

<p className="excerpt">Shade is a stack of layers. Each layer has one job and lives in one folder. Pick the right layer when you build, and the rest of the system answers itself.</p>

The stack

Layer	What it is	Lives in	Examples
Tokens	Named visual values (colour, size, duration). No markup.	theme-variables.css, tailwind.theme.css	--background, --text-base, --radius-md
Primitives	Layout vocabulary — rows, columns, padding, gaps. No domain meaning.	src/components/primitives/	Stack, Inline, Box, Grid, Container, Text
Components	Generic, accessible UI controls. Same on every page.	src/components/ui/	Button, Input, Dialog, Tabs, Card
Recipes	Shared visual rules (class-string functions). No JSX.	src/components/ui/<name>.ts	inputSurface — chrome shared by Input, Textarea, Select trigger
Patterns	Product-shaped compositions. Know Ghost.	src/components/patterns/	PageHeader, ListPage, Filters, KpiCard, GhAreaChart

Each layer is allowed to use anything below it. The reverse is forbidden: a Button can't reach into a Pattern, a Primitive can't import a Component.

Picking a layer

Ask: what is this thing doing?

• Changing spacing, alignment, or structure? → Primitive (Stack, Inline, Box, Grid, Container).
• A generic interactive control with no Ghost-specific knowledge? → Component (use an existing one; otherwise add to components/ui/).
• The same chrome, focus ring, or visual rule appears on multiple components? → Recipe (a class-string function in components/ui/).
• It knows about Ghost — KPIs, members, posts, newsletters? → Pattern (components/patterns/<name>.tsx).

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

When to add to Shade at all

The default is to keep code local first. A component used in one place doesn't belong in a design system.

Promote to Shade when:

1. Real reuse exists, not expected reuse. You've already built substantially the same shape a second time in a different surface.
2. The shape has settled. Slots and composition have been stable across both local copies for at least one iteration.
3. The name is generic. PageHeader, KpiCard, PostShareModal describe concepts. MembersFilterBar names a single surface and will date the moment that surface changes.
4. API is slots, not props. 3–6 named subcomponents (.Title, .Actions, .Body) — not a prop bag.
5. State stays with the consumer. No useQuery inside a pattern. No app context reads. Bring-your-own state.

When in doubt: keep it local, build it again somewhere else, then promote.

Posts–Stats (temporary)

The posts-stats/ folder is an interim home for components shared between the Posts and Stats apps until they merge. Don't generalise it — that category goes away on its own.

Where to go next

• Browse the galleries. The sidebar lists every primitive, component, recipe, and pattern with live examples.
• For implementation rules (where new files go, naming, ShadCN guardrails, commit format): see Contributing.
• For agent-facing rules: see apps/shade/AGENTS.md — the canonical decision flow for AI-assisted work.

</div>