@blackbelt-technology/frontend-mockup-loop

A pi package — extension + skill — for a disciplined frontend design loop:

GROUND → CONTRACT → MOCKUP → TEST → FIX → PROMOTE → LEARN

It exists to defeat distributional convergence: an undirected agent regresses to the statistical mean (generic Inter font, purple gradient, centered hero). The fix — deliberate direction, a consistent token system, and a screenshot feedback loop — is what this loop enforces.

Generic: works in any React/Tailwind/shadcn (or plain HTML) project.

Install

pi install npm:@blackbelt-technology/frontend-mockup-loop
# or try without installing:
pi -e npm:@blackbelt-technology/frontend-mockup-loop

This registers:

• Skill frontend-mockup-loop — the 7-step workflow (load via /skill:frontend-mockup-loop).
• Tools the agent can call:

  Tool	Purpose
  serve_mockup	Serve a mockup dir over HTTP on 0.0.0.0; returns clickable local + LAN URLs (LAN works on a phone). Zero deps.
  score_mockup	Capture full-page screenshots at mobile/tablet/desktop widths via Playwright; returns paths + a scoring rubric. With system, uses that preset's boolean rubric.
  init_ui_contract	Scaffold a token-referencing ui-contract.md consistency control plane. With system, write that preset's DTCG token contract.
  list_design_systems	Enumerate the selectable design-system presets.
  validate_mockup	Run the layered validation pipeline for a system (L1+L2 gates, L3+L4 advisory); returns { gates, advisory, pass }.

• Command /mockup-loop — print the loop and point at the skill.

Selectable design systems

The loop runs design-system agnostic by default. Pass --system <id> (the tools' system param) to target a specific system. v1 presets:

id	system	platform	substrate
shadcn	shadcn/ui + Tailwind	web	HTML + Tailwind
mui	Material UI	web	HTML
material-3	Material Design 3	web	HTML
fluent-2	Fluent 2	web	HTML
apple-hig	Apple HIG	iOS	HTML approximation → SwiftUI on promote

• init_ui_contract{system:"shadcn"} writes the shadcn DTCG contract from a bundled offline snapshot (presets-data/<id>/); no system still writes the generic blank template (back-compat).
• validate_mockup{system,dir} gates on L1 (token-lint) + L2 (axe + WCAG contrast) and scores on L3 (named-system auditor) + L4 (boolean rubric).
• Apple HIG ships a hand-authored rule pack (presets-data/apple-hig/rules.md); rendered as an HTML approximation in-loop, SwiftUI emitted only on PROMOTE.

Dependency posture

• Bundled (hard deps): @axe-core/playwright + eslint-plugin-tailwindcss (shadcn L1). WCAG contrast math is inline (no extra dep).
• Optional (shelled out only if installed, else skipped + noted): hig-doctor, material3-mcp, MUI/Fluent eslint plugins, lumo.
• score_mockup uses Playwright if present — enable breakpoint capture with npm i -D playwright && npx playwright install chromium; without it, score_mockup returns the rubric plus manual-capture guidance.

Refreshing snapshots

Bundled token snapshots (presets-data/<id>/contract.tokens.json) are versioned with the package and lag upstream. init_ui_contract{system,refresh:true} re-fetches the upstream source before writing. Upstream sources per preset:

preset	upstream source
shadcn	shadcn CSS variables (default theme) → DTCG
mui	@mui/material createTheme() defaults → DTCG
material-3	Material 3 --md-sys-* baseline tokens → DTCG
fluent-2	@fluentui/tokens webLightTheme → DTCG
apple-hig	hand-authored rule pack (no upstream token JSON)

Expert UX designer mode

The skill acts as an expert UX designer: every decision is grounded in an externally documented, public-facing design rule (Nielsen's 10 heuristics, Laws of UX, Gestalt, WCAG 2.2, GOV.UK/USWDS/Material patterns) — never invented. The full citable rule corpus is bundled at references/ux-best-practices.md: the source hierarchy (licensing-safe), universal laws, per-component pattern rules, the 5-step expert evaluation protocol, and a 22-item checkable rubric seed used by score_mockup / validate_mockup.

The design contract

ui-contract.md is the single source of truth for cross-screen consistency: color ramps, spacing/type scales, radius, elevation, motion, component invariants — every value references a design token, never a raw hex/px. init_ui_contract scaffolds it; you fill it from the real tokens captured in the GROUND step.

License

MIT