Design

---
name: design
description: 'Set visual and interaction direction for any UI surface (web, React, TUI, CLI, desktop, Qt, design-system tokens) before any UI code. Direction-first: generates 3-4 distinct directions via verbalized sampling, picks one via per-axis single-select, then derives palette, typography, spacing, motion budget. Loads when the user asks for UI work, palette/theme/tokens, mentions a design system, or when output looks AI-generic, vibe-coded, sloppy, or default Tailwind/shadcn/Bootstrap. Enforces two-sided anti-slop charter: forbids purple gradients, `transition: all`, system-ui, default Tailwind palette AND overkill compensation (sprites, gradients everywhere, animation on every element).'
---

Direction first, tokens second, code last. Restraint is the default posture; ONE intentional moment per surface earns the lift.

## Posture

Direction precedes tokens; tokens precede code. The picked direction is the contract — palette, type, spacing, motion all derive from it, not the other way around. Restraint is the default; reach for decoration only when a named surface goal demands it. Posture rests on `references/soul.md` (design philosophy) — load when the user asks "why this look" or when the model is tempted to add decoration to compensate for a thin idea.

**Balance, not maximalism.** ODIN's "don't hold back" (borrowed from the `<design>` block above) means conviction, not volume. The two failure modes catalogued in the anti-slop charter below are reciprocals — AI-generic timidity (Side A) and decorative overkill (Side B) both come from the same fear of commitment. Balance simplicity and verbosity per surface; restraint as the default, the one intentional moment as the lift, neither timid nor loud.

## ODIN `<design>` block — LOAD-BEARING

Quoted verbatim from `output-styles/odin.md` lines 254–262.

```
<design>
Modern, elegant UI/UX. Don't hold back.

**Tokens:** MUST use design system tokens, not hardcoded values.
**Density:** 2-3x denser. Spacing: 4/8/12/16/24/32/48/64px. Medium-high density default. Ask preference when ambiguous.
**Paradigms:** Post-minimalism [default] | Neo-brutalism | Glassmorphism | Material 3 | Fluent. Avoid naive minimalism.
**Forbidden:** Purple-blue/purple-pink | `transition: all` | `font-family: system-ui` | Pure purple/red/blue/green | Self-generated palettes | Gradients (unless explicitly requested, NEVER on buttons/titles)
**Gate:** Design excellence >= 95%
</design>
```

## Register × paradigm matrix — pointer

Every design surface is **brand** (marketing, landing, campaign, long-form content, portfolio — design IS the product) or **product** (app UI, admin, dashboard, tool — design SERVES the product). Identify before designing.

**Detection rule.** First match wins:
1. Cue in the task itself — "landing page" / "campaign hero" → brand; "dashboard" / "settings panel" → product.
2. Surface in focus — the page, file, or route being worked on; the route segment usually disambiguates (`/marketing/*` vs. `/app/*`).
3. Register field in PRD or project context (`AGENTS.md`, `CLAUDE.md`, brand brief).

Brand register opens neo-brutalism / glassmorphism / M3 Expressive with Committed / Full palette / Drenched color strategies; product register defaults to Restrained + post-minimalism / Fluent 2. Full matrix in `references/paradigms.md §0`.

## Anti-slop charter — LOAD-BEARING

Two-sided ban-list. Each row: ban — WHY in one line. Depth in `references/anti-slop.md`.

**Side A — slop tells (the AI-generic look):**

- Purple-blue or purple-pink gradient — RLHF over-aligns to this; betrays self-generated palette.
- Inter alone as the type system — default of every Vercel template; no commitment, no contrast.
- Centered hero plus 3-column feature grid — the shadcn landing-page silhouette; reads as preset.
- Glassmorphism on every surface — translucence loses meaning when nothing is opaque.
- `rounded-lg` uniform on every element — radius without hierarchy is decoration, not signal.
- `shadow-md` uniform across the surface — elevation that conveys nothing.
- `transition: all` — animates layout, color, and transform together; jank guaranteed.
- `font-family: system-ui` — abdicates the type decision; reads as "did not pick".
- Default Tailwind palette (slate-500 / blue-500) — the costume of "I used the framework defaults".
- Colored card borders to assert structure — borders are not the right tool for hierarchy.
- Emoji icons in production UI — accessibility hostile; locale-fragile; reads as draft.

**Side B — overkill compensation (slop's louder cousin):**

- Sprites on every empty pixel — decoration substituting for missing information density.
- Gradient on every section background — every section "important" means none are.
- Animation on every element entrance — motion budget is a budget; spend it once.
- Multi-paradigm mash (neo-brutalism shadow on a glass card on a Material 3 button) — paradigm conflict reads as confusion, not eclecticism.
- Decorative noise compensating for a thin idea — when the surface earns its weight, restraint amplifies it.

**Color strategy axis (commitment level).** Pick the strategy before picking colors. Each tier is deliberate, not a fallback.

- **Restrained** — tinted neutrals plus one accent at ≤10% surface coverage. Product default.
- **Committed** — one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
- **Full palette** — 3-4 named roles, each used deliberately. Brand campaigns; product data viz.
- **Drenched** — the surface IS the color. Brand heroes, campaign pages.

The "one accent ≤10%" cap applies only to **Restrained**. Committed / Full palette / Drenched exceed it on purpose; treat the cap as direction-conditional, not universal.

## Direction-first workflow

Six steps. Do not skip the divergence step.

1. **Frame the surface.** Capture: surface (landing / dashboard / settings / docs / one-screen tool), primary user, density target, motion budget in ms. **Then write one sentence of physical scene** (who, where, ambient light, mood) that FORCES the dark/light decision. Category names alone do not force the answer — "observability dashboard" fails; "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" succeeds. Pin *why* this design must feel a certain way before deciding *how*. Surface answers before generating directions; designing on assumed callers wastes the parallel budget.

2. **Diverge: 3-4 directions in parallel via Verbalized Sampling.** Dispatch one Explore agent per direction with a constraint that *forces* contrast (post-minimalism vs neo-brutalism vs Material 3 vs Fluent, or named taste anchors that pull in opposite directions). Reject converged outputs; re-dispatch with sharpened constraints if two directions read alike. See `references/diversity.md` for the six diversity-engineering techniques (verbalized sampling, actor-critic per candidate, persona injection, temperature, most-unlikely reframing, anti-pattern catalog).

3. **Per direction, return a fixed shape.** Each direction states: name (one or two words), 1-2 taste anchors (Linear / Stripe / Things 3 / Rosé Pine / Are.na — name the references), OKLCH palette stub (4-6 swatches, never the default Tailwind ramp), type pair (display + text, named families), spacing scale subset committed (e.g., 4/8/16/24/48), motion budget in ms with one easing curve.

4. **Pick via per-axis single-select.** Each axis (direction, density, motion budget, type pair) is its own single-select question; the recommended option carries `(Recommended)` and is placed first. Ticking `(Recommended)` *is* accepting the default. Never use `multiSelect` for axis-with-default override semantics — that shape collapses N independent decisions into one ambiguous checklist; reserve `multiSelect` for additive picks only (feature toggles, optional sub-tasks).

5. **Derive DTCG-shaped tokens from the picked direction.** Color, type, space, radius, shadow, motion — each a token, each referenced not hardcoded. Tokens precede component code; component code references tokens.

6. **Route to the surface reference.** Pick the row in §6 that matches the runtime; load that reference for surface-specific patterns and pitfalls.

## Surface routing

| Runtime | Reference |
|---|---|
| Vanilla CSS / static HTML | `references/web.md` |
| React / Tailwind / shadcn | `references/react.md` |
| Bubble Tea / Ratatui / Textual | `references/tui.md` |
| clap / cobra / cmdliner / typer | `references/cli.md` |
| Tauri / Slint / egui / Iced | `references/desktop.md` |
| Qt / QML | `references/qt.md` |
| Cross-platform tokens | `references/design-systems.md` |
| Motion across runtimes (timing / easing / reduced motion) | `references/motion.md` |

## Cross-runtime references

These references are runtime-agnostic — load them when the task fits the trigger, alongside whatever surface reference is already loaded.

| Reference | Load when… |
|-----------|------------|
| `references/interaction-design.md` | Designing or auditing interactive elements (states, focus rings, dropdowns, modals, popovers, keyboard navigation) — applies across web / React / desktop / Qt. |
| `references/cognitive-load.md` | Auditing a surface for mental-effort overhead (working-memory rule, the eight common violations, the cognitive-load checklist). |
| `references/personas.md` | Running a persona-based design audit (Alex / Jordan / Sam / Riley / Casey, plus project-specific personas derived from PRD / brand brief). |
| `references/ux-writing.md` | Drafting UI labels, error messages, empty states, confirmation dialogs, and any user-facing copy — copy is design. |
| `references/diversity.md` | Generating diverse direction candidates in step 2 (Diverge) of the workflow — six techniques to defeat centroid convergence. |
| `references/cjk.md` | Designing for Chinese / Japanese / Korean content — locale tagging, Pan-CJK fonts, vertical writing / ruby, locale-specific glyphs. Routes into `korean.md` / `japanese.md` / `chinese.md` for per-locale production trends and DS landscape. |

## Cross-surface invariants

- **Color as input, never as default.** Custom OKLCH palette derived from the picked direction; never the default Tailwind, Material, or Bootstrap ramp.
- **Spacing scale is 4/8/12/16/24/32/48/64.** Pick a subset that matches density target; commit and stick. A new value mid-build is a smell.
- **At most two type families.** Display plus text. A third family is a smell unless the direction explicitly demands it (e.g., a mono accent for code).
- **Motion is budgeted in milliseconds.** One easing curve per surface. `transition: all` is forbidden — name the properties (`transition: opacity 120ms ease, transform 120ms ease`) so layout and paint do not animate together.
- **Semantic structure precedes class names.** `<nav>` / `<main>` / `<article>` first; utility classes second. Class soup over weak structure is slop.
- **Contrast: WCAG 2.1 AA is the legal floor.** APCA is a *design-input* tool only — it was REMOVED from WCAG 3 in July 2023 and never reinstated. Do not claim "WCAG 3 compliant via APCA"; that compliance does not exist. Verify AA with axe-core or the browser DevTools accessibility panel.

## Verification gate

1. ODIN design gate ≥95% per the `<design>` block above (tokens / density / paradigm / forbidden list).
2. Anti-slop checklist (§4 Side A AND Side B) returns zero violations.
3. Direction artifact recorded in commit body or PR description: name plus taste anchors plus one-line rationale.
4. Tokens referenced not hardcoded — `git grep` for raw hex, raw px values in component code; should be empty.
5. Cross-surface invariants honored — spacing subset committed, ≤2 type families, motion named-properties only.
6. Contrast verified via axe-core CLI or DevTools accessibility panel; WCAG 2.1 AA pass on every text surface.
7. Audit tools — data-dense surfaces pass the `references/cognitive-load.md` checklist (≤1 failure); shipped surfaces have been read against ≥2 of the `references/personas.md` archetypes.

## Anti-patterns

- "Be creative" / temperature-up — generates more slop, not better direction. VS structure or nothing.
- Single-shot palette generation — RLHF over-aligns to purple; the model's first guess is the slop.
- Skipping the direction commit and jumping to component code — components without a direction are coupling without contract.
- Mixing two paradigms on one surface — neo-brutalism shadow on a glass card reads as confusion.
- Ranking directions by implementation effort — short-term cost is the wrong axis; taste fit and depth are the right ones.