Shade — ShadCN install guardrails

Most new Shade components start from a ShadCN install. The CLI is destructive by default — follow these guardrails.

Command

bash

pnpm dlx shadcn@latest add <component-name>

(Use pnpm, not npx / yarn / bunx. Ghost is pnpm.)

Be on a fresh branch. The CLI's diff is mixed in with your branch's changes otherwise.
Check if the component already exists in apps/shade/src/components/ui/. If it does, do not run the CLI against the repo — generate into a scratch repo and manually port the parts you want. The CLI will offer to overwrite, and you'd lose Shade customisations.

Raw ShadCN output is not Shade-quality yet. Do all of these:

Swap raw colours for semantic tokens. ShadCN ships things like bg-white, border-gray-200, text-zinc-500. Replace with bg-surface-elevated, border-border-default, text-muted-foreground, etc. See the shade-tokens-not-hex skill for the inventory.
Remove any dark: colour variants. Semantic tokens flip automatically. See shade-no-dark-variants.
Use the @/ alias for internal imports (@/lib/utils, @/components/ui/...) — not relative paths.
Ensure all four required states work: default, hover, focus-visible, disabled. (focus-visible: only — never focus:.)
Trim props that hint at a specific surface. If a prop name reads like product workflow (isMembersPage, layoutMode), it doesn't belong on a generic Component — extract a Pattern instead.
For form controls, drive border/background/focus through the inputSurface recipe instead of duplicating the chrome. See shade-input-surface-recipe.
Add a sibling <name>.stories.tsx if one isn't already there. Copy useful examples from https://ui.shadcn.com/docs/components/<name> into stories. See shade-new-component.
forwardRef + className merge via cn() — both are required.

ShadCN default	Shade convention
`bg-background dark:bg-background`	`bg-background` (token already flips)
`bg-white text-zinc-950 dark:bg-zinc-950 dark:text-zinc-50`	`bg-surface-elevated text-foreground`
`border border-input`	`border border-control-border` (form controls) or `border-border-default` (other chrome)
Direct `focus-visible:ring-2 focus-visible:ring-ring` chrome on every input	`inputSurface('self')` recipe
Relative imports `import {cn} from "../../lib/utils"`	`@/` alias: `import {cn} from '@/lib/utils'`

The component already exists in Shade — port from a scratch repo instead.
You're building a Pattern (something Ghost-shaped like KpiCard, PageHeader). ShadCN doesn't ship Patterns — write it from primitives + components.
It's a Recipe (pure class-string function). ShadCN doesn't ship Recipes.

apps/shade/AGENTS.md, Storybook → Overview / Contributing.