Ui Skills

To invoke the portfolio selection:

1. Detect when starting new UI work (not modifying existing components)
2. Present the portfolio selection from /docs/ui-portfolio/index.html
3. Once user selects a direction, apply that design system consistently

Skip portfolio selection only when:

• Modifying existing components (maintain current style)
• User explicitly requests a specific style
• Working in a codebase with established design system

Core Principles

1. Component Architecture

Single Responsibility

• Each component should do one thing well
• Extract complex logic into custom hooks or composables
• Keep components small and focused (< 200 lines)

Composition Over Complexity

// Good: Composable, reusable
<Card>
  <CardHeader>
    <CardTitle>Dashboard</CardTitle>
  </CardHeader>
  <CardContent>
    {children}
  </CardContent>
</Card>

// Avoid: Monolithic with too many props
<Card
  title="Dashboard"
  showHeader
  headerAlign="left"
  contentPadding="large"
  // ... 20 more props
/>

Props Design

• Use discriminated unions for variants
• Prefer children over render props when possible
• Make common use cases simple, advanced use cases possible
• Use TypeScript for prop validation

2. Accessibility (a11y)

Always Include

• Semantic HTML elements (<button>, <nav>, <main>, etc.)
• ARIA labels where needed (aria-label, aria-describedby)
• Keyboard navigation (Tab, Enter, Escape, Arrow keys)
• Focus management (visible focus states, focus trapping in modals)
• Color contrast ratios (WCAG AA minimum: 4.5:1 for text)

Common Patterns

// Accessible button
<button
  onClick={handleClick}
  aria-label="Close dialog"
  aria-pressed={isActive}
>
  <Icon aria-hidden="true" />
  Close
</button>

// Accessible form input
<div>
  <label htmlFor="email" className="block mb-2">
    Email Address
  </label>
  <input
    id="email"
    type="email"
    aria-describedby="email-hint"
    aria-invalid={hasError}
  />
  <span id="email-hint" className="text-sm text-gray-600">
    We'll never share your email
  </span>
</div>

// Skip to main content
<a href="#main-content" className="sr-only focus:not-sr-only">
  Skip to main content
</a>
<main id="main-content">
  {/* content */}
</main>

3. Responsive Design

Mobile-First Approach

• Start with mobile layout, enhance for larger screens
• Use Tailwind breakpoints: sm:, md:, lg:, xl:, 2xl:
• Test at breakpoints: 320px, 768px, 1024px, 1440px

Fluid Typography & Spacing

/* Use clamp for fluid sizing */
font-size: clamp(1rem, 2vw + 0.5rem, 2rem);

/* Or Tailwind responsive utilities */
<h1 className="text-2xl sm:text-3xl lg:text-5xl">

Container Queries (when supported)

@container (min-width: 400px) {
  .card { grid-template-columns: 1fr 1fr; }
}

4. State Management

Local State First

• Use component state (useState, ref) for UI-only state
• Lift state only when needed by multiple components
• Use context sparingly (avoid overuse)

Server State

• Use TanStack Query (React Query) for server data
• Implement optimistic updates for better UX
• Handle loading, error, and success states

Form State

• React Hook Form for complex forms
• Controlled vs uncontrolled inputs (prefer uncontrolled with refs)
• Validation with Zod or Yup

// Good: Server state with TanStack Query
const { data, isLoading, error } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
})

// Good: Form state with React Hook Form
const { register, handleSubmit, formState: { errors } } = useForm()

5. Performance

Lazy Loading

// Code splitting
const Dashboard = lazy(() => import('./Dashboard'))

// Image optimization
<Image
  src="/hero.jpg"
  alt="Hero"
  loading="lazy"
  width={1200}
  height={600}
/>

Memoization

• Use useMemo for expensive calculations
• Use useCallback for stable function references
• Use memo() for expensive components
• Don't over-optimize - profile first

Virtual Lists

• Use react-virtual for long lists (> 100 items)
• Implement infinite scroll with Intersection Observer

6. Styling Best Practices

Tailwind CSS

• Use @apply sparingly (components only)
• Prefer utility classes in JSX
• Extract repeated patterns to components, not @apply
• Use arbitrary values when needed: w-[347px]

Component Variants

// Using class-variance-authority (cva)
const buttonVariants = cva(
  "rounded font-medium transition-colors", // base
  {
    variants: {
      variant: {
        default: "bg-blue-600 text-white hover:bg-blue-700",
        outline: "border border-gray-300 hover:bg-gray-50",
        ghost: "hover:bg-gray-100",
      },
      size: {
        sm: "px-3 py-1.5 text-sm",
        md: "px-4 py-2 text-base",
        lg: "px-6 py-3 text-lg",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "md",
    },
  }
)

CSS Modules (when not using Tailwind)

• Use for component-scoped styles
• Name files Component.module.css
• Compose styles with composes

7. Component Patterns

Compound Components

// API that reads well
<Tabs defaultValue="overview">
  <TabsList>
    <TabsTrigger value="overview">Overview</TabsTrigger>
    <TabsTrigger value="analytics">Analytics</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">
    {/* content */}
  </TabsContent>
</Tabs>

Render Props (when composition isn't enough)

<DataFetcher url="/api/users">
  {({ data, loading, error }) => (
    loading ? <Spinner /> : <UserList users={data} />
  )}
</DataFetcher>

Slots Pattern (React, Vue)

// React
<Layout
  header={<Header />}
  sidebar={<Sidebar />}
  footer={<Footer />}
>
  {children}
</Layout>

8. Error Handling

Error Boundaries (React)

<ErrorBoundary fallback={<ErrorPage />}>
  <App />
</ErrorBoundary>

Error States in UI

if (error) {
  return (
    <Alert variant="error">
      <AlertTitle>Failed to load data</AlertTitle>
      <AlertDescription>
        {error.message}
        <Button onClick={retry}>Try Again</Button>
      </AlertDescription>
    </Alert>
  )
}

9. Animation & Transitions

Framer Motion (React)

<motion.div
  initial={{ opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
  exit={{ opacity: 0 }}
  transition={{ duration: 0.2 }}
>
  {content}
</motion.div>

CSS Transitions (Tailwind)

<div className="transition-all duration-200 hover:scale-105">

Reduced Motion

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

10. Testing

Component Tests

• Test user interactions, not implementation
• Use Testing Library queries (getByRole, getByLabelText)
• Test accessibility (keyboard nav, screen reader labels)

Visual Regression

• Consider Storybook + Chromatic for component libraries
• Screenshot tests for critical UI

Framework-Specific Guidance

React / Next.js

File Organization

src/
  components/
    ui/          # Reusable UI primitives (Button, Input, Card)
    features/    # Feature-specific components
  hooks/         # Custom hooks
  lib/           # Utilities, API clients
  app/           # Next.js app router

Server Components (Next.js 13+)

• Default to Server Components
• Use Client Components only when needed (interactivity, hooks)
• Pass server data as props to client components

Data Fetching

// Server Component
async function Page() {
  const data = await fetch('https://api.example.com/data')
  return <Dashboard data={data} />
}

// Client Component with TanStack Query
'use client'
function Dashboard() {
  const { data } = useQuery(...)
  return <div>{data}</div>
}

Vue / Nuxt

Composition API

• Prefer <script setup> syntax
• Use composables for reusable logic
• Leverage auto-imports

Reactivity

// Reactive state
const state = reactive({ count: 0 })

// Computed properties
const doubled = computed(() => state.count * 2)

// Watch for changes
watch(() => state.count, (newVal) => {
  console.log(newVal)
})

Svelte / SvelteKit

Reactivity

<script>
  let count = 0
  $: doubled = count * 2  // Reactive declaration
</script>

<button on:click={() => count++}>
  Count: {count}, Doubled: {doubled}
</button>

Stores

// Writable store
const count = writable(0)

// Derived store
const doubled = derived(count, $count => $count * 2)

// Auto-subscription in components
<script>
  import { count } from './stores'
</script>

<div>{$count}</div>

Common Anti-Patterns to Avoid

❌ Don't

Over-Abstraction

// TOO GENERIC
<FlexBox direction="column" justify="center" align="items" gap={4}>

Prop Drilling

• Passing props through 3+ levels
• Solution: Context, composition, or state management

Inline Functions in JSX (if causing perf issues)

// Can cause re-renders
<button onClick={() => handleClick(id)}>

Magic Numbers

// Bad
<div className="w-[347px] h-[291px]">

// Good
<div className="w-80 h-72"> // or semantic sizes

Ignoring Loading States

// Bad: Just shows nothing while loading
{data && <UserList users={data} />}

// Good: Show skeleton or spinner
{isLoading ? <Skeleton /> : <UserList users={data} />}

✅ Do

Use Semantic HTML

<button> for actions, not <div onClick>
<a> for navigation, not <div onClick>
<nav>, <main>, <article>, <section>

Keep Props Simple

// Good: Clear, typed props
interface ButtonProps {
  variant?: 'default' | 'outline' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  disabled?: boolean
  onClick?: () => void
  children: React.ReactNode
}

Handle Edge Cases

• Empty states (no data)
• Loading states (fetching data)
• Error states (failed request)
• Disabled states (form submission)

Tools & Libraries

Essential

• Tailwind CSS - Utility-first CSS
• TanStack Query - Server state management
• React Hook Form - Form state
• Zod - Schema validation

UI Components

• shadcn/ui - Copy-paste components
• Radix UI - Headless components
• Headless UI - Tailwind-specific

Animation

• Framer Motion - React animations
• Auto-animate - Drop-in animations

Icons

• Lucide React - Icon library
• Heroicons - Tailwind icons

Workflow

Starting New UI Work

1. Check for existing design system

   • Look for existing components in components/ui/
   • Check for Tailwind config, color schemes
   • Review any design documentation

2. If no design system exists

   • Invoke ui-portfolio-design skill
   • Present portfolio selection to user
   • Load chosen design system specifications

3. Build components

   • Start with semantic HTML
   • Apply styles (Tailwind or CSS Modules)
   • Add interactivity (event handlers, state)
   • Implement accessibility features
   • Handle loading/error states

4. Test & refine

   • Test keyboard navigation
   • Test at different screen sizes
   • Test with screen reader (if possible)
   • Review with user

Modifying Existing UI

1. Understand current patterns

   • Read existing component code
   • Identify naming conventions
   • Note styling approach (Tailwind, CSS Modules, etc.)

2. Maintain consistency

   • Match existing component structure
   • Use same styling patterns
   • Follow established naming conventions

3. Improve incrementally

   • Fix accessibility issues when found
   • Suggest refactors only when asked
   • Don't rewrite working code without reason

Best Practices Summary

1. Accessibility First - Always include semantic HTML, ARIA labels, keyboard nav
2. Mobile First - Start mobile, enhance for desktop
3. Performance - Lazy load, code split, optimize images
4. Composition - Small, reusable components
5. Type Safety - Use TypeScript for props and state
6. Error Handling - Always handle loading, error, empty states
7. Testing - Test user behavior, not implementation
8. Consistency - Follow existing patterns in the codebase

When to Ask for Clarification

• Design direction unclear - Invoke portfolio selection
• Accessibility requirements - Ask about target WCAG level
• Browser support - Ask about target browsers/devices
• Performance constraints - Ask about expected data volume
• State management - Ask if existing solution is in place

Remember: Before starting new UI work, consider invoking the ui-portfolio-design skill to select a design direction. This ensures intentional, cohesive aesthetics from the start.