# Frontend UI Engineering

> Builds production-quality UIs and maintainable component architectures. Use when building or modifying user-facing interfaces, components, layouts, or stateful interactions. Do not use for backend-only or non-UI changes, or for schema-driven UIDL documents (uidl-runtime).

- Skill: `hi-donwi/frontend-ui-engineering` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add hi-donwi/frontend-ui-engineering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hi-donwi/frontend-ui-engineering/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: hi-donwi (https://skillmd.com/u/hi-donwi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/hi-donwi/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