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.\"
\nColocate everything related to a component:
\nsrc/components/\n TaskList/\n TaskList.tsx # Component implementation\n TaskList.test.tsx # Tests\n TaskList.stories.tsx # Storybook stories (if using)\n use-task-list.ts # Custom hook (if complex state)\n types.ts # Component-specific types (if needed)\nPrefer composition over configuration:
\n// Good: Composable\n<Card>\n <CardHeader>\n <CardTitle>Tasks</CardTitle>\n </CardHeader>\n <CardBody>\n <TaskList tasks={tasks} />\n </CardBody>\n</Card>\n\n// Avoid: Over-configured\n<Card\n title=\"Tasks\"\n headerVariant=\"large\"\n bodyPadding=\"md\"\n content={<TaskList tasks={tasks} />}\n/>\nKeep components focused:
\n// Good: Does one thing\nexport function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {\n return (\n <li className=\"flex items-center gap-3 p-3\">\n <Checkbox checked={task.done} onChange={() => onToggle(task.id)} />\n <span className={task.done ? 'line-through text-muted' : ''}>{task.title}</span>\n <Button variant=\"ghost\" size=\"sm\" onClick={() => onDelete(task.id)}>\n <TrashIcon />\n </Button>\n </li>\n );\n}\nSeparate data fetching from presentation:
\n// Container: handles data\nexport function TaskListContainer() {\n const { tasks, isLoading, error } = useTasks();\n\n if (isLoading) return <TaskListSkeleton />;\n if (error) return <ErrorState message=\"Failed to load tasks\" retry={refetch} />;\n if (tasks.length === 0) return <EmptyState message=\"No tasks yet\" />;\n\n return <TaskList tasks={tasks} />;\n}\n\n// Presentation: handles rendering\nexport function TaskList({ tasks }: { tasks: Task[] }) {\n return (\n <ul role=\"list\" className=\"divide-y\">\n {tasks.map(task => <TaskItem key={task.id} task={task} />)}\n </ul>\n );\n}\nChoose the simplest approach that works:
\nLocal state (useState) → Component-specific UI state\nLifted state → Shared between 2-3 sibling components\nContext → Theme, auth, locale (read-heavy, write-rare)\nURL state (searchParams) → Filters, pagination, shareable UI state\nServer state (React Query, SWR) → Remote data with caching\nGlobal store (Zustand, Redux) → Complex client state shared app-wide\nAvoid 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.
\nAI-generated UI has recognizable patterns. Avoid all of them:
\n| AI Default | \nWhy It Is a Problem | \nProduction Quality | \n
|---|---|---|
| Purple/indigo everything | \nModels default to visually \"safe\" palettes, making every app look identical | \nUse the project's actual color palette | \n
| Excessive gradients | \nGradients add visual noise and clash with most design systems | \nFlat or subtle gradients matching the design system | \n
| Rounded everything (rounded-2xl) | \nMaximum rounding signals \"friendly\" but ignores the hierarchy of corner radii in real designs | \nConsistent border-radius from the design system | \n
| Generic hero sections | \nTemplate-driven layout with no connection to the actual content or user need | \nContent-first layouts | \n
| Lorem ipsum-style copy | \nPlaceholder text hides layout problems that real content reveals (length, wrapping, overflow) | \nRealistic placeholder content | \n
| Oversized padding everywhere | \nEqual generous padding destroys visual hierarchy and wastes screen space | \nConsistent spacing scale | \n
| Stock card grids | \nUniform grids are a layout shortcut that ignores information priority and scanning patterns | \nPurpose-driven layouts | \n
| Shadow-heavy design | \nLayered shadows add depth that competes with content and slows rendering on low-end devices | \nSubtle or no shadows unless the design system specifies | \n
Use a consistent spacing scale. Don't invent values:
\n/* Use the scale: 0.25rem increments (or whatever the project uses) */\n/* Good */ padding: 1rem; /* 16px */\n/* Good */ gap: 0.75rem; /* 12px */\n/* Bad */ padding: 13px; /* Not on any scale */\n/* Bad */ margin-top: 2.3rem; /* Not on any scale */\nRespect the type hierarchy:
\nh1 → Page title (one per page)\nh2 → Section title\nh3 → Subsection title\nbody → Default text\nsmall → Secondary/helper text\nDon't skip heading levels. Don't use heading styles for non-heading content.
\ntext-primary, bg-surface, border-default — not raw hex valuesEvery component must meet these standards:
\n// Every interactive element must be keyboard accessible\n<button onClick={handleClick}>Click me</button> // ✓ Focusable by default\n<div onClick={handleClick}>Click me</div> // ✗ Not focusable\n<div role=\"button\" tabIndex={0} onClick={handleClick} // ✓ But prefer <button>\n onKeyDown={e => {\n if (e.key === 'Enter') handleClick();\n if (e.key === ' ') e.preventDefault();\n }}\n onKeyUp={e => {\n if (e.key === ' ') handleClick();\n }}>\n Click me\n</div>\n// Label interactive elements that lack visible text\n<button aria-label=\"Close dialog\"><XIcon /></button>\n\n// Label form inputs\n<label htmlFor=\"email\">Email</label>\n<input id=\"email\" type=\"email\" />\n\n// Or use aria-label when no visible label exists\n<input aria-label=\"Search tasks\" type=\"search\" />\n// Move focus when content changes\nfunction Dialog({ isOpen, onClose }: DialogProps) {\n const closeRef = useRef<HTMLButtonElement>(null);\n\n useEffect(() => {\n if (isOpen) closeRef.current?.focus();\n }, [isOpen]);\n\n // Trap focus inside dialog when open\n return (\n <dialog open={isOpen}>\n <button ref={closeRef} onClick={onClose}>Close</button>\n {/* dialog content */}\n </dialog>\n );\n}\n// Don't show blank screens\nfunction TaskList({ tasks }: { tasks: Task[] }) {\n if (tasks.length === 0) {\n return (\n <div role=\"status\" className=\"text-center py-12\">\n <TasksEmptyIcon className=\"mx-auto h-12 w-12 text-muted\" />\n <h3 className=\"mt-2 text-sm font-medium\">No tasks</h3>\n <p className=\"mt-1 text-sm text-muted\">Get started by creating a new task.</p>\n <Button className=\"mt-4\" onClick={onCreateTask}>Create Task</Button>\n </div>\n );\n }\n\n return <ul role=\"list\">...</ul>;\n}\nDesign for mobile first, then expand:
\n// Tailwind: mobile-first responsive\n<div className=\"\n grid grid-cols-1 /* Mobile: single column */\n sm:grid-cols-2 /* Small: 2 columns */\n lg:grid-cols-3 /* Large: 3 columns */\n gap-4\n\">\nTest at these breakpoints: 320px, 768px, 1024px, 1440px.
\n// Skeleton loading (not spinners for content)\nfunction TaskListSkeleton() {\n return (\n <div className=\"space-y-3\" aria-busy=\"true\" aria-label=\"Loading tasks\">\n {Array.from({ length: 3 }).map((_, i) => (\n <div key={i} className=\"h-12 bg-muted animate-pulse rounded\" />\n ))}\n </div>\n );\n}\n\n// Optimistic updates for perceived speed\nfunction useToggleTask() {\n const queryClient = useQueryClient();\n\n return useMutation({\n mutationFn: toggleTask,\n onMutate: async (taskId) => {\n await queryClient.cancelQueries({ queryKey: ['tasks'] });\n const previous = queryClient.getQueryData(['tasks']);\n\n queryClient.setQueryData(['tasks'], (old: Task[]) =>\n old.map(t => t.id === taskId ? { ...t, done: !t.done } : t)\n );\n\n return { previous };\n },\n onError: (_err, _taskId, context) => {\n queryClient.setQueryData(['tasks'], context?.previous);\n },\n });\n}\nFor detailed accessibility requirements and testing tools, see references/accessibility-checklist.md.
| Rationalization | \nReality | \n
|---|---|
| \"Accessibility is a nice-to-have\" | \nIt's a legal requirement in many jurisdictions and an engineering quality standard. | \n
| \"We'll make it responsive later\" | \nRetrofitting responsive design is 3x harder than building it from the start. | \n
| \"The design isn't final, so I'll skip styling\" | \nUse the design system defaults. Unstyled UI creates a broken first impression for reviewers. | \n
| \"This is just a prototype\" | \nPrototypes become production code. Build the foundation right. | \n
| \"The AI aesthetic is fine for now\" | \nIt signals low quality. Use the project's actual design system from the start. | \n
After building UI:
\n