React Ui

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

  
    Tasks
  
  
    
  

// Avoid: Over-configured
}
/

Keep components focused:

// Good: Does one thing
export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {
  return (
    
       onToggle(task.id)} />
      {task.title}
       onDelete(task.id)}>
        
      
    
  );
}

Separate data fetching from presentation:

// Container: handles data
export function TaskListContainer() {
  const { tasks, isLoading, error } = useTasks();

  if (isLoading) return ;
  if (error) return ;
  if (tasks.length === 0) return ;

  return ;
}

// Presentation: handles rendering
export function TaskList({ tasks }: { tasks: Task[] }) {
  return (
    
      {tasks.map(task => )}
    
  );
}

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 | Production Quality | |---|---| | Purple/indigo everything | Use the project's actual color palette | | Excessive gradients | Flat or subtle gradients matching the design system | | Rounded everything (rounded-2xl) | Consistent border-radius from the design system | | Generic hero sections | Content-first layouts | | Lorem ipsum-style copy | Realistic placeholder content | | Oversized padding everywhere | Consistent spacing scale | | Stock card grids | Purpose-driven layouts | | Shadow-heavy design | 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.

Accessibility (WCAG 2.1 AA)

Every component must meet these standards:

For final WCAG 2.1 AA gating and verification, invoke the ui-accessibility skill and apply checks from references/accessibility-checklist.md.

Keyboard Navigation

// Every interactive element must be keyboard accessible
Click me        // ✓ Focusable by default
Click me               // ✗ Not focusable

     onKeyDown={e => e.key === 'Enter' && handleClick()}>
  Click me

Invocation Example

When finalizing a React component change, run this short flow:

• Start the dev server (npm start, pnpm dev, or equivalent).
• Run automated accessibility checks: npx axe-core ./path/to/page-or-story.html and/or npx pa11y http://localhost:3000/route.
• Run component/unit tests and Storybook visual checks where available (npm test, npm run test:visual).
• Final gating: invoke the ui-accessibility skill and attach the generated checklist report from references/accessibility-checklist.md.

• Agent invocation (one-liner): Invoke ui-accessibility attaching axe-report.json, pa11y-report.html, and manual-checks.md as artifacts.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: caraya
• Source: caraya/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.