paulund/frontend-ui-engineering

Core Workflow

1. Component architecture — colocate implementation, tests, and hooks in one directory per component. Prefer composition over configuration. Separate data-fetching containers from presentation components. Split any component over 200 lines.

2. State management — choose the simplest approach that works:

   • useState → component-specific UI state
   • Lifted state → shared between 2–3 siblings
   • URL state (searchParams) → filters, pagination, shareable UI state
   • Server state (React Query / SWR) → remote data with caching
   • Global store (Zustand) → complex client state shared app-wide
   • Avoid prop drilling deeper than 3 levels

3. Avoid the AI aesthetic — AI-generated UI has recognisable patterns. Avoid all of them:

   | AI Default | Production Quality | |---|---| | Purple/indigo everything | Use the project's actual colour palette | | Excessive gradients | Flat or subtle gradients matching the design system | | rounded-2xl on everything | Consistent border-radius from the design system | | Equal oversized padding everywhere | Consistent spacing scale; hierarchy through variation | | Stock card grids | Purpose-driven layouts based on content priority | | Lorem ipsum placeholder copy | Realistic content that reveals actual layout problems |

4. Accessibility (WCAG 2.1 AA) — every interactive element must be keyboard-accessible. Label all inputs (<label htmlFor> or aria-label). Manage focus when dialogs open. Never rely on colour alone to convey state — always pair with text or an icon.

5. Responsive — mobile-first. Use the project's breakpoint scale. Test at 320px, 768px, 1024px, and 1440px before marking any layout task done.

6. Loading / error / empty states — all three must be handled for every data-driven component. Never show a blank screen. Use skeleton loading (not spinners) for content areas.

Common Rationalizations

| Rationalization | Reality | |---|---| | "Accessibility is a nice-to-have" | Legal requirement in many jurisdictions and an engineering quality standard. | | "We'll make it responsive later" | Retrofitting responsive design is 3× harder than building it from the start. | | "The AI aesthetic is fine for now" | It signals low quality to reviewers. Use the project's design system from the start. | | "This is just a prototype" | Prototypes become production code. Build the foundation right. | | "I'll add error/empty states later" | "Later" doesn't happen. Three states, handled once, cost less than fixing them post-launch. |

Red Flags

• [ ] Components over 200 lines
• [ ] Inline styles or arbitrary pixel values outside the spacing scale
• [ ] Missing error, loading, or empty states
• [ ] Interactive elements not reachable by keyboard
• [ ] Colour as the sole indicator of state (red/green without text or icon)
• [ ] Generic AI aesthetic (purple palette, rounded-2xl on everything, equal oversized padding, stock card grids)
• [ ] Prop drilling deeper than 3 levels

Verification

After building UI:

• [ ] Renders without console errors or warnings
• [ ] All interactive elements are keyboard-accessible (Tab through the page end-to-end)
• [ ] 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 scale, colour tokens, typography)
• [ ] No accessibility warnings in DevTools or axe-core

Constraints

MUST DO

• Handle loading, error, and empty states for every data-driven component.
• Follow the project's spacing scale — no arbitrary pixel values.
• Test keyboard navigation before shipping any interactive component.
• Use the project's colour tokens — not raw hex or Tailwind palette defaults.

MUST NOT DO

• Use colour alone to convey state — always pair with text, icon, or pattern.
• Skip empty or error states ("we'll add them later").
• Apply the AI aesthetic defaults: purple/indigo palette, rounded-2xl on everything, equal oversized padding, stock card grids.

Reference Guide

| Topic | Reference | Load When | |-------|-----------|----------| | Accessibility Checklist | references/accessibility-checklist.md | Implementing or auditing any interactive component for WCAG 2.1 AA compliance |