/design

How it routes

Not a fixed pipeline — a router. Enter at whatever job you have: "set a visual direction for this landing page" pulls direction plus its craft leaves; "critique this dashboard" jumps straight to the critique gate; "map this checkout" runs one journey. Every route selects the smallest sufficient reference set — one primary job, at most one surface overlay, only the concerns that matter — and nothing unrelated is loaded.

The skill operates standalone — invoked alone it runs the full loop; given compatible upstream artifacts it builds on them without silently overriding established decisions.

Register first

Before any craft, the skill names the register — per surface, not per project. It's the single decision that sets the bar for everything after, and the audience picks it, not taste. Get it wrong and a dashboard tries to be memorable, or a landing page settles for competent.

One bold move, then restraint. The shared trait of Linear, Stripe, and Vercel is restraint, not a look — spend boldness in one place per section and keep everything else quiet. Two bold moves compete; zero reads generic.

Before the pixels

Most of the work lands before a single pixel is styled. The upstream jobs — research, journeys, and information architecture — decide what's true, what path a person takes, and where everything lives. Skip them and you get a pretty screen answering the wrong question.

Place  Budget overview
  Add expense → Expense sheet
  [ remaining · this month ]
Place  Expense sheet
  Save → Overview
  edges empty · loading · error · offline

Home
├ Budgets    list + detail
├ Expenses   list + detail
└ Settings
objects  Budget ─< Expense
nav ≤7 · any item < 3 clicks

The craft, in exact values

When direction is set, the craft leaves carry it — each with precise tokens, not adjectives. Typography, color, layout, motion, interaction states, and depth are separate references the router loads only when the job needs them. A sample of what each one decides:

The non-negotiable laws

These universal invariants govern every reference — the load-bearing ones, condensed.

• Register firstName the register per surface before craft — design IS the product (brand, marketing) vs design SERVES it (dashboards, app shells). The audience picks the aesthetic, not taste; the serve register legitimately inverts several distinctiveness defaults.
• Design the full state setDefault, hover, focus, active, disabled, loading, error, success — plus empty for every data region. Missing states are the usual gap between a mock and a real product.
• One bold move, then restraintSpend one bold move per section or page and keep everything else quiet. Two bold moves compete; zero reads generic.
• Real content, real lengthsUse the longest realistic string, the empty case, the overflow case. Never fabricate metrics, logos, testimonials, or decorative data.
• Label the maturityEvery coded artifact is disposable, design-reference, or production-candidate. Never present prototype code as production-ready without engineering, accessibility, and quality review.
• Accessibility floors are constraintsContrast, target size, focus order, and reduced-motion hold even when the accessibility reference is never opened.
• A visual verdict needs rendered evidenceWhen no build was viewed, the skill states "code-level pass, not an art review" rather than signing off on appearance — and it preserves established product, brand, and architecture constraints, reporting any conflict rather than silently overriding it.

Pick by job

The SKILL.md is a router — load only the reference your current job needs. A condensed cut of the primary-job table:

Full table — plus the surface and concern overlays: SKILL.md.

The critique gate

Critique is its own route — a scored review, not a vibe check, kept strictly separate from fixing. The bar isn't "does the grid align" but "would a design lead at Linear or Apple put their name on this?" It judges against the design's own intent, then returns a binary verdict and a Before/After/Why punch-list — never a patch.

Reference map

21 references, grouped by facet — primary jobs, surface overlays, and concern overlays. Every one is copy-pasteable rather than abstract; the whole point of the router is that you never read all of them at once.

primary · research & structure4

research.mdjourneys.mdinformation-architecture.mdinteraction.md

primary · visual craft6

visual-direction.mdtypography.mdlayout-composition.mdcolor.mdimagery-depth-decoration.mdmotion.md

primary · systems & delivery4

prototyping.mddesign-systems.mdcritique.mdhandoff.md

surface overlays4

surface-website.mdsurface-webapp.mdsurface-ios.mdsurface-android.md

concern overlays2

accessibility.mdcontent.md

sources1

SOURCES.md— traces every technique to its source

Browse the full set: skills/design/references/.

The handoff

The skill owns experience intent, not production code — so a route that expects downstream work ends in a handoff: a package an engineer who was never in the room can build from. It ships tokens twice (a structured JSON block for tooling and a human design map), a motion plan with exact curves and durations, and a compact handoff.yaml companion for pipeline routing.

The package targets at least Level 4 on a 1–5 maturity ladder (screenshot → annotated → interactive spec → full spec → integrated). When cutting scope, it never cuts error states or accessibility.

Start here

Install once. It's a plain SKILL.md router — no flags, no config, no scripts — so it activates on design language ("design an onboarding flow", "set a visual direction for this app", "critique this dashboard", "spec the states for this form") rather than a fixed command.

The same install runs on any Agent Skills host. Codex installs to ${CODEX_HOME:-$HOME/.codex}/skills; agents remains a separate cross-agent installation target.