Shadcn UI & Blocks

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

	Blocks	Components
What	Full page sections	Reusable UI elements
Size	Hero, pricing, footer, etc.	Buttons, inputs, dialogs, etc.
Count	1,338 across 71 categories	1,189 across 60+ groups
Access	Premium (API key required)	Free
Install	@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 for structured multiple-choice refinement. Consult references/block-index.md → selection_prompts for the pre-defined questions and options per section.

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 is unavailable, ask the same question inline with numbered options.

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 entries. Return exactly 2-3 recommendations in this format:

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 used to differentiate blocks:

Dimension	What it tells you	Example values
layout	Visual arrangement	centered, split_right_media, grid_cards, bento, alternating
tone	Aesthetic feel	minimal, modern, bold, enterprise, elegant, playful
goal	Business purpose	awareness, explain, trust, convert, capture_leads, compare
cta_pattern	Action type	single_primary, primary_secondary, form_capture, multi_action
media	Visual content	screenshot, illustration, video, icons, avatars, logos
interaction	Dynamic behavior	static, accordion, tabs, carousel, toggle, hover
items_count	Number of items displayed	few, moderate, many
content_density	How much content	minimal, standard, rich
complexity	Implementation effort	low, medium, high

When to Use Which Reference

Scenario	Use
Recommending best-fit blocks (default)	references/block-index.md — tagged picks with selection prompts
User wants a specific numbered variant	references/block-catalog.md — full catalog with all variant numbers
Section not in block-index (e.g., blog, gallery)	references/block-catalog.md — fall back to category defaults
User wants to browse all options	Direct to https://shadcnblocks.com/explorer/blocks
Need an individual UI element	references/component-catalog.md — free components

---

Quick Category Reference

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

Content & Blog

Need	Category	Start With
Blog listing	blog (22 variants)	blog1
Blog post page	blogpost (7 variants)	blogpost1
Changelog	changelog (7 variants)	changelog1
Code snippets	code-example (5 variants)	code-example1

About & Team

Need	Category	Start With
About section	about (17 variants)	about1
Team page	team (14 variants)	team1
Company timeline	timeline (15 variants)	timeline1
Job listings	careers (9 variants)	careers1

Ecommerce

Need	Category	Start With
Product cards	product-card (10 variants)	product-card1
Product listing	product-list (10 variants)	product-list1
Product detail	product-detail (10 variants)	product-detail1
Shopping cart	shopping-cart (11 variants)	shopping-cart1
Checkout	checkout (6 variants)	checkout1
Order history	order-history (5 variants)	order-history1

App & Dashboard

Need	Category	Start With
Dashboard charts	chart-card (27 variants)	chart-card10
Data tables	data-table (32 variants)	data-table1
App sidebar	sidebar (21 variants)	sidebar1
App shell layout	application-shell (14 variants)	application-shell1
User profile	user-profile (12 variants)	user-profile1

Portfolio

Need	Category	Start With
Image gallery	gallery (48 variants)	gallery1
Project listing	projects (25 variants)	projects1
Project detail	project (33 variants)	project1
Case studies	case-studies (6 variants)	case-studies1

Visual & Decorative

Need	Category	Start With
Background patterns	background-pattern (40 variants)	background-pattern1
Animated shaders	shader (10 variants)	shader1
Bento grid layout	bento (8 variants)	bento1

Navigation & Misc

Need	Category	Start With
Announcement bar	banner (7 variants)	banner1
Sale/promo bar	promo-banner (7 variants)	promo-banner1
Partner logos	logos (13 variants)	logos1
Comparisons	compare (10 variants)	compare1

---

Selecting the Right Component

Consult references/component-catalog.md for the full catalog. Key groups:

Need	Component Group	Example
Form layout	Form (86)	form-signin-1
Labeled input	Field (38)	field-standard-1
Input with addon	Input Group (39)	input-group-standard-1
Searchable select	Combobox (42)	combobox-standard-1
File upload	File Upload (44)	file-upload-standard-1
Date picker	Date Picker (8)	date-picker-standard-1
Alert message	Alert (25)	alert-error-1
Confirm dialog	Alert Dialog (39)	alert-dialog-standard-1
Loading skeleton	Skeleton (30)	skeleton-standard-1
Toast notification	Sonner (24)	sonner-standard-1
Empty state	Empty (22)	empty-standard-1
Modal dialog	Dialog (17)	dialog-standard-1
Side panel	Sheet (29) / Drawer (22)	sheet-standard-1
Accordion	Accordion (21)	accordion-standard-1
Data chart	Chart (70)	chart-standard-1
Command palette	Command (21)	command-standard-1
Dropdown menu	Dropdown Menu (30)	dropdown-menu-standard-1
Keyboard shortcuts	KBD (39)	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 in the project root.

2. Configure ShadcnBlocks Registry

Check if components.json already has the @shadcnblocks registry. If not, run:

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

This adds the @shadcnblocks registry to components.json and sets SHADCNBLOCKS_API_KEY in .env.

If the script can't run (e.g., jq missing), configure manually:

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 with SHADCNBLOCKS_API_KEY and ensure .env is in .gitignore.

Troubleshooting

Issue	Resolution
Auth error on install	Verify SHADCNBLOCKS_API_KEY is set in .env with a valid key
Registry not found	Check registries key exists in components.json
components.json missing	Run npx shadcn@latest init
1Password access	Run op signin; verify vault with op vault list
Block not found	Check block name at https://shadcnblocks.com

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)