---

name: add-shadcn-component description: Add shadcn/ui components via pnpm dlx, then normalize generated Tailwind color classes to Scaffa theme tokens

Add shadcn Component

Add one or more shadcn/ui components, then replace any generated “design system” color utility classes with Scaffa’s Tailwind theme tokens.

Usage

Copy/add-shadcn-component <component...>

Example:

Copy/add-shadcn-component button dropdown-menu dialog

Prerequisites (assumed)

1. shadcn is initialized for the renderer and src/renderer/components.json exists (assume true; do not check).
2. The renderer theme tokens are defined in src/renderer/styles.css (Tailwind v4 @theme tokens).

If shadcn is not initialized yet, STOP and ask the user to run init first.

What This Skill Does

1. Adds shadcn components using pnpm dlx … add <componentList>
2. Identifies the files that were created/modified
3. Rewrites generated Tailwind color classes to Scaffa theme tokens (surfaces/fg/border/focus/selected/etc.)
4. Runs a build to verify TypeScript + CSS compilation
5. Lands the change (commit + bd sync + push), respecting the repo workflow

Instructions

You MUST follow these steps in order.

Phase 1: Add the component(s)

1. Run shadcn from the same folder as src/renderer/components.json:

   Copypushd src/renderer
   

2. While still in src/renderer, add the requested components.

   Preferred (explicit) command:

   Copypnpm dlx shadcn@latest add <component...>
   

   If this repo’s shadcn init documented a shorter alias (e.g. pnpm dlx add ...), use the repo’s convention instead, but keep the semantics identical: “run shadcn add for these components”.

3. Return to the repo root:

   Copypopd
   

4. Capture what changed:

   Copygit status --porcelain
   

Phase 2: Normalize generated colors to Scaffa theme tokens

Scaffa’s renderer uses Tailwind v4 theme tokens defined in src/renderer/styles.css (e.g. bg-surface-panel, bg-surface-card, bg-surface-overlay, text-fg-muted, border-default, ring-focus, bg-selected, etc).

The shadcn generator commonly emits palette tokens like bg-background, text-foreground, border-border, ring-ring, bg-primary, text-muted-foreground, etc. Those MUST be replaced with Scaffa tokens.

Prefer Scaffa’s surface role tokens over numeric surface levels:

• bg-surface-app, bg-surface-panel, bg-surface-pane (reserved; currently aliases panel), bg-surface-card, bg-surface-overlay, bg-surface-inset
• For text/borders/rings, keep using text-fg*, border-*, ring-focus, etc.

2.1 Required mapping (default)

Use this mapping as the baseline. Adjust only if the component semantics demand it.

• Backgrounds

  • bg-background → bg-surface-app
  • bg-card → bg-surface-card
  • bg-popover → bg-surface-overlay
  • bg-muted → bg-surface-inset
  • bg-accent → bg-hover
  • bg-primary → bg-selected
  • bg-secondary → bg-surface-card
  • bg-destructive → bg-danger

• Text

  • text-foreground → text-fg
  • text-muted-foreground → text-fg-muted
  • text-popover-foreground → text-fg
  • text-card-foreground → text-fg
  • text-primary-foreground → text-selected-fg
  • text-secondary-foreground → text-fg
  • text-accent-foreground → text-fg
  • text-destructive-foreground → text-fg-inverse
  • text-destructive → text-danger

• Borders

  • border-border → border-default
  • border-input → border-default
  • border-ring → border-focus
  • border-destructive → border-danger

• Rings / focus

  • ring-ring → ring-focus
  • outline-ring → outline-focus

  For common shadcn focus patterns:

  • focus-visible:ring-ring → focus-visible:ring-focus
  • focus-visible:ring-offset-background → focus-visible:ring-offset-surface-app

If you encounter shadcn tokens not covered above (e.g. bg-input, text-primary, etc.), prefer mapping them to the closest Scaffa semantic token from src/renderer/styles.css rather than introducing a new color.

2.2 How to apply the mapping safely

1. Find newly added/modified component files (from git status).
2. Search within those files for shadcn palette tokens:

   Copyrg -n \"bg-(background|card|popover|muted|accent|primary|secondary|destructive)|text-(foreground|muted-foreground|popover-foreground|card-foreground|primary-foreground|secondary-foreground|accent-foreground|destructive(-foreground)?)|border-(border|input|ring|destructive)|ring-ring|ring-offset-background|outline-ring\" <file-or-folder>
   

3. Replace only the color tokens. Do not “re-style” spacing, sizing, or layout unless necessary for compile or obvious correctness.
4. After edits, re-run the search to ensure no shadcn palette tokens remain in the touched files.

Phase 3: Verify

Run a production build:

Copypnpm build

Phase 4: Landing protocol

1. Stage changes:

   Copygit add <files>
   

2. Commit code changes (do NOT include .beads/issues.jsonl):

   Copygit commit -m \"feat(ui): add shadcn <components> (Scaffa theme)\"
   

3. Persist beads updates (if any) and push:

   Copygit pull --rebase
   # If this session is explicitly "no beads", skip `bd sync`.
   bd sync
   git push
   git status  # MUST show up to date
   

Notes / Gotchas

• This repo uses Tailwind v4 @theme tokens; prefer bg-surface-*, text-fg*, border-*, ring-focus, bg-selected, etc over shadcn’s palette tokens.
• Prefer surface roles (bg-surface-app/panel/card/overlay/inset) over numeric surface levels (bg-surface-0..3) when choosing container backgrounds.
• If a generated component requires additional tokens not in the Scaffa theme, file a ticket instead of inventing new one-off colors inside components.