ui-craft

What this skill does

# UI Craft

## The Fundamental Law

```
AI-GENERATED UI FAILS THE SAME WAYS EVERY TIME.
Visual sameness. Weak hierarchy. Fake interactivity.
Half the states missing. Hex codes outside the token system.
"Welcome!" microcopy that nobody asked for.
This skill exists so the UI being shipped is not slop.
```

UI craft is the discipline of producing user-facing surfaces that respect the user, the brand, and the medium. It is not "make it pretty." It is: every visible state explicit, every interactive element reachable by keyboard, every value drawn from the design system, every word earning its place, every motion serving a purpose.

A user interface is a contract with a real person. Ship slop and the contract breaks.

## Required Reading Router

Match your task to the row. Read the listed files **in full before generating anything visual**. They are not appendices — they are load-bearing. Inline content in this SKILL.md is a pointer to the reference file, not a substitute for it. Files are loaded JIT (never all at once); but every row whose trigger applies to your task is mandatory, not optional.

| Task                                          | MUST read                                                        |
| --------------------------------------------- | ---------------------------------------------------------------- |
| Any interactive widget (dialog, menu, combo)  | `references/accessibility-floor.md`                              |
| Auditing AI-generated UI                      | `references/ai-slop-patterns.md` + `references/anti-defaults.md` |
| Designing a novel surface                     | `references/usability-foundations.md`                            |
| Picking or extending a component pattern      | `references/component-patterns.md`                               |
| Writing or reviewing user-visible text        | `references/microcopy-quality.md`                                |
| Implementing or reviewing dark mode           | `references/dark-mode.md`                                        |
| Animation / transitions / motion review       | `references/motion-patterns.md`                                  |
| AI / agent UI (chat, streaming, citations)    | `references/human-ai-ux.md`                                      |
| Working with DESIGN.md or extending tokens    | `references/design-system-integration.md`                        |
| Performance work / pre-ship gates             | `references/performance.md`                                      |
| "We need a [Linear/Notion-like] X" brief      | `references/archetypes.md`                                       |
| No existing token system in the repo          | `references/visual-craft.md`                                     |

## Reference Index

What each file covers (the Router above tells you *when* to load them):

- `references/usability-foundations.md` — Nielsen 10 heuristics, Laws of UX, progressive disclosure, mental models.
- `references/accessibility-floor.md` — Full WCAG 2.2 AA checklist, ARIA patterns (dialog, combobox, menu, tabs, slider, listbox), verification recipes.
- `references/visual-craft.md` — Typography scales, color systems, spacing rhythm, motion physics, dark mode, elevation.
- `references/component-patterns.md` — Do/don't per component: buttons, inputs, dialogs, navigation, tables, dropdowns, tabs, popovers, toasts.
- `references/microcopy-quality.md` — Full banned-vocabulary list, tone guides per surface, error/empty/CTA copy rules.
- `references/ai-slop-patterns.md` — Before/after for each of the 14 anti-slop patterns. Detection prompts. Remediation recipes.
- `references/anti-defaults.md` — 17 literal artifacts to refuse on sight (emoji-as-icon, "Inter" by reflex, centred hero, placeholder names, gradient text, glassmorphism padrão, modal-as-first-thought, etc.).
- `references/human-ai-ux.md` — Microsoft + IBM agent/AI UI guidelines distilled.
- `references/design-system-integration.md` — Canonical DESIGN.md sections, semantic tokens, shadcn/Radix composition, rules-files for AI codegen.
- `references/performance.md` — 80ms perceived-performance threshold, font-loading zero-CLS strategy, executable pre-ship gate.
- `references/motion-patterns.md` — 100/300/500 duration rule, easing curves, Tailwind/CSS/Framer code, reduced-motion templates, severity-tagged anti-patterns.
- `references/dark-mode.md` — Surface-lightness elevation, accent desaturation, semantic token strategy, dangerous combinations.
- `references/archetypes.md` — Seven named archetypes (Bento, Command Palette, Focus Mode, Live Status, Intelligent List, Empty State Hero, Inline Editor) each with a six-slot signature contract.

### Scripts

- `scripts/check-contrast.mjs` — verify foreground/background WCAG AA/AAA + APCA Lc. Zero-dependency, accepts hex / rgb / oklch. Wire into CI when token files change.
- `scripts/detect-token-drift.mjs` — scan source for raw hex / rgb / hsl / oklch outside designated token paths. Reports file:line with replacement suggestion.
- `scripts/validate-metadata.py` — validate this skill's `name`/`description` frontmatter against the agentskills.io spec.

## Tunable Design Dials

Three named dials let the user steer taste without dragging the conversation through dozens of micro-preferences. Declare values before generating anything visual, and pin them in the deliverable so a future review can re-anchor.

| Dial                  | Range | Default | Low end (1–3)                                | High end (8–10)                                       |
| --------------------- | ----- | ------- | -------------------------------------------- | ----------------------------------------------------- |
| `VISUAL_VARIANCE`     | 1–10  | 6       | Conservative, system-aligned, recognizable   | Bold, expressive, willing to diverge from the category default |
| `MOTION_INTENSITY`    | 1–10  | 4       | Reduced/utility only: state feedback         | Rich orchestration, layered materials, premium feel   |
| `INFORMATION_DENSITY` | 1–10  | 5       | Spacious, calm, marketing-leaning            | Dense, data-heavy, dashboard-leaning                  |

What changes at each end:

- **`VISUAL_VARIANCE`** — at low values, defaults to the closest equivalent of a familiar pattern (e.g. shadcn defaults, Material 3, Apple HIG). At high values, breaks the category template deliberately — bento over grid, asymmetric over centred, branded color over neutral.
- **`MOTION_INTENSITY`** — drives durations (low → 80–150ms only; high → up to 500ms entrances, layered easing), and unlocks premium materials (blur, mask, clip-path) at ≥ 7.
- **`INFORMATION_DENSITY`** — drives spacing scale ramps (low → space-6/8/10; high → space-1/2/3), row heights, line-height, and chart annotation richness. High density implies tabular-nums and keyboard-first interactions.

When the user asks for "more bold" / "calmer" / "tighter" / "looser", translate to dial moves. Do not re-derive every other choice from scratch.

Cite: dial pattern adapted from `taste-skill` (Leonxlnx, open-design ecosystem).

## HARD-GATE

```
Do NOT generate, modify, or approve any user-facing UI surface until:

1. The brand authorities have been READ (not skimmed):
   - DESIGN.md (root) if present
   - Design token files (e.g. packages/ui/src/tokens.css, theme.ts, tailwind.config.*)
   - Frontend conventions doc (e.g. web/CLAUDE.md, .cursorrules, .ai/rules.md)
   - Copy authority (e.g. COPY.md, content/style-guide.md)
2. The surface's JOB is stated in one sentence (what the user is here to do).
3. The complete STATE LIST for the surface is enumerated
   (default, hover, active, focus-visible, disabled, loading, empty, error, success — plus any domain states).
4. The component is known to either EXIST in the design system already
   or is JUSTIFIED as a new addition with a token-level proposal.
5. The SCENE SENTENCE has been written (see below). Categories are not scenes.
6. The REGISTER has been picked: Product or Brand (see below).