Shadcn UI & ShadcnBlocks Integration

This skill enables building polished frontends using shadcn/ui components and premium ShadcnBlocks templates. Its primary capability is intelligently recommending the best block or component for any UI need — not just the right category, but the right variant within that category — then handling setup and installation.

When to Use

Activate this skill when:

• Creating a new frontend, landing page, marketing site, or app UI
• The project uses or should use React/Next.js with Tailwind CSS
• Pre-built UI sections (hero, pricing, features, testimonials, etc.) would accelerate development
• The user needs a specific UI element (form, chart, dialog, navigation, etc.)
• The user mentions shadcn, shadcn/ui, shadcnblocks, or Tailwind-based UI components

Blocks vs Components

@shadcnblocks/<name><number>

@shadcnblocks/<type>-<style>-<number>

Use blocks to compose full page layouts from pre-built sections. Use components for individual UI elements inside custom code.

Intelligent Block Selection

The 0-2 Question Rule

When recommending blocks, follow this progressive disclosure flow:

• 0 questions: The user's request is specific enough to match directly (e.g., "add a hero with email capture form" → match on

  cta_pattern: form_capture

  )
• 1 question: The section is clear but the style/layout is ambiguous (e.g., "add a feature section" → ask about layout preference)
• 2 questions max: Both section and style are unclear (e.g., "add a section to show our product" → ask section type, then style)

Never ask more than 2 questions. If still ambiguous, pick the best 2-3 and explain the tradeoffs.

Decision Flow: Infer → Ask → Shortlist

Step 1 — Infer from the request (always do this first)

Extract as many constraints as possible before asking anything:

• Section type: hero, feature, pricing, testimonial, cta, faq, navbar, footer, contact, stats
• Goal keywords: "signup" → convert/capture_leads, "trust" → trust, "compare plans" → compare
• Layout hints: "grid" → grid_cards, "side by side" → split, "accordion" → accordion interaction
• Tone hints: "clean" → minimal, "bold" → bold, "professional" → enterprise
• Media hints: "with screenshots" → screenshot media, "video" → video media
• Density hints: "simple" → minimal density, "detailed" → rich density

Step 2 — Ask targeted questions (only if needed)

Use

AskUserQuestion

references/block-index.md

selection_prompts

Sections with pre-defined prompts: hero, feature, pricing, testimonial, cta, faq, navbar, footer, contact, stats.

Example for a feature section request:

AskUserQuestion:
  question: "How do you want to showcase your features?"
  options:
    - "Card grid (3-4 columns with icons)" — Classic feature grid with icon + description per card
    - "Alternating image + text rows" — Deep-dive with large visuals, great for product tours
    - "Bento / asymmetric grid" — Modern editorial layout with mixed-size cards
    - "Simple icon list or checklist" — Compact, scannable benefit list

If

AskUserQuestion

Step 3 — Match tags and return 2-3 best picks

Map the user's answer to tag filters, then match against

references/block-index.md

Here are the best matches for your [section type]:

1. **[block-id]** — [1-line "why this one"]
   Layout: [layout] · Tone: [tone] · [key differentiator]

2. **[block-id]** — [1-line "why this one"]
   Layout: [layout] · Tone: [tone] · [key differentiator]

3. **[block-id]** — [1-line "why this one"]
   Layout: [layout] · Tone: [tone] · [key differentiator]

Which one works best? I'll install it and set it up.

After the user picks, provide the install command and compose it into the page.

Tag Dimensions Used for Matching

These are the key dimensions from

references/block-index.md

layout

tone

goal

cta_pattern

media

interaction

items_count

content_density

complexity

When to Use Which Reference

references/block-index.md

references/block-catalog.md

references/block-catalog.md

references/component-catalog.md

Quick Category Reference

For sections not yet in block-index.md, use these defaults:

Content & Blog

blog

blog1

blogpost

blogpost1

changelog

changelog1

code-example

code-example1

About & Team

about

about1

team

team1

timeline

timeline1

careers

careers1

Ecommerce

product-card

product-card1

product-list

product-list1

product-detail

product-detail1

shopping-cart

shopping-cart1

checkout

checkout1

order-history

order-history1

App & Dashboard

chart-card

chart-card10

data-table

data-table1

sidebar

sidebar1

application-shell

application-shell1

user-profile

user-profile1

Portfolio

gallery

gallery1

projects

projects1

project

project1

case-studies

case-studies1

Visual & Decorative

background-pattern

background-pattern1

shader

shader1

bento

bento1

Navigation & Misc

banner

banner1

promo-banner

promo-banner1

logos

logos1

compare

compare1

Selecting the Right Component

Consult

references/component-catalog.md

form-signin-1

field-standard-1

input-group-standard-1

combobox-standard-1

file-upload-standard-1

date-picker-standard-1

alert-error-1

alert-dialog-standard-1

skeleton-standard-1

sonner-standard-1

empty-standard-1

dialog-standard-1

sheet-standard-1

accordion-standard-1

chart-standard-1

command-standard-1

dropdown-menu-standard-1

kbd-standard-1

Core Workflow

1. Ensure Project Foundation

Verify the project has shadcn/ui initialized. If not:

npx shadcn@latest init

This creates

components.json

2. Configure ShadcnBlocks Registry

Check if

components.json

@shadcnblocks

bash "${CLAUDE_PLUGIN_ROOT}/skills/shadcn-ui/scripts/setup-shadcnblocks.sh" .

This adds the

@shadcnblocks

components.json

SHADCNBLOCKS_API_KEY

.env

If the script can't run (e.g.,

jq

1. Add to

   .env

   :

   SHADCNBLOCKS_API_KEY=<key>

2. Add registry to

   components.json

   :

{
  "registries": {
    "@shadcnblocks": {
      "url": "https://shadcnblocks.com/r/{name}",
      "headers": {
        "Authorization": "Bearer ${SHADCNBLOCKS_API_KEY}"
      }
    }
  }
}

3. Select and Install Blocks

Use the intelligent selection flow (above) to recommend the best blocks, then install:

# Blocks (full page sections)
npx shadcn add @shadcnblocks/hero125
npx shadcn add @shadcnblocks/pricing3

# Components (UI elements)
npx shadcn add @shadcnblocks/accordion-standard-1
npx shadcn add @shadcnblocks/file-upload-standard-1

4. Compose the Page

Import and compose blocks in the page layout:

import { Navbar1 } from "@/components/navbar1";
import { Hero125 } from "@/components/hero125";
import { Feature3 } from "@/components/feature3";
import { Footer1 } from "@/components/footer1";

export default function LandingPage() {
  return (
    <>
      <Navbar1 />
      <Hero125 />
      <Feature3 />
      <Footer1 />
    </>
  );
}

Blocks are fully editable source code, not locked dependencies. Customize props and content after installation.

Landing Page Assembly Pattern

For a typical marketing landing page, use the intelligent selection flow for each section. A common assembly:

npx shadcn add @shadcnblocks/navbar1      # Simple nav with CTA
npx shadcn add @shadcnblocks/hero125      # Modern centered hero
npx shadcn add @shadcnblocks/logos1        # Trust logos strip
npx shadcn add @shadcnblocks/feature3     # 3-column feature cards
npx shadcn add @shadcnblocks/stats1       # Metrics bar
npx shadcn add @shadcnblocks/testimonial1 # Social proof grid
npx shadcn add @shadcnblocks/pricing3     # 3-tier pricing cards
npx shadcn add @shadcnblocks/faq1         # Accordion FAQ
npx shadcn add @shadcnblocks/cta1         # Final call to action
npx shadcn add @shadcnblocks/footer1      # Multi-column footer

Each of these was selected for a "modern SaaS" tone. For different tones (enterprise, minimal, bold, playful), the selection flow will recommend different variants.

API Key Management

The ShadcnBlocks API key can be provided in multiple ways (checked in order):

1. Environment variable (simplest): Set

   SHADCNBLOCKS_API_KEY

   in your shell or

   .env

   file
2. 1Password CLI: The helper script uses

   op read

   to retrieve the key. Set

   OP_SHADCNBLOCKS_REF

   to your 1Password reference path, or it defaults to

   op://Platform Infra/ShadcnBlocks API Key/credential

Retrieve the key using the helper script:

bash "${CLAUDE_PLUGIN_ROOT}/skills/shadcn-ui/scripts/get-api-key.sh"

Security: Never hardcode the API key in source files. Always use

.env

SHADCNBLOCKS_API_KEY

.env

.gitignore

Troubleshooting

SHADCNBLOCKS_API_KEY

.env

registries

components.json

components.json

npx shadcn@latest init

op signin

op vault list

Reference Files

• references/block-index.md

  — Tagged picks with selection prompts for intelligent block recommendation (primary source)

• references/block-catalog.md

  — Full catalog of 1,338 blocks across 71 categories with variant numbers and install commands

• references/component-catalog.md

  — Full catalog of 1,189 components across 60+ groups with install syntax

• references/setup-guide.md

  — Detailed step-by-step setup with troubleshooting

Scripts

• scripts/setup-shadcnblocks.sh

  — Automated project setup (retrieves key, configures registry)

• scripts/get-api-key.sh

  — Retrieve API key (env var or 1Password)