git:20260710.c27f42a to git:20260711.1e33409

18 added, 88 removed. Audit A to A.

---

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.

+ description: Use only after explicit Codex `$superloopy:superloopy-frontend` or Claude Code `/superloopy:superloopy-frontend` invocation for a web frontend or Qt desktop GUI task, such a task started with a leading `loopy` or `루피`, or an active Superloopy loop explicitly routing a web frontend, Qt Widgets, Qt Quick/QML, or mixed web/Qt subtask here. Do not activate from UI, frontend, Qt, QML, Widgets, or other semantic vocabulary alone, or for non-web/non-Qt visual deliverables.

---

# 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:

+ **Explicit activation only.** Engage when the user invokes `$superloopy:superloopy-frontend` in Codex or `/superloopy:superloopy-frontend` in Claude Code for a web frontend or Qt desktop GUI task, begins such a task with a leading `loopy` or `루피`, or an already-active Superloopy loop explicitly assigns a web frontend, Qt Widgets, Qt Quick/QML, or mixed web/Qt subtask to this skill. A plain mention of UI, frontend, CSS, layout, responsiveness, Qt, QML, Widgets, or a visible symptom is not authorization to activate this workflow. Non-web/non-Qt visual deliverables and backend, API, data, concurrency, or infrastructure work stay with their primary workflows.

- 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.

+ ## Inspect and route

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

+ Resolve the requested surface, existing stack, target platform, existing styling or tokens, and available validation. For a Qt route, also resolve the minimum Qt version. Ask one question only when a material ambiguity would change the route or result. Load the smallest route-specific set:

- ## Phase 4 — Measured quality gate

+ | Requested surface | Load |

+ | --- | --- |

+ | web UI | [`references/web.md`](references/web.md) |

+ | Qt Widgets | [`references/qt.md`](references/qt.md), [`references/qt-widgets.md`](references/qt-widgets.md), and [`references/qt-qa.md`](references/qt-qa.md) |

+ | Qt Quick/QML | [`references/qt.md`](references/qt.md), [`references/qt-quick.md`](references/qt-quick.md), and [`references/qt-qa.md`](references/qt-qa.md) |

+ | mixed Qt Widgets and Qt Quick/QML | [`references/qt.md`](references/qt.md), [`references/qt-widgets.md`](references/qt-widgets.md), [`references/qt-quick.md`](references/qt-quick.md), and [`references/qt-qa.md`](references/qt-qa.md) |

+ | mixed web UI and Qt | [`references/web.md`](references/web.md) plus [`references/qt.md`](references/qt.md), the relevant one or both of [`references/qt-widgets.md`](references/qt-widgets.md) and [`references/qt-quick.md`](references/qt-quick.md), and [`references/qt-qa.md`](references/qt-qa.md) |

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

+ For a mixed web/Qt task, apply gates and evidence independently for each surface. Web proof cannot substitute for Qt proof, and Qt proof cannot substitute for web proof.

- - **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).

+ ## Shared design gate

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

+ `DESIGN.md` owns app-defined semantics. Preserve the project's architecture and existing styling infrastructure. Before using an app-defined color, typography, spacing, radius, depth, motion, or component value that the design contract lacks, add its token to `DESIGN.md`. Platform runtime values remain authoritative when native.

- ## Evidence contract

+ ## Build, dispatch, and evidence

- - 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>"`.

+ Preserve the existing stack. For parallel work, dispatch self-contained crew slices with the relevant requirements and tokens inline, then judge each lane by delivered evidence. Capture real rendered-surface evidence and write `VISUAL_QA.md` under `.superloopy/evidence/frontend/`. Finish with a `SUPERLOOPY_EVIDENCE` artifact and record the final evidence through the active Superloopy loop.

- ## Completion checklist

+ ## Completion

- - 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.

+ Apply only the selected platform checklist. The design contract, interaction states, real rendered-surface evidence, and no weakened UX are mandatory for every route.