Choose a visual direction

Design Intel

The decision layer above polish. ux-scan finds what's broken, polish-pass sands what exists; this skill decides what the thing should look like and why, before (or beneath) either. Given a surface to design, it commits to one named visual direction and cashes it out as concrete tokens: palette, type pairing, spacing scale, layout system, component choices, chart treatment. The output is a spec a builder (human or agent) can implement without making a single taste call of their own.

Core Insight: Generic defaults are how AI-built UIs all look the same: blue-500, Inter, a card grid, done. Taste starts with a commitment: name one direction and let every token derive from it, so the surface is coherent instead of assembled. The direction is sticky. Pass 1 chooses it, every later pass refines within it (deeper hierarchy, better contrast, tighter states), never flips it. And premium is mostly subtraction: one accent color, two typefaces, neutrals doing 90% of the work, restraint at Stripe/Linear level. A bold direction executed with discipline beats a tasteful mood board every time.

Preconditions / guards

1. A surface to design. A new page/screen/app/component family. This skill designs forward. Cleaning up an existing mess is ux-scan + polish-pass work.
2. Stack identified. Default target is Next.js + React + Tailwind + shadcn/ui (emit Tailwind tokens + shadcn component picks); Expo/RN gets StyleSheet/NativeWind equivalents. Read the repo before assuming.
3. Existing design language wins. If the project already has a committed direction (tokens, a prior .design/DIRECTION.md, an established brand), new surfaces extend it. Proposing a fresh direction for one page of a styled app is a coherence bug, not creativity.
4. Greenfield direction = taste call. A brand-new product's direction is the user's to approve: present the pick + runner-up (decision inbox or direct), don't auto-bank it. Extending an established language is auto.

The Pipeline (staged: issue each phase only when the prior finishes)

Phase 0: Ground

Read the project: what the surface is for, who uses it, in what mood (a monitoring dashboard at 2am is not a marketing page). Inventory the existing design language: tokens, tailwind config, globals.css, installed shadcn components, any prior .design/ artifacts. Detect the stack. Note what data the surface shows (tables? time series? money?); that decides the chart layer.

Phase 1: Direction

Choose a named direction from the starter library (references/LIBRARY.md) or compose one. Never "clean and modern." Shortlist 2–3 candidates that fit the surface's job and audience, reason each through (what it signals, what it costs, how it ages), commit to one with rationale. Write <project>/.design/DIRECTION.md, the sticky contract every later pass and every sibling surface inherits. Greenfield → this is the user's approval gate (guard 4).

Phase 2: System (tokens)

Derive everything from the direction, concretely: - Palette: semantic CSS variables in shadcn convention (--background, --foreground, --primary, --muted, --destructive, ...), light + dark, actual OKLCH/hex values. One accent. Verify every fg/bg pair ≥ 4.5:1 (3:1 for large text). A palette that fails contrast is not a palette. - Typography: a named pairing (display + body, or one family two optical roles), a modular scale (give the actual px/rem steps), weights, line heights, where tabular-nums applies. - Layout: grid system (12-col, bento, sidebar+canvas), container widths, a spacing scale (stick to Tailwind's; name the rhythm: section/card/element gaps), radius scale, shadow/elevation policy, border-vs-shadow stance. - Motion: durations, easing, what animates and what never does.

Phase 3: Components + charts

Map the surface's needs to specific shadcn/ui components with variant and composition notes (which Card anatomy, which Table density, Dialog vs Sheet vs Drawer and why). If the shadcn MCP is available, search it for the components and pull real examples instead of guessing APIs. Where data viz exists: pick chart types per question-the-user-is-asking (LIBRARY.md has the mapping), default Recharts via shadcn charts, derive series colors from the palette, strip chartjunk (no 3D, no rainbow, gridlines whisper).

Phase 4: The spec

Write <project>/.design/specs/<surface>.md: direction recap → token blocks ready to paste (CSS variables / tailwind config) → per-region layout (annotated ASCII or structured description) → component manifest with states (hover, focus-visible, loading, empty, error: specified, not implied) → chart specs → an implementation order. The test: a builder with zero taste and this spec ships something coherent.

Phase 5: Build (Mode: build only)

When routed here to design and build (project-autopilot's "new UI surface" route), implement the spec under the green ratchet: tokens first, then layout shell, then components, checkpoint per slice. Then look at it: run the app, screenshot the surface, check it against the spec's intent. Spec mode stops at Phase 4 and hands off.

Re-run semantics (how deepen passes work)

This skill is re-runnable with progressive deepening; ux-maximizer's cascade runs it 3× via /deepen. The discipline:

• Pass 1: full pipeline: choose direction, build system, write spec.
• Pass k ≥ 2: read .design/DIRECTION.md + existing specs first. The direction is settled; go deeper within it: hierarchy sharpened, contrast pairs re-verified, state coverage completed, type scale tightened, spacing drift reconciled, chart treatments unified, dark mode parity, the places where the implementation quietly diverged from the spec.
• A pass may conclude the direction itself is wrong. That's a flag to the caller (or the user), never a silent re-roll. Saturation = a pass that only rephrases settled tokens.

Contract (what orchestrators can rely on)

• ux-maximizer / deepen: 3× design-intelligence passes (styles, palettes, type, layout) land here. Each pass is coherent and self-contained, refines rather than restarts (direction sticky), and its deltas are loggable to PASSLOG.md.
• project-autopilot: routes "New UI surface to design/build" here, auto, except greenfield direction choice, which goes to <project>/.autopilot/DECISIONS.md (recommended option first).
• Artifacts: <project>/.design/DIRECTION.md (one per product, sticky) · <project>/.design/specs/<surface>.md (one per surface). Both survive the run: they're the product's design memory, not scratch.
• Pairs with: ux-scan (finds problems) · polish-pass (elevates execution) · premium-palette-design, if installed (deep palette work when the palette IS the task; otherwise do it in Phase 2). design-intel owns the decide layer; those own find and finish.

THE EXACT PROMPT

/design-intel
Target:    <project path>
Surface:   <what to design, e.g. "admin analytics dashboard" | "marketing landing">
Mode:      spec | build   (default: spec)
Direction: <optional: force/keep a named direction; default: choose (sticky after pass 1)>

Anti-Patterns

• "Clean and modern": that's the absence of a direction. Name one or compose one; every token must trace back to it.
• Generic defaults: blue-500 primary, Inter-for-everything, uniform card grid, shadow-md on all the things. If the spec could describe any app, it describes no app.
• Re-rolling the direction on pass 2 because a different one seems fresher. Direction is sticky; flag it, don't flip it.
• A new direction for one page of an already-styled product. Extend the existing language (guard 3).
• Auto-banking a greenfield direction without the user's gut-check. Taste stays the user's.
• Mood-board specs: "elegant, airy, premium" with no hex values, no scale steps, no component names. If a builder still has to make taste calls, the spec isn't done.
• Shipping a palette that fails contrast because it "looks better". 4.5:1 is the floor; work the lightness until it passes.
• Three accents, four typefaces, five radii. Premium is subtraction.
• Decorating charts (3D, rainbow series, heavy gridlines) instead of choosing the chart that answers the user's actual question.
• Specifying only the happy path. Hover, focus-visible, loading, empty, and error states are part of the design, not the implementer's problem.
• Guessing shadcn component APIs when the shadcn MCP is sitting right there.

References

• LIBRARY.md: the starter library: named directions with palettes + type pairings + layout systems, the chart-selection map, and token emission templates (Tailwind/shadcn + Expo/RN)