frontend-engineering

Common requests:

• Create: “Build this dashboard screen from the brief.” The agent writes a proportional contract, implements the surface, runs gates, and produces evidence. You approve the contract and accept or fix exceptions.
• Retrofit: “Improve this existing checkout page without changing its flow.” The agent starts with brownfield inspection, then produces a preservation list, implementation path, and evidence manifest. You decide which existing debts are in scope.
• Audit: “Audit this landing page for frontend quality.” The agent writes a prioritized report without changing code. You decide which findings become work.
• Verify: “Verify this completed page before release.” The agent runs the gate suite and produces an evidence manifest. You accept the release evidence or send it back.

The journey

1. Choose the frontend job

• You provide: the surface or request: create a new page, retrofit an existing one, audit without edits, or verify completed work.
• Agent does: loads frontend-engineering, selects create, retrofit, audit, or verify, and names the expected output before touching code or gates.
• You do: confirm that the mode matches the job you actually want done.
• You decide: choose the operating mode.
• Output: a mode decision with the work boundary: contract, brownfield inspection, audit report, or verification manifest.
• State: decision-required

Pick the depth first — explore is the default

The surface’s risk-tier decides how much of the shared experience contract you owe and which states the surface must handle. It is a per-run choice, not a property of the pack: a tooltip and a checkout flow walk the same six stages at different depths. Raise the tier as the surface matures; nothing makes you start high.

• explore — the default, and the right choice for a prototype, an internal tool, or a surface still finding its shape. 10 of the contract’s 32 fields. States: loading, empty, error, success, content, partial, disabled, keyboard-only, reduced-motion, high-zoom.
• pilot — 25 fields. Adds first-run, no-results, blocked, large-data-set.
• production — 32 fields. Adds offline, long-content, and the evidence manifest’s two production fields.

Gates at explore. Four of the five run: structural HTML validation, the accessibility audit, the visual QA checklist, and the rendered-page inspection. Token enforcement runs only where stylelint is already configured, at every tier.

Captures do not thin with the tier. A route owes four captures per channel — a short and a tall viewport, each at rest and scrolled — at every tier. A surface declaring no breakpoints and no minimum width has two channels, so eight captures per route; declared breakpoints change the channel count, never the four each channel owes.

Two states sit outside the ladder and bind at every tier once their trigger fires: permission/denied on a surface behind authorization, and destructive-confirmation on a primary action that is irreversible or destroys data the user controls.

What explore drops, and what it never drops. Measured against production, explore drops 22 contract fields and 6 states. It drops no state the shared state-coverage map records as failing WCAG 2.2 AA when absent: all seven banded accessibility-bearing states are already in the explore set, and the eighth is destructive-confirmation, which is conditional and binds wherever its trigger fires. The accessibility audit runs at every tier. Depth buys evidence and completeness; it never buys a surface someone cannot use.

---

2. Write or confirm the page/screen contract

• You provide: the surface brief, target user, primary job, first-screen requirements, existing design constraints, and any measurement event already known. When a design pack produced the work, the brief is not from nowhere: the pre-flight reads direction/<slug>.md for the aesthetic direction, screens/<slug>/<screen>.md for this screen, and tokens/<slug>.md for the token taxonomy, each relative to the design output directory the adopter configures.
• Agent does: for create mode, drafts the page/screen contract proportional to the surface’s risk and scope — a new route or a feature-gating screen warrants the full twelve fields; a single form field, a tooltip, or a minor component variant does not. For retrofit mode, runs brownfield inspection first and then narrows or expands the contract only if the surface is being substantially rebuilt.
• You do: read the contract as the product owner: can you tell what the surface must show, what action it supports, what state coverage applies, and whether the primary action reads or writes data?
• You decide: approve the contract or send it back with the missing product, state, responsive, a11y, or measurement detail.
• Output: an approved contract or brownfield inspection that constrains implementation.
• State: proposed-write

---

3. Implement or audit the surface

• You provide: repository access, the route or component location, design-system constraints, and any existing token, a11y, performance, or rendering requirements.
• Agent does: follows the implementation sequence for create or retrofit: reads the design handoff the adopter’s [design] output_dir names when one resolves, then resolves visual authority from the highest rung that supplies it — a visual target recorded as visual_target: confirmed, the direction and token taxonomy, the repository’s incumbent system, or a premise stated in-session — and records which rung supplied composition and which supplied values; then optional genre routing through the co-installed design pack, token values, state matrix, semantic HTML, CSS token discipline, responsive behavior, and public-surface checks where applicable. It renders the surface and compares it against that authority before the gates run, correcting once within a stated bound and recording anything left over. States that are genuinely inapplicable to the surface are omitted with the reason recorded, and a retrofit narrows the state matrix to what is absent or broken rather than re-enumerating all eighteen. In audit mode, it reads the surface and reports findings without writing code.
• You do: answer any product decision that changes the contract, such as what to preserve in a retrofit or which known debt is allowed as a ride-along.
• You decide: accept scoped implementation decisions or keep them out of this change.
• Output: implemented frontend work for create/retrofit, or an audit report for audit mode.
• State: confirmed-write

---

4. Run verification gates

• You provide: a runnable local route, static file, or completed surface, plus any browser or environment constraints, and the routes you want inspected.
• Agent does: runs the verification gates in order: structural HTML validation, accessibility audit, the optional CSS token enforcement gate where stylelint is already configured, and visual QA against applicable states. It then runs the rendered-page inspection: it opens each route you named at two viewport heights, at rest and scrolled, and judges what the page actually looks like — content covering other content, text running out of its container, a control too small to hit.
• You do: provide access or manual evidence for any browser-only check the agent cannot run, and decide whether any signed-in or sensitive view should be captured at all.
• Output: gate results with pass, fail, or unverified status for each required check, plus the inspection’s observations — what was seen in the captures, the result state, and the verdict (pass, or fail when a blocking reader-visible failure is unresolved) — which carry into the evidence manifest. A filename is not an observation. When no browser is reachable the inspection takes its named skip, recording skipped-no-browser and naming the missing capability; a skip stays visibly different from a completed inspection everywhere the result is read, so it reaches you as a decision rather than passing as a pass.
• State: read-only

---

5. Produce the evidence manifest

• You provide: screenshots, field data, analytics-event proof, or known-exception decisions that are not available from local gates.
• Agent does: assembles the evidence manifest with routes, viewports, browsers, states, screenshots, inspection observations (what was seen in the captures, the result state, and the verdict), a11y result, perf result, console/network result, analytics events, known exceptions, and unverified items. For a production surface it also records security/privacy review status and reliability/recovery status — the state of those reviews and who they were routed to, not a verdict of its own.
• You do: inspect the unverified items and known exceptions instead of treating them as noise.
• You decide: accept the known exceptions, require fixes, or defer the surface.
• Output: a completion-ready evidence manifest for create, retrofit, or verify mode.
• State: decision-required

---

6. Get an independent frontend review

• You provide: the diff and evidence manifest.
• Reviewer does: reads the HTML/CSS/JS diff for token drift, ARIA mutation completeness, state coverage regression, WCAG 2.2 manual-verification items, and Core Web Vitals regression signals, and reads the rendered-page captures for what a diff cannot show — something covering something else, text out of its container, a control too small to hit — taking its own captures where the set it was given does not cover what the diff makes it suspicious of. Security, reliability, and broader product-design findings route to their own reviewers instead of being claimed here.
• You do: review findings and decide whether each one blocks the handoff.
• You decide: merge after clean review, or send the work back through implementation and gates.
• Output: reviewed frontend work with the contract, gates, manifest, and reviewer disposition connected.
• State: confirmed-write