Design System Skill
A design system you choose from three options, built from your own codebase.
A Claude Code skill. It reads your project, proposes three
design-system directions on one switchable page, and turns your choice into the approved reference
that all later design work follows.
The live demo is the neutral template the skill starts from. In your project, every colour,
label and screen comes from your own code.
One screen, three directions
The same dashboard in each option. The switcher in the header redraws the whole page.
| A · Calm | B · Institutional | C · Brand-forward |
|---|
| | |
| Evolution of your current UI. Lowest migration cost. | Hairlines, tight radii, standard-aligned. | Brand colour in the shell and primary action. |
How it works
"make a design system for this project"
│
▼
┌──────────────────────────────┐ you choose ┌───────────────────────────┐
│ index.html: 3 options │ ───────────────────▶ │ final.html: approved │
│ A · B · C, one click to swap │ A / B / C / mix │ tokens.css: the variables │
│ comparison · sources · screen │ │ DESIGN.md: rules to follow│
└──────────────────────────────┘ └───────────────────────────┘
Contents: Why · What you get · Install · Usage ·
What it reads · Quality bar ·
Customising · Contributing · بالعربي
Why
Asking for "a design system" usually gets you one opinionated mock-up, and you can only say yes or
no to it. This skill gives you a decision instead:
- Three real alternatives built on the same foundations. You compare the choices that matter
(shape, depth, where the brand colour goes), not three random styles.
- Grounded in your code. Colours, radii, font sizes and shadows are counted from your
stylesheets. The options start from what you have, and every number cites its source
(
file:line, brand guide or standard).
- Shown on your own screen. The page renders your most-used screen with your real labels in
every option, alongside a full component sheet.
- It ends with a reference, not a mood board. After you decide, you get a single approved page,
a
tokens.css and a DESIGN.md that people and AI agents can follow from then on.
What you get
Phase 1: index.html, the options page
One self-contained HTML file (opens from disk, no server, no build). A switcher in the header
restyles the whole page between options A, B and C:
| Section | Contents |
|---|
| Three options | One card per direction (sketch, description, key facts) and a row-by-row comparison table |
| Sources | Every value we used, where it came from, and whether it was measured or is to confirm |
| Colour | Brand and secondary ramps, status colours (wash · ink · dot, contrast computed), semantic roles of the shown option |
| Type | The full scale with live values (it changes on mobile), weights, a real-length paragraph |
| Space & grid | 4px spacing scale, breakpoints with "you are here", S/M/L component heights |
| Shape, depth, motion | Radii, shadow levels, easing |
| Icons & focus | Icon set, a focus ring that passes contrast |
| Components | Buttons, fields, selects, checkboxes/radios/switches, search, tabs, tags/status, avatar, breadcrumb/pagination, cards, table, alerts/modal/menu, nav bar, each in all its states |
| Sample screen | Your key screen, on desktop and in a 390px phone frame |
| Open decisions | The questions only you can answer (font licence, mandated standard, base size…) |
The three directions share the same foundations (palette, type scale, spacing, sizes) and differ
on exactly three axes:
| Direction | Typical shape |
|---|
| A | Evolution of your current UI: lowest migration cost | your existing radii and depth, put on a consistent scale |
| B | Institutional / standard: most systematic | hairlines instead of shadows, tighter radii, follows the applicable standard |
| C | Brand-forward: most distinctive | brand colour on the shell and primary action, secondary palette for categories |
Phase 2: the approved reference
After you choose, in the same folder:
| File | For | Contents |
|---|
final.html | visual reference | The same page rendering only the approved system, opening with an Approved decisions table (layer · decision · source) |
tokens.css | developers | :root custom properties: brand ramps, neutrals, status, type, space, sizes, radii, shadows, motion, resolved semantic roles, mobile scale |
DESIGN.md | whoever designs next, people or AI | Decisions, token roles and when to use each, scales, per-component rules, do / don't, what's still open |
index.html stays untouched as the record of what was proposed.
You don't have to take one option whole. Mix them per layer, for example "surfaces and shape
from A, header bar and focus ring from B". The skill takes each layer from one option only, so the
result stays coherent, and it recomputes contrast for every pair that changed.
Install
Clone into your personal skills folder:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
