/ui-design

name: ui-design
description: 'Use when directing, building, or auditing React/Next.js Tailwind UI: visual direction, responsive/dark-mode retrofits, UX audits. Not for typography or motion: use typography-audit or ui-animation.'
disable-model-invocation: true

UI design

Contract

| Field | Bound contract | |---|---| | Trigger | visual direction, Tailwind build, screenshot to markup, dark mode, responsive, UX audit, design QA, deslop UI | | Authority | Reversible local: writes only files under the project directory; rollback is version control. No credential, paid, published, deployed, or remote mutation. | | Side effect | Builds, audits, or provides direction for React/Next.js UI; may edit files | | Done | UI has a track, is built or audited with ship-readiness, and has no AI slop |

Inputs

• Required: a UI target (either an existing built frontend to audit, or a request to build or direct a new surface) plus the project's existing framework, component patterns, and design tokens.
• Optional: reference screenshot, Figma export, mockup, or wireframe for scaffold mode; a screen recording for motion-adjacent checks; existing brand direction or design system.
• Blocked: requests targeting non-local, credential-protected, or deployed resources; non-UI code review; deep typography or motion passes; copywriting-only tasks.

Procedure

1. **Resolve the mode.** Pick exactly one before acting:

• Direction: the user asks for visual direction, palettes, fonts, tokens, a brand kit, or "pick a style"; deliverable is a spec, not code.
• Build: the target does not exist yet: "build a landing page", "create a dashboard", "add a pricing section".
• Audit: the target exists and no change was named: "audit this component", "is this accessible", "design QA this page", "is this ready to ship". Deslop scope activates on "remove AI slop", "looks vibe coded", "simplify this UI".
• Options: variants to compare: "show me 3 hero layouts".
• Scaffold: semantic, unstyled markup from a screenshot, Figma export, mockup, or wireframe.
• Retrofit: one dimension added to existing UI: "add dark mode", "make this responsive", "fix this on mobile".
• Componentize: extracting components or cleaning up classes: "componentize this page", "clean up the Tailwind".
• If no mode is named: Build if the target does not exist. Audit if it does and no change was requested. Resolving "look at this page" to Build silently skips the audit, which is the most expensive mistake this step prevents.

**Done when:** exactly one mode is selected by the stated discriminator.

2. **Direction mode: choose the visual system.** Write no markup; the build is Build mode's job. Output a decision set: a one-sentence visual thesis (mood, material, energy), palette as CSS variables, type pairing and scale, spacing grid, radius and depth strategy, the layout pattern for the primary surface, and for conversion pages the section sequence, CTA plan, and proof placement. Pick a track:

• **Product track** for dashboards, admin panels, data tables, settings, internal and dev tools; optimise for information density, calm chrome, scanability, and utility copy.
• **Marketing track** for landing pages, brand sites, promotional pages, portfolios, pricing pages; optimise for visual impact, storytelling, and a one-CTA conversion flow.
• Tie-break: a marketing site for a SaaS product is the marketing track; the app behind the login is product. A surface that converts a stranger is marketing; one that lets an operator work is product.
• Close against the Quality Bar (step 6), then hand off to Build.

**Done when:** one visual track and its decision set are complete.

3. **Build mode: implement one design in code.** Use restraint: build the smallest thing that serves the product, not the most impressive thing that fits.

• Inspect the request, target files, existing design conventions, and available components.
• Implement using the project's existing framework, component patterns, assets, and conventions.
• Use project tokens for sizes, gaps, radii, weights, colours, and elevation. No default Tailwind indigo or gray as a palette; no stock SaaS gradients.
• Build interactive states for hover, focus, pressed, disabled, loading, empty, and error where applicable. Controls preserve stable dimensions when labels, counts, or loading text change.
• Preserve user constraints unless a design conflict requires asking.
• Verify (step 7).

**Done when:** the design is implemented in existing project conventions and ready for verification.

4. **Audit mode: find user-facing defects and fix the ones in scope.** Unlike Build, default to flagging; approval is earned.

• Scope: diff-aware by default (`git diff --name-only <base-branch> --` against the base branch for UI files, or the named files). A full sweep needs an explicit request.
• Detect features in scope and run per-feature checks in order.
• Confirm each finding at its file:line. Never present a finding without evidence; with no evidence the result is `unknown` with a reason, never a fail.
• Tier each finding: reserve `release-blocker` for data loss, broken critical paths, and dark patterns. No slop rule is ever a release-blocker.
• Apply fixes that stay inside the audited files, unless the request was report-only. After each fix, re-run the rule that produced it; a fix that does not clear its own finding is reverted and reported as `remaining`. A fix that would change a shared component outside scope is emitted as a finding with a proposed diff, not applied.
• Report-only when the user asked a question, not for a change: "is this ready to ship", "is this accessible", "design QA this page" ask for a verdict. Apply when the wording asks for one ("fix", "clean up", "remove the slop"), or when the user confirms after a report.
• Report what was rejected. Name 2-5 things looked at and deliberately not flagged, each with the guard that