Shadcn design skill for AI agents

Overview

Shadcn is a minimal, developer-first design system skill for AI-powered development. It captures the aesthetic that defined the modern React component era — clean surfaces, black-and-white palette, precise typography with Geist, and components that feel like they were built by engineers who care deeply about craft but refuse to over-design. If you've used shadcn/ui, you already know this look. Now your AI agent can produce it consistently.

When you add this skill file to your AI coding tool, every component it generates reflects the shadcn philosophy: tasteful restraint, functional clarity, and the kind of understated elegance that comes from removing everything that isn't necessary.

Design tokens

Color palette

Shadcn uses the most reduced palette of any typeui.sh design skill — pure black as primary, near-black as secondary, and white surfaces. Color is almost entirely absent from the default state:

The black + near-black pairing is radical in its simplicity. The AI agent cannot rely on color to differentiate between primary and secondary elements — it must use size, weight, opacity, borders, and spatial position instead. This constraint is what produces the distinctive shadcn look: interfaces where hierarchy comes from typography and spacing alone, and where the occasional flash of success green or danger red carries enormous visual weight because color is so rare.

Typography

Shadcn uses Geist for all body and display text — the typeface created by Vercel that has become synonymous with the modern developer tooling aesthetic. Geist is engineered for screens: tight metrics, excellent rendering at small sizes, and a neutrality that lets content speak without the typeface calling attention to itself.

The type scale uses six sizes with a practical range:

• 12px — Fine print, tertiary metadata
• 14px — Captions, helper text, secondary labels (the default for most UI chrome)
• 16px — Body text (default)
• 20px — Large body, lead text, card titles
• 24px — Section headings (h3)
• 32px — Page headings, hero text (h1/h2)

Font weights span 100 (thin) to 900 (black), but the shadcn approach heavily favors the 400-600 range — regular to semibold. The skill file teaches the AI to use weight changes subtly: a shift from 400 to 500 is enough to establish hierarchy. Reserve 700+ for rare moments of emphasis.

Fira Code handles monospaced content — code blocks, terminal output, inline code, and technical data. Its programming ligatures and clear glyph differentiation make it ideal for the developer-facing contexts where shadcn-style interfaces are most commonly deployed.

Spacing

A 4px base unit drives the spacing scale: 4 / 8 / 12 / 16 / 24 / 32. The shadcn aesthetic depends on spacing that's tight but never cramped. Components sit close together with consistent, small gaps — 8px between related items, 16px between groups, 24-32px between sections. The result is information-dense layouts that still feel clean, because the spacing rhythm is perfectly consistent.

Component coverage

The skill file covers 40+ component families grouped by function:

• Inputs and forms — buttons, text inputs, selects, comboboxes, checkboxes, radios, switches, textareas, date/time pickers, file uploaders
• Data display — cards, tables, data lists, data grids, charts, stats/metrics, badges, chips, avatars
• Navigation — breadcrumbs, pagination, steppers, sidebars, top bars, command palette, tabs
• Overlays — modals, drawers, sheets, tooltips, popovers, menus
• Feedback — alerts, toasts, notifications center, progress indicators, skeletons, empty states
• Page-level — authentication screens, settings pages, documentation layouts, onboarding flows, pricing blocks, search

For each component, the skill defines required interaction states (default, hover, focus-visible, active, disabled, loading, error), keyboard and touch behavior, spacing and typography token usage, and responsive edge cases.

Design philosophy

Shadcn is the design system for people who think most design systems do too much. Every decision optimizes for clarity, composability, and developer ergonomics:

• Monochrome by default — with black and near-black as the only accent tokens, the AI agent builds interfaces where color is functional (success, warning, danger) and never decorative. The absence of a colored primary is what makes shadcn-style UI instantly recognizable
• Typography-driven hierarchy — without color to differentiate, size and weight do all the work. The skill teaches the AI to make small, precise weight shifts (400 to 500, not 400 to 700) that create hierarchy through subtlety
• Thin, precise borders — shadcn components are defined by fine 1px borders in light gray. Not thick brutalist borders, not invisible borderless cards — just enough structure to define boundaries without adding visual weight
• Utility-class mindset — the skill produces components that feel like they were built with Tailwind CSS utility classes. Consistent padding, predictable margins, and no bespoke spacing values
• Composable, not opinionated — the minimal aesthetic means components combine cleanly. A shadcn card next to a shadcn table next to a shadcn form always looks like a cohesive layout because nothing is fighting for visual attention

This makes Shadcn a strong fit for:

• Developer tools, CLIs with web interfaces, and admin dashboards
• SaaS applications and internal tools
• Documentation sites and knowledge bases
• Open-source project landing pages
• Next.js and React applications using Tailwind CSS
• Any product where the team values clean engineering over flashy design

Accessibility

Shadcn enforces WCAG 2.2 AA compliance as a hard requirement. Minimal design and accessible design are natural allies — less visual noise means less that can go wrong. The skill file instructs the AI agent to:

• Use keyboard-first interaction patterns for all interactive elements
• Include visible focus states on every focusable component — the monochrome palette means focus rings can use the black primary and be unambiguously visible
• Maintain sufficient color contrast ratios, with the black-on-white foundation providing near-maximum contrast (close to 21:1) by default
• Prioritize accessibility over aesthetics when the two conflict

The minimal palette inherently supports accessibility: black text on white surfaces exceeds AA requirements by a wide margin, and the absence of decorative color means the AI never introduces contrast issues through accent colors. The challenge is ensuring that interactive elements remain distinguishable when the entire interface is monochrome — the skill addresses this through border, spacing, and interaction state definitions.

Every accessibility rule is written to be testable in code review.

How to use with Claude AI

In Cursor IDE

1. Pull the skill file into your project:

npx typeui.sh pull shadcn

2. The file is saved to .cursor/skills/shadcn/SKILL.md by default. Cursor automatically picks up skill files from this directory and makes them available to Claude.

3. Start prompting — Claude will generate shadcn-style interfaces with Geist typography, monochrome palette, thin borders, and precise spacing.

In Claude Desktop or API

1. Copy the skill file content from the typeui.sh page (use the Copy button in the sidebar).

2. Paste it into your system prompt or as a reference document at the start of your conversation.

3. Ask Claude to build components or pages. It will follow the Shadcn guidelines — black-and-white palette, Geist + Fira Code type pairing, subtle weight-based hierarchy, and tight, consistent spacing throughout.

In other AI tools

The skill file is standard markdown and works with any AI tool that accepts system-level instructions:

• Windsurf — place the file in your project's .windsurf/rules/ directory
• GitHub Copilot — add it to .github/copilot-instructions.md or reference it in your prompt
• OpenAI GPTs — upload it as a knowledge file in the GPT configuration
• Any LLM API — include the file content in the system message

What sets Shadcn apart

Shadcn is the most restrained design skill on typeui.sh. Where other skills add personality through color, type drama, or visual metaphor, Shadcn removes until only structure remains:

• Zero-color primary — #000000 primary and #111111 secondary. No blue, no purple, no accent. The AI builds hierarchy entirely through typography, borders, and space
• Geist as identity — the typeface that defined the Vercel/Next.js ecosystem gives every generated component instant recognition within the modern developer tooling world
• Subtle weight hierarchy — the skill teaches the AI to shift from 400 to 500, not 400 to 700. This micro-restraint is what separates shadcn-style UI from generic minimal design
• Fira Code for developer contexts — programming ligatures and clear glyph differentiation make code-heavy interfaces feel native rather than bolted on
• Minimal as a feature, not a limitation — the monochrome palette, thin borders, and tight spacing aren't constraints the skill works around; they're the product. Every component looks better because there's less competing for attention
• Quality gates — every rule is anchored to a token or measurable threshold, ensuring the minimal aesthetic stays systematic whether the AI generates a single dropdown or an entire admin dashboard