Frontend implementation

Frontend UI Engineering

Build UI the way a design-aware engineer would: on the project's design system, accessible, responsive, with every state handled.

Components

• Keep a component's code, tests and stories together, in the project's layout. One job per component; split one that grows past about 200 lines.
• Composition over configuration: children and slots, not a long list of layout props.
• Separate loading data from showing it: a container decides loading, error, empty or content; the presentational part only renders.

State: the simplest that works

• Local state for one component; lift it for 2–3 siblings; context for read-heavy, rarely written values (theme, auth, locale); the URL for filters, pagination and shareable view state; the project's server-state cache for remote data; a global store only for complex app-wide client state.
• Props passed through more than 3 levels that do not use them: restructure or use context.
• Optimistic updates only with rollback on error and a refresh afterwards.

Avoid the generated look

• Spacing, color and type come from the scale and semantic tokens: no off-scale values such as 13px or 2.3rem, no raw hex.

Focus and dialogs

• Visible :focus-visible styles; never outline: none without a replacement. :focus-within for compound controls.
• Sticky headers, footers and overlays must not cover the focused element.
• Dialogs: the native dialog opened with showModal(), or the project's accessible dialog. It needs a label, keeps focus inside, closes on Escape and returns focus to the trigger. Moving focus once is not a focus trap.

Forms

• The right type and inputmode, autocomplete and a meaningful name; spellcheck off for emails, codes and usernames.
• Never block paste. A checkbox or radio and its label share one hit area.
• Submit stays enabled until the request starts, then shows progress. Errors appear inline at the field; focus the first one on submit.
• Placeholders show an example, not the label. Warn before leaving with unsaved changes.

Touch and layout

• touch-action: manipulation on controls; overscroll-behavior: contain in modals, drawers and sheets.
• Every drag, swipe or pinch has a tap or keyboard alternative; no text selection while dragging.
• Autofocus only on desktop, for one primary input.
• Full-bleed layouts respect env(safe-area-inset-*). Prefer flex and grid to measuring in JavaScript. Fix overflow at its source instead of hiding scrollbars. Never disable zoom.

Responsive and states

• Mobile first; check 320, 768, 1024 and 1440 px.
• Loading content gets a skeleton shaped like it (aria-busy); a spinner only for an action in progress.
• Every data view handles loading, empty (explain and offer the next action), error (message and retry), success and no-permission.

Before you finish

• No console errors; works at 320, 768, 1024 and 1440 px.
• Keyboard pass with visible focus; dialogs trap and return focus.
• Loading, empty, error, success and permission states handled.
• Design system spacing, color and type; no generated-look defaults.
• Forms: types, autocomplete, inline errors, paste allowed.