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

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:

// 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:

// 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:

// 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:

/* Use the scale: 0.25rem increments (or whatever the project uses) */
/* Good */  padding: 1rem;      /* 16px */
/* Good */  gap: 0.75rem;       /* 12px */
/* Bad */   padding: 13px;      /* Not on any scale */
/* Bad */   margin-top: 2.3rem; /* Not on any scale */

Typography

Respect the type hierarchy:

h1 → Page title (one per page)
h