UI Craft — build it designed, then look at it
Implementation skill. The concept lives in DESIGN.md; the guard rails live in
rules/core/ui-anti-slop.mdc (~/goodai-base/rules/core/ui-anti-slop.mdc when running outside goodai-base). This skill turns both into code and refuses to call it done
until it has looked at real renders.
Workflow
ui-craft Progress:
- [ ] Step 0: Gate — DESIGN.md exists (else run ui-direction or derive a minimal one)
- [ ] Step 1: Read the stack and existing tokens/components
- [ ] Step 2: Tokens first
- [ ] Step 3: First screen at desktop + phone
- [ ] Step 4: Remaining sections/screens with varied structure
- [ ] Step 5: States, forms, interaction
- [ ] Step 6: Motion and accessibility pass
- [ ] Step 7: Browser verification loop (≤3 rounds)
- [ ] Step 8: Pre-delivery checklist and honest report
Step 0 — Gate
DESIGN.md present → read it fully; it overrides personal taste and this skill's defaults.
- Absent and the task is a new surface or a redesign → stop and offer
ui-direction.
- Absent and the task is a small addition to an existing UI → derive a 10-line direction from
the existing tokens and screens, write it to
DESIGN.md, and state that you did.
Step 1 — Read the stack
Find the styling system (Tailwind config, CSS variables, CSS modules, styled-components,
AntD/MUI/shadcn theme), the component library, and two or three existing screens. Adapt the
rules below to that stack — never introduce a second styling system. If the project has
convention docs (CLAUDE.md, STYLING.md, THEMING.md), they win over this skill.
Step 2 — Tokens first
Before any component, define or extend semantic tokens:
- Color — the DESIGN.md palette as semantic roles (
--color-ground, --color-ink,
--color-accent, --color-muted, --color-danger …), light and dark tuned separately.
No raw hex in components.
- Type — families, the modular scale (≤5 sizes), weights at the extremes, body
16–20px / 1.45–1.6, display tracking −0.02 to −0.05em.
- Space — one scale (4/8/12/16/24/32/48/64/96/128). No one-off pixel values.
- Radius — a scale by role; nested radius concentric (child ≤ parent).
- Elevation — shadow tokens for floating layers only (menus, popovers, dialogs).
- Motion — durations (fast ~100ms, base ~200ms, slow ~300ms) and easings
(ease-out enter, ease-in exit).
With a component library: override its theme tokens instead of fighting each component.
Library defaults left untouched are a tell.
Step 3 — First screen first
Build the first screen at desktop and 390px before anything else. It must answer the visitor's
first question in large type, carry the signature element from DESIGN.md, and offer one primary
action with an outcome label. Check it in the browser (Step 7 method) before continuing —
direction mistakes are cheapest here.
Step 4 — The rest
- Each section is a claim with its proof; delete sections without a claim.
- Neighbor sections use different structures. Structure follows content: tables for tabular
data, lists for lists, one large proof instead of three small cards.
app surfaces: quiet panels, aligned figures, tabular-nums, color reserved for data and
status, navigation that folds away on phones.
- Real copy from the brief. Missing content → clearly-marked sample content, listed in the
report. Never invent stats, logos, testimonials, or customers.
Step 5 — States, forms, interaction
Every interactive element: default, hover (only where clickable), :focus-visible, active,
disabled, loading. Every data view: loading, empty, error, sparse, dense.
- Loading: indicator after ~150–300ms; spinner for 2–10s; percent-done + cancel for ≥10s;
skeletons with final dimensions.
- Empty: specific reason + direct action. Never "No results" while still loading.
- Errors: next to the source, plain language, what happened + how to fix, input preserved.
- Forms: visible label on every field (placeholder is never the label), correct
type /
inputmode / autocomplete, paste allowed, submit enabled until submission starts, focus
the first error, inputs ≥16px on mobile.
- Destructive actions: confirm or an Undo window. Optimistic updates roll back on failure.
- Behavior stays conventional:
<a> navigates, <button> acts, Enter submits, Esc closes.
Step 6 — Motion and accessibility
- Motion: animate
transform/opacity only, never transition: all; 100–400ms; one
orchestrated moment at most; every animation has a prefers-reduced-motion variant that keeps
content and drops travel; nothing loops for >5s without a pause control.
- WCAG 2.2 AA floor: text ≥4.5:1, large text and UI boundaries ≥3:1, color never the only
signal, focus ring visible and not obscured by sticky bars (
scroll-padding), targets
≥24px (≥44px on touch), drag has a click alternative, reflow at 320px, zoom never disabled,
icon-only buttons have accessible names, aria-live="polite" for toasts/inline validation,
heading order and a skip link.
Step 7 — Browser verification loop
Open the result in a real browser (built-in browser / Playwright / preview server):
- Screenshot at 1440, 768, 390 px, light and dark if supported.
- Look at the screenshots, not at the code. Squint test: the intended focal element still
dominates when blurred. Five-second test: what is this and what do I do?
- Score against the tell catalog in
ui-anti-slop.mdc; measure contrast and target sizes on
the render, not from class names.
- Fix the top 3 problems. Repeat — at most 3 rounds; then report what remains.
No browser available → say so explicitly and list the checks that were not run.
Step 8 — Pre-delivery checklist and report
Report: what was built, screenshots or their paths, slop score with remaining tells, sample
content to replace, checks not run. Offer review-ui-ux for an independent pass.
Iron Laws
| Rule |
Why |
| DESIGN.md wins over taste |
The concept was chosen deliberately; drifting back is re-convergence |
| Never "done" without looking at renders |
Slop is invisible in code and obvious on screen |
| Never invent proof |
Fake numbers and logos destroy trust and are a T1 tell |
| One styling system |
Mixed systems drift into inconsistent tokens |
| Don't claim unrun checks |
An honest gap is fixable; a false pass ships |
Red Flags
| Thought |
Reality |
| "I'll add states later" |
Later never comes; missing states are behavioral slop |
"rounded-2xl shadow-lg looks nice everywhere" |
One radius + one shadow everywhere is the SaaS card kit |
| "A gradient will make the hero pop" |
It makes it look like every other generated hero |
| "The library default button is fine" |
Untouched library defaults are a tell |
| "Looks right in the code" |
Open the browser |
1---2name: ui-craft3description: |4 Use when: building or restyling UI (page, screen, component set) and the result must look5 designed rather than AI-generated — tokens first, real content, every state, purposeful6 motion, WCAG 2.2 AA, verified in a real browser. Builds from DESIGN.md (run ui-direction7 first when none exists). Stack-agnostic: adapts to the project's Tailwind / CSS modules /8 component library. Triggers: "build this page", "сверстай", "make this UI look good",9 "implement the design", "restyle", "/ui-craft".10 NOT for: choosing the visual concept (ui-direction), reviewing a diff (review-ui-ux),11 React/MobX architecture (review-frontend), or measuring layout regressions (review-layout).12version: "1.0.0"13triggers:14 - "build ui"15 - "build this page"16 - "сверстай"17 - "restyle"18 - "implement the design"19 - "/ui-craft"20metadata:21 source: https://skillmd.com/skills/mrciphersmith/ui-craft22 author: "MrCipherSmith"23 version: "1.0.0"24 category: "design"25license: "MIT"26compatibility: "cursor,codex,zed,opencode,claude"27---2829# UI Craft — build it designed, then look at it3031Implementation skill. The concept lives in `DESIGN.md`; the guard rails live in32`rules/core/ui-anti-slop.mdc` (`~/goodai-base/rules/core/ui-anti-slop.mdc` when running outside goodai-base). This skill turns both into code and refuses to call it done33until it has looked at real renders.3435---3637## Workflow3839```40ui-craft Progress:41- [ ] Step 0: Gate — DESIGN.md exists (else run ui-direction or derive a minimal one)42- [ ] Step 1: Read the stack and existing tokens/components43- [ ] Step 2: Tokens first44- [ ] Step 3: First screen at desktop + phone45- [ ] Step 4: Remaining sections/screens with varied structure46- [ ] Step 5: States, forms, interaction47- [ ] Step 6: Motion and accessibility pass48- [ ] Step 7: Browser verification loop (≤3 rounds)49- [ ] Step 8: Pre-delivery checklist and honest report50```5152---5354## Step 0 — Gate5556- `DESIGN.md` present → read it fully; it overrides personal taste and this skill's defaults.57- Absent and the task is a new surface or a redesign → stop and offer `ui-direction`.58- Absent and the task is a small addition to an existing UI → derive a 10-line direction from59 the existing tokens and screens, write it to `DESIGN.md`, and state that you did.6061## Step 1 — Read the stack6263Find the styling system (Tailwind config, CSS variables, CSS modules, styled-components,64AntD/MUI/shadcn theme), the component library, and two or three existing screens. Adapt the65rules below to that stack — never introduce a second styling system. If the project has66convention docs (`CLAUDE.md`, `STYLING.md`, `THEMING.md`), they win over this skill.6768## Step 2 — Tokens first6970Before any component, define or extend semantic tokens:7172- **Color** — the DESIGN.md palette as semantic roles (`--color-ground`, `--color-ink`,73 `--color-accent`, `--color-muted`, `--color-danger` …), light and dark tuned separately.74 No raw hex in components.75- **Type** — families, the modular scale (≤5 sizes), weights at the extremes, body76 16–20px / 1.45–1.6, display tracking −0.02 to −0.05em.77- **Space** — one scale (4/8/12/16/24/32/48/64/96/128). No one-off pixel values.78- **Radius** — a scale by role; nested radius concentric (child ≤ parent).79- **Elevation** — shadow tokens for floating layers only (menus, popovers, dialogs).80- **Motion** — durations (fast ~100ms, base ~200ms, slow ~300ms) and easings81 (ease-out enter, ease-in exit).8283With a component library: override its theme tokens instead of fighting each component.84Library defaults left untouched are a tell.8586## Step 3 — First screen first8788Build the first screen at desktop and 390px before anything else. It must answer the visitor's89first question in large type, carry the signature element from DESIGN.md, and offer one primary90action with an outcome label. Check it in the browser (Step 7 method) before continuing —91direction mistakes are cheapest here.9293## Step 4 — The rest9495- Each section is a claim with its proof; delete sections without a claim.96- Neighbor sections use different structures. Structure follows content: tables for tabular97 data, lists for lists, one large proof instead of three small cards.98- `app` surfaces: quiet panels, aligned figures, `tabular-nums`, color reserved for data and99 status, navigation that folds away on phones.100- Real copy from the brief. Missing content → clearly-marked sample content, listed in the101 report. Never invent stats, logos, testimonials, or customers.102103## Step 5 — States, forms, interaction104105Every interactive element: default, hover (only where clickable), `:focus-visible`, active,106disabled, loading. Every data view: loading, empty, error, sparse, dense.107108- Loading: indicator after ~150–300ms; spinner for 2–10s; percent-done + cancel for ≥10s;109 skeletons with final dimensions.110- Empty: specific reason + direct action. Never "No results" while still loading.111- Errors: next to the source, plain language, what happened + how to fix, input preserved.112- Forms: visible label on every field (placeholder is never the label), correct `type` /113 `inputmode` / `autocomplete`, paste allowed, submit enabled until submission starts, focus114 the first error, inputs ≥16px on mobile.115- Destructive actions: confirm or an Undo window. Optimistic updates roll back on failure.116- Behavior stays conventional: `<a>` navigates, `<button>` acts, Enter submits, Esc closes.117118## Step 6 — Motion and accessibility119120- Motion: animate `transform`/`opacity` only, never `transition: all`; 100–400ms; one121 orchestrated moment at most; every animation has a `prefers-reduced-motion` variant that keeps122 content and drops travel; nothing loops for >5s without a pause control.123- WCAG 2.2 AA floor: text ≥4.5:1, large text and UI boundaries ≥3:1, color never the only124 signal, focus ring visible and not obscured by sticky bars (`scroll-padding`), targets125 ≥24px (≥44px on touch), drag has a click alternative, reflow at 320px, zoom never disabled,126 icon-only buttons have accessible names, `aria-live="polite"` for toasts/inline validation,127 heading order and a skip link.128129## Step 7 — Browser verification loop130131Open the result in a real browser (built-in browser / Playwright / preview server):1321331. Screenshot at **1440**, **768**, **390** px, light and dark if supported.1342. Look at the screenshots, not at the code. Squint test: the intended focal element still135 dominates when blurred. Five-second test: what is this and what do I do?1363. Score against the tell catalog in `ui-anti-slop.mdc`; measure contrast and target sizes on137 the render, not from class names.1384. Fix the top 3 problems. Repeat — at most 3 rounds; then report what remains.139140No browser available → say so explicitly and list the checks that were not run.141142## Step 8 — Pre-delivery checklist and report143144- [ ] Tokens only; no raw hex or one-off spacing in components145- [ ] DESIGN.md signature element present; exactly one146- [ ] No T1 tells; slop score ≤3 (or exemptions recorded in DESIGN.md)147- [ ] All states implemented for every interactive element and data view148- [ ] WCAG 2.2 AA floor met on the render149- [ ] Reduced-motion variant for every animation150- [ ] Verified at 1440 / 768 / 390 (or stated as not run)151- [ ] Before finishing: removed one element152153Report: what was built, screenshots or their paths, slop score with remaining tells, sample154content to replace, checks not run. Offer `review-ui-ux` for an independent pass.155156---157158## Iron Laws159160| Rule | Why |161|---|---|162| DESIGN.md wins over taste | The concept was chosen deliberately; drifting back is re-convergence |163| Never "done" without looking at renders | Slop is invisible in code and obvious on screen |164| Never invent proof | Fake numbers and logos destroy trust and are a T1 tell |165| One styling system | Mixed systems drift into inconsistent tokens |166| Don't claim unrun checks | An honest gap is fixable; a false pass ships |167168## Red Flags169170| Thought | Reality |171|---|---|172| "I'll add states later" | Later never comes; missing states are behavioral slop |173| "`rounded-2xl shadow-lg` looks nice everywhere" | One radius + one shadow everywhere is the SaaS card kit |174| "A gradient will make the hero pop" | It makes it look like every other generated hero |175| "The library default button is fine" | Untouched library defaults are a tell |176| "Looks right in the code" | Open the browser |