Claude Code's frontend design skill: what it does and what it misses

A skill is a bundle of instructions that loads when it is relevant rather than on every request — the on-demand half of the agent-file stack. The frontend design skill loads when you ask for UI work and pushes the model toward stronger defaults.

In practice the differences that show up most consistently are these, and they are real rather than cosmetic:

• Spacing gains a rhythm. Values start coming from a scale rather than being picked per element, so vertical rhythm survives across a page.
• Hierarchy gets deliberate. Size, weight and colour are used together to separate levels, instead of size alone.
• Fewer default-shaped layouts. The reflexive three-equal-cards grid appears less often when the content does not actually suggest three peers.
• States are handled. Hover, focus, disabled and error turn up without being asked for, which is where most generated components are thin.

That is a meaningful lift, and it is the reason the skill is worth installing. It is also the entire scope of it.

A skill carries *how to decide*. It does not carry *what was decided*. That distinction sounds academic until you look at two sessions side by side.

The skill will reliably tell the model that a primary action needs sufficient contrast against its surface and should not compete with a secondary. It has no way to know that your primary is oklch(0.55 0.19 45) — because you never told it, and there is nowhere in a skill for that to live. So it picks something defensible. Next session, it picks something else defensible.

Do not take this on trust — the test is short and the result is unambiguous.

1. 1

   Ask for a pricing card in a fresh session

   With the skill active and no design system present. Keep the output.

2. 2

   Start a genuinely new session

   Not a new message — a new session, so nothing carries over.

   Copy

   claude

3. 3

   Ask for a settings panel for the same product

   Same wording about the product, no reference to the first component.

4. 4

   Diff the two

   Compare the primary colour, border radius, base font size, and the vertical gap between label and control.

5. 5

   Read the result honestly

   Both will look competent. In our runs, three or four of those four values disagree — and each is individually a reasonable choice.

Keep the skill. It is doing a job nothing else does. Add the layer it cannot contain: a token set plus a DESIGN.md in the repo, which the agent reads at the start of every session.

The division of labour is clean once both are in place. The file answers *which* blue, *which* radius, *which* type scale. The skill answers how to compose them into a screen that reads well. Neither substitutes for the other, and the common mistake is assuming the skill made the file unnecessary.

1. 1

   Install a kit into the repo

   This writes DESIGN.md plus the token files your agent will read.

   Copy

   npx --yes identityforge@latest install --client claude-code

2. 2

   Apply the kit you want

   Free kits need no account.

   Copy

   identityforge apply ambient-sage

3. 3

   Point AGENTS.md at it

   One line, so the design contract is discoverable rather than incidental.

   Copy

   Never hardcode theme colors. Use the semantic tokens in DESIGN.md.

4. 4

   Re-run the two-session test

   Same procedure as above. The values should now agree exactly, because they are read rather than re-decided.

This is the question people actually ask about design skills, and almost nothing written about them answers it. The honest answer: a skill respects your theme only to the extent your theme exists as values it can read. A skill is instructions about how to work. It is not a source of your values.

That distinction decides the outcome in an existing codebase:

There is a measurable version of this. We sampled 299 public DESIGN.md files and found that of the 72 describing a visual system, 86% use no semantic colour role names — they list hexes, or name colours by hue. A skill given --primary can apply your system to a component nobody described. A skill given a table of hexes can only copy, and copying is where it starts guessing.

1. 1

   Check whether your theme is readable at all

   Look for a DESIGN.md or a token file at the repo root. If the only source is Figma, the skill has nothing to work from.

2. 2

   Make the values semantic

   Roles rather than hues, so the skill can place them correctly in cases you never wrote down.

3. 3

   Point at them from AGENTS.md as a prohibition

   Copy

   Never hardcode theme colors, spacing or radii. Use the tokens in DESIGN.md.

4. 4

   Re-run the same build in a fresh session

   Same primary, same radius means it is reading. Near-misses mean it is remembering, and remembering decays.

Most of the writing about this is roundups, and roundups use the three words interchangeably. They are not the same thing, and the difference decides whether the thing you installed can even load.

The practical consequence is the load condition. A skill is selected by the model from its description, so it only participates when your request reads like design work. Ask for "a settings page" and it engages. Ask to "fix the padding on line 40" and it may not, because that reads like an edit rather than a design task — and you will get an ordinary edit with none of the craft you installed the skill for.

This is the question the comparison roundups skip entirely, and it is the one that matters once you have both. They do conflict, because they are written by different people for different purposes. Your file says the primary is oklch(0.55 0.19 45). The skill's judgment says a primary needs to clear a contrast threshold against the surface it sits on. On a light card those agree. On your dark elevated surface they may not.

Neither layer is wrong, and there is no built-in arbiter — the model resolves it, and by default it resolves toward whichever instruction is more specific and more recently read. That is why the resolution has to be written down rather than assumed:

1. Values are not negotiable; composition is. State it that way in AGENTS.md. The hex, the radius, the type scale come from the file. How they are arranged on a screen is the skill's call.
2. Give the file the escape hatch the skill needs. The conflict above only exists because the system has one primary. Ship a primary that is legible on your dark surfaces too, or a documented pair, and the disagreement disappears rather than being adjudicated per session.
3. Write prohibitions, not preferences. "Prefer semantic tokens" loses to a specific contrast argument. "Never hardcode theme colors" does not, because it leaves nothing to weigh.
4. Expect silence on conflict. The model will not tell you it overrode your token. The only reliable detection is grepping the diff for literal colour and spacing values.

# the only conflict detector that actually fires: literals in the diff
git diff | grep -nE '#[0-9a-fA-F]{3,8}|oklch\(|rgb\(|[0-9]+px'

Run that on every agent-authored diff. A clean result means the values were read. Anything it returns is a place where judgment quietly replaced a decision you had already made — which is the same drift as the two-session test, just arriving through a different door.