# Frontend Architecture > Use when turning a design system, product requirement, or frontend codebase into a maintainable component, content, state, and delivery architecture with measurable quality gates. - Skill: `peterbamuhigire/frontend-architecture` (Agent Skill) - Install (CLI): `npx skillmds@latest add peterbamuhigire/frontend-architecture` - Raw SKILL.md: https://api.skillmd.com/api/skills/peterbamuhigire/frontend-architecture/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: peterbamuhigire (https://skillmd.com/u/peterbamuhigire) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/peterbamuhigire/frontend-architecture --- # 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. For premium or client-facing work, preserve the design thesis, signature choice, real-content hierarchy, and state model in the implementation contract. Treat inspiration as a principle, never as a copied visual surface. 7. 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. ## 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` ## Capability contract Read/search of the frontend, requirements and design source is required. Code edits need an implementation request; architecture review alone is read-only. Use the available build, test and browser tools for the selected flow. Do not deploy, publish or replace the design source as an incidental architecture step. ## Degraded mode Without the target runtime or browser, deliver the ownership map and proposed migration slice, with interaction, accessibility, visual and performance checks marked NOT ASSESSED. A static component inspection cannot establish rendered behaviour. Retain the current implementation until required acceptance checks can support the migration decision.