83.3K+Download
Skip to the usage guide
shadcn-uiby Google Labs

shadcn UI Skill.

A Claude Code and Codex skill for UI design: integrating and customizing shadcn/ui components: discovery, install, best practices.

  • Web & UI
  • UI code
Download OpenDesignView usage guide
google-labs-code/stitch-skills · plugins/stitch-build/skills/shadcn-ui/SKILL.mdSKILL.md
--- name: shadcn-ui description: Expert guidance for integrating and building applications with shadcn/ui components, including component discovery, installation, customization, and best practices. --- ## Core Principles ## Component Discovery and Installation ## Project Setup ## Component Architecture ## Customization Best Practices ## Blocks and Complex Components
Front matter and section headings read from the upstream file on 2026-09-14 · 9,117 characters in full

01 What it does

What the shadcn-ui Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

This skill gives an agent expert guidance for building applications with shadcn/ui, the collection of accessible, customizable components built with Radix UI or Base UI and Tailwind CSS. It covers component discovery through the shadcn MCP tools, installation with the CLI or manual integration, project setup via the create and init commands, and the components.json options such as style, baseColor, cssVariables, rsc and rtl.

It explains the components/ui/ file layout and the cn() helper, then customization through CSS variables in app/globals.css, class-variance-authority variants and wrapper components. Blocks are organized by category, followed by accessibility rules, common form, dialog and table patterns, troubleshooting, and a five-step validation list.

What it produces

  • Component source files written into components/ui/ and wired into your imports.
  • An updated components.json reflecting the configuration and added components.
  • Block source code retrieved for multi-file interfaces such as dashboards or login flows.
  • Your own wrapper component files, for example components/custom-button.tsx.
See the example prompt ↗

How It Works

  1. 01
    Browse the Catalog First

    Explore available components through the shadcn MCP tools rather than guessing names, using list_components, get_component_metadata and get_component_demo.

  2. 02
    Add the Component with the CLI

    The recommended route is the add command, which downloads source adapted to your config, installs dependencies and places files in components/ui/.

  3. 03
    Or Integrate the Source by Hand

    For manual integration, pull the code with get_component, create the file yourself, install peer dependencies and adjust imports.

  4. 04
    Initialize Project Configuration

    New projects use create to pick style, fonts and component library; existing projects run init, which writes components.json.

  5. 05
    Theme with CSS Variables

    Colors live in Tailwind config and CSS variables, with a .dark block supplying dark mode overrides.

  6. 06
    Validate Before Committing

    Type check, lint, test accessibility, check light and dark modes and verify breakpoints.

02 Find your fit

When to Use the shadcn-ui Skill

Use the shadcn-ui skill in Claude Code or Codex when the job is UI design of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

  • Starting a new project where style, fonts and component library should be chosen up front.
  • Retrofitting shadcn/ui into an existing codebase that needs a components.json configuration.
  • Working against a private or team registry declared in components.json, or browsing the public Registry Directory.
  • Assembling larger screens such as authentication flows or dashboards from prebuilt blocks.
  • Projects where keyboard navigation, ARIA attributes and focus management are non-negotiable.

Know the Boundaries

  • Component and primitive versions drift, so upgrades can break and require checking release notes.

What to Provide

  • Primitive libraryPick Radix UI or Base UI; the downloaded source is adapted to that choice.
  • Registry namesWhen more than the default registry is configured, list what is available before pulling items from it.
  • Block categoryAn optional category filter narrows which blocks are listed before fetching their source.

03 Inside the skill

Rules the shadcn-ui Skill Gives Claude Code and Codex

7 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

  1. Own the Component Code

    Treat the components as source you copied in and may rewrite, not as a dependency to be upgraded wholesale; you can change styling, behavior and structure freely.

  2. Keep Wrappers Out of Components/ui/

    Composed or extended components go in components/, never in components/ui/, which holds the shadcn components themselves.

  3. Merge Classes with Cn()

    Every shadcn component uses the cn() helper, a clsx plus tailwind-merge combination, so overrides do not conflict.

  4. Express Variants with Cva

    Variant and size logic belongs in class-variance-authority, with defaultVariants declaring which variant and size apply when none is passed.

  5. Preserve Accessibility While Customizing

    Hold on to ARIA attributes, keep keyboard handlers, test with screen readers and maintain visible focus indicators.

  6. Respect the Runtime Requirements

    shadcn/ui v4 needs React 18+ and, on Next.js projects, Next.js 13+; some components also pin specific Radix UI versions.

  7. Install Peer Dependencies Yourself When Going Manual

    Manual integration means you resolve peer dependencies and fix imports by hand instead of letting the CLI do it.

04 Put it to work

Install shadcn-ui in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add shadcn-ui to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal
npx skills add https://github.com/google-labs-code/stitch-skills --skill shadcn-ui

Generic skills CLI form for plugins/stitch-build/skills/shadcn-ui/SKILL.md; the repository may document its own path.

Give the Skill a First UI Design Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt
Set up shadcn/ui in my existing [Next.js app] with the new-york style and zinc base color, then add Button, Card and Dialog. Use the login block for the sign-in page, and wrap Button in a LoadingButton in components/ that shows a spinner while [the form submission] is pending. Keep the ARIA attributes and keyboard handling intact.

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

  • Run the project linter to catch style issues in the copied source.
  • Check accessibility with tooling such as axe DevTools.
  • Do a visual pass in both light and dark modes.
  • Verify behavior across different breakpoints.

In OpenDesign shadcn-ui is bundled: Plugins → Skills, pick it in the top bar.

Download OpenDesignRead the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author
Google Labs
Repository
github.com/google-labs-code/stitch-skills Branch main
Skill file
plugins/stitch-build/skills/shadcn-ui/SKILL.md Content checksum recorded at verification; commit 0337446
License
Apache-2.0 From LICENSE.
Repository stars
8,304 GitHub snapshot taken 2026-09-14 for the whole google-labs-code/stitch-skills repository, which contains 12 skills in this catalog. Not a rating or usage count for shadcn-ui.
Verified by OpenDesign
2026-09-14 Source file, path, license text and star count were checked. Bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

  1. Core PrinciplesWhy copied code you own beats a dependency.
  2. Component Discovery and InstallationMCP tools, CLI versus manual install, custom registries.
  3. Project Setupcreate versus init, components.json options, required dependencies.
  4. Component ArchitectureDirectory layout and the cn() class-merge utility.
  5. Customization Best PracticesCSS variable theming, cva variants, wrapper components outside components/ui/.
  6. Blocks and Complex ComponentsListing, fetching and installing multi-file blocks by category.
  7. AccessibilityRadix-backed keyboard, ARIA, focus and disabled behavior to preserve.
  8. Common PatternsImport recipes for forms, dialogs and data tables.
  9. TroubleshootingFixes for import, style conflict, dependency and version problems.
  10. Validation and QualityFive pre-commit checks from type check to responsive QA.
  11. ResourcesSetup, catalog, customization and migration reference files.
  12. ExamplesExample implementations plus form, dashboard, auth and data table patterns.
The Skill's Own Description
“Expert guidance for integrating and building applications with shadcn/ui components, including component discovery, installation, customization, and best practices.”

Front-matter description from SKILL.md. The full file is about 9,117 characters. Read the full file on GitHub.

06 Before you install

Questions About the shadcn-ui Skill

Answers come from the SKILL.md as read on 2026-09-14, not from a recorded run.

Radix UI or Base UI?

Either. You choose the primitive in your config and the CLI adapts the downloaded source accordingly. The accessibility guarantees described are tied to components built on Radix UI primitives.

shadcn UI

Run shadcn-ui on a Real UI Design Task.

The shadcn-ui skill ships inside OpenDesign. Download the app, pick the skill in Plugins → Skills, paste the prompt above, and read the plan before the result.

Download OpenDesignBrowse all skills
Terminal
npx skills add https://github.com/google-labs-code/stitch-skills --skill shadcn-ui