A Claude Code skill for your design system: keep new UI matching your app

The problem: design skills bring their own look

Most design skills for Claude Code are written for a blank project. They tell the model which fonts, colours and spacing to use, and the output looks polished. In a new project that is great.

In an app you already have, the same instructions fight your design system. The new page uses a different font, hard-coded hex colours instead of your CSS variables, and a hand-written button next to the Button component you already built. It looks fine on its own and wrong next to every other page.

What you want for an existing app is the opposite: a skill that brings no look at all and copies yours.

How Claude Code skills work (the short version)

A skill is a folder with a SKILL.md file, placed in .claude/skills/<name>/ in your project (or in your user folder for all projects). The file starts with a name and a description. Claude Code reads the descriptions at the start of a session and loads the full instructions when a task matches, for example when you ask it to build a page.

That means a design-system skill can force a routine before any UI code is written: look first, then build. The instructions are plain Markdown, so you can write one yourself.

What a design-system skill should do

1. Survey the tokens. Read globals.css, the Tailwind config or the theme file, and list the colour, radius and font variables that already exist.
2. Inventory the components. Find the Button, Card, Input, Dialog and table components and note their props. If a component exists, new code must use it.
3. Read two sibling pages. Pick the pages closest to the one being built (another settings page, another list page) and note the layout, header, spacing and heading sizes.
4. Write a short style fingerprint before coding: tokens to use, components to reuse, the page skeleton to copy. This keeps the model honest for the rest of the task.
5. Build by reuse. New code uses only those tokens and components. No new fonts, no hex colours, no new button styles.
6. Self-check. Grep the new files for hex colours, font imports and raw button elements, and fix anything found before saying the task is done.

Step 6 is the one most people skip, and it is where most of the drift gets caught. A model will happily say it used your tokens while one hard-coded colour slipped in.

A SKILL.md skeleton you can start from

Save this as .claude/skills/match-project-style/SKILL.md and adjust the paths to your project:

---
name: match-project-style
description: Use before building or changing any UI page or component in this project. Reads the existing design tokens, components and sibling pages so new UI matches the app.
---

# Match the project's style

Before writing UI code:
1. Read the theme: src/app/globals.css and tailwind config. List colour, radius and font variables.
2. List components in src/components/ui/ and their props.
3. Read the two pages most similar to the one you are building.
4. Write a 5-line style fingerprint: tokens, components, page skeleton.

While building:
- Use only the tokens and components above. No hex colours, no new fonts.
- Copy the header, container width and heading sizes from the sibling pages.

Before you finish:
- grep the changed files for "#[0-9a-fA-F]{3,6}", "font-family" and "<button".
- Replace anything found with the project's token or component.

This alone fixes a lot. It works best when your project has a real Button component and colour variables to point at. If it does not, the skill can only copy what the sibling pages do.

A small test: generic design skill vs. a style-matching skill

We ran one test with the same project, the same prompt, and one new page added to a live Next.js app. We did it twice: once on a project with design docs, once on a project without. Here is what the new page did (with docs / without docs):

One run per project. Small sample, real numbers. It shows the direction clearly, but it is not a benchmark.

When a generic design skill is the better pick

If you are starting a new project and have no look yet, a skill with a strong built-in style is useful: it gives you a decent design system on day one. Once the app exists, switch to a skill that reads and copies what is there.

If you would rather not maintain your own version, Match Style packages the routine above with recipes for the pages people add most (forms, settings, data tables, pricing, empty states) and the self-check step. It is in early access, and it works with Claude Code and any agent that reads SKILL.md.

Questions