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:
npx skills add AlexDemzz/skills --skill design-to-shadcn -gIt loads the shadcn skill before anything else, so install that one too if you haven’t:
npx skills add shadcn/ui --skill shadcn -gThen 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 |
| Tokens | That mapping written to |
| Primitives | Missing primitives installed from a registry, then skinned in their base classes and variants, shown on a |
| 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:
/design-to-shadcn https://example.com/design-to-shadcn ./shots/home-light.png ./shots/home-dark.png settingsWithout 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
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.
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.
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.
Yes. The agent lists every region of the screen with the primitive and variant that renders it, then waits for your 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 (opens in a new tab), next to shadcn-composition-patterns, the compound-component laws for shadcn projects, and grokbot-notify, which messages you in your Grok Bot chat when your agent finishes, gets blocked or needs your decision.