← All runbooks
shadcn / shadcn

shadcn/ui

This runbook guides an agent through managing shadcn/ui components and projects — adding, searching, fixing, debugging, styling, and composing UI elements. It provides project context, component docs, and usage examples sourced from the official shadcn/ui skill (https://skills.sh

agent claude-codemodel claude-sonnet-4-6snapshot python312-uveval programmatic11 stepsv1.0.0

Deploy shadcn/ui to your jetty.io

One-click installs this runbook into a collection on your Jetty account. You can run it from the Spot dashboard, schedule it, or pipe inputs in via the API.

Deploy on jetty.io →View source
The shape of the run

11 steps · start to finish.

  1. 1
    Step 1

    Environment Setup

    ▶

    Verify the project is a shadcn/ui project and capture the package runner.

    # Check that components.json exists
if [ ! -f components.json ]; then
  echo "ERROR: components.json not found — this does not appear to be a shadcn/ui project"
  exit 1
fi

# Determine the package manager (from packageManager field in project context)
# Adjust PKG_RUNNER based on npx/pnpm/bunx availability
PKG_RUNNER="npx shadcn@latest"

# Create output directory
mkdir -p /app/results

echo "Environment ready. Using runner: $PKG_RUNNER"
  2. 2
    Step 2

    Get Project Context

    ▶

    Capture the full project context and save it for diagnostics.

  3. 3
    Step 3

    Determine Task and Check Installed Components

    ▶

    Before adding or modifying anything, check what is already installed.

  4. 4
    Step 4

    Search for and Install Components (max 3 rounds)

    ▶

    Search the appropriate registry and install required components. Repeat as needed, up to 3 rounds.

  5. 5
    Step 5

    Handle Preset Operations

    ▶

    When the user asks to switch or apply a preset, always ask for the merge strategy first: **overwrite, partial, merge, or skip?**

  6. 6
    Step 6

    Enforce Critical Rules

    ▶

    Apply these rules to all generated or modified code. Fix every violation before marking the task complete.

  7. 7
    Step 7

    Updating Existing Components (max 3 rounds)

    ▶

    When asked to update a component from upstream while keeping local changes, use smart merge. **Never fetch raw files from GitHub manually — always use the CLI.**

  8. 8
    Step 8

    Record Component Changes

    ▶

    After all changes are complete, document what was done.

  9. 9
    Step 9

    Validate the Result

    ▶

    Run a final check to confirm compliance.

  10. 10
    Step 10

    Write Executive Summary

    ▶

    Write `/app/results/summary.md` with:

  11. 11
    Step 11

    Write Validation Report

    ▶

    Write `/app/results/validation_report.json` reflecting actual stage outcomes for this run.