An agent skill that audits and fixes the design of interfaces that already exist in your files.
Most AI-generated interfaces look the same. This skill is a written-down policy for why that happens and what to do about it, packaged so Claude Code (or any agent that reads skills) can apply it to real code.
Seventeen modes. Three audit modes that only report, one fix mode, and thirteen that change files. Four rules every mode inherits, the most important of which is that a mode may only claim it fixed something when the change is visible in the rendered result.
The concept, the mode taxonomy, and the diagnose-then-treat structure come from Command Code and their /design command. Their writing is where the core insight lives: that the model was never missing the capability to write good CSS, it was missing the policy of when, and that this policy is low-dimensional enough to write down.
This repository is an independent open-source reimplementation of that idea as a portable agent skill. The instructional content here (the ten tells, the seven work patterns, the nine control states, every mode body, and all three Python scripts) was written for this repo. The command surface and the framing are theirs.
If you want the original, polished, supported product, go to commandcode.io. This project is not affiliated with, endorsed by, or supported by Command Code.
- Why
/designexists — the announcement thread from Command Code's founder - Live walkthrough — the modes run against real UI
Copy the design/ folder into your skills directory.
Claude Code
git clone https://github.com/adnanalpolink/design-skill.git
cp -r design-skill/design ~/.claude/skills/designWindows PowerShell:
git clone https://github.com/adnanalpolink/design-skill.git
Copy-Item -Recurse design-skill\design $env:USERPROFILE\.claude\skills\designVerify it loaded by asking Claude /design help.
Requirements: Python 3.8+ for the three bundled scripts. No pip packages, standard library only.
/design checkup # triage. writes a report, changes nothing
/design smell # name the generic patterns. also report-only
/design deslop # fix what the reports found, in real filesReports land in .design/ as a markdown file the next mode reads and an HTML file you open.
/design # route itself and act
/design make this hero stronger # freeform, picks the closest mode
/design typeset src/components/Hero.tsx # one mode, one target
/design help # full usage guideYou do not have to name a mode. The skill also triggers on plain complaints: "this dashboard looks like every other admin template", "the type hierarchy is flat", "cards look AI-generated".
/design setup # 1. give the project design context
/design checkup # 2. diagnose
/design smell
/design deslop # 3. treat what the reports found
/design relayout
/design recolor
/design tokenize # 4. systematize and harden
/design surface
/design responsive # 5. pre-ship
/design finishEverything below is a real run against examples/before/, a deliberately generic static site for a fictional satellite-tasking product called orbital. The defects were planted; the fixes were not scripted. Open the files yourself.
| Path | |
|---|---|
| Before | examples/before/ |
| After, landing page | examples/after-landing/ |
| After, dashboard | examples/after-dashboard/ |
| The reports that drove it | examples/reports/ |
/design checkup scored the untouched site 2/10 · UNSAFE TO SHIP, with six of ten vitals critical:
| Vital | Status | Observed |
|---|---|---|
| Contrast | critical | #9CA3AF secondary copy at 2.54:1 against a 4.5:1 floor, six sites |
| Focus visibility | critical | outline:none on all controls, zero :focus-visible in the repo |
| Touch targets | critical | nav links 52x19, row actions 32x32, against 44x44 |
| Responsive integrity | critical | 390px scrollWidth 547 and 800, zero @media rules exist |
| Control states | critical | no disabled, active, error or loading anywhere |
| View states | critical | table has no empty, loading or error branch |
| Type hierarchy | warning | --text-xl and --text-2xl both 20px, a 1.0 ratio against 1.3 |
/design smell scored it 0/10 · OVERPOWERING. All ten generic tells present.
Note the prescription order. The report put token repair above the more severe contrast fix, because 10 of 12 color tokens had zero var() references while their literals were pasted 2 to 9 times each. Fixing contrast first would have been roughly 35 separate edits instead of one. Severity says what matters; dependency says what comes first.
<span class="hero__badge">✨ Now with AI</span>
<h1>The <span class="grad">powerful</span> platform built for modern teams</h1>
<p>Seamlessly integrate with your existing workflow and take your operations
to the next level. Built for scale, designed for humans.</p>--primary: #6366F1;
--gradient: linear-gradient(135deg, #6366F1 0%, #A855F7 100%);
.hero { background: var(--gradient); text-align: center; padding: 96px 24px; }
.features { display: grid; grid-template-columns: repeat(3, 1fr); }
a:focus, button:focus, input:focus { outline: none; }Three identical card grids, one per section. Emoji as icons. Nothing on the page could only be true of a satellite-tasking product.
<!-- Work pattern: lead. One focal object (the capture table) against a reading
edge on the left. The field is flat, not a gradient, because the capture
record is the subject and a gradient behind it would compete with it. -->
<p class="eyebrow">Satellite tasking and imagery delivery</p>
<h1>Name a place on Earth. Follow the capture until it is on the ground.</h1>
<p class="hero__sub">
orbital takes a target name and a bounding box, turns it into a tasking
request, and tracks that request through capture and downlink until the
imagery reaches your ground team.
</p>The specifics were three files away, in package.json and the dashboard's own vocabulary. The skill found them there rather than inventing them.
Measured on the final page: 0 gradients, 0 emoji, 0 centered blocks, 12 tab stops each with a visible 2px ring, all targets 44px or larger, 390px scrollWidth down from 547 to 375.
Structure changed, not just surface. Section heights went from 516, 516, 516, 505, 351 to 768, 821, 835, 438, 117. The hero became an asymmetric lead with the real capture table as its focal object, "how it works" became a true sequence on one rail, and pricing became a comparison with one column broken out.
The page needed concrete claims. The real numbers were not in the repository. So the skill left 17 [NEEDS: ...] markers, 13 visible on the page and 4 in HTML comments, and listed every one in its summary.
It invented nothing.
This is rule 4, and it is the single behavior that most separated this skill from an unaided agent in testing. Run the same task without it and you get a beautiful page asserting a 9h 12m delivery time, 0.5m ground sample distance, and a $4.00/km² price, none of which exist anywhere. Those numbers are plausible, which is exactly what makes them dangerous. A vague sentence announces itself. A fabricated statistic does not.
Measured against the same tasks run by an unaided agent, three tasks, one run each.
| With skill | Without | Delta | |
|---|---|---|---|
| Assertion pass rate | 100% | 81.7% | +18.3 pts |
| Wall clock | 1289s | 1616s | −327s |
| Tokens | 166,491 | 155,907 | +10,583 |
Read these honestly:
- One run per configuration. No variance data. Treat the delta as directional, not significant.
- The baseline is contaminated upward. The skill was installed where the "unaided" agent could see it, and one baseline run admitted consulting it before noticing it shouldn't. The real gap is wider than shown.
- 100% means the assertions are exhausted, not that the skill is perfect. Ten of the assertions pass in both arms. The benchmark stopped discriminating and cannot say more without harder tests.
What the testing actually showed. The skill does not make an agent better at finding design problems. A capable model already does that well. What it changes is narrower:
- It refuses to fabricate. 17 marked gaps instead of 4 invented specifications.
- It catches what nobody checks by hand. 5 of 40 color tokens outside the sRGB gamut, caught while the palette was still a draft. Two status pairs that survive only on a thin lightness difference under color vision deficiency.
- It separates audit from treatment, so a fix pass starts from written evidence rather than instinct.
The second iteration was both better and cheaper than the first, 32% faster and 15% fewer tokens, because bundling the measurement scripts stopped every run from rebuilding a WCAG checker from scratch.
Every mode inherits these.
1. Report modes only report. checkup, smell and review write their artifacts and stop. They never edit a source file, not even an obvious one-line fix. An audit never changes a file behind your back.
2. Treatment modes read the reports first. Any mode that changes the interface checks .design/ before deciding what to change, then still runs its own full bar.
3. Truthful completion. Say "added", "fixed" or "changed" only when the change is visible in the rendered result. If something was looked at and left alone, the word is inspected. If a state was implemented but cannot be reached in the current UI, say so instead of counting it.
4. Never invent evidence. When the facts are not in the repository, the answer is a marked gap, never a plausible number. No invented statistics, prices, customer names, testimonials or logo walls.
Audit — report only, change nothing
| Mode | Job |
|---|---|
checkup |
Fast triage. Is this safe to keep building on. |
smell |
Name the generic and reflexive patterns. Scored out of 10. |
review |
Honest scored critique, walked as a story. |
Fix
| Mode | Job |
|---|---|
deslop |
Replace every generic tell with a decision that belongs to this product. |
System
| Mode | Job |
|---|---|
typeset |
Build or repair the type system across every text role. |
recolor |
Build or repair the color system in OKLCH, applied to real components. |
motion |
Build the page-wide motion system, then tune what exists. |
interaction |
Add missing behavior and states, not hover polish. |
Compose
| Mode | Job |
|---|---|
relayout |
Change structure, not spacing. |
responsive |
Recompose across contexts, not shrink. |
Build
| Mode | Job |
|---|---|
redesign |
Full visual transformation, handled as a system. |
tokenize |
Pull proven repetition into tokens, then migrate real usage. |
setup |
Read the repo and write the project's design context. |
Ship
| Mode | Job |
|---|---|
finish |
Pre-ship pass. Use it like a real person, remove the friction found. |
refine |
Change the character. One of push, settle, strip, proof, texture. |
voice |
Marketing and editorial surfaces, where arrival is the deliverable. |
surface |
App UI, where trust is earned through consistency. |
design/
├── SKILL.md router, the four rules, core rules, evidence ladder
├── modes/ 17 files, loaded only when that mode runs
├── references/
│ ├── ten-tells.md the ten patterns that read as machine-made
│ ├── work-patterns.md the seven jobs a surface can have
│ ├── control-states.md nine control states, five view states
│ ├── color.md commitment levels, OKLCH, contrast, color vision
│ ├── type.md scale, measure, roles, font loading
│ └── report-format.md exact report structure
└── scripts/
├── contrast.py WCAG ratios, sRGB gamut, color vision simulation
├── verify_static.py dangling refs, labels, focus, reduced motion
└── render_report.py report markdown to a designed HTML page
The skill uses progressive disclosure. SKILL.md is 165 lines and always loaded; a mode file loads only when that mode runs; a reference loads only when a mode calls for it.
These exist because in testing, four of five runs independently rewrote the same WCAG contrast checker. Write it once.
python design/scripts/contrast.py --pair "oklch(0.55 0.14 42)" "#ffffff"
python design/scripts/contrast.py --css css/tokens.css # gamut + lightness sweep
python design/scripts/contrast.py --cvd "#16A34A" "#DC2626" # color vision separability
python design/scripts/verify_static.py . # dangling refs, labels, focus
python design/scripts/render_report.py .design/smell-report.mdcontrast.py handles hex, rgb, hsl, oklch and oklab. Run it before committing to a palette. Catching an out-of-gamut color while the ramp is a draft costs nothing; catching it after the palette is on 40 components costs a migration.
It also reports a MARGINAL band, which matters more than it sounds. A default green/red status pair typically survives color vision deficiency only on a thin lightness difference:
$ python design/scripts/contrast.py --cvd "#16A34A" "#DC2626"
#16A34A vs #DC2626
normal vision distance 0.341
deuteranopia distance 0.109 MARGINAL (#7A7A4D vs #5B5B22)
protanopia distance 0.310 separable (#939349 vs #3A3A27)
tritanopia distance 0.357 separable (#5D5DFF vs #808000)
These two survive only on a thin lightness difference, which is not enough to
carry meaning by itself. A default green/red status pair usually lands here.
Fix by widening the LIGHTNESS gap, and pair them with an icon, label, or position.
A hue change alone usually does not fix it.
A plain pass/fail would have waved that through.
verify_static.py catches the boring breakage design edits cause: a var() pointing at a renamed token, a getElementById for a removed id, a label pointing at nothing, outline: none with no replacement, animation with no reduced-motion guard. It prints its own limits so those limits end up in your report:
What this did NOT check, and what you therefore may not claim:
layout, overflow, or anything about how the page actually renders
computed contrast (use scripts/contrast.py)
whether a font file loads over the network
keyboard order, focus visibility in practice, or any real interaction
whether a state can be reached by a user
Passing here means nothing is dangling. It does not mean the design works.
Both scripts exit non-zero on failure, so they can gate a pass in CI.
Color. OKLCH first. Pick a commitment level before a hue: whisper, statement, conversation, flood. 60-30-10. Neutrals carry a trace of the brand hue. Never default to indigo.
Typography. Body measure 60 to 76ch. Minimum 1.3 ratio between hierarchy steps. Three fonts only when each has a role: display, body, UI.
Layout. 1-4-9 rhythm: 4px inside a component, 16px between components, 36px and multiples between sections. Use gap, never sibling margins. A card inside a card is never right.
Motion. Animate transform and opacity only. Ease out, never bounce. Exits at about 70% of entrance duration. prefers-reduced-motion is not optional.
Interaction. Nine states per control. Touch targets at least 44x44px. Labels always visible; a placeholder is not a label.
Responsive. Base experience first, more structure as space earns it. Never gate functionality behind hover. Adapt the interface, never amputate the feature.
Copy. One verb per button. Sentence case. No exclamation points. Errors are recovery paths, not blame.
Agents usually cannot see the page. That does not excuse an unverified claim, it changes which claims are available. The skill defines an evidence ladder and requires each claim to say which rung it rests on:
- Drive a real browser. Assert the URL inside the same call that takes the measurement.
- Headless measurement. Serve it and read
scrollWidth, computed styles, tab-stop counts as numbers. - Compute it. Contrast, gamut, color vision and grid arithmetic are deterministic.
- Parse it.
verify_static.py. - Read it. Weakest rung. Enough for "this token is defined", never for "this renders correctly".
Promoting a lower rung to a higher one is forbidden. "The CSS says 44px" is not "the hit area measures 44px". Anything unreachable is marked unverified, and unverified is never healthy.
Issues and pull requests welcome. The most useful contributions:
- A tell that is missing. The ten in
references/ten-tells.mdare a starting point, not scripture. - A work pattern that does not fit the seven.
- Framework-specific reference files. The skill is framework-agnostic today, which means it is less specific than it could be for Tailwind, shadcn, Chakra or Material.
- Better evals. The current three are in the git history of this project, and their weakness is documented above: most assertions stopped discriminating. Harder tests would tell us more.
If you change a mode, say in the PR what you ran it against and what visibly changed. The skill asks that of its modes; the repo should ask it of its contributors.
MIT. See LICENSE.
Concept and command taxonomy credit to Command Code. Not affiliated.
Adnan Akram