`.
- **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs.
- **Use `Badge`** instead of custom styled spans.
```
Source: https://raw.githubusercontent.com/shadcn-ui/ui/main/skills/shadcn/SKILL.md
### Forcing the CLI as the only source of truth (no training-data guessing, no raw GitHub fetches)
Category: `tool-gating` (Tool-gating) · all 20 in this category: https://state-of-ai-in-design-systems.netlify.app/techniques/tool-gating.md
The skill repeatedly forbids the model from relying on memory or ad-hoc HTTP, routing every knowledge lookup and every mutation through the CLI. It also refuses to let the agent pick a registry on the user’s behalf, and forbids destructive `--overwrite` without explicit approval, an anti-autonomy guardrail.
```markdown
**When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing.
...
8. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, `@tailark`, `owner/repo`, etc.), ask which registry to use. Never default to a registry on behalf of the user.
## Updating Components
When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.**
1. Run `npx shadcn@latest add
--dry-run` to see all files that would be affected.
2. For each file, run `npx shadcn@latest add --diff ` to see what changed upstream vs local.
...
4. **Never use `--overwrite` without the user's explicit approval.**
```
Source: https://raw.githubusercontent.com/shadcn-ui/ui/main/skills/shadcn/SKILL.md
### Live project-context injection at skill load (`info --json`)
Category: `curated-context` (Curated context) · all 21 in this category: https://state-of-ai-in-design-systems.netlify.app/techniques/curated-context.md
Rather than describing shadcn/ui in the abstract, the skill executes the CLI inside its own body (`!` command interpolation) so the model always sees the real project’s aliases, base library, icon library, Tailwind version and installed components. It then tells the model exactly how to act on each field: never assume lucide-react, never hardcode `@/`, never create a new CSS file. `allowed-tools` narrows the agent to shadcn CLI invocations only.
````markdown
---
name: shadcn
description: Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. ...
user-invocable: false
allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)
---
## Current Project Context
```json
!`npx shadcn@latest info --json`
```
...
## Key Fields
- **`aliases`** → use the actual alias prefix for imports (e.g. `@/`, `~/`), never hardcode.
- **`isRSC`** → when `true`, components using `useState`, `useEffect`, event handlers, or browser APIs need `"use client"` at the top of the file.
- **`tailwindCssFile`** → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
- **`base`** → primitive library (`radix` or `base`). Affects component APIs and available props.
- **`iconLibrary`** → determines icon imports. Use `lucide-react` for `lucide`, `@tabler/icons-react` for `tabler`, etc. Never assume `lucide-react`.
````
Source: https://raw.githubusercontent.com/shadcn-ui/ui/main/skills/shadcn/SKILL.md
### MCP-side audit checklist as a post-generation validation loop
Category: `validation-loop` (Validation loop) · all 29 in this category: https://state-of-ai-in-design-systems.netlify.app/techniques/validation-loop.md
The MCP server exposes a tool whose whole purpose is to make the agent self-review after generating code. The tool description is written as an instruction to the model (‘Make sure to run the tool after all required steps have been completed’), and the returned payload is a markdown checkbox list that pushes the agent into lint/typecheck/browser verification, including chaining to Playwright MCP.
```typescript
{
name: "get_audit_checklist",
description:
"After creating new components or generating new code files, use this tool for a quick checklist to verify that everything is working as expected. Make sure to run the tool after all required steps have been completed.",
inputSchema: zodToJsonSchema(z.object({})),
},
// ...
case "get_audit_checklist": {
return {
content: [
{
type: "text",
text: dedent`## Component Audit Checklist
After adding or generating components, check the following common issues:
- [ ] Ensure imports are correct i.e named vs default imports
- [ ] If using next/image, ensure images.remotePatterns next.config.js is configured correctly.
- [ ] Ensure all dependencies are installed.
- [ ] Check for linting errors or warnings
- [ ] Check for TypeScript errors
- [ ] Use the Playwright MCP if available.
`,
},
],
}
}
```
Source: https://raw.githubusercontent.com/shadcn-ui/ui/main/packages/shadcn/src/mcp/index.ts
### Incorrect/Correct exemplar pairs as the rule bodies
Category: `exemplars` (Exemplars) · all 10 in this category: https://state-of-ai-in-design-systems.netlify.app/techniques/exemplars.md
Every Critical Rule links to a rules/*.md file (styling, forms, composition, icons, chat, base-vs-radix) built almost entirely out of minimal-pair code blocks labelled **Incorrect:** / **Correct:**. This is few-shot conditioning rather than prose policy: the model sees the exact wrong output it is likely to produce next to the sanctioned one.
````markdown
## Semantic colors
**Incorrect:**
```tsx
```
**Correct:**
```tsx
```
---
## No raw color values for status/state indicators
For positive, negative, or status indicators, use Badge variants, semantic tokens like `text-destructive`, or define custom CSS variables — don't reach for raw Tailwind colors.
**Incorrect:**
```tsx
+20.1%
Active
-3.2%
```
````
Source: https://raw.githubusercontent.com/shadcn-ui/ui/main/skills/shadcn/rules/styling.md
### Committed eval suite for the skill (rule-level assertions)
Category: `validation-loop` (Validation loop) · all 29 in this category: https://state-of-ai-in-design-systems.netlify.app/techniques/validation-loop.md
skills/shadcn/evals/evals.json holds prompt → expectations pairs where each expectation is a restatement of a Critical Rule (‘Uses gap-* instead of space-y-*’, ‘No manual dark: color overrides’). This turns the coercion rules into a regression-testable contract on model output, which is rare among design systems.
```json
{
"skill_name": "shadcn",
"evals": [
{
"id": 1,
"prompt": "I'm building a Next.js app with shadcn/ui (base-nova preset, lucide icons). Create a settings form component with fields for: full name, email address, and notification preferences (email, SMS, push notifications as toggle options). Add validation states for required fields.",
"expected_output": "A React component using FieldGroup, Field, ToggleGroup, data-invalid/aria-invalid validation, gap-* spacing, and semantic colors.",
"files": [],
"expectations": [
"Uses FieldGroup and Field components for form layout instead of raw div with space-y",
"Uses Switch for independent on/off notification toggles (not looping Button with manual active state)",
"Uses data-invalid on Field and aria-invalid on the input control for validation states",
"Uses gap-* (e.g. gap-4, gap-6) instead of space-y-* or space-x-* for spacing",
"Uses semantic color tokens (e.g. bg-background, text-muted-foreground, text-destructive) instead of raw colors like bg-red-500",
"No manual dark: color overrides"
]
}
```
Source: https://raw.githubusercontent.com/shadcn-ui/ui/main/skills/shadcn/evals/evals.json
### Globbed parity rule for contributors’ agents
Category: `instruction-files` (Instruction files) · all 9 in this category: https://state-of-ai-in-design-systems.netlify.app/techniques/instruction-files.md
The single builder-facing rule file uses Cursor’s .mdc frontmatter (description + globs + alwaysApply:false) so it only fires when an agent touches the dual Base UI / Radix registry trees, then forbids one-sided edits and demands the agent report which trees it updated.
```markdown
---
description: Keep registry base and radix trees in sync when editing shared UI
globs: apps/v4/registry/bases/**/*
alwaysApply: false
---
# Registry bases: Base UI ↔ Radix parity
`apps/v4/registry/bases/base` and `apps/v4/registry/bases/radix` are **parallel registries**. Anything that exists in both trees for the same purpose (preview blocks, mirrored examples, shared card layouts, etc.) **must stay in sync**.
## When editing
- If you change a file under **`bases/base/...`**, apply the **same behavioral and visual change** to the matching path under **`bases/radix/...`** (and the reverse).
- Only diverge where APIs differ (e.g. import paths like `@/registry/bases/base/ui/*` vs `@/registry/bases/radix/ui/*`, or Base UI vs Radix component props).
- Do **not** update only one side unless the user explicitly asks for a single-base change.
After edits, briefly confirm both trees were updated (or state why one side is intentionally unchanged).
```
Source: https://raw.githubusercontent.com/shadcn-ui/ui/main/.cursor/rules/registry-bases-parity.mdc
### Registry-as-oracle AI codemod (golden-pair three-way merge)
Category: `design-code-mapping` (Design–code mapping) · all 3 in this category: https://state-of-ai-in-design-systems.netlify.app/techniques/design-code-mapping.md
AI-driven codemod. The Radix→Base UI migration skill refuses to let the model invent transforms: it makes the agent diff the user’s file against the canonical registry payload for their exact style URL, then replay their diff onto the base variant with `git merge-file`, and finishes with a mandatory grep sweep because ‘A clean merge is NOT proof of a clean file.’ It also enforces a baseline typecheck before any dependency change and one commit per component.
```markdown
You migrate shadcn wrappers, hand-rolled radix compositions, and their
consumers to `@base-ui/react`, keeping the project buildable at every step.
Be precise; never guess a mapping. When a prop or part is not in these
reference files, check `node_modules/@base-ui/react/**/*.d.ts` before
transforming, and record gaps in the report.
## Preflight (always)
1. `npx shadcn@latest info --json` ... Trust it over inference.
3. Require a clean git tree; work on a branch; one commit per component.
4. Baseline check BEFORE touching dependencies: run the project's
typecheck/build so pre-existing failures are never attributed to you.
## Strategy: golden pair first, transformation engine second
1. Classify each ui wrapper FIRST: diff the user's file against its stock
origin, using the components.json style VERBATIM in the URL
(`https://ui.shadcn.com/r/styles/