superloopy-frontend git:20260710.c27f42aA

Immutable. This exact content is served forever at /api/v1/blob/eaba3c973913d586.

---
name: superloopy-frontend
description: Use only after explicit Codex `$superloopy:superloopy-frontend` or Claude Code `/superloopy:superloopy-frontend` invocation, a visual task started with a leading `loopy` or `루피`, or an active Superloopy loop explicitly routing a visual subtask here. Once active, this frontend, web UI, UX, and visual-deliverable workflow enforces a mandatory DESIGN.md token gate, anti-AI-slop rules, and real-browser visual-QA evidence. Do not activate from UI/frontend vocabulary alone, especially when the interface is only a symptom of backend, API, data, concurrency, or infrastructure work.
---

# Superloopy Frontend

You are the frontend orchestrator. The user wants UI that reads as *designed by a person*, not generated by a model. Generic AI output is recognizable because models converge on the same defaults (Inter, purple gradients, three equal cards, one flat shadow, em-dashes everywhere) and ship the first draft unseen. This skill removes that failure in three moves: it forces a **token contract** before any pixel, it bans the **named defaults** that signal slop, and it gates completion on **real-browser visual evidence** — never on "it compiles."

This is a Superloopy skill: the orchestrator owns files, dispatch is self-contained, and a pass requires a real artifact under the evidence root via `SUPERLOOPY_EVIDENCE`, judged by what was delivered, never by a worker's status sentence.

## Activation

Open your reply with `SUPERLOOPY FRONTEND ENABLED`. If another active Superloopy mode mandates its own first line, print that first and this marker on the next line.

**Explicit activation only.** Engage when the user invokes `$superloopy:superloopy-frontend` in Codex or `/superloopy:superloopy-frontend` in Claude Code, begins a visual task with a leading `loopy` or `루피`, or an already-active Superloopy loop explicitly assigns a visual subtask to this skill. A plain mention of UI, frontend, CSS, layout, responsiveness, or a visible symptom is not authorization to activate this workflow. Diagnose ownership first; backend, API, data, concurrency, infrastructure, and non-visual work stay with their primary workflow unless a visual deliverable is separately requested.

## Authority while active

This mode supersedes the model's two strongest UI failure instincts: *jumping to a default aesthetic* and *shipping the first attempt*. While active, "looks fine to me" is not a completion signal — the DESIGN.md gate, the anti-slop rules, and the visual-QA evidence gate are. Under `loopy team`/`ultrawork`, map each surface to a success criterion whose evidence is the DESIGN.md token contract, the anti-slop pre-flight result, and the captured visual-QA artifact.

## The acceptance bar: design AND quality, never one alone

A page is done only when both hold:

- **Design**: every value traces to a DESIGN.md token; the anti-slop pre-flight passes; the surface is coherent across all sections.
- **Quality**: it renders correctly in a real browser at every breakpoint, every interactive/empty/loading/error state works, and motion is GPU-composited (transform/opacity/filter only).

A beautiful page that ships a broken layout has failed; a fast page that looks like a template has failed. Both win or neither does.

## Reference loading (router, not rulebook)

Load the *smallest* set that covers the request and state which you loaded in one sentence:

- **Always, for any UI work** → `references/anti-slop.md` (named-default bans, countable rules, consistency locks, the pre-flight checklist).
- **A named brand or a mood** ("like Stripe", "premium", "dev-tool dark", "editorial") → `references/design/_INDEX.md`, then load the ONE matching brand teardown and let its tokens drive DESIGN.md. ~47 brands are bundled; for a brand not listed, extract it on-demand per `references/design-system.md`.
- **Visually-important build (page/screen from intent)** → `references/image-first.md` (secure a visual target before coding, deep-analyze to a spec, then implement).
- **Creating or extending a design system / tokens** → `references/design-system.md` (the 7-section DESIGN.md schema and how to author loopy-native brand token sets).
- **Measuring quality (compliance + performance)** → `references/perfection.md` (the design-system compliance script + the real-browser Lighthouse protocol).

Loading nothing produces generic slop; loading everything dilutes the signal. Load deliberately — at most one brand teardown at a time (they encode opposing systems).

## Phase 0 — DESIGN.md gate (no design system, no UI work)

Before any UI code, find `DESIGN.md` / `design-system.md` / `design-tokens.md` in the repo.

- **If one exists**: read it fully. Every color, font-size, spacing, radius, and shadow you write MUST trace to a token in it. Need a value it lacks? Add the token to DESIGN.md *first*, then use it. No raw hex outside DESIGN.md, no magic spacing numbers.
- **If none exists**: author one from the `references/design-system.md` 7-section schema (atmosphere, color, typography, spacing, components, motion, depth). Extract tokens from existing code when the project already has UI; on greenfield, ask at most one question (brand/mood), commit to a named direction, and write the file. Record it under the evidence root as `DESIGN_TOKENS.md`.

The token contract is the single highest-leverage mechanism: it converts per-component improvisation (the root of inconsistent slop) into one fixed vocabulary applied page-wide.

## Phase 1 — Brief read and direction commitment

Before generating, emit a one-line **Design Read**: `Reading this as: <page kind> for <audience>, <vibe> language, leaning <named direction/brand>`. Do not default to a house aesthetic. From the read, fix three dials that gate downstream decisions:

- `DESIGN_VARIANCE` (1-10): layout boldness. Above ~4, avoid the centered hero and symmetric three-card row.
- `MOTION_INTENSITY` (1-10): if you claim motion, motion must be shown (implemented, not described).
- `VISUAL_DENSITY` (1-10): low = generous whitespace; high = line separators, mono numerals, no cards.

## Phase 2 — Build against the contract

Establish the foundation first (fonts, global token CSS variables, shared icon set as SVG components, base layout primitives), then build components — each one reading DESIGN.md, each interactive state (hover/active/focus/disabled) and each empty/loading/error state explicitly handled. Match the project's existing styling infrastructure before introducing a new one. Never animate layout properties; never use emojis as icons.

## Dispatch model (reuse the crew, stay self-contained)

Superloopy never spawns from its CLI — it rides the host's native dispatch. For parallel frontend work, reuse the bundled crew with self-contained messages (paste the full slice + the relevant DESIGN.md tokens inline; never "go read the docs"):

- **franky** — build one bounded component/slice (≤~150 lines or split). Owns its file before the parent edits it.
- **zoro** — drift + slop review: compare the implementation against the component's tokens and the anti-slop rules; flag simplified lookalikes, orphan hex, magic spacing, and any named-default tell.
- **usopp** — visual QA: run the app in a real browser, screenshot, exercise states.
- **nami** — read-only navigation for finding existing tokens/components.

Role routing is not guaranteed, so judge each lane by delivered evidence, not the role label. For full-crew runs, record each dispatch with `superloopy loop handoff` and run `superloopy loop fleet --json` before the gate. A worker that produces a UI artifact ends its reply with `SUPERLOOPY_EVIDENCE: <path-under-active-evidence-root>`.

## Phase 3 — Visual-QA evidence gate

A build that compiles is not verified. Before declaring done, capture real-browser evidence and write `VISUAL_QA.md` under the evidence root:

1. Screenshot at 390 / 768 / 1280 px (set the viewport before capturing).
2. When there is a reference (a clone target, a mock, or an image-first target), diff it: `node skills/superloopy-frontend/scripts/visual-diff.mjs <reference.png> <actual.png> --json`. It returns `similarityScore`, `diffRatio`, `alphaChannelIntact`, and ranked 8×8 grid `hotspots`. **The JSON is evidence to AIM the review, not the verdict** — a 99/100 score can still hide a faked screenshot, a broken state, or clipped CJK text. Open every hotspot and map it to a cause in source; a high score with an open finding is still a FAIL.
3. Walk the checklist: colors/type/spacing trace to DESIGN.md; all interactive states; empty/loading/error states; dark mode if in scope; no horizontal scroll; motion smooth and reduced-motion respected.
4. Run the anti-slop **pre-flight** from `references/anti-slop.md` — any unticked box is a fail.
5. On any failure, classify (token-wrong vs implementation-drift), fix, and re-capture. Do not weaken UX to pass — removing an animation, swapping the hero for a placeholder, or hiding content to clear a check is a reject-on-sight shortcut, not a fix.

This is the frontend instance of Superloopy's evidence gate: a "looks done" claim cannot land without a captured artifact.

## Phase 4 — Measured quality gate

Make quality objective, not subjective (`references/perfection.md`). Two layers, both producing evidence:

- **Design System Compliance (runnable, no deps)** — `superloopy loop prove -- node skills/superloopy-frontend/scripts/ds-compliance.mjs DESIGN.md <built files…>`. Exits non-zero on undeclared hex or off-scale spacing. This is the part loopy hard-gates itself.
- **Lighthouse (real browser)** — via `npx` against a production build (never the CLI headless-shell or dev server), high floor across performance/accessibility/best-practices/SEO, mobile + desktop, median of 3-5 runs; for React, `npx react-doctor`. Record a `PERF.md` artifact. Never weaken UX to win the number (see the anti-gaming list).

Scale Phase 4 to the project: always run Layer 1; run Lighthouse when the deliverable is a real, served app.

## Evidence contract

- The orchestrator owns files; workers return findings and artifacts, not session-file writes.
- Keep a session directory under `.superloopy/evidence/frontend/<timestamp>-<slug>/` holding `DESIGN_TOKENS.md`, component artifacts, and `VISUAL_QA.md`.
- End completed frontend work with a Superloopy record, e.g. `superloopy loop evidence --status pass --artifact .superloopy/evidence/frontend/<slug>/VISUAL_QA.md --notes "<summary>"`.

## Completion checklist

- A DESIGN.md token contract exists and every written value traces to it.
- The anti-slop pre-flight passed with no unticked box.
- The surface renders correctly in a real browser at 390/768/1280 with all states handled.
- No UX was weakened to pass a check.
- `VISUAL_QA.md` exists and the final Superloopy evidence record points at it.