frontend-design — frontend low-level design

Design the frontend for a feature: read enough of the existing UI to ground the design in real components and patterns, then write a buildable frontend LLD. Design artifact, not code — never edit app code. Prefer reuse over reinvention; cite file:line for constraints.

When to use / not use

• Use in the design phase, after the HLD is approved, in parallel with the backend LLD.
• Don't implement, and don't design the backend. The cross-repo contract is not

written here — you describe the API/data your UI needs to consume, and /api-contract reconciles the two LLDs into the formal OpenAPI contract afterward.

Inputs

• feature, featureslug, approved hldpath.
• Artifact path — resolve it yourself from skills.config.yaml → artifacts.lld with

{slug} = feature_slug, i.e. docs/technical/<slug>/lld/frontend.md. The caller passes no path; this skill owns where it writes.

Steps

1. Ground in the code (read-only). Locate the app(s)/routes this feature touches and read

what matters — routing/pages, the component library/design system, state & data-fetching layer (store, cache/invalidation, the API client/hooks), forms/validation approach, the existing loading/empty/error/permission UI-state patterns, accessibility conventions, i18n, and the component/E2E test setup. Capture only what constrains the design, with file:line evidence. (No separate map is produced — this feeds the LLD.)

1. Component & state design — the component hierarchy and responsibilities, where screens

attach in routing, the state model, data-fetching + cache keys/invalidation, and the form schema/validation (parity with backend rules).

1. UI-state matrix — for each view, define every state: loading, empty, success,

partial, error/retry, permission-denied, and offline/slow-network where relevant.

1. API to CONSUME — the endpoints/events and response shapes the UI expects (your side of

the contract). /api-contract reconciles this with the backend's exposed API.

1. Accessibility strategy (keyboard, focus, roles/labels, contrast — WCAG AA),

performance (bundle/render, code-splitting on heavy routes), security (XSS/CSRF, authz in the UI, no secrets in the client), i18n, and resilience (error boundaries, optimistic UI + rollback).

1. Test plan — component + E2E coverage, including the negative UI states.
2. Write the frontend LLD; flag anything that forces a backend/contract change.

What the frontend LLD must cover (write all)

Context & constraints (grounded in the code, cited) · component & state design · routing · data-fetching + caching · forms & validation · UI-state matrix · API consumed (the frontend's side of the contract) · accessibility · performance · security · i18n · resilience · test plan.

Edge cases the design must define (not leave to the implementer)

• Views with no existing loading/empty/error state to copy; long lists / virtualization.
• Concurrent edits / stale data; optimistic update failure and rollback.
• Slow or failed API calls; partial data; pagination boundaries (first/last/empty page).
• Permission-gated UI; expired session mid-flow.
• Unicode / locale / timezone / RTL; large form validation; accessibility of dynamic content.
• Bundle-size-sensitive routes; areas with no tests; heavy/legacy components.

External skill (provision — research)

Read skills.config.yaml → lld.external.research (a skill name, e.g. deep-research, or none). If set, use it to research unfamiliar libraries or patterns — it must return sourced findings you can cite in the LLD. If none, design from the code + HLD.

Output

Write docs/technical/<slug>/lld/frontend.md with the sections above, each constraint citing file:line. Return lld_path and a short list of the decisions/constraints that shape the contract (e.g. "data-fetching goes through hook X — reuse it"; "needs GET /searches returning {items, nextCursor}"). The API-consumed section feeds /api-contract.

Definition of done

Every section present; UI-state matrix complete (no state omitted); API-consumed concrete enough to formalize; edge cases specified (not "TBD"). Do not implement — that is /frontend-impl after the contract is approved.