frontend-ui-engineering

name	frontend-ui-engineering
description	Build production-quality UI that is accessible, performant, and consistent with the design system. Not AI-generated-looking.
when-to-use	Any time you are creating or modifying UI components or sections.

Frontend UI Engineering

Build UI "that looks like it was built by a design-aware engineer at a top company — not like it was generated by an AI." Adhere to the actual design system rather than defaulting to generic AI patterns.

Core Architecture

Colocate related files — Keep tests, hooks, and types near the component they belong to.

Composition over configuration — Build flexible components through composition, not a growing list of props.

Separate concerns — Data fetching belongs in hooks or server components, not in the render tree of presentational components.

Single responsibility — Each component does one thing. If a component is hard to name, it's doing too many things.

State Management Decision Tree

Is this UI-only state? ──────────────────────────────→ useState
Do siblings need it? ────────────────────────────────→ lift state
Is it theme, locale, or auth (read-heavy)? ──────────→ Context
Does it belong in the URL (filter, page, sort)? ─────→ URL state
Is it remote server data? ───────────────────────────→ SWR / React Query
Is it complex client state with many writers? ───────→ Zustand / Redux

Avoiding "AI Aesthetic" Patterns

Do not default to:

• Monochromatic purple/indigo palettes
• Excessive or gratuitous gradients (unless they're part of the design system)
• Uniform rounded corners on everything
• Generic hero sections with centered text and a CTA button
• Oversized, uniform padding throughout

Reference the actual design system (this project uses a green-400 → sky-500 gradient palette, Tailwind with custom utilities in globals.css, and Inter/Calistoga fonts).

Accessibility Requirements (WCAG 2.1 AA)

• Keyboard navigation works for all interactive elements
• Focus indicators are visible
• ARIA labels present on icon-only buttons and non-obvious interactive elements
• Color contrast ≥ 4.5:1 for normal text, ≥ 3:1 for large text
• Images have meaningful alt text (or alt="" for decorative images)
• Form inputs have associated labels
• Error states are communicated to screen readers
• Meaningful empty and loading states exist

Responsive Design

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

Apply mobile-first: write base styles for mobile, layer up with md: and lg: prefixes.

Component Checklist

Before marking a UI task complete:

• Renders correctly at all target breakpoints
• Keyboard navigable
• Accessible (ARIA, labels, contrast)
• Loading, error, and empty states handled
• Animations respect prefers-reduced-motion
• No console errors or warnings
• Verified in a real browser, not just TypeScript

Project-Specific Conventions

This is a Next.js 15 + React 19 + Tailwind portfolio. Key patterns:

• Use cn() from @/utils/helpers for conditional Tailwind classes
• Custom Tailwind utilities live in src/app/globals.css (.gradient-text, .gradient-bg, .hero-glow-ring, .center-abs-obj, etc.)
• SVGs are React components by default via @svgr/webpack; append ?url for a URL string
• Fonts: font-sans (Inter) and font-serif (Calistoga)
• Animation: use motion (Motion for React) — mark the component 'use client' when using hooks or motion

Red Flags

• Adding a new color palette that doesn't match the existing green/sky/gray theme
• Interactive elements that aren't keyboard accessible
• Hard-coding pixel values instead of Tailwind classes
• Client components where a Server Component would suffice