| name | designer-frontend-contract |
| description | The universal, tech-agnostic DESIGNER ↔ FRONTEND contract — how the web designer and the frontend dev help each other, where they store their shared data, how they communicate, and how the contract between them is written and ENFORCED. Three sides: the DESIGNER freezes an approved mockup into a canonical oracle (oracle-manifest.json + baseline renders + a region/element inventory + token parity + a four-part visual acceptance contract); the FRONTEND dev consumes that contract and PORTS the oracle 1:1 (transcribe, never redesign), self-gating census → DOM → pixel before handoff; the VERIFIER (design-diff) independently screenshots every built page × access state × breakpoint against the frozen baseline and reports per-page PASS/FAIL — report-only, a mismatch is a gate reject. Works on ANY stack (Phoenix/LiveView, Rails/Hotwire, React, …): stack facts (dev server, template language, settle signal, token source, seed accounts) are read at runtime from docs/project_config/info.md, never baked in. Use when: freezing an approved design for handoff; building a page from a frozen mockup; verifying a built page matches the approved design; establishing/refreshing a design baseline; deciding where design/frontend data lives or how the two roles hand off. Owned by the designer agent; on the architect's verify path; consumed by the frontend dev. |
TASKLANG
TYPE SKILL
IDENTITY "Designer ↔ Frontend Contract (universal — any stack)"
ONE skill = the WHOLE collaboration between the web designer and the frontend dev:
what each side PRODUCES for the other, where the shared data is STORED, how they
COMMUNICATE (paths + committed artifacts, never chat blobs), and how the CONTRACT
between them is written and mechanically ENFORCED. The designer freezes the approved
mockup into an ORACLE; the frontend PORTS it 1:1 and self-gates; the independent
design-diff VERIFIES the running UI against the oracle and feeds the pipeline's
verify gate. TECH-AGNOSTIC by construction: no framework, port, template language,
or product fact lives here — those are read from docs/project_config/info.md
({config.frontend_runtime} + {config.spec_path}) at runtime, per rule R14.
It exists because builds without this contract silently re-style, drop whole page
regions, and ship broken UI that a green HTTP-200 smoke never catches.
This SKILL.md is a MAP. Detail lives in workflows/ (the three role playbooks) +
references/ (atomized notes) + maps/ (machine-readable nav). Read this file +
maps/index.json to orient, then open ONLY the workflow/note a task needs.
The three sides (who runs what)
| Side | Role | Playbook | Runs when |
|---|
| PRODUCER | the designer agent (skill owner) | [[designer-handoff]] | An approved mockup must become a build target: freeze → manifest → inventory → token parity → acceptance contract. |
| CONSUMER | the frontend dev agent | [[frontend-port]] | Building a page from a frozen oracle: consume the contract → port 1:1 → self-gate census→DOM→pixel → report + KB write-back. |
| VERIFIER | the designer (owner) + the architect (verify-gate path) | [[design-diff]] | Independently verifying built pages against the oracle (pipeline verify gate, fan-out audit finder, or ad-hoc). |
Top Rules / Invariants (headlines — detail in references)
!!! The contract is COMMITTED ARTIFACTS, not conversation. Every handoff between the
designer and the frontend travels as committed files under docs/design/ (the
designer's library) and docs/frontend/ (the frontend's KB), referenced by PATH via
pipeline-state. If an obligation isn't written into an artifact, it doesn't exist.
→ [[contract-and-communication]].
!!! The oracle is docs/design/. ONE canonical frozen renderable mockup per page
(resolved via docs/design/oracle-manifest.json — never guessed), baseline renders
per pinned breakpoint, and the rule oracle (design-tokens + design-system.md).
Never diff or build against a guess or a re-derived design. → [[baseline-and-oracle]].
!!! PORT, don't redesign. The frontend OPENS the canonical oracle and transcribes its
markup verbatim into the project's template language (typically a near-superset of
HTML — apply only the mechanical escaping/attribute mapping the language requires,
e.g. JSX's class→className), injecting ONLY the stack's dynamic bindings.
Authoring a page fresh from memory is what drops whole regions. A change to the
rendered DOM/CSS is a contract violation even if it "looks the same".
→ [[frontend-port]].
!!! CENSUS FIRST — completeness before pixels. Before any pixel diff, both the
frontend self-gate and the verifier run the region/element COMPLETENESS CENSUS
against the designer's inventory: every region + interactive element PRESENT, in
order, none extra. A whole missing region is a Blocker; census needs NO pixel
baseline, so it runs even when no baseline exists. A page can never PASS on a green
pixel diff while its census is short. → [[region-census]].
!!! ONE token source — declared, never assumed. The mockup and the app render from the
SAME declared token source, whatever the project declares in
{config.frontend_runtime} (e.g. CSS custom properties in :root, a utility-framework
config, a CSS-in-JS theme), mirrored by docs/design/design-tokens. Never introduce a
SECOND styling source beside the declared one; never assume which kind it is — read the
declaration. Verify a token resolves identically before porting.
→ [[fidelity-checks]], [[contract-and-communication]].
!!! Every built page × every access state × every pinned breakpoint. The verification
matrix is pages × the project's access states (from {config.frontend_runtime} /
the design spec) × the pinned breakpoints (default 375/768/1024/1440; the per-feature
design spec's visual acceptance contract is authoritative). A page proven at one
width/state is not proven. Screenshot the RUNNING app, never a static file.
→ [[design-diff]].
!!! The verifier is REPORT-ONLY — findings are ROUTED. Design-diff never edits
application source (templates/views/components/stylesheets). Build drift + missing
regions route to the FRONTEND dev (fix by porting the oracle); a legitimate design
change routes to the DESIGNER (refresh the oracle + re-run the approval gate). A
mismatch or broken/obscured interaction is a gate reject, same weight as a functional
violation. → [[design-diff]], [[fidelity-checks]].
!!! No oracle? ESTABLISH one — never silently pass. When no frozen baseline exists
(design phase skipped / migration), capture or promote an ACKNOWLEDGED baseline
first, mark it ESTABLISHED-THIS-RUN, and diff against that. [NO-ORACLE] is a
blocking finding, not a free pass. → [[baseline-and-oracle]].
!!! Stack facts live in project config, product facts in the spec — NEVER here. Dev
server command/URL, per-PR preview scheme, template language + its dynamic-binding
whitelist, settle signal, token-source path, seed accounts, access states: read them
from docs/project_config/info.md ({config.frontend_runtime}). To reuse this skill
on another project/stack, swap that config — not this skill (R14).
Workflows
| Playbook | What it does | Run when |
|---|
| [[designer-handoff]] | PRODUCER: freeze the approved mockup (pin widths · self-host fonts · snapshot baseline renders) → register it as THE canonical oracle in oracle-manifest.json → emit the region/element inventory → declare token parity → write the four-part visual acceptance contract into the design spec → hand off PATHS. | After the design approval gate passes and the build needs a measurable target. |
| [[frontend-port]] | CONSUMER: read the six binding inputs from the spec + manifest → verify token parity → PASS A static 1:1 transcription → PASS B interactivity without DOM change → self-gate census→DOM→pixel per component AND per assembled page/state → report evidence + write back the docs/frontend/ KB. | Building/fixing a page that has a frozen oracle + acceptance contract. |
| [[design-diff]] | VERIFIER: resolve the oracle via the manifest → enumerate the page × state × breakpoint matrix → capture the RUNNING app post-settle → census FIRST → pixel-diff vs baseline → rule-check tokens/8pt/60-30-10 → hit-test interactions → per-page PASS/FAIL verdict, findings routed. | The pipeline verify gate, the fan-out audit's visual finder, or an ad-hoc fidelity pass. |
References map
| Note | Summary | Load when |
|---|
| [[contract-and-communication]] | THE CONTRACT ITSELF: the artifact/link graph both roles share, the storage layout (docs/design/ library · docs/frontend/ KB · .ai_log/ evidence · pipeline-state paths), the communication protocol (handoff timing, ask-don't-guess, findings routing, deviations ledger, refresh loop), and the three-way data-test hook contract with QE. | Deciding where an artifact lives, how to hand off, who to ask/route to, or what each side owes the other. |
| [[baseline-and-oracle]] | What the oracle is (ONE canonical frozen renderable file per page via the manifest + baseline renders + the token/system rule oracle), how to resolve it per page/state, canvas-export de-framing, and how to ESTABLISH/REFRESH a baseline — including when the design phase was skipped. | Resolving/refreshing the baseline; no oracle exists yet; the design legitimately changed. |
| [[region-census]] | The region/element COMPLETENESS CENSUS — the FIRST check on both the frontend self-gate and the verifier: build the oracle's ordered inventory, walk the built DOM, tick each region/element off by data-test, FAIL on any missing/reordered/extra region. Needs no pixel baseline. | Gating a page; a whole section may be missing; the pixel diff "looks fine" but the page feels incomplete; no baseline exists. |
| [[fidelity-checks]] | The measurable checks + thresholds: completeness census (first), layout, spacing (8pt grid), color (palette + 60/30/10), type (scale/weight/line-height), token conformance (against the project's declared token source), DOM-structure preservation, and broken/obscured-interaction hit-testing; severity model + the PASS/FAIL rule. | Deciding what to measure; classifying a diff as PASS/FAIL; setting/holding the drift threshold. |
Companion Files
FORMAT.md — the handoff manifest (producer), the port-evidence report (consumer),
the per-page PASS/FAIL design-diff report + gate verdict line (verifier).VOICE.md — communication style / tags ([DESIGN-DIFF-*], [NO-ORACLE],
[CONTRACT-GAP], report-only framing).workflows/ — the three role playbooks mapped above.references/ — the atomized knowledge notes mapped above.maps/ — index.json (master nav), tags.json, links.json, manifest.json.
Knowledge Strategy
- Patterns to capture: reliable screenshot/diff recipes (agent-browser + Playwright
toHaveScreenshot / pixelmatch / odiff), per-breakpoint threshold tuning, recurring
drift shapes (font-loading FOUT, second-styling-source drift, off-grid spacing),
census misses and the inventory entries that would have caught them.
- Examples to collect: baseline establishment on a design-phase-skipped page,
token-parity verification across stacks, obscured-interaction (overlay/z-index)
catches, contract-gap escalations.
- Update permission: agents may freely add/update files in
references/. Changes to
SKILL.md require user approval.
VERSION 2.0
