Frontend Architecture

---
name: frontend-architecture
description: Use when turning a design system, product requirement, or frontend codebase into a maintainable component, content, state, and delivery architecture with measurable quality gates.
---

# Frontend Architecture

## Use when

- A website or application needs component boundaries, composition rules, a source of truth, or a sustainable design-system implementation.
- A frontend has duplicated tokens, inconsistent states, slow delivery, fragile responsive behaviour, or unclear ownership between design and code.
- A Kaizen cycle needs to improve the frontend engine or a rendered web product without copying a reference site.

## Do not use when

- The task is only visual mood-board analysis; route to website-skills `design-reference`.
- The task is only page composition; route to `page-builder` after architecture is approved.
- Framework-specific current claims are required without current verification.

## Required inputs

| Input | Required | Purpose |
|---|---:|---|
| Product flows, supported viewports, content/data shapes, design-system source, stack, and quality targets | Yes | Define boundaries and acceptance |
| Existing component inventory, defects, performance/accessibility evidence, and ownership | When available | Expose duplication and risk |
| Reference captures or PDF/image inspiration | Optional | Extract principles only; never copy protected assets or distinctive styling |

## Workflow

1. Inventory routes, user flows, components, tokens, states, content contracts, data dependencies, and delivery owners. Mark unknowns rather than inferring them.
2. Define a single source of truth for tokens, components, patterns, content schemas, and responsive rules. Record which layer owns each decision.
3. Choose the smallest architecture that supports the required flows: composition boundaries, state model, loading/error/empty states, accessibility semantics, and extension points.
4. Connect design, code, documentation, and release checks. Require unit/interaction coverage for logic, visual regression for rendered states, accessibility checks, and performance budgets for critical flows.
5. Validate a representative flow at narrow and wide viewports, with slow network, keyboard, reduced motion, long content, failure, and localisation cases where applicable.
6. Document the decision record, migration slice, ownership, rollback path, and next measurable improvement. Standardise only after evidence passes.

## Outputs

- architecture decision record and component/content ownership map;
- token/component/state inventory with source-of-truth links;
- representative implementation or migration slice;
- visual, accessibility, interaction, performance, and failure-path evidence;
- Kaizen record with a capped 65/100 baseline and 95/100 improvement target.

## Decision rules

| Finding | Action | Risk avoided |
|---|---|---|
| A component differs only because its state or content contract is undocumented | Consolidate the contract before cloning | System drift |
| A shared abstraction increases coupling or slows a critical flow | Keep the boundary local and record why | Premature generalisation |
| A visual reference is distinctive or its rights are unclear | Reject the asset/style and abstract the user-facing principle | Imitation and IP risk |
| A change improves visual consistency but breaks accessibility or performance budgets | Reject, narrow, or roll back | Local optimisation |

## Anti-patterns

- Choosing a framework pattern before understanding flows, content, and ownership.
- Treating a component catalogue as a design system without states, contracts, docs, or release checks.
- Duplicating tokens or styling from an inspiration source.
- Validating only the happy path or desktop screenshot.
- Increasing the published audit above 65 before the initial evidence-backed improvement cycle.

## Cross-references

- `frontend-ux/frontend-performance`
- `frontend-ux/accessibility`
- `frontend-ux/visual-qa`
- `frontend-ux/practical-ui-design`
- `sdlc-meta/kaizen-improvement-system`
- website-skills `skills/build/design-reference` and `skills/build/design-system`