UI Craft

A user interface is a contract with a real person. Slop is what breaks it: visual sameness, weak hierarchy, fake interactivity, half the states missing, raw hex outside the token system, "Welcome!" copy nobody asked for. AI-generated UI fails these same ways every run. This skill is the floor that stops it — every visible state explicit, every value from the design system, every interactive element reachable by keyboard, every word earning its place.

Frame the surface before generating

Lock these before any pixel. They apply to every change — a one-line tweak, a new variant, a full page. "It's just a small change" is the most common slop excuse.

Read the brand authorities (normative — quote them, never re-invent):
```
DESIGN.md
```
(root, or
```
packages/ui/
```
,
```
apps/web/
```
,
```
docs/
```
,
```
.ai/
```
), token files (
```
tokens.css
```
,
```
theme.ts
```
,
```
tailwind.config.*
```
), frontend conventions (
```
web/CLAUDE.md
```
,
```
.cursorrules
```
), copy authority (
```
COPY.md
```
). None present → fall back to
```
references/visual-craft.md
```
defaults and record a finding: "No DESIGN.md / token system; recommend scaffolding before further UI work." Don't bootstrap DESIGN.md as a side effect.
State the job in one user-perspective sentence ("The user opens this dialog to confirm irreversible deletion of a project"). More than one job → split the surface.
Write the scene sentence (below).
Pick the register — Product or Brand (below).
Declare the dials — VISUAL_VARIANCE, MOTION_INTENSITY, INFORMATION_DENSITY (below).

Scene sentence

Physical context that forces the visual answer: who uses this, where, under what ambient light, in what mood. A category ("observability dashboard", "marketing landing") points at a thousand average answers; a scene forces one.

✅ "SRE glances at incident severity on a 27" monitor at 2am in a dim room — every element competes with a paged-alert sound."

If the scene doesn't force the decision, add detail until it does. Most weak visual calls come from a missing scene. (Adapted from
impeccable
, pbakaus/impeccable.)

Register: Product or Brand

Pick one; switching mid-surface is the source of half of all "this feels off" reactions. If undecidable, it is almost always Product — Brand is the exception.

Register	Lives in	Color	Type	Motion
Product	App shells, dashboards, settings, forms, lists	Restrained: tinted neutrals + 1 accent ≤10%	System fonts ok; fixed rem scale	150–250ms state feedback only; no decoration
Brand	Landing pages, heroes, onboarding, marketing	Committed: 1 saturated color carries 30–60%	Display + body pairing	Full orchestration; entrance reveals welcome

Recurring task by a known user → Product. First/deliberate impression or campaign → Brand. (Adapted from
impeccable
.)

Tunable dials

Declare values before generating; pin them in the deliverable so review can re-anchor. Translate "more bold / calmer / tighter / looser" to a dial move — don't re-derive every choice.

Dial	Default	Low (1–3)	High (8–10)
`VISUAL_VARIANCE`	6	System-aligned, closest familiar pattern	Breaks the category template (bento, asymmetric, branded color)
`MOTION_INTENSITY`	4	80–150ms utility feedback only	Up to 500ms entrances, layered materials (blur/mask/clip-path) at ≥7
`INFORMATION_DENSITY`	5	Spacious, marketing-leaning	Dense/dashboard: tabular-nums, keyboard-first, tight spacing ramp

(Dial pattern adapted from
taste-skill
, Leonxlnx.)

The operating loop

Run every task through these steps in order; each ends on a checkable bar. The one-line bar is the floor — the linked file is the full contract, and you must read it in full before generating or reviewing that dimension (loaded just-in-time, never all at once). The inline bar is not a substitute for the file.

Usability filter. Run the surface through Nielsen's 10 heuristics + the load-bearing Laws of UX (Jakob, Hick, Miller, Fitts, Tesler); fix the one or two that most threaten this surface. → Novel or audited surface: read
references/usability-foundations.md
. Bar: no unjustified heuristic violation (visible system status, reversible exits, recognition over recall).
Accessibility floor (WCAG 2.2 AA, the floor not the ceiling). Bar: text contrast ≥4.5:1 (≥3:1 large / non-text / state indicators);
```
:focus-visible
```
≥2px and ≥3:1 on every interactive element; full keyboard reach + operation; target ≥24×24 (≥44×44 touch);
```
prefers-reduced-motion
```
honored; color never the sole carrier of meaning. → Any interactive widget: read
references/accessibility-floor.md
for the ARIA patterns (dialog, combobox, menu, tabs, slider, listbox) and verification recipes. A floor item that can't be met is a blocker, not a trade-off.
Visual craft — draw every value from the system. Type from the scale, color from semantic tokens (
```
--color-bg-danger-subtle
```
, never raw hex), spacing snapped to the scale, radius/elevation/motion from their scales. → No token system, or a scale needs extending: read
references/visual-craft.md
. A real gap → propose a token (step 7), never inline-invent. → Extending DESIGN.md / tokens / shadcn-Radix: read
references/design-system-integration.md
.
State matrix — every state, designed at once. Fill
```
assets/state-matrix.md
```
for the component: default, hover, active, focus-visible, disabled, loading, empty, selected, error, success, plus domain states. → Any button/input/dialog/nav/table/card/dropdown/tabs/popover/toast: read
references/component-patterns.md
. A listed-but-undesigned state is
```
StateMatrixHoles
```
.
Anti-slop scan. Match the surface against the 14 patterns (scorecard below) and the literal blocklist. Then the two-level slop test: could a stranger guess the aesthetic from the category alone (first-order default), or from category + your anti-references (second-order — brutalist mono is still a default)? Both are trapped; escape by re-deriving from the scene. → Auditing AI-generated UI: read
references/ai-slop-patterns.md
(before/after + remediation) and
references/anti-defaults.md
(17 artifacts to refuse on sight). Every hit is stop-and-fix.
Microcopy — every word earns its place. Bar: CTAs are verb + object (
```
Delete project
```
, not
```
OK
```
); errors say what happened + why + how to recover, no blame; empty states explain what lives here + the one action; no AI vocabulary (
```
seamless
```
,
```
delve
```
,
```
elevate
```
,
```
unleash
```
), no empty greetings, no filler (
```
Please
```
,
```
In order to
```
). → Any user-visible text: read
references/microcopy-quality.md
.
Verify, then document deltas. Visually confirm at supported breakpoints; force each state and screenshot the non-trivial ones; keyboard-test the full interaction; contrast-check rendered values; toggle
```
prefers-reduced-motion
```
. New token/variant/pattern → append it to
```
DESIGN.md
```
in the same change set (silent drift otherwise). Run
```
assets/pre-ship-checklist.md
```
as the binary gate. → Per-ARIA verification recipes in
references/accessibility-floor.md
; if CWV/fonts/images are in scope, read
references/performance.md
. A surface that can't be rendered for verification is not "done" — say so.

Branch-specific pointers, loaded when the branch applies:

Animation / transitions:
```
references/motion-patterns.md
```
(duration bands, easing curves, CSS/Framer/
```
@starting-style
```
code, reduced-motion templates).
Dark theme:
```
references/dark-mode.md
```
(surface-lightness elevation, accent desaturation, dangerous pairs).
AI / agent surface (chat, streaming, citations, approvals):
```
references/human-ai-ux.md
```
(Microsoft 18 + IBM 4 pillars).
"We need a [Linear/Notion]-like X" / reinventing a primitive:
```
references/archetypes.md
```
(7 signature contracts).
Reviewing an existing surface: deliver findings in the
```
assets/ui-audit-template.md
```
format.

Reference router

Every row whose trigger applies is mandatory reading before generating that dimension, not an appendix.

When	File	Covers
Designing a novel surface / auditing usability	`references/usability-foundations.md`	Nielsen 10, Laws of UX, progressive disclosure, mental models
Any interactive widget (dialog, menu, combobox, tabs, slider)	`references/accessibility-floor.md`	WCAG 2.2 AA non-negotiables, ARIA patterns, verification recipes
Buttons/inputs/dialogs/nav/tables/cards/dropdowns/tabs/toasts	`references/component-patterns.md`	States, keyboard contract, a11y, and slop per component
Writing or reviewing user-visible text	`references/microcopy-quality.md`	Banned vocabulary, per-surface tone, error/empty/CTA templates
Auditing AI-generated UI	`references/ai-slop-patterns.md`	Before/after + remediation for the 14 patterns, detection prompts
A choice feels like a category-average default	`references/anti-defaults.md`	17 literal artifacts to refuse on sight
Building an AI/agent surface	`references/human-ai-ux.md`	Microsoft 18 + IBM 4 pillars, streaming/citation/confidence UI
Reading/extending DESIGN.md, tokens, shadcn/Radix, codegen rules	`references/design-system-integration.md`	DESIGN.md sections, token discipline, Figma/Code Connect
No token system, or extending a scale	`references/visual-craft.md`	Type/color/spacing/radius/elevation/motion defaults
Adding or reviewing animation	`references/motion-patterns.md`	Duration bands, easing, CSS/Framer/ `@starting-style` , reduced-motion
Implementing or reviewing dark mode	`references/dark-mode.md`	Surface-lightness elevation, accent desaturation, dangerous pairs
Unprofiled ship, CWV regress, heavy dep on a hot route	`references/performance.md`	CWV floors, 80ms threshold, font zero-CLS, pre-ship gate
"We need a [Linear/Notion]-like X"	`references/archetypes.md`	7 archetypes, each a six-slot signature contract

Anti-slop scorecard

Match every surface. Hits are not nits; severity drives the response. Full symptom/fix per pattern lives in

references/ai-slop-patterns.md

(by number) and

references/anti-defaults.md

Critical — blocks merge (accessibility, broken keyboard/focus contract, missing states).
Serious — blocks review approval (training-data defaults, design-system drift, weak hierarchy).
Moderate — polish later, unless ≥3 stack on one surface → treat as Serious.

#	Pattern	Severity	#	Pattern	Severity
1	VisualSameness	Moderate	8	GenericIllustration	Serious
2	WeakHierarchy	Serious	9	DesignSystemDrift	Serious
3	TextOverflow	Serious	10	StateMatrixHoles	Critical
4	FakeInteractivity	Critical	11	CenteredEverything	Moderate
5	EmojiSpam	Moderate	12	RandomRadii	Moderate
6	GradientCrutch	Serious	13	GhostFocus	Critical
7	GlassmorphismAbuse	Moderate	14	MagicNumbers	Moderate

Scripts

```
scripts/check-contrast.mjs
```
— WCAG AA/AAA + APCA Lc for a foreground/background pair; hex/rgb/oklch, zero-dependency. Wire into CI on token changes.
```
scripts/detect-token-drift.mjs
```
— scan source for raw hex/rgb/hsl/oklch outside token paths; reports
```
file:line
```
+ suggestion. Must exit 0 to ship.
```
scripts/validate-metadata.py
```
— validate this skill's frontmatter against the agentskills.io spec (author tooling).

Edge cases

Tokens conflict between DESIGN.md and a token file → trust DESIGN.md; flag the divergence as a finding.
State matrix exceeds the surface → prune to states the surface supports, justifying each pruning; never silently drop.
User insists on shipping a known hit → name the anti-default, run the scene sentence with them; if no scene emerges, record the override as acknowledged slop debt. Never invent a justification for it.

ui-craft

NPX Install

Tags

SKILL.md Content