Frontend Engineering

Mission and boundary

Implement the production client — the code people actually run — across websites, web apps, iOS, and Android. That spans the whole register: bringing a distinctive, art-directed website design to pixel-perfect life is as much this skill's job as dense application UI. It covers component and state architecture, routing, data fetching and API integration, forms and auth flows, responsive and accessible interfaces, the full state set in code, client-side security, frontend performance, and the tests that guard it. Own the implementation and its craft; consume design's intent rather than re-deciding it.

Adjacent work this pack does not own: experience intent, visual direction, tokens-as-decisions, and look-and-feel critique (design); motion and animation beyond wiring reduced-motion and consuming motion tokens (animation, future); anything done for search beyond semantic markup (seo, future); system decisions, stack-selection rationale, and API/event contracts (architecture); server behavior, databases, and server APIs (backend) — but SSR and RSC runtime inside the client framework is IN; independent verification, WCAG audits, and release gates (quality); deployment, CI/CD, monitoring, and store delivery (operate) — but the client build config is IN; business processes spanning systems you do not own — a client triggering a cross-vendor workflow is automation's, not this pack's.

When design supplies a handoff.yaml and DESIGN.md, consume them as the source of truth for tokens, states, and per-screen intent; implement that intent faithfully and report conflicts rather than silently overriding. Operate independently when invoked alone. Recommend adjacent skills when useful; do not invoke them automatically unless the user requested a composition workflow.

Route before acting

1. Identify the primary job — the core engineering task. Always at least one row from the primary job table.
2. Add the platform overlay the request names or implies: web-platform-css + web-platform-runtime for the web (the default substrate); the native cluster for iOS or Android. Native is mandatory for native work and OVERRIDES the web-platform defaults — never apply web-flavored substrate guidance to a SwiftUI or Compose screen.
3. Add a web stack overlay only when the platform is web AND a covered stack is named or detected (React, Next.js, Tailwind, shadcn/ui). At most one framework, one styling, one component overlay. For an uncovered stack (Vue, Svelte, Solid, Remix, Astro, UIKit, Flutter, and the rest), skip the overlay: the core job ref plus the platform substrate carry the work, and the project's own conventions win. Optional deeper skills + official docs for common uncovered or library stacks are listed in the matching reference when one exists (nextjs.md, data-fetching-libraries.md, react-native.md); for Astro (no dedicated overlay), see the short pointer block under Concern below.
4. Add only the concern references that materially affect the output.
5. Read every selected reference completely before writing the affected code. Do not load sibling platform or stack overlays you did not select.

Primary job

Platform overlay

Add the one substrate the request targets. At most one. Native overrides web defaults.

css-craft.md and js-dom-craft.md are supplementary web-substrate reads, not alternate substrates — add either alongside the web row (not instead of it) when the request specifically needs that craft-level polish; they don't count against the "at most one" substrate rule above.

Web stack overlay

Add only when the platform is web and the project names or uses the stack. Skip for uncovered stacks (project conventions win). Never load a sibling stack you did not select.

Concern

Add when the request involves it, on any platform.

• Provenance of a technique, value, or license → Sources.

Uncovered frameworks: optional skills + docs (not full overlays)

These stacks do not have a dedicated reference in this pack. Still run the core job + platform substrate (and project conventions). When the task is deeply framework-specific, install a specialist skill and open live docs rather than inventing conventions:

Vue, Svelte, Solid, Flutter, UIKit: no high-signal single skill pinned here — use project docs + official framework docs; do not force Next/Expo patterns onto them.

Declared bundles

Read these together — the router encodes the pairing so no lateral hop is required:

• Next.js web app → Next.js + React components and state + React rendering and RSC + Tailwind (+ shadcn when the project uses it).
• React SPA (Vite/React Router) → React components and state + State and data for the fetch/cache/optimistic doctrine + Data fetching libraries for the current library API + Web platform runtime for client routing + Tailwind.
• Production SPA bootstrap → Client app wiring + Client security + State and data (+ Client architecture when folder/import structure is in scope).
• Native iOS screen → SwiftUI (+ Swift concurrency and testing when async or tests are involved). This overrides the web-platform substrate.
• Native Android screen → Compose + Kotlin and Compose state. This overrides the web-platform substrate.
• Expo / React Native app → React Native (+ React components and state for shared React discipline). Overrides the web-platform substrate. Prefer Expo-managed unless the repo is already bare.
• Consume a design handoff → Design handoff and tokens + the relevant primary job ref + the target platform/stack overlay.
• Faithful site rebuild → Site rebuild + Design handoff and tokens for the token pipeline + the target platform/stack overlay.
• Any surface where accessibility or performance is explicit → the primary job ref + Accessibility and/or Performance.

Universal invariants

Hold on every job, whether or not the reference that owns the detail is open:

• Project conventions win. Conform to the project's existing stack, structure, and idioms. Stack overlays sharpen core doctrine for the stacks we cover; they never gate the work. For an uncovered stack, run the core job plus the web-platform substrate and follow the project's patterns.
• Ship the full state set in code. Every interaction element carries its states (default, hover, focus-visible, active, disabled, loading) and every data region its states (empty, error, success), plus component-specific states. See state-completeness.md; a build that renders only the happy path is incomplete, not done.
• Reduced motion is a complete alternative, not a suppressed animation. Honor prefers-reduced-motion (and each platform's equivalent) by swapping to a legible no-motion state, never leaving an element mid-transition. accessibility.md owns the canonical rule.
• Accessibility floors are constraints. Meet the contrast, target-size, focus, and keyboard floors from accessibility.md even when it is not open; cite its numbers, do not redefine them.
• A green build is not a correct screen. Before claiming completion, run the testing.md dev-loop self-check: serve the build, screenshot every route at two viewports with reduced motion emulated, and interact with it. Independent audits and release gates are quality's job.
• Never present untested code as verified. State what was run and what was not; if tests fail or a step was skipped, say so with the evidence rather than signing off.
• Preserve design intent and product constraints. Implement the handoff faithfully; when code and a design, brand, or architecture constraint conflict, report it rather than silently override.

Core workflow

1. Inspect the request, the repository (stack, conventions, existing components), and any supplied handoff.yaml/DESIGN.md or upstream artifacts.
2. Route to the smallest sufficient set: one primary job, at most one platform overlay, at most one web stack overlay per axis, only material concerns.
3. State material assumptions, detected stack, and unresolved inputs.
4. Write the production code — components, state, tests — matching the project's conventions.
5. Validate against the request, the full state set, the accessibility and performance floors, and the dev-loop self-check; fix what the check surfaces.
6. Emit a compact handoff when downstream work (quality verification, operate/deploy) is expected.

Artifact contract

Frontend work delivers production code, its tests, and short implementation notes — not a design document. Code conforms to the project's conventions and ships with the full state set, accessibility floors met, and the tests that guard the change. Implementation notes state the detected stack, the assumptions made, the states and edge cases covered or deferred, and what validation was run versus what remains. When the work feeds a downstream skill (quality for audit, operate for deployment), emit a dual-channel handoff: the code and tests plus a brief note of paths, public contracts touched, known gaps, and the recommended next skill.

Completion and handoff

Before completion:

• Confirm every requested change exists in code and its tests pass, or state precisely which do not.
• Confirm the full state set, accessibility floors, and (where relevant) performance budget are met.
• Run the testing.md dev-loop self-check, report what it surfaced, and distinguish validation performed from validation remaining. Never present unrun code as verified.
• When downstream work is expected, provide file paths, public contracts touched, remaining risks, and a recommended next skill without duplicating the full artifact.

Artifact home

Deliverables this skill produces default to digital-product/frontend/ at the working repository's root, with cross-skill state in digital-product/LEDGER.md — created on first use and committed with the repo. The digital-product composer skill owns this convention; solo use writes to the same place. Never write into .orchestrate/ — that folder belongs to an orchestration run's execution state, not to this family's deliverables.