frontend-ui-engineering

Frontend UI Engineering

Stack Activation Gate

Detect the active stack from the project's package files. State it explicitly: "Active stack: {name}".

Stack	Detection signal
Next.js	next in package.json (not Angular, not React Native)
React Native	react-native in package.json
Flutter	pubspec.yaml containing flutter:
Angular	angular.json present or @angular/core in package.json

Required before any output — do not skip:

1. Derive the skill directory from the path this SKILL.md was loaded from.
2. Read the matching reference file from that directory:
   • Next.js → references/nextjs.md
   • React Native → references/react-native.md
   • Flutter → references/flutter.md
   • Angular → references/angular.md
3. Apply the patterns from that file and run its Verification Checklist before completing any output.

MCP Tools

Use these MCP servers when available. At the start of any UI task, check which are active. If one is missing, ask the user once: "I can use the [X] MCP for this — do you have it configured? If not, I'll proceed without it." Never block on a missing MCP — always offer a fallback path.

Figma — Extract design specs before building

If available: When the user provides a Figma URL or references a design, extract specs before writing a single line of UI code:

1. Invoke figma:figma-use skill first — mandatory prerequisite before any use_figma call.
2. Call get_design_context with the fileKey and nodeId from the URL.
3. Use the returned code, screenshot, and tokens as reference — do not copy verbatim.
4. Map Figma output to the project's existing components and design tokens.

URL parsing: figma.com/design/:fileKey/:name?node-id=:nodeId — convert - to : in nodeId.

Key tools: get_design_context, get_screenshot, get_metadata, search_design_system.

If not available: Ask for screenshots or a written description of the design intent before proceeding.

Component Library — Find the right component before writing custom code

If available: When building with shadcn/ui, query the MCP before implementing a component from scratch:

1. Query the shadcn MCP for a component matching the UI need.
2. Review the component's API, variants, and built-in accessibility behavior.
3. If not yet in the project, install via CLI: npx shadcn@latest add <component>.
4. Compose from shadcn primitives — never re-implement what shadcn already provides.

Prefer shadcn primitives for: Button, Dialog, Dropdown, Form, Input, Select, Sheet, Toast, Tooltip, Table, Tabs, Command.

If not available: Fall back to the project's existing component library (@repo/ui or equivalent). Do not introduce shadcn without confirming with the user. The active stack's reference file specifies the component library and how to use it. Check there before adding new dependencies.

Output Artifact

Code generated in the feature slice per the active stack's architecture. This skill produces working code files — components, hooks, pages — co-located per stack conventions.

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

Keep all files related to a component in one directory: implementation, tests, stories (if applicable), custom state hooks, and component-specific types. Delete the directory and that capability disappears cleanly.

Locate 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: Compose UIs from small, focused pieces rather than building large components with many configuration props. A component with five boolean flags is five components in disguise.

// 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: Each component should do one thing. Split when a component manages unrelated state or when the template grows beyond what fits on one screen.

// 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: A container handles data fetching, loading, error, and empty states; a presentation component receives props and renders. Presentation components are independently testable, reusable, and easier to review.

// 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)
h2 → Section title
h3 → Subsection title
body → Default text
small → Secondary/helper text

Don't skip heading levels. Don't use heading styles for non-heading content.

Color

• Use semantic color tokens: text-primary, bg-surface, border-default — not raw hex values
• Ensure sufficient contrast (4.5:1 for normal text, 3:1 for large text)
• Don't rely solely on color to convey information (use icons, text, or patterns too)

Accessibility (WCAG 2.1 AA)

Every component must meet these standards:

Keyboard Navigation

// Every interactive element must be keyboard accessible
<button onClick={handleClick}>Click me</button>        // ✓ Focusable by default
<div onClick={handleClick}>Click me</div>               // ✗ Not focusable
<div role="button" tabIndex={0} onClick={handleClick}    // ✓ But prefer <button>
     onKeyDown={e => e.key === 'Enter' && handleClick()}>
  Click me
</div>

ARIA Labels

// Label interactive elements that lack visible text
<button aria-label="Close dialog"><XIcon /></button>

// Label form inputs
<label htmlFor="email">Email</label>
<input id="email" type="email" />

// Or use aria-label when no visible label exists
<input aria-label="Search tasks" type="search" />

Focus Management

// Move focus when content changes
function Dialog({ isOpen, onClose }: DialogProps) {
  const closeRef = useRef<HTMLButtonElement>(null);

  useEffect(() => {
    if (isOpen) closeRef.current?.focus();
  }, [isOpen]);

  // Trap focus inside dialog when open
  return (
    <dialog open={isOpen}>
      <button ref={closeRef} onClick={onClose}>Close</button>
      {/* dialog content */}
    </dialog>
  );
}

Meaningful Empty and Error States

// Don't show blank screens
function TaskList({ tasks }: { tasks: Task[] }) {
  if (tasks.length === 0) {
    return (
      <div role="status" className="text-center py-12">
        <TasksEmptyIcon className="mx-auto h-12 w-12 text-muted" />
        <h3 className="mt-2 text-sm font-medium">No tasks</h3>
        <p className="mt-1 text-sm text-muted">Get started by creating a new task.</p>
        <Button className="mt-4" onClick={onCreateTask}>Create Task</Button>
      </div>
    );
  }

  return <ul role="list">...</ul>;
}

Responsive Design

Design for mobile first, then expand:

// Tailwind: mobile-first responsive
<div className="
  grid grid-cols-1      /* Mobile: single column */
  sm:grid-cols-2        /* Small: 2 columns */
  lg:grid-cols-3        /* Large: 3 columns */
  gap-4
">

Test at these breakpoints: 320px, 768px, 1024px, 1440px.

Loading and Transitions

// Skeleton loading (not spinners for content)
function TaskListSkeleton() {
  return (
    <div className="space-y-3" aria-busy="true" aria-label="Loading tasks">
      {Array.from({ length: 3 }).map((_, i) => (
        <div key={i} className="h-12 bg-muted animate-pulse rounded" />
      ))}
    </div>
  );
}

// Optimistic updates for perceived speed
function useToggleTask() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: toggleTask,
    onMutate: async (taskId) => {
      await queryClient.cancelQueries({ queryKey: ['tasks'] });
      const previous = queryClient.getQueryData(['tasks']);

      queryClient.setQueryData(['tasks'], (old: Task[]) =>
        old.map(t => t.id === taskId ? { ...t, done: !t.done } : t)
      );

      return { previous };
    },
    onError: (_err, _taskId, context) => {
      queryClient.setQueryData(['tasks'], context?.previous);
    },
  });
}

See Also

For detailed accessibility requirements and testing tools, see references/accessibility-checklist.md.

Common Rationalizations

Rationalization	Reality
"Accessibility is a nice-to-have"	It's a legal requirement in many jurisdictions and an engineering quality standard.
"We'll make it responsive later"	Retrofitting responsive design is 3x harder than building it from the start.
"The design isn't final, so I'll skip styling"	Use the design system defaults. Unstyled UI creates a broken first impression for reviewers.
"This is just a prototype"	Prototypes become production code. Build the foundation right.
"The AI aesthetic is fine for now"	It signals low quality. Use the project's actual design system from the start.

Red Flags

• Components with more than 200 lines (split them)
• 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)

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

Next Step

When the UI is built, suggest to the user:

"UI complete. When you're ready, run /review before merging (dev-code-review-and-quality)."

Do not invoke /review automatically.