ui-ux-expert-skill
Technical workflow for implementing accessible React user interfaces with shadcn/ui, Tailwind CSS, and TanStack Query. Includes 6-phase process with mandatory Style Guide compliance, Context7 best practices consultation, Chrome DevTools validation, and WCAG 2.1 AA accessibility standards. Use after Test Agent, Implementer, and Supabase agents complete their work.
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-22
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: ui-ux-expert-skill
description: Technical workflow for implementing accessible React user interfaces with shadcn/ui, Tailwind CSS, and TanStack Query. Includes 6-phase process with mandatory Style Guide compliance, Context7 best practices consultation, Chrome DevTools validation, and WCAG 2.1 AA accessibility standards. Use after Test Agent, Implementer, and Supabase agents complete their work.
---
# 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)
```typescript
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)
```typescript
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)
```typescript
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)
```typescript
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)
```typescript
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**:
```typescript
// 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**:
```markdown
## 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**:
```markdown
## 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**:
```markdown
## 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**:
```markdown
## 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**:
```markdown
## 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`
```typescript
'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`
```typescript
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;
}) {
// 1. Get authenticated user
const supabase = createClient();
const { data: { user }, error: authError } = await supabase.auth.getUser();
if (authError || !user) {
redirect('/login');
}
// 2. Get current workspace (from cookies or URL)
const workspaceId = 'workspace-id'; // TODO: Get from context
// 3. Load user's ability for this workspace
const ability = await loadUserAbility(user.id, workspaceId);
// 4. Provide ability to all child components
return (
<AbilityProvider ability={ability}>
{children}
</AbilityProvider>
);
}
```
**Step 0.3: Use in Components**
**Declarative visibility with `<Can>` component**:
```typescript
'use client';
import { Can } from '@casl/react';
import { useAppAbility } from '../context/AbilityContext';
import { Button } from '@/components/ui/button';
import { Trash2, Edit, Plus } from 'lucide-react';
export function BoardActions({ board }: { board: Board }) {
const ability = useAppAbility();
return (
<div className="flex gap-2">
{/* Show button ONLY if user can create boards */}
<Can I="create" a="Board" ability={ability}>
<Button variant="default">
<Plus className="mr-2 h-4 w-4" />
Create
</Button>
</Can>
{/* Show button ONLY if user can update boards */}
<Can I="update" a="Board" ability={ability}>
<Button variant="secondary">
<Edit className="mr-2 h-4 w-4" />
Edit
</Button>
</Can>
{/* Show button ONLY if user can delete boards */}
<Can I="delete" a="Board" ability={ability}>
<Button variant="destructive">
<Trash2 className="mr-2 h-4 w-4" />
Delete
</Button>
</Can>
</div>
);
}
```
**Programmatic checks with `ability.can()`**:
```typescript
'use client';
import { useAppAbility } from '../context/AbilityContext';
import { Button } from '@/components/ui/button';
import { Settings } from 'lucide-react';
export function BoardHeader({ board }: { board: Board }) {
const ability = useAppAbility();
// Complex conditional rendering
const canManage = ability.can('update', 'Board') && ability.can('delete', 'Board');
return (
<div className="flex items-center justify-between">
<h1>{board.name}</h1>
{/* Conditional rendering based on multiple abilities */}
{canManage && (
<Button variant="outline">
<Settings className="mr-2 h-4 w-4" />
Manage Board
</Button>
)}
{/* Disable button if user cannot perform action */}
<Button
disabled={!ability.can('archive', 'Board')}
onClick={() => archiveBoard(board.id)}
>
Archive
</Button>
</div>
);
}
```
**Field-level permissions**:
```typescript
'use client';
import { Can } from '@casl/react';
import { useAppAbility } from '../context/AbilityContext';
export function BoardDetails({ board }: { board: Board }) {
const ability = useAppAbility();
return (
<div>
<p>Name: {board.name}</p>
<p>Description: {board.description}</p>
{/* Show sensitive field ONLY if user can read it */}
<Can I="read" a="Board" field="settings" ability={ability}>
<p>Settings: {JSON.stringify(board.settings)}</p>
</Can>
</div>
);
}
```
**CASL Implementation Checklist**:
- [ ] ✅ AbilityContext.tsx created with provider and hook
- [ ] ✅ AbilityProvider wraps feature in layout/page
- [ ] ✅ loadUserAbility() called server-side
- [ ] ✅ `<Can>` component used for show/hide logic
- [ ] ✅ `ability.can()` used for complex conditional rendering
- [ ] ✅ Buttons disabled (not just hidden) when user lacks permission
- [ ] ✅ Field-level permissions implemented (if applicable)
- [ ] ✅ E2E tests pass (verify visibility matches permissions)
- [ ] ✅ No console errors about missing AbilityContext
**Critical Rules**:
- ✅ ALWAYS use `<Can>` for simple show/hide (cleaner, declarative)
- ✅ Use `ability.can()` for complex logic (multiple checks, computed values)
- ✅ Disable buttons when user can't act (better UX than hiding)
- ✅ Wrap pages/layouts with AbilityProvider (not individual components)
- ❌ NEVER implement authorization logic in components (use ability)
- ❌ NEVER bypass CASL checks to "improve UX" (security first)
- ❌ NEVER call useAppAbility() outside AbilityProvider (will throw error)
---
#### Pattern 1: Page Component
```typescript
'use client'
import { useQuery } from '@tanstack/react-query'
import { taskUseCases } from '@/features/tasks/use-cases'
import { TaskList } from '@/features/tasks/components/TaskList'
import { CreateTaskDialog } from '@/features/tasks/components/CreateTaskDialog'
import { Button } from '@/components/ui/button'
import { Plus } from 'lucide-react'
import { useState } from 'react'
export default function TasksPage() {
const [createDialogOpen, setCreateDialogOpen] = useState(false)
const { data: tasks, isLoading, error } = useQuery({
queryKey: ['tasks'],
queryFn: taskUseCases.getTasks,
})
return (
<div className="container mx-auto px-4 py-8">
{/* Header */}
<div className="flex items-center justify-between mb-6">
<div>
<h1 className="text-3xl font-bold text-foreground">Tasks</h1>
<p className="text-sm text-muted-foreground">
Manage your tasks and track progress
</p>
</div>
<Button
onClick={() => setCreateDialogOpen(true)}
data-testid="create-task-button"
>
<Plus className="mr-2 h-4 w-4" />
Create Task
</Button>
</div>
{/* Content */}
{isLoading && <TaskListSkeleton />}
{error && <ErrorDisplay error={error} />}
{tasks && <TaskList tasks={tasks} />}
{/* Dialogs */}
<CreateTaskDialog
open={createDialogOpen}
onOpenChange={setCreateDialogOpen}
/>
</div>
)
}
```
#### Pattern 2: Form Component
```typescript
'use client'
import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { TaskCreateSchema, type TaskCreate } from '../entities'
import { taskUseCases } from '../use-cases'
import { useTranslations } from 'next-intl'
import {
Form,
FormControl,
FormField,
FormItem,
FormLabel,
FormMessage,
} from '@/components/ui/form'
import { Input } from '@/components/ui/input'
import { Button } from '@/components/ui/button'
import { toast } from 'sonner'
interface TaskFormProps {
onSuccess?: () => void
}
export function TaskForm({ onSuccess }: TaskFormProps) {
const t = useTranslations('tasks')
const queryClient = useQueryClient()
// Create Zod schema inside component for translation access
const form = useForm<TaskCreate>({
resolver: zodResolver(TaskCreateSchema),
defaultValues: {
title: '',
description: '',
status: 'pending',
},
})
const createMutation = useMutation({
mutationFn: taskUseCases.createTask,
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: ['tasks'] })
toast.success(t('create.success'))
form.reset()
onSuccess?.()
},
onError: (error) => {
toast.error(t('create.error'), {
description: error.message,
})
},
})
return (
<Form {...form}>
<form onSubmit={form.handleSubmit((data) => createMutation.mutate(data))}>
<FormField
control={form.control}
name="title"
render={({ field }) => (
<FormItem>
<FormLabel htmlFor="title">{t('form.title.label')}</FormLabel>
<FormControl>
<Input
id="title"
data-testid="task-title-input"
{...field}
/>
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<Button
type="submit"
disabled={createMutation.isPending}
data-testid="submit-button"
>
{createMutation.isPending ? t('form.submitting') : t('form.submit')}
</Button>
</form>
</Form>
)
}
```
#### Pattern 3: Responsive Component
```typescript
<div className="
grid
grid-cols-1 /* Mobile: 1 column */
md:grid-cols-2 /* Tablet: 2 columns */
lg:grid-cols-3 /* Desktop: 3 columns */
gap-4 md:gap-6 /* Responsive gap */
p-4 md:p-6 lg:p-8 /* Responsive padding */
">
{items.map(item => <ItemCard key={item.id} item={item} />)}
</div>
```
**Critical Rules**:
- ✅ Use `data-testid` from E2E tests
- ✅ Use `useTranslations()` for ALL text (NO hardcoded strings)
- ✅ Use semantic tokens from Style Guide (NO arbitrary values)
- ✅ Integrate with use cases via TanStack Query (NOT data services)
- ✅ Add ARIA labels for icon buttons
- ✅ Ensure keyboard navigation works
**Deliverable**: Implemented React components following all patterns.
---
### PHASE 4: Validation (Chrome DevTools + Accessibility)
**Objective**: Verify implementation meets all quality standards.
**Steps**:
1. **Run E2E tests** (MANDATORY - must pass 100%)
```bash
cd app
npm run test:e2e -- --grep "{feature}"
```
**Expected**: ALL tests GREEN ✅
**If RED**: Fix implementation (DO NOT modify tests)
2. **Visual verification with Chrome DevTools MCP** (MANDATORY)
```typescript
// Start browser session
mcp__chrome_devtools__new_page()
// Navigate to feature
mcp__chrome_devtools__navigate_page({