ui-ux-expert-skill

UI/UX Expert Technical Skill

Version: 1.0.0 Agent: ui-ux-expert Last Updated: 2025-01-26

---

Purpose

This skill provides the complete technical workflow for implementing accessible, performant React user interfaces that:

• Pass 100% of E2E tests without modification
• Comply with WCAG 2.1 AA accessibility standards
• Follow the project's Style Guide exactly
• Achieve Core Web Vitals green metrics
• Integrate with implemented use cases (not data services directly)

---

6-PHASE WORKFLOW (MANDATORY)

PHASE 0: Style Guide Study (MANDATORY FIRST STEP)

Objective: Internalize the project's visual design system before ANY implementation.

⚠️ CRITICAL: This is the FIRST step. All implementations must reference the Style Guide.

Steps:

1. Read Style Guide completely:

   Read('.claude/STYLE_GUIDE.md')
   

2. Memorize key constraints:

   • Color Palette: 5 brand colors (Brand-1 through Brand-5) + semantic tokens
     • NO arbitrary hex values (e.g., bg-[#4A5FFF] is PROHIBITED)
     • ONLY use semantic tokens: bg-primary, text-foreground, border, etc.
   • Typography Scale: text-xs through text-4xl ONLY
     • NO arbitrary font sizes (e.g., text-[32px] is PROHIBITED)
   • Spacing Scale: spacing-1 (4px) through spacing-24 (96px) ONLY
     • NO arbitrary values (e.g., p-[17px] is PROHIBITED)
   • Animation Durations: 200ms, 300ms, or 500ms ONLY
     • NO other durations
   • Border Radius: --radius variable (default 0.5rem)

3. Note component conventions:

   • Hover states: hover:bg-accent, hover:shadow-lg
   • Focus states: focus:ring-2 focus:ring-ring
   • Disabled states: disabled:opacity-50 disabled:cursor-not-allowed
   • Dark mode: automatic via .dark class

Deliverable: Mental model of Style Guide constraints to apply during implementation.

---

PHASE 1: Component Research (BEFORE Design)

Objective: Consult Context7 and shadcn MCP for latest best practices BEFORE designing components.

⚠️ CRITICAL: Research first, design second. Avoid implementing outdated patterns.

Steps:

1. Context7: React patterns (MANDATORY)

   mcp__context7__get_library_docs({
     context7CompatibleLibraryID: "/reactjs/react.dev",
     topic: "hooks useEffect useState useMemo useCallback custom hooks best practices",
     tokens: 2500
   })
   

   Extract: Latest Hook patterns, composition strategies, performance tips

2. Context7: Next.js App Router (MANDATORY)

   mcp__context7__get_library_docs({
     context7CompatibleLibraryID: "/vercel/next.js",
     topic: "client components use client app router best practices",
     tokens: 2000
   })
   

   Extract: 'use client' directive usage, routing hooks, data fetching

3. Context7: Tailwind CSS (MANDATORY)

   mcp__context7__get_library_docs({
     context7CompatibleLibraryID: "/tailwindlabs/tailwindcss.com",
     topic: "responsive design mobile-first breakpoints animations utilities",
     tokens: 2000
   })
   

   Extract: Responsive patterns, utility combinations, animation classes

4. Context7: TanStack Query (MANDATORY)

   mcp__context7__get_library_docs({
     context7CompatibleLibraryID: "/tanstack/query",
     topic: "useQuery useMutation optimistic updates error handling",
     tokens: 2500
   })
   

   Extract: Data fetching patterns, cache invalidation, loading states

5. shadcn MCP: Component discovery (MANDATORY)

   mcp__shadcn__search_items_in_registries({
     registries: ['@shadcn'],
     query: "form input button card dialog", // Adjust based on feature
     limit: 20
   })
   
   mcp__shadcn__view_items_in_registries({
     items: ['@shadcn/button', '@shadcn/form', '@shadcn/dialog']
   })
   

   Extract: Available components, composition patterns, accessibility features

6. Additional Context7 queries (as needed):

   • React Hook Form: /react-hook-form/react-hook-form - "zodResolver validation errors"
   • Framer Motion (if animations needed): /grx7/framer-motion - "variants spring animations"

Deliverable: Notes on latest patterns to apply in design phase.

---

PHASE 2: Design Architecture (BEFORE Implementation)

Objective: Plan component hierarchy, state management, and user flows.

Steps:

1. Review E2E test specifications:

   // Read E2E tests to understand required user flows
   Read('app/e2e/{feature}.spec.ts')
   

   Extract:

   • Required data-testid selectors
   • User interaction sequences
   • Expected UI elements (buttons, forms, lists)
   • Success/error state behaviors

2. Design component hierarchy:

   ## Component Architecture
   
   ### Page Level (app/(main)/{feature}/page.tsx)
   - Route container
   - TanStack Query for data fetching
   - Layout composition
   
   ### Feature Components (features/{feature}/components/)
   - {Feature}List - Display collection
   - {Feature}Form - Create/Edit form
   - {Feature}Dialog - Modal interactions
   
   ### Presentation Components
   - {Feature}Item - Single item card
   - {Feature}Filters - Filter controls
   - {Feature}Stats - Statistics display
   
   ### Base Components (shadcn/ui)
   - Button, Input, Card, Dialog (composition, not modification)
   

3. Plan state management:

   ## State Strategy
   
   **Server State** (TanStack Query):
   - useQuery for reads (list, single item)
   - useMutation for writes (create, update, delete)
   - Query key structure: ['feature', ...params]
   
   **Form State** (React Hook Form):
   - Zod schema for validation
   - zodResolver integration
   - Accessible error messages
   
   **UI State** (Zustand - if needed):
   - Dialog open/close
   - Sidebar collapsed state
   - Theme preference (handled by next-themes)
   

4. Design user flows:

   ## Flow 1: Create {Entity}
   1. User clicks "Create" button
      → Opens dialog with form
   2. User fills fields (real-time validation)
   3. User submits
      → Loading state, disable form
   4. Success:
      → Close dialog, toast notification, refetch list
   5. Error:
      → Show error in form, keep dialog open, focus first error
   
   ## Flow 2: Edit {Entity}
   [Similar pattern...]
   
   ## Flow 3: Delete {Entity}
   [Similar pattern...]
   

5. Plan accessibility patterns:

   ## Accessibility Design
   
   **Keyboard Navigation**:
   - Tab order: logical flow
   - Enter: submit forms, activate buttons
   - Escape: close dialogs
   - Arrow keys: navigate lists
   
   **ARIA Labels**:
   - Icon buttons: aria-label with context
   - Form fields: htmlFor + id association
   - Loading states: aria-busy
   - Error messages: aria-invalid + aria-describedby
   
   **Focus Management**:
   - Auto-focus first field on dialog open
   - Return focus to trigger on close
   - Focus trap in modals
   

6. Plan responsive strategy:

   ## Responsive Design
   
   **Mobile (< 640px)**:
   - Single column layout
   - Stack cards vertically
   - Full-width buttons
   - Hide non-essential content
   
   **Tablet (640px - 1024px)**:
   - 2-column grid
   - Sidebar collapsible
   - Optimized spacing
   
   **Desktop (> 1024px)**:
   - 3-column grid
   - Fixed sidebar
   - Full feature set
   

Deliverable: Written design document covering hierarchy, state, flows, accessibility, and responsive strategy.

---

PHASE 3: Implementation (Following Design)

Objective: Build React components following the design from Phase 2.

🔐 CASL Integration (IF Authorization Required):

If E2E tests verify <Can> component visibility or the feature requires permission-based UI, implement CASL React integration FIRST before other components. See Pattern 0: CASL React Integration below.

Implementation Order (Bottom-Up):

0. CASL Integration (IF authorization required - implement FIRST)

   • AbilityContext provider
   • useAppAbility hook
   • Load ability in layout/page

1. Form Components (Highest Priority)

   • Complex, reusable
   • React Hook Form + Zod validation
   • Example: CreateTaskForm.tsx

2. List/Display Components

   • TanStack Query integration
   • Loading and error states
   • Example: TaskList.tsx

3. Action Components

   • Buttons, dialogs
   • Wire up mutations
   • Example: CreateTaskDialog.tsx

4. Page Integration

   • Compose all components
   • Test user flows
   • Example: app/(main)/tasks/page.tsx

Code Patterns:

Pattern 0: CASL React Integration (IF Authorization Required)

When to implement: If E2E tests verify <Can> component visibility or PRD specifies permission-based UI.

Step 0.1: Create Ability Context

File: features/{feature}/context/AbilityContext.tsx

'use client';

import { createContext, useContext, type ReactNode } from 'react';
import type { AppAbility } from '../entities';

const AbilityContext = createContext<AppAbility | null>(null);

export function AbilityProvider({
  ability,
  children,
}: {
  ability: AppAbility;
  children: ReactNode;
}) {
  return (
    <AbilityContext.Provider value={ability}>
      {children}
    </AbilityContext.Provider>
  );
}

export function useAppAbility() {
  const ability = useContext(AbilityContext);
  if (!ability) {
    throw new Error('useAppAbility must be used within AbilityProvider');
  }
  return ability;
}

Step 0.2: Load Ability in Layout/Page

File: app/(main)/{feature}/layout.tsx or app/(main)/{feature}/page.tsx

import { loadUserAbility } from '@/features/{feature}/use-cases/loadUserAbility';
import { AbilityProvider } from '@/features/{feature}/context/AbilityContext';
import { createClient } from '@/lib/supabase-server';
import { redirect } from 'next/navigation';

export default async function FeatureLayout({
  children,
}: {
  children: React.ReactNode;
}) {


---

*Content truncated.*