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

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

Example:

/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

   :

   pushd src/renderer
   

2. While still in

   src/renderer

   , add the requested components.

   Preferred (explicit) command:

   pnpm 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:

   popd
   

4. Capture what changed:

   git 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:

   rg -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:

pnpm build

Phase 4: Landing protocol

1. Stage changes:

   git add <files>
   

2. Commit code changes (do NOT include

   .beads/issues.jsonl

   ):

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

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

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