shade-shadcn-install

name	Shade ShadCN install
description	Guardrails for running `pnpm dlx shadcn@latest add` in Shade — never overwrite existing components, fresh branch first, swap raw colours for semantic tokens after integrating. Trigger when the user proposes a shadcn add, or when a fresh ShadCN-shaped file lands in apps/shade/src/components/ui.
autoTrigger	[{"fileEdit":"apps/shade/src/components/ui/**/*.tsx"}]

Shade — ShadCN install guardrails

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

Command

pnpm dlx shadcn@latest add <component-name>

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

Before running

1. Be on a fresh branch. The CLI's diff is mixed in with your branch's changes otherwise.
2. 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.

During the prompts

• If asked to overwrite an existing file: choose No. Always.
• If asked about path aliases: keep @/.

After the file lands — required cleanup

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

1. 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.
2. Remove any dark: colour variants. Semantic tokens flip automatically. See shade-no-dark-variants.
3. Use the @/ alias for internal imports (@/lib/utils, @/components/ui/...) — not relative paths.
4. Ensure all four required states work: default, hover, focus-visible, disabled. (focus-visible: only — never focus:.)
5. 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.
6. For form controls, drive border/background/focus through the inputSurface recipe instead of duplicating the chrome. See shade-input-surface-recipe.
7. 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.
8. forwardRef + className merge via cn() — both are required.

What ShadCN gets wrong that Shade fixes

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'

When NOT to use the CLI

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

Source of truth

Storybook → Overview / Contributing. This skill adds the agent-specific safety steps for running the destructive ShadCN CLI.