User Interface Engineering

--- name: frontend-ui-engineering description: Builds production-quality UIs. Use when building or modifying user-facing interfaces. Use when creating components, implementing layouts, managing state, or when the output needs to look and feel production-quality rather than AI-generated. --- # 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 ## Component Architecture ### File Structure Colocate everything related to a component: `` src/components/ TaskList/ TaskList.tsx # Component implementation TaskList.test.tsx # Tests TaskList.stories.tsx # Storybook stories (if using) use-task-list.ts # Custom hook (if complex state) types.ts # Component-specific types (if needed) ` ### Component Patterns **Prefer composition over configuration:** `tsx // Good: Composable <Card> <CardHeader> <CardTitle>Tasks</CardTitle> </CardHeader> <CardBody> <TaskList tasks={tasks} /> </CardBody> </Card> // Avoid: Over-configured <Card title="Tasks" headerVariant="large" bodyPadding="md" content={<TaskList tasks={tasks} />} /> ` **Keep components focused:** `tsx // Good: Does one thing export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) { return ( <li className="flex items-center gap-3 p-3"> <Checkbox checked={task.done} onChange={() => onToggle(task.id)} /> <span className={task.done ? 'line-through text-muted' : ''}>{task.title}</span> <Button variant="ghost" size="sm" onClick={() => onDelete(task.id)}> <TrashIcon /> </Button> </li> ); } ` **Separate data fetching from presentation:** `tsx // Container: handles data export function TaskListContainer() { const { tasks, isLoading, error } = useTasks(); if (isLoading) return <TaskListSkeleton />; if (error) return <ErrorState message="Failed to load tasks" retry={refetch} />; if (tasks.length === 0) return <EmptyState message="No tasks yet" />; return <TaskList tasks={tasks} />; } // Presentation: handles rendering export function TaskList({ tasks }: { tasks: Task[] }) { return ( <ul role="list" className="divide-y"> {tasks.map(task => <TaskItem key={task.id} task={task} />)} </ul> ); } ` ## State Management **Choose the simplest approach that works:** ` Local state (useState) → Component-specific UI state Lifted state → Shared between 2-3 sibling components Context → Theme, auth, locale (read-heavy, write-rare) URL state (searchParams) → Filters, pagination, shareable UI state Server state (React Query, SWR) → Remote data with caching Global store (Zustand, Redux) → Complex client state shared app-wide ` **Avoid prop drilling deeper than 3 levels.** If you're passing props through components that don't use them, introduce context or restructure the component tree. ## Design System Adherence ### Avoid the AI Aesthetic AI-generated UI has recognizable patterns. Avoid all of them: | AI Default | Why It Is a Problem | Production Quality | |---|---|---| | Purple/indigo everything | Models default to visually "safe" palettes, making every app look identical | Use the project's actual color palette | | Excessive gradients | Gradients add visual noise and clash with most design systems | Flat or subtle gradients matching the design system | | Rounded everything (rounded-2xl) | Maximum rounding signals "friendly" but ignores the hierarchy of corner radii in real designs | Consistent border-radius from the design system | | Generic hero sections | Template-driven layout with no connection to the actual content or user need | Content-first layouts | | Lorem ipsum-style copy | Placeholder text hides layout problems that real content reveals (length, wrapping, overflow) | Realistic placeholder content | | Oversized padding everywhere | Equal generous padding destroys visual hierarchy and wastes screen space | Consistent spacing scale | | Stock card grids | Uniform grids are a layout shortcut that ignores information priority and scanning patterns | Purpose-driven layouts | | Shadow-heavy design | Layered shadows add depth that competes with content and slows rendering on low-end devices | Subtle or no shadows unless the design system specifies | ### Spacing and Layout Use a consistent spacing scale. Don't invent values: ``css /* Use the scale: 0.25rem increments (or whatever the project