# Design system skills for coding agents

A set of Agent Skills that encode a design system's rules so that AI-generated UI
starts *inside* the system rather than beside it.

Design systems have always had a distribution problem: the rules live in Figma and in
documentation, and the code is written somewhere else by someone who did not read
either. That gap used to be closed by review. When a team ships daily with AI
assistance, review is too slow — the rules have to be where the agent reads them,
before the code exists.

These four skills are that. They are the same decisions I would write into
documentation, written instead in a form a coding agent loads on demand.

## What's here

| Skill | What it encodes |
|---|---|
| **`design-tokens`** | Token tiers and naming grammar, DTCG authoring, a validator that fails a PR on unresolved aliases, raw values in semantic tokens and sub-AA contrast pairs, and a Style Dictionary config compiling to CSS, Tailwind, React Native and docs |
| **`design-system-usage`** | Which component to reach for, forbidden variant combinations, layout and spacing rhythm, and what to do when nothing in the library fits |
| **`ai-surface-patterns`** | Streaming, agent steps and tool calls, citations, latency budgets, empty states, human approval gates, and the error-versus-refusal distinction most teams get wrong |
| **`rtl-bilingual`** | Logical properties, direction handling, icon mirroring, Arabic type metrics, bidi-safe numerals, and a linter that fails the build on physical direction |

Plus a `CLAUDE.md` showing the split between always-loaded project context and
on-demand skills.

## Why skills rather than a longer CLAUDE.md

`CLAUDE.md` is loaded on every session. A skill is loaded when it becomes relevant.
That difference is what lets a system carry this much specificity without paying for
all of it on every turn — a large skill library costs almost nothing idle, while a
5,000-line context file costs on every request.

It also means the rules are *addressable*. "Read the RTL skill" is a review comment
that resolves to something specific.

## What's in the folder

```
design-system-skills/
├── README.md                          this file
├── CLAUDE.md                          project context — copy to your repo root
└── skills/
    ├── design-tokens/
    │   ├── SKILL.md
    │   ├── reference/token-grammar.md
    │   ├── scripts/validate-tokens.mjs
    │   ├── config/style-dictionary.config.js
    │   └── tokens.example.tokens.json
    ├── design-system-usage/
    │   ├── SKILL.md
    │   └── reference/component-inventory.json
    ├── ai-surface-patterns/
    │   ├── SKILL.md
    │   └── reference/state-matrix.md
    └── rtl-bilingual/
        ├── SKILL.md
        ├── reference/icon-mirroring.md
        └── scripts/lint-physical-properties.mjs
```

## Install

Claude Code discovers skills automatically from `.claude/skills/` (project) or
`~/.claude/skills/` (personal) — no registration step. `.claude` is a hidden folder,
which is why the skills ship in a visible `skills/` directory here; copy them into
place:

```bash
mkdir -p your-repo/.claude/skills
cp -r skills/* your-repo/.claude/skills/
cp CLAUDE.md your-repo/
```

The format is the Agent Skills open standard, so the same files work across tools
that implement it.

## Run the checks

Both scripts are dependency-free Node (ESM, Node 18+) and exit non-zero on failure,
so they can gate a pull request.

```bash
node skills/design-tokens/scripts/validate-tokens.mjs tokens/
node skills/rtl-bilingual/scripts/lint-physical-properties.mjs src/
```

The Style Dictionary config needs `style-dictionary` v4+ installed in the consuming
project.

## Adapting these

The rules are opinionated on purpose — a skill that hedges gives an agent nothing to
act on. The parts to change for your own system are the component inventory
(`skills/design-system-usage/reference/component-inventory.json`), the token grammar
and inventory (`skills/design-tokens/reference/token-grammar.md`), and the
primitive/component name sets at the top of `validate-tokens.mjs`.

The parts I would keep as written are the error-versus-refusal distinction, the
approval gate rules, and the icon mirroring test. Those are not house style; they are
the ones that are actually wrong when they are wrong.

---

Waqar H. Syed — [waqarhsyed.com](https://waqarhsyed.com)