Frontend Mockup Loop

frontend-mockup-loop

A disciplined loop for designing frontend surfaces. It exists to defeat distributional convergence: an undirected agent regresses to the statistical mean of its training data — generic Inter font, a purple gradient, a centered hero. "Make it look better" just returns the average again.

The fix the whole agentic-design field converged on, and what this loop enforces every time:

1. deliberate direction from a real reference (GROUND),
2. a consistent token system (the ui-contract),
3. a screenshot feedback loop (eyes on output).

This skill is paired with an extension that registers five tools: serve_mockup, score_mockup, init_ui_contract, list_design_systems, validate_mockup.

Select a design system (optional)

The loop runs design-system agnostic by default (generic anti-slop rubric). To target a specific system, pick a preset and pass its id to the tools' system param. v1 presets (list_design_systems enumerates them):

With a system selected: init_ui_contract{system} writes that system's DTCG token contract (from a bundled, offline snapshot; refresh:true re-fetches upstream), score_mockup{system} swaps in the system's boolean rubric, and validate_mockup{system,dir} runs the gated pipeline.

Gate vs advisory

Validation is layered. Gates block pass; advisory layers only score and drive the fix loop (LLM visual scores skew positive — never hard-block):

• L1 token-lint — static; HARD GATE when a linter applies (off-token color literals fail shadcn/material-3).
• L2 a11y floor — rendered axe + WCAG contrast; HARD GATE, every system.
• L3 named-system auditor — hig-doctor / material3-mcp etc., advisory, shelled out only if installed (absent → skipped + noted, never errors).
• L4 vision rubric — per-preset boolean checks; score = pass/N computed in code, advisory.

validate_mockup returns { gates, advisory, pass }; pass is gate-only.

Apple HIG in a browser-first loop

Apple publishes no token JSON, so apple-hig ships a hand-authored rule pack (presets-data/apple-hig/rules.md). Render an HTML approximation of the iOS screen so serve_mockup can serve it and hig-doctor (if installed) can audit it — no SwiftUI/Xcode required in-loop:

• SF Pro stack: font-family: -apple-system, "SF Pro Text", system-ui.
• 44×44pt minimum tap targets; 8pt spacing grid.
• Safe areas: padding: env(safe-area-inset-top) … env(safe-area-inset-bottom).
• Bottom tab bar, ≤5 items; iOS semantic colors (label, systemBackground, systemBlue), no hardcoded brand hex on system chrome.

On PROMOTE, optionally emit real SwiftUI — validated on source by hig-doctor / orchard-hig (no live browser preview; real-device fidelity needs macOS/Xcode). SwiftUI is never required for the in-loop preview.

Act as an expert UX designer

Rule: ground every UX decision in an externally documented, public-facing design rule — never invent one. When you make a call, you must be able to name the rule and cite its public source. "I think it looks better" is not a reason; "Hick's Law — reduce the choices here (lawsofux.com/hicks-law)" is.

The full citable rule corpus lives in references/ux-best-practices.md: Nielsen's 10 heuristics, Laws of UX, Gestalt, cognitive load, per-component pattern rules, the 5-step expert evaluation protocol, and a 22-item checkable rubric seed. Read it before designing or reviewing.

Source order (adapt, don't copy): the selected design system's documented guidance first → then the universal sources, in licensing-safe order (USWDS is CC0; GOV.UK is OGL; NN/g + Laws of UX cite-with-attribution; Material/Carbon are Apache-2.0). Adapt the principle to this product; never copy proprietary assets/text (Apple HIG, Refactoring UI, Mobbin).

Anti-slop companion (advisory). For the AI-tell layer — the countable signatures an undirected model defaults to (AI-purple, Inter-everywhere, em-dashes, div-based fake screenshots, eyebrow-per-section, Jane Doe / Acme data) — pull the anti-slop-frontend skill (@blackbelt-technology/anti-slop-frontend). It is advisory only: its tells feed the FIX step's defect list (step 5), but they NEVER override this loop's hard gates. When an anti-slop tell conflicts with a cited public rule or the WCAG-AA / severity-4 floor, the cited rule and the gate win. Apply its Part A (universal) to any surface; skip its Part B (marketing-only) for product UI.

When to Use

Designing or refining any frontend surface — new screens, redesigns, or a consistency pass across existing screens. Skip for trivial one-class tweaks. Not for backend/protocol work.

Procedure

1. GROUND — adapt what ships + what's documented, don't invent

Two grounds, both external:

• The real UI — open the running app and READ the authoritative component source. Capture the EXACT tokens already in use: class names, CSS custom properties (--background, --primary, --radius), spacing, dark + light.
• The documented rules — open references/ux-best-practices.md and the selected design system's public guidance. Identify the specific patterns and laws that govern this surface (e.g. a form → NN/g web-form-design + GOV.UK error-summary; a nav → Hick's Law + hamburger-menu guidance).

Designing without either ground produces a parallel style that looks "off" and a UX that violates well-known rules — the opposite of adapting documented design.

2. CONTRACT — the consistency control plane

Read or scaffold ui-contract.md (run init_ui_contract). It is the single source of truth for cross-screen properties: color ramps, spacing scale, type scale, radius, elevation, motion, component invariants. Every value references a design token — never a raw hex or px literal. If a surface needs a token that doesn't exist, add it to the theme layer first, then cite it in the contract. This file is what stops screens from drifting apart.