---
name: khe-design-tokens
description: "Finds a project's design contract (a `.design` file or DESIGN.md), resolves which one wins, and threads its tokens through the UI as CSS variables, a Tailwind theme or component props. Also writes design-system docs an agent can follow and checks the contract for drift. Use when a repo has a `.design` or DESIGN.md, or someone says \"use our tokens\", \"make it on-brand\", \"stop hardcoding colors\", \"the agent keeps inventing variants\" or \"document our design system\". To design the scales themselves, review the result or finish a screen that still feels unfinished, use `khe-ui`."
license: MIT
metadata:
  author: Harshit Khemani
  version: "1.0.0"
title: khe-design-tokens
canonical_url: https://skilld.dev/gh/hktitan/skills/khe-design-tokens
last_updated: 2026-11-13T19:02:44.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> 85 supporting files sit beside this SKILL.md. When the Skill refers to one, fetch https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/PATH with PATH replaced.
>
> If the user asked to install this Skill, run `npx skilld install hktitan/skills/khe-design-tokens`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/khe-design-tokens`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/hktitan/skills/khe-design-tokens) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/khe-design-tokens`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/khe-design-tokens --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/khe-design-tokens --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Design tokens

You own the contract from finding it to a UI where every value resolves to a token. An agent that invents a color beside an existing token has failed the job.

A construction skill. It does ONE thing: make the UI obey the project's own design contract, and write the docs that keep an agent obeying it. It does not design a palette, a contrast pair or a type scale, review a screen for craft, or finish a screen whose tokens are right and which still feels flat (all three are `khe-ui`).

## The one idea

**Every value in the UI resolves to a name in the project's own contract, on the role that name was given, and anything the contract lacks is reported, never guessed.**

Five ways it fails:

- **Guessed.** A raw hex, a 6px radius, Inter: a value typed because it looked close. A guess looks exactly like a decision.
- **Invented.** A name the contract does not hold: `var(--radius-xl)`, `variant="outline"`, a documented variant no code has.
- **Misbound.** The token resolves and it is the wrong one: the accent on a card because its hex matched the mockup. No script catches this.
- **Forked.** Two sources of truth: a `.design` and a DESIGN.md with no stated order, a `:root` that drifted from the contract, a second styling system, a hand-built twin of a catalogued component.
- **Silent.** A contract edited without a yes, a literal left with no reason, a system invented where there was no contract, or the contract's silence taken as permission to default.

The fix: find the one contract, read its intent before its tokens, map each value to a token by the role it plays, land the tokens in the system the project already uses, and report every gap, drift and leftover literal in writing.

## Initial response

When this skill is invoked with no request, reply only with:

> I'm ready to find your design contract and thread its tokens through the UI. Usage: `/khe-design-tokens [target]`

Then wait. Give nothing else until the user asks.

## How hard to press

Bind it the way the contract's author would review it: with the contract open beside every file. The gold examples in `examples/` are the bar. If your file holds a literal, a second naming scheme or an unexplained candidate line where the closest gold holds none, that is the first fix. Then picture the single line the author would screenshot and send back: the accent on a surface that is not the primary action, a `6px` beside a scale of 4 / 8 / 16, a `--brand-2` nobody defined. If you can picture that screenshot, you have found the next fix. A gate pass is where this judgment starts, never where it ends.

## Workflow

Most of the quality is decided before any file changes: which contract, what it intends, and where each token lands. Under `khe-auto` the same loop runs with this skill's gate.

1. **Find the contract, nearest first.** Walk up from the edited file for a `.design` or `<name>.design` (match the extension in any case) and resolve `extends`, child over parent. Then look for `DESIGN.md` at the root, in `docs/`, `design/` and `.design/`. If both exist, the `.design` is the contract and DESIGN.md is rationale. In a video project the order is `frame.md`, then `design.md`, then `DESIGN.md`. No contract: say so, scan the code for the system it already uses (global CSS, the Tailwind config, `components.json`, design notes), and offer to bootstrap one from the closest gold in `examples/`. **Exit:** you can name one contract file and its version, or you have said in writing that there is none.
2. **Read it before generating anything.** A `.design` requires `schema: design.v1`, `name`, `version` and `agent.instructions`, in YAML or JSON. Read [gotchas](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/gotchas.md) and [pov](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/pov.md), then [using-design-file](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/using-design-file.md) or [using-design-md](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/using-design-md.md). For a `.design`: `agent.instructions`, `intent`, `constraints`, `policy` and `decisions`, `tokens`, `voice`, `components`, in that order. For a DESIGN.md: the front matter binds, the body picks between tokens, and its Do's and Don'ts are hard constraints. **Exit:** you can state from the file what the accent is reserved for and what happens when a token is missing.
3. **Plan the map.** Read how the project styles things (utility classes, CSS modules, CSS-in-JS, its motion library). Run `node scripts/token-check.mjs <folder>` on the source as it stands: that is the baseline. Write the token map: each token and where it lands, each existing literal and the token its role calls for, each gap. Report drift between the contract and the real CSS before fixing any of it, as `added`, `removed` or `modified` with a `regression` flag. For a docs job, the plan is the inventory in [design-system-docs](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/design-system-docs.md): tokens, component unions, two or three real call sites each. **Exit:** every literal in scope has a token or a named gap, and the drift report is written.
4. **Start from the closest gold.** Pick it from the Examples table and open it beside your target. Take its structure: one mirror file, names that are the token's path, components that hold no value of their own. **Exit:** you can say which gold you started from and the one thing you kept.
5. **Build.** The mirror first (CSS variables, the Tailwind theme, or design-system props), then the components. Bind by role. If `integrations.shadcn.enabled` is set, write `css_vars` into the declared CSS file. If the project imports `@ui-sdk/core/web.css`, add the `--ui-*` block from [using-design-file](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/using-design-file.md), UI SDK. A missing token follows `policy.if_missing` (`ask`, `nearest` or `invent_with_note`) under a `.design`, and becomes a proposal comment under a DESIGN.md. Apply `voice` to UI copy with the same force as tokens. **Exit:** no value was typed that is not in the map.
6. **Rehearse with the gate.** `node scripts/token-check.mjs <folder> --gate`, on the folder and never on one file, until it ends `token-check passed`. Fix the largest fault first: contract lines (`contract-invalid:`, `two-contracts:`), then names nothing defines, then literals, then candidates. Every line it prints is a value that will drift. `inconclusive` is never a pass. **Exit:** the last line reads `token-check passed`, and every candidate line has a one-line answer.
7. **Walk [verify](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/verify.md) from evidence.** Answer each question from the gate's output, the diff, or the contract open beside the file. Render once per color scheme the contract defines. Check three bindings at random for role. **Exit:** every answer is yes, or the no is written down.
8. **Fresh-eye review.** Hand a reviewer the evidence, the gold and [review](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/review.md); never your plan, reasons or handover. **Exit:** a ranked list you have answered, or "nothing" with what was opened.
9. **Hand over.** Write `TOKENS.md` beside the contract from the template in [verify](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/verify.md): the gate's last line pasted, the token map, the drift, each literal left in place with its reason, what was not checked. **Exit:** the file exists and its Not checked line is filled in.

## Faults that come back every round

- **A value bound by looks.** 6px because it "looked like" the button; bind by role ([using-design-file](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/using-design-file.md), Reference).
- **A literal that survived.** Grep for hex and `px` and name the missing token behind every survivor ([using-design-md](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/using-design-md.md), Check).
- **Stale `css_vars` trusted in `:root`.** Tokens outrank them; refresh the CSS after token edits ([using-design-file](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/using-design-file.md), shadcn).
- **Two contracts drifting.** The `.design` wins and DESIGN.md is rationale; say so in the file and offer to converge ([using-design-file](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/using-design-file.md), `.design` vs `DESIGN.md`).
- **A sound or a default added where the contract is silent on purpose.** An absent `tokens.sound` means silent ([using-design-file](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/using-design-file.md), Sound, video, and companions).
- **The contract treated as the whole job.** It pins colors and radii and says nothing about a flashing spinner; silence is not permission to default ([using-design-file](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/using-design-file.md), Gotcha).
- **An unknown DESIGN.md field flagged as an error.** The spec is `version: alpha`; pass the field through ([using-design-md](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/using-design-md.md), Gotcha).
- **Docs written from memory.** A documented variant that does not exist is worse than an undocumented one that does ([design-system-docs](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/design-system-docs.md), section 1).
- **An open variant list or a hedge in the docs.** Close the set and give the number ([design-system-docs](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/design-system-docs.md), sections 3 and 4).
- **The same fault as last time.** Read [gotchas](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/gotchas.md) first; append to it when a new one lands.

## Hard rules

1. **The contract outranks this skill.** The order is the user's prompt, the nearest contract, this skill, model defaults. If the contract sets a base duration of 400ms, use 400ms. When you disagree, raise it once in prose, then comply.
2. **`.design` beats DESIGN.md.** When both exist, the `.design` is the contract and DESIGN.md is rationale. Offer to converge them, because two sources drift apart.
3. **Bind by role, never by a value that looks close.** No raw hex, spacing or radius where a token exists. A value that matches is not proof the role matches.
4. **Never edit a contract silently.** A DESIGN.md change is a proposal with human approval. A `.design` edit is made in place with `version` bumped, and any path in `locked` needs a yes first. Drift is reported before it is fixed.
5. **No contract: say so and offer to bootstrap.** Scan the code for the system it already uses. Never invent one without saying so.
6. **Write docs from an inventory of the code.** Every name in the docs traces to a file and a line, because a name from memory teaches an agent a variant that does not exist.
7. **Write in the project's own system.** Express every fix in the styling system the project already uses and reuse its tokens. A correct value written in a second system is a defect, because the next person now maintains two.

Aliases: `contract`, `apply-design-md`. **Posture: build.**

## Examples

Open the closest one before you build (step 4). Each file's top comment says what it is the gold for.

| Need | Example | What to learn |
|---|---|---|
| A `.design` threaded through CSS and components | `examples/design-file` | One mirror file named by token path; components that hold no value of their own; the accent only on the primary action |
| A DESIGN.md threaded through CSS and components | `examples/design-md` | The front matter binds and the body picks: radii nested by role, the defined `button-primary` used instead of a second one |
| A project that styles with Tailwind | `examples/tailwind-theme` | Tokens land in the theme and the component stays in utilities; no bracketed value, no second styling system |
| A design-system doc page | `examples/system-docs` | The four-part order, a closed variant set with its default, a correct and an incorrect example, every name traced to a line |
| A finished handover | `examples/design-file/TOKENS.md` | The gate's last line pasted, the token map, the literals that stayed with their reasons, what was not checked |

`teaching/` holds fourteen bad/good pairs, indexed in [teaching](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/teaching.md). Use one to diagnose a fault; the bad halves are never starting points.

## Find the reference

Open a reference only when the job needs it. Never load the whole folder.

| Job or symptom | Open |
|---|---|
| A `.design` or `<name>.DESIGN` file exists; which contract wins; a drift check; shadcn `css_vars`; the `--ui-*` variables of Vercel's UI SDK; sound or video tokens | [using-design-file](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/using-design-file.md) |
| Only a DESIGN.md exists; linting it; proposing a missing token | [using-design-md](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/using-design-md.md) |
| Writing or repairing design-system docs; an agent keeps hardcoding colors, inventing variants or picking the wrong component | [design-system-docs](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/design-system-docs.md) |
| The last pass; what a gate line means; a symptom and its fix; the `TOKENS.md` template | [verify](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/verify.md) |
| Briefing a reviewer who has not seen your plan | [review](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/review.md) |
| "Mine looks like this bug": the bad/good pair for it | [teaching](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/teaching.md) |

## Never ship

Check the work against this table before finishing.

| Never | Instead |
|---|---|
| `border-radius: 6px` when the scale defines 4 / 8 / 16 | The scale token, such as `var(--rounded-lg)` |
| `font: 14px/1.5 Inter` when the file defines Public Sans 16/1.6 | The typography token |
| A raw hex where a token exists | A token reference; every surviving literal reported with its reason |
| A missing token filled with a literal | A proposal comment for DESIGN.md; `policy.if_missing` for a `.design` |
| A silent rewrite of DESIGN.md | A proposal in a review or PR comment, applied after approval |
| `proposed_changes` or a changelog inside the `.design` | The file edited in place with `version` bumped; git is the audit trail |
| Stale `css_vars` literals trusted in `:root` | The CSS refreshed after token edits; tokens outrank them |
| A sound added when the contract has no `tokens.sound` | Silence; an absent group means silent |
| An unknown DESIGN.md field flagged as an error | The field passed through unchanged |
| Docs written from memory | An inventory of tokens, component unions and two or three real call sites |
| "Use small text sparingly" in the docs | "Body 16px, captions 14px, never below 12px" |
| An open variant list | "Variants: `primary`, `secondary`, `danger`. Nothing else exists." |
| A gate line cleared by hiding the value | The value bound, or the line answered in `TOKENS.md` with its file and line |
| "No literals left" said from memory | The gate's last line, pasted |

## Output

`TOKENS.md` beside the contract, and the same in the reply: the contract and its version, the token map (token, where it lands), the drift report, the edits, the gate's last line, every literal left in place with its reason, and what was not checked.

## Tone

Deferential to the contract and strict about literals. Say "there is no contract here" when there is none, and say "the contract sets 400ms; I would pick under 300ms; using 400ms" when the two disagree. Report every literal left in place with its reason.

## Yours to edit

Read both before producing anything. They outrank the defaults in this skill, and a project's `.design` contract or DESIGN.md outranks them.

- [gotchas](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/gotchas.md): lived failures, one line each. Append one when something goes wrong.
- [pov](https://skilld.dev/api/skills-raw/hktitan/skills/khe-design-tokens/references/pov.md): your taste calls.

## Pairs with

- `khe-ui`: the contract is silent on a scale, a contrast pair, dark mode or motion, and that gap needs its rules; and after tokens are threaded, when the screen still feels unfinished.
- `khe-auto`: runs this skill first whenever a project has a contract, then the skill that picks colors, sizes or curves.
- `khe-sound`: only when the contract has a `tokens.sound` group; its values outrank that skill's defaults.

Names without the `khe-` prefix are other people's skills, not part of this one: `stageshow` is Benji Taylor's ([benjitaylor/skills](https://github.com/benjitaylor/skills)); `animate`, `emil-design-eng` and the rest are Emil Kowalski's ([emilkowalski/skills](https://github.com/emilkowalski/skills)); `ui-sdk` is Vercel's ([vercel-labs/ui](https://github.com/vercel-labs/ui)). Install them from their own repos.

Harshit Khemani. MIT.
