Frontend UI Engineering

Frontend UI Engineering

Overview

Build production-quality user interfaces that are accessible, performant, and visually polished. The goal is UI that looks like it was built by a design-aware engineer at a top company — not like it was generated by an AI. This means real design system adherence, proper accessibility, thoughtful interaction patterns, and no generic "AI aesthetic."

When to use

• Building new UI components or pages
• Modifying existing user-facing interfaces
• Implementing responsive layouts
• Adding interactivity or state management
• Fixing visual or UX issues

Do not use for schema-driven UIDL documents (uidl-runtime).

Process

1. Confirm it is hand-built UI. If the screen is a UIDL JSON document, stop and use uidl-runtime.
2. Discover before inventing. Grep the project's primitives, page-kit, and Storybook. Reuse or extend before adding a new component. See references/component-reuse.md.
3. Colocate, then decompose by responsibility. Keep a small component in one file. Create a family directory when tests, stories, hooks, or subcomponents appear. Split when a file mixes visual regions, state, and data adaptation — 200 lines is a review threshold, not a target. Placement and composition: references/component-structure.md.
4. Choose the simplest state. Local state → lifted → context (read-heavy) → URL (shareable) → server cache → global store. Avoid prop drilling deeper than 3 levels.
5. Match the project's design system and WCAG 2.1 AA. No generic AI palette. Semantic tokens, keyboard access, labels, focus, empty/error/loading states. Details: references/visual-and-a11y.md. Review against references/production-ui-checklist.md.
6. Keep layers honest. Components render. Hooks own state and effects. Services talk to APIs. Utilities stay pure.

Red flags

• Components over roughly 200 lines that have not been reviewed for decomposition
• Large components containing multiple visual regions, state concerns, and interaction flows
• Extracted subcomponents that remain in the parent file despite having independent behavior
• Tiny one-use subcomponents that add navigation cost without improving cohesion
• Private component-family details exported as public API
• Domain-specific components prematurely placed in the app-wide components/ui/ directory
• Flat component directories with unrelated files or deeply nested directories without clear scope
• Inline styles or arbitrary pixel values
• Missing error states, loading states, or empty states
• No keyboard navigation testing
• Color as the sole indicator of state (red/green without text or icons)
• Generic "AI look" (purple gradients, oversized cards, stock layouts)
• Business logic or API calls inside Components (extract to Hook or Service)
• Duplicated state/effect patterns across Components (extract to shared Hook)
• Inline utility logic in Components or Hooks (extract to utils/)
• Mixing presentation with domain logic in the same file

Verification

After building UI:

• Component renders without console errors
• All interactive elements are keyboard accessible (Tab through the page)
• Screen reader can convey the page's content and structure
• Responsive: works at 320px, 768px, 1024px, 1440px
• Loading, error, and empty states all handled
• Follows the project's design system (spacing, colors, typography)
• No accessibility warnings in dev tools or axe-core
• Architecture: no business logic in Components, no API calls in UI, no duplicated hooks
• Architecture: Components consume Hooks, Hooks delegate to Services, Utilities are stateless
• Large components were reviewed and split along meaningful UI or behavioral boundaries
• Subcomponents live at the narrowest valid reuse scope and private details remain private
• Component directories are cohesive, shallow, consistently named, and intentionally exported

References

• references/component-reuse.md — four-layer reuse (Component / Hook / Utility / Service)
• references/component-structure.md — file layout, composition, and state
• references/visual-and-a11y.md — design-system, accessibility, responsive, and loading patterns
• references/production-ui-checklist.md — review-mode checklist