Skip to main content
skill CX Codex

agentic-design-systems — Claude Code skill: features and install

The agentic-design-systems Claude Code skill guides the design and review of component libraries built for AI agents. It activates for AI-readable design systems, component metadata work, and library audits.

MIT ★ 107 updated 2026-11-08

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add thedesignproject/agent-skills --skill agentic-design-systems -a claude-code
Open on GitHub

What agentic-design-systems does

The skill defines metadata for component props, variant choices, relationships, design tokens, and agent guidance. It distinguishes four tasks: starting a library, adapting an existing one, auditing its metadata, or changing a single component.

A shared contract in meta.types.ts defines the fields, while each component gets its own .meta.ts file. The validator catches missing keys. Metadata also captures variant-selection guidance and structured anti-patterns with a reason and an alternative. If a request is ambiguous, the skill calls for one focused clarification.

What it helps with

  • record component props and variants in machine-readable metadata
  • connect components to their contexts, tokens, and accessibility roles
  • adapt an existing library for AI-agent use
  • spot missing metadata fields and invalid variant combinations
  • write metadata for an individual component

Example prompts for the agent

  • Design a metadata schema for a component library used by an AI agent.
  • Audit these component records for missing relationships and invalid variants.
  • Add a Button component with its metadata and agent guidance.

How to install agentic-design-systems

1Skills CLI (Vercel)

npx skills add thedesignproject/agent-skills --skill agentic-design-systems -a claude-code

2Manually: put the files in place

~/.claude/skills/agentic-design-systems/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/agentic-design-systems/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about agentic-design-systems

How do I install agentic-design-systems in Claude Code?

Run npx skills add thedesignproject/agent-skills --skill agentic-design-systems -a claude-code. The skill file is at ~/.claude/skills/agentic-design-systems/SKILL.md.

What does agentic-design-systems do?

It guides the creation, extension, and review of component libraries with metadata for AI agents. The schema covers props, variants, relationships, tokens, and usage guidance.

Is agentic-design-systems for human-facing design systems?

Its focus is libraries whose primary consumer is an AI agent. For design-system work aimed only at people, its description points to figma:figma-generate-library.

Source text

SKILL.md · MIT
---
name: agentic-design-systems
description: Use when designing, scaffolding, extending, or auditing a component library whose primary consumer is an AI agent — i.e. the design system needs machine-readable metadata (props, variants, relationships, tokens, anti-patterns) rather than only prose docs. Triggers include "agentic design system", "design system for AI/Claude", "make my design system AI-readable", "component metadata schema", "scaffold a UI library for an agent", or planning a new component library where the main consumer is an LLM. Don't use this skill for purely human-facing design system work — use figma:figma-generate-library for that.
---

# Agentic Design Systems

When this skill triggers, you're helping the user build, extend, or audit a component library whose primary consumer is an AI agent. The bar: given a prose request like *"Build a confirmation modal with a destructive action,"* an agent picks the right component, the right variant, and the right tokens — without inventing patterns.

This skill gives you the schema, the workflow, and the principles. Adapt it to where the user is.

---

## Diagnose first

Before producing anything, figure out which mode applies:

- **Greenfield** — user is starting a new system intended for agent consumption. Walk through the [build workflow](#build-workflow). Start with the schema and one worked component (Button is canonical); don't try to scaffold everything at once.
- **Retrofitting** — user has a component library and wants to make it agent-readable. Skip workspace setup. Add `meta.types.ts`, then write a `.meta.ts` per component, then build the index and validator. Anti-patterns first (see [Step 5](#step-5--anti-patterns-first)).
- **Auditing** — user has metadata already. Score each component against the [four pillars](#the-four-pillars) and the [validator checks](#step-9--metadata-validator). Flag missing relationships, prose anti-patterns, raw global tokens, and ungrounded variant axes.
- **Single component** — user wants to add or fix one component. Generate the full file set in [Step 3](#step-3--build-one-component-end-to-end). Metadata ships with the component or it doesn't ship.

If the prompt is ambiguous, ask one targeted question — don't guess.

---

## The four pillars

Treat every component as the intersection of four things. Most metadata schemas only model the first; that's why agents misuse the components.

| Pillar | What it answers | Failure mode if missing |
|---|---|---|
| **Props** | What you set | (always present) |
| **Variants** | Which combination to pick | Agent picks invalid combinations |
| **Relationships** | Where the component fits structurally and a11y-wise | Agent generates code that compiles but is structurally wrong |
| **Tokens** (component-scoped) | Which design values bind to this component | Agent invents colors and spacing |

Plus `aiHints` — the meta layer that tells an agent *when* to use the component, *which* variant fits *which* situation, and *what never to do*.

### Four design decisions baked into the schema

- **States are implicit in tokens, not a separate pillar.** Encode `button-primary-bg-hover`, `button-primary-bg-disabled`, etc. Theming becomes a token swap; one source of truth.
- **Variants are a matrix, not a flat enum.** Declare axes (`appearance × size × density`) and let the agent pick a cell. Use `invalidCombinations` for cells that shouldn't ship.
- **Accessibility folds into Relationships.** ARIA `role`, `keyboardSupport`, and `screenReader` describe how the component fits into the document and interaction model — that's relational. No separate a11y pillar.
- **Anti-patterns are first-class and structured.** Never prose. Always `{scenario, reason, alternative}` triples — they force precision.

---

## The schema (canonical contract)

Write this once at `meta.types.ts`. Every component's `.meta.ts` imports it and is type-checked. The schema *is* the contract.

```ts
interface ComponentMeta {
  component: {
    name: string;
    category: "atoms" | "molecules" | "organisms";
    type: "interactive" | "display" | "container" | "input" | "navigation";
    description: string;
    path: string;
    figma?: { nodeId: string | null };
  };

  props: Record<string, PropDef>;

  variants: {
    axes: Record<string, readonly string[]>;
    purpose: Record<`${string}.${string}`, string>;
    invalidCombinations?: { axes: Record<string, string>; reason: string }[];
  };

  relationships: {
    requires?: string[];           // contexts/providers above
    mustBeChildOf?: string[];
    mustBeParentOf?: string[];
    optionalSibling?: string[];
    commonPartners?: string[];
    triggers?: string[];           // events emitted
    blocksWhen?: { when: string; effect: string }[];
    exposesState?: string[];       // state descendants can read
    role: string;                  // a11y
    keyboardSupport: string;
    screenReader: string;
  };

  tokens: {
    color?: Record<string, string>;
    spacing?: Record<string, string>;
    typography?: Record<string, string>;
    border?: Record<string, string>;
    motion?: Record<string, string>;
    elevation?: Record<string, string>;
  };

  aiHints: {
    priority: "high" | "medium" | "low";
    keywords: string[];
    selectionCriteria: Record<string, string>;
    usage: {
      useCases: string[];
      commonPatterns: { name: string; composition: string }[];
      antiPatterns: { scenario: string; reason: string; alternative: string }[];
    };
  };
}
```

When generating a component's `.meta.ts`, fill every field that applies. Empty arrays are fine; missing keys aren't — that's what the validator catches.

---

## Build workflow

### Step 1 — Workspace shape
Recommend a sibling package inside the consuming app's monorepo (`packages/ui-next/`). Switchover later is just an import rewrite. A separate repo only makes sense when independent versioning is required.

### Step 2 — Schema as TypeScript contract
Write `meta.types.ts` before any components. Everything else flows from it.

### Step 3 — Build one component end-to-end
Pick something small and high-traffic. Button is canonical. Ship the full set together:

```
Button/
  Button.tsx              ← implementation
  Button.meta.ts          ← four pillars + aiHints
  Button.tokens.css       ← component-scoped tokens
  Button.stories.tsx      ← visual test surface
  Button.test.tsx         ← behavior tests
  index.ts                ← single canonical export
```

Wire up Storybook early (`.storybook/main.ts` for story discovery, `.storybook/preview.ts` for theme imports). One story per variant matrix cell makes design-space regressions obvious at a glance.

Metadata ships with the component or the component doesn't ship. Don't defer it.

### Step 4 — Tokens at two levels
- `tokens/core.css` — raw brand palette and scales (`--color-brand-600`, `--space-4`).
- `tokens/themes/*.css` — map component-scoped tokens (`--button-primary-bg`) to core values.

Component CSS only ever references component-scoped tokens. Theme swaps stay mechanical.

### Step 5 — Anti-patterns first
For each component, write the `antiPatterns` array *before* writing the implementation. The structured-triple format (`scenario`, `reason`, `alternative`) forces precision — you can't write "don't overuse primary buttons"; you have to write *which scenario*, *why it's wrong*, *what to do instead*. The anti-patterns end up driving the API.

### Step 6 — Variant axes as a coordinate system
Variants aren't a flat list of strings. Declare axes (`appearance × size × density`) so the agent picks along independent dimensions. Use `invalidCombinations` to rule out cells that shouldn't ship (e.g. `appearance: "ghost" × size: "xs"` — too small to be tappable).

### Step 7 — Relationships as machine-checkable rules
- `requires` — providers that must exist above
- `mustBeChildOf` / `mustBeParentOf` — structural constraints
- `triggers` — events emitted
- `blocksWhen` — prop-state-dependent behavior
- `exposesState` — what descendants can read

This is the pillar that prevents agents from generating code that compiles but is structurally wrong.

### Step 8 — Hierarchical metadata index
Generate `metadata/index.json` — a flat list of `{name, category, path, keywords, priority}`. Agents scan this first to shortlist candidates, then read the full `.meta.ts` only for relevant components. Cheap discovery, expensive depth.

Build with a script (`scripts/build-index.ts`) that walks every `*.meta.ts`, dynamically imports each one, and writes the JSON. Run it on every metadata change so the index can never lie about what exists.

### Step 9 — Metadata validator
A short script (`scripts/validate-metadata.ts`) walks every `*.meta.ts` (via fast-glob), dynamically imports each one, shape-checks the export, and asserts:

- Every variant axis cell appears in `aiHints.selectionCriteria` or `variants.purpose`
- Every `tokens.*` key is component-scoped (kebab-case of the component name)
- `antiPatterns` is non-empty for `priority: "high"` components
- `relationships.role` / `keyboardSupport` / `screenReader` are non-empty (enforces the "a11y folds into Relationships" decision)
- `invalidCombinations` references only declared axis values

Run in CI. If the metadata is wrong, the build fails. The schema is enforced, not aspirational.

### Step 10 — Switchover (per-component, not big-bang)
Don't switch over at the end — switch per-component as parity is reached.

- **API parity tracker** — markdown checklist of old library exports → new equivalents.
- **Token bridge** — map old tokens to new component-scoped ones.
- **Codemod** — rewrite imports page-by-page.

---

## Principles

- **Lean over generated.** Hand-write metadata for the first ~10 components. Automate only after the patterns are obvious.
- **Direct imports, no barrels.** One canonical path per component. Two ways in means the agent picks wrong.
- **Co-locate everything.** Component, metadata, tokens, stories, tests — one folder.
- **Anti-patterns drive design.** Write them first. They reveal the contract.
- **Component-scoped tokens.** Never reference raw global tokens from a component's CSS.
- **States live in tokens.** No `states` block. No `behavior.states` array.
- **A11y is relational.** It belongs in Relationships, not its own pillar.
- **The schema is the contract.** Validator runs in CI; failing metadata fails the build.

---

## What success looks like

The user hands an agent a Figma screenshot or a prose request — *"Build a confirmation modal with a destructive action"* — and the agent:

1. Scans `metadata/index.json` and shortlists `Modal`, `Button`, `Heading`.
2. Reads each shortlisted component's `.meta.ts`.
3. Sees `Button.relationships.mustBeChildOf` includes `ModalFooter`; picks `appearance: "danger"` from `aiHints.selectionCriteria`.
4. Avoids two `appearance: "primary"` siblings because `antiPatterns` flags it.
5. References component-scoped tokens — never invents a color.
6. Generates code that follows the contract on the first try.

That's the bar. If the metadata can't get an agent to that outcome, fix the metadata.

© thedesignproject · MIT · thedesignproject/agent-skills

Similar skills

All skills for Frontend and UI →

From the same set13

The whole set →
performance-review-self-assessment The performance-review-self-assessment Claude Code skill guides employees through a quarterly self-assessment. It covers accomplishments, challenges, leadership principles, and progress on development goals. CX Codex +1 ★ 107repo stars performance-review-manager The performance-review-manager Claude Code skill guides a manager through a quarterly employee review. It gathers peer feedback and helps assess performance, potential, and development. CX Codex +1 ★ 107repo stars performance-review-360-peer The performance-review-360-peer Claude Code skill guides a colleague through peer feedback using Nonviolent Communication. It asks about strengths, growth areas, leadership principles, and future collaboration. CX Codex +1 ★ 107repo stars create-skill This Claude Code skill helps create Cursor skills and explains the structure of SKILL.md. It applies to requests for a new skill or questions about its instruction file. CX Codex +1 ★ 107repo stars create-prd create-prd is a Claude Code skill that turns a feature request or transcript into a PRD. It examines the codebase and can create a Linear project with issues. CX Codex +1 ★ 107repo stars business-kickoff-workshop The business-kickoff-workshop Claude Code skill prepares a Business Model Canvas workshop and turns call notes into a completed canvas. It activates for kickoff planning, customer discovery questions, or post-call canvas work. CX Codex +1 ★ 107repo stars build-my-designer-brain The build-my-designer-brain Claude Code skill builds a designer’s personal collection of methods, preferences, and lessons. It runs to create or revise that collection, or to apply it while working on a feature. CX Codex +1 ★ 107repo stars ai-component-metadata The ai-component-metadata Claude Code skill creates structured metadata for design system components used in AI-generated interfaces. It runs during component analysis and records how each component should be composed and used. CX Codex +1 ★ 107repo stars

Project sponsors

Companies that keep this analytics open