agentleFS
Sign inStart free
tdiminotdimino/claude-code-minoan/skills/design-media/shadcn/SKILL.md

shadcn

Skill41 starsChanged 7 months agoMITView on GitHub

Install, customize, and compose shadcn/ui components with design-system awareness. Covers CLI v4, custom registries, Tailwind v4 OKLCH theming, components.json, presets, and monorepo setup. Pairs with minoan-frontend-design for creative direction. Triggers on shadcn, install component, shadcn theme, OKLCH colors, custom registry.

We split this skill into the rules it gives an agent

8 rules. 0 are common, 3 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 175 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every shadcn interaction follows four steps: Orient, Install, Refine, Verify.

    line 16
  2. Very specific:

    Read project state before any CLI operation.

    line 20
  3. Distinctive:

    Add components via CLI, never by copying from docs manually.

    line 24
  4. Very specific:

    Before re-adding an existing component, run npx shadcn@latest diff <name> to see upstream changes.

    line 32
  5. Distinctive:

    Composition: Create wrapper components that compose shadcn primitives.

    line 43
  6. Very specific:

    When minoan-frontend-design is active, translate its creative direction into shadcn theme variables and component customizations.

    line 45
  7. Very specific:

    Leave tailwind.config blank in components.json for v4 projects.

    line 66
  8. Very specific:

    Use cn() (clsx + tailwind-merge) for all class name composition.

    line 79

“Common” is measured: kept by at least 6 in 10 of the 175 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

Install, customize, and compose shadcn/ui components with design-system awareness. shadcn is a code distribution system — components are source files you own, not packages.

Workflow

Every shadcn interaction follows four steps: Orient, Install, Refine, Verify.

1. Orient

Read project state before any CLI operation. Run npx shadcn@latest info to get framework, installed components, aliases, icon library, and base library. Read components.json directly for theme config. Never guess configuration.

2. Install

Add components via CLI, never by copying from docs manually.

npx shadcn@latest add button card dialog    # Multiple at once
npx shadcn@latest add @namespace/component  # From custom registry
npx shadcn@latest add --dry-run button      # Preview before writing

Before re-adding an existing component, run npx shadcn@latest diff <name> to see upstream changes. Commit local customizations first — add overwrites files.

3. Refine

This is where craft lives. After every add, audit the component against the project's design system:

  • Typography: Does it use the project's font variables and scale? Replace any hardcoded font sizes.
  • Color tokens: Does it reference the project's CSS custom properties? Convert any raw color values to semantic tokens.
  • Spacing rhythm: Does it follow the project's spacing scale? Harmonize padding and margins.
  • Border radius: Does it use --radius from the theme? Shadcn sets this globally.
  • Animation: Does it use tw-animate-css classes, not tailwindcss-animate?
  • Composition: Create wrapper components that compose shadcn primitives. Edit base components only for structural changes.

When minoan-frontend-design is active, translate its creative direction into shadcn theme variables and component customizations.

4. Verify

Build the project to catch type errors. Visually inspect the component in context. Check dark mode. Check mobile.

Tailwind v4 Contract

shadcn v4 uses OKLCH color space with @theme inline — not HSL, not tailwind.config.ts.

:root {
  --primary: oklch(0.205 0.03 264.05);
  --primary-foreground: oklch(0.985 0 0);
}
@theme inline {
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

Leave tailwind.config blank in components.json for v4 projects. Use data-slot attributes for targeted styling. Use React.ComponentProps<> — forwardRef is removed.

Theming

Colors follow background + foreground pairs. The background suffix is omitted for the primary role: --primary (background), --primary-foreground (text on that background).

Extend with custom semantic tokens by adding both the CSS variable and the @theme inline mapping:

:root { --warning: oklch(0.84 0.16 84); --warning-foreground: oklch(0.14 0.04 84); }
@theme inline { --color-warning: var(--warning); --color-warning-foreground: var(--warning-foreground); }

Use cn() (clsx + tailwind-merge) for all class name composition.

References

Consult references/ on demand:

  • cli-v4-reference.md — Full command reference, flags, monorepo patterns. Read for any CLI operation.
  • components-json-schema.md — Configuration schema with all fields. Read when initializing or reconfiguring.
  • theming-oklch.md — OKLCH color system, CSS variable conventions, dark mode, custom colors. Read when theming.
  • registry-authoring.md — Custom registry creation, namespacing, auth, item types. Read when building registries.
  • tailwind-v4-migration.md — Breaking changes, upgrade path, tw-animate-css, data-slot. Read when migrating or troubleshooting.
  • component-inventory.md — 59 components by category. Read when choosing what to install.
  • customization-patterns.md — Wrapper composition, data-slot styling, diff tracking. Read when customizing components.

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.

Reviews can't be read right now.

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.

Check your setup, free