| name | design-system |
| description | Derive a unique, domain-fit design direction and enforce design-token + anti-slop discipline. Read/author DESIGN.md before building any UI; override framework defaults so output is bespoke by construction, not generic. |
Design System Protocol
Invoke this skill for any web UI work (new frontend, new screen, UI refactor).
Its job: stop AI-generated UI from converging on the statistical mean of the
training data ("AI slop") by committing design decisions before code, and
enforcing them as a machine-checkable filter.
Root cause it fixes: LLMs emit the highest-probability "nice" defaults —
Inter font, purple→blue gradients, shadcn-default cards, centered hero + three
feature columns, <div onClick> accessibility. No prompt adjective escapes this;
only pre-committed constraints do. This skill produces and enforces those
constraints.
The steering bundle: DESIGN.md + design/tokens.json
Every UI-bearing project commits a bundle, not a prose memo:
DESIGN.md at repo root — human + machine readable (YAML front-matter tokens
- prose rationale and bans).
design/tokens.json — DTCG-format design tokens, two-tier primitive →
semantic. Components reference only semantic tokens (else dark mode / re-theming
becomes a rewrite). Compiles to tokens.css (Tailwind v4 @theme → CSS variables).
If the bundle is missing, author it first (Step 1–2). If it exists, read it
before writing any component and build strictly within it.
Step 1 — Derive direction from the business domain (not taste)
"Clean and modern" is the slop default, not a direction. Derive an opinionated
direction from the app's domain:
- Brand archetype (pick a primary + secondary from Jung's 12 — Ruler, Hero,
Outlaw, Caregiver, Creator, Explorer, Sage, …). Each maps to visual semiotics:
Ruler → restrained composition, elegant type, muted+metal; Outlaw → bold edgy
type, dark + acid accent; Caregiver → soft, warm, rounded, reassuring.
- Target user + key tasks → information density and IA (a compliance analyst
scanning tables ≠ a consumer onboarding flow).
- Tone → voice/copy rules + type personality.
- Lock one aesthetic direction from a small enumerated set (Swiss/editorial,
brutalist, industrial-mono, organic, warm-minimal, high-density-data) and commit
its tokens.
- Reference-ground: 1–3 real UIs whose feeling matches — extract palette,
type scale, density; use to set constraints, never to clone.
In the Plan phase, ask 1–2 art-direction clarifying questions before locking this
(see clarification-protocol).
Step 2 — Override the four defaults that create the "AI look"
The single highest-leverage action. In design/tokens.json, never ship the
framework defaults for:
- Neutral — pick a distinct neutral, not default
slate/zinc.
- Primary/accent — one saturated brand accent, not Tailwind
indigo-600.
- Font — a real display+body pairing, not Inter/Poppins/Geist/Space Grotesk.
- Radius — a deliberate radius vocabulary, not the default.
Author color in OKLCH (perceptually uniform). Add one deliberate signature
token (a shadow, an accent treatment) that is yours — the fingerprint that
de-generics output.
Step 3 — The anti-slop catalog (bans → enforce in DESIGN.md "Don'ts")
Each is a concrete tell with a codified remedy. Write a matching "Don't" in
DESIGN.md for every one that applies:
| Tell | Ban / remedy |
|---|
| Purple→blue "vibecode" gradient | Ban gradient accents; one solid brand accent token |
Default slate + indigo-600 | Replace palette tokens; never ship default --primary |
1px-border card + rounded-2xl shadow-lg p-6 on everything | One card vocabulary (border or shadow, not both); one radius site-wide |
| Colored 3–4px left-border strip | Ban (the single most reliable AI tell) |
| "Cardocalypse" — cards nested in cards | No card-in-card; use whitespace + hierarchy |
| Inter/Poppins/Space Grotesk/Geist default type | Committed font-pairing token; ban defaults |
| Centered hero + badge-above-H1 + "1·2·3" steps + exactly 3 feature cards | Break the layout grammar (Step 4); vary column counts; asymmetry |
| Glassmorphism / floating gradient orbs / neon glowing borders / 3D blobs | Ban decorative effects unless in art direction |
| Giant Lucide icon centered above a heading; emoji-as-iconography | Committed icon set + size tokens; ban emoji icons |
| Hover states that do nothing; same fade-in on everything | Motion tokens (durations + easing); purposeful only |
| Generic stock ("diverse team at laptop"); plastic 3D | Art-direction imagery rules |
| Copy: "Empower your team to unlock productivity" | Voice/tone rules; real domain content |
<div onClick> soup — no landmarks/roles/headings | Semantic HTML + ARIA (enforced by the a11y gate) |
| Lorem ipsum / "Item 1, 2, 3" | Realistic domain data |
Step 4 — Layout grammar (ban the single centered column)
Real product UIs are structured, multi-column, grid-aligned — not a vertical stack
of centered cards. Select a deliberate layout, e.g.:
- Master–detail split (list rail + detail pane) — assets, logs, transactions.
- Asymmetric dashboard grid (main panel + auxiliary rail) — metrics, telemetry.
- Marketing/content pages may use centered composition, but still break the
badge→H1→3-cards→logo-strip template.
Whitespace restraint on dense/data UIs (no py-20/space-y-12 to fill space);
generous rhythm on marketing. Density follows the domain (Step 1).
Step 5 — States are design, not function (non-negotiable)
Every data-bearing component must ship empty, loading (skeleton matching final
layout), error, success, disabled, focus states — the most reliable tell of
release-grade vs "happy-path only" AI output. Destructive actions get confirmation.
Handoff
Once UI is built against the bundle, the visual-review skill runs the closed
render→critique→a11y-gate→iterate loop that scores the result against DESIGN.md.
The design bar is not met until that loop passes.
Note: this skill governs appearance and structure only. A polished UI is not
a secure backend — AI reliably ships the login screen and skips authorization. Keep
security-review in the loop for any auth/data path.
