agentleFS
mikeOnBreezemikeOnBreeze/cc-crossbeam/.claude/skills/shadcn/SKILL.md

shadcn

Skill297 starsChanged 9 months agoMITView on GitHub

Expert guide for ShadCN UI component library with Next.js. Use when working with ShadCN/UI projects including (1) Initial setup and configuration, (2) Adding and customizing components, (3) Theming and styling patterns, (4) Avoiding common mistakes like hardcoding styles instead of using variants/design tokens. Critical for maintaining consistent, reusable component patterns instead of one-off hardcoded implementations.

190 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use migrate-radix-to-base, nuqs and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • shadcn-uiSkill

    migrate-radix-to-base

    Migrates React projects and components from Radix UI to Base UI. Use when asked to migrate from radix, move to base-ui, convert radix primitives, or switch a shadcn project's base library. Handles single components ("migrate accordion") and whole projects.

    Also in 15 projects that use this

  • thongdn-itSkill

    nuqs

    nuqs (type-safe URL query state) best practices for Next.js applications. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, or Next.js routing with state.

    Also in 4 projects that use this

  • bergsideSkill

    friendly

    Approachable, intuitive design with rounded elements, ample whitespace, and soft pastel color palettes.

    Also in 4 projects that use this

  • bergsideSkill

    professional

    Polished, business-ready design with modern typography, structured layouts, and a trustworthy visual identity.

    Also in 4 projects that use this

  • SupabaseSkill

    react-hook-form

    Correct React Hook Form usage anywhere in the monorepo — data flow, subscriptions,

    Also in 5 projects that use this

  • barisariburnuSkill

    tanstack

    Expert assistance for TanStack Router, Query (v5), and Table (v8). Use when users need help with file-based routing, type-safe navigation, data loading, search params, queries, mutations, optimistic updates, infinite queries, table state management, or debugging TanStack libraries.

    Also in 4 projects that use this

  • +6 more from bergside

The file

We split this skill into the rules it gives an agent

6 rules. 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 187 edited versions we read keep these.

  • 5

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Critical Rule: Always use CSS variables and component variants for styling.

    line 12
  2. Distinctive:

    Use Variants: - Never hardcode styles; always create/use component variants

    line 58
  3. Very specific:

    cn() Utility: - Always use cn() from lib/utils.ts for conditional classes

    line 61
  4. Distinctive:

    Search the official docs for:

    line 122
  5. Distinctive:

    Always use the theming system - never hardcode colors or spacing

    line 140
  6. Distinctive:

    Use composition to build complex UIs from simple pieces

    line 142

“Common” is measured: kept by at least 6 in 10 of the 187 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

ShadCN UI Expert Guide

Core Philosophy

ShadCN UI is NOT a traditional component library - it's a code distribution system that copies source code directly into your project at components/ui/. You own and control the code completely.

Critical Rule: Always use CSS variables and component variants for styling. NEVER hardcode styles directly in components. This maintains consistency across your design system.

⚠️ Critical: Tailwind v4 Color Issue

If colors aren't showing up in Tailwind v4, you need to wrap CSS variables with hsl():

/* ❌ WRONG - Colors won't work */
@theme inline {
  --color-primary: var(--primary);
}

/* ✅ CORRECT - Wrap with hsl() */
@theme inline {
  --color-primary: hsl(var(--primary));
}

ShadCN stores HSL channels as raw values (28 100% 50%). Tailwind v4's @theme inline needs hsl() wrapper to recognize them as colors.

See theming-guide.md for full details.

Quick Reference

Initial Setup

npx shadcn@latest init        # Interactive setup
npx shadcn@latest init -d     # Use defaults (recommended)

Adding Components

npx shadcn@latest add button card dialog

Components install to components/ui/[component-name].tsx

Import & Use

import { Button } from "@/components/ui/button"

<Button variant="default" size="lg">Click me</Button>

Core Principles

  1. Use Variants - Never hardcode styles; always create/use component variants
  2. CSS Variables - Theme with CSS variables in globals.css, not hardcoded colors
  3. Composition - Build complex UIs by composing simple components
  4. cn() Utility - Always use cn() from lib/utils.ts for conditional classes
  5. Own Your Code - Components live in your repo; modify them as needed

Detailed Documentation

For comprehensive guides and examples, read these reference files:

  • setup-guide.md - Detailed installation, configuration, and components.json setup
  • component-patterns.md - Complete examples: forms with validation, data tables, dialogs, layouts
  • theming-guide.md - CSS variables, dark mode, custom themes, color systems
  • variant-creation.md - How to create and extend component variants properly
  • common-mistakes.md - Anti-patterns to avoid with correct alternatives

Quick Anti-Patterns

❌ Wrong

// Hardcoded styling
<Button className="bg-blue-600 text-white px-8">Submit</Button>

// Arbitrary overrides
<Button className="!bg-red-500 !text-lg">Click</Button>

// Duplicated code
<button className="rounded-lg bg-primary px-4 py-2">Save</button>

✅ Correct

// Use variants
<Button variant="primary" size="lg">Submit</Button>

// Create new variant in components/ui/button.tsx
variants: {
  variant: {
    danger: "bg-destructive text-destructive-foreground"
  }
}

// Use component system
<Button>Save</Button>

File Structure

project/
├── components/
│   ├── ui/              # ShadCN components (YOU OWN)
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   └── ...
│   └── custom/          # Your extensions
├── lib/
│   └── utils.ts         # cn() utility
├── app/
│   └── globals.css      # Theme CSS variables
└── components.json      # ShadCN config

When to Use Web Search

Search the official docs for:

  • Specific component API details
  • New/updated component examples
  • Advanced composition patterns
  • Latest features or changes

Example: shadcn ui [component-name] examples

Server vs Client Components

  • Server Components (no "use client"): Card, Badge, Typography, Separator
  • Client Components (has "use client"): Dialog, Dropdown, Sheet, Form

Interactive components automatically include the directive.

Key Reminders

  • Components don't auto-update; manually re-add or update them
  • Always use the theming system - never hardcode colors or spacing
  • Build reusable patterns with variants, not one-off implementations
  • Use composition to build complex UIs from simple pieces
  • Official docs: https://ui.shadcn.com

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.