# design-to-shadcn

An agent skill that skins your shadcn primitives from a reference design.

## Setup

You need a shadcn project on Tailwind v4. A folder without `components.json` works too: the agent scaffolds one first, in the shadcn style closest to the reference.

Install the skill:

```bash
npx skills add AlexDemzz/skills --skill design-to-shadcn -g
```

It loads the `shadcn` skill before anything else, so install that one too if you haven’t:

```bash
npx skills add shadcn/ui --skill shadcn -g
```

Then make sure these tools are on your machine:

| Tool | What it’s for |
| --- | --- |
| `magick` | ImageMagick. Samples the pixel each color comes from. |
| `node` | Runs the two bundled scripts. |
| `agent-browser` | Drives a live site and reads its computed styles. Without it, headless Chrome takes the screenshots, with no style readout. |

## What it does

Give your agent a reference: a live website, a case study made of screenshots, or a folder of images. It skins your project’s shadcn primitives until they match: same colors, radii, type, spacing and states, in light and dark. Your app never restyles; it only lays out.

The work runs in four phases, in order, one commit each:

| Phase | What you get |
| --- | --- |
| Capture | A `DESIGN.md` written from sampled pixels, with a `shadcnMapping` block every later phase reads. |
| Tokens | That mapping written to `:root` and `.dark` in your CSS file, in OKLCH. No component file changes. |
| Primitives | Missing primitives installed from a registry, then skinned in their base classes and variants, shown on a `/dev/primitives` page. |
| Iso page | One screen rebuilt from the primitives alone, compared region by region with the reference. |

The iso page is the proof. If a stranger can tell it from the reference, a primitive still needs work.

## When to reach for it

You have a reference design but no tokens for it yet: a live site, a case study or a set of screenshots. Your project runs shadcn on Tailwind v4, or doesn’t exist yet.

Your agent never picks this skill on its own. You call it with the reference and, optionally, the screen to rebuild:

```bash
/design-to-shadcn https://example.com
/design-to-shadcn ./shots/home-light.png ./shots/home-dark.png settings
```

Without a screen, the agent picks the one that uses the most primitives: a settings page beats a hero. If your `DESIGN.md` already holds the reference, say so instead, and the capture phase shrinks to a check.

## Common questions

**Will my app fill up with overrides?**

No. Your app keeps layout classes only. A color, border, radius or font class there counts as an override, and each one goes on the record with its reason. A new variant has to earn its place: a role the reference reuses at least twice, or a change to at least two of color, radius, size, spacing, type, border and shadow. Anything less becomes a `className` or folds into the base classes.

**Is the brand color my primary?**

Not by default. `--primary` follows the reference’s primary button, read from its computed style. The hex everyone quotes for a brand is often a pressed state or a section band.

**What about the frame around case-study screenshots?**

Ignored. The window on a gray desk, the browser bar, the device bezel and the drop shadow are the portfolio’s staging. The agent samples inside the screen only.

**Do I get a say before the iso page?**

Yes. The agent lists every region of the screen with the primitive and variant that renders it, then waits for your go.

**Where does the progress go?**

Into a ledger, `docs/design/<slug>-skin.md`, one section per phase. On a repository with `docs/agents/issue-tracker.md`, the four phases become four tickets instead.

## It’s working if

Your iso page and the reference look the same in light and dark, and the ledger lists the primitives that had to change and the overrides your app needed.

## Where it fits

design-to-shadcn lives in [my skills repository on GitHub](https://github.com/AlexDemzz/skills/tree/master/design-to-shadcn), next to [shadcn-composition-patterns](https://alexandrejoly.me/skills/shadcn-composition-patterns.md), the compound-component laws for shadcn projects, and [grokbot-notify](https://alexandrejoly.me/skills/grokbot-notify.md), which messages you in your Grok Bot chat when your agent finishes, gets blocked or needs your decision.

[Back to Alexandre Joly](https://alexandrejoly.me/index.md)