@incidental/project-templates/templates/skills/ui-builder/SKILL.md

Claude Code template library for JavaScript projects with framework auto-detection

---
name: ui-builder
description: Build UI components with proper styling, accessibility, and responsive design
allowed-tools: Read, Write, Edit, Grep, Glob
---

# UI Builder Skill

Build accessible, responsive UI components following design best practices.

## When to Use

Use this skill when you need to:
- Create new UI components
- Build forms with validation
- Implement responsive layouts
- Add accessibility features
- Style components consistently

## What This Skill Does

This skill generates production-ready UI components including:

1. **Component structure** with proper TypeScript types
2. **Styling** using Tailwind CSS, CSS Modules, or styled-components
3. **Accessibility** with ARIA attributes and keyboard navigation
4. **Responsiveness** with mobile-first approach
5. **Prop validation** with TypeScript interfaces
6. **Documentation** with JSDoc and usage examples

## Component Template

### Basic Component Structure
```typescript
import React from 'react'

interface ComponentProps {
  /** Component description */
  variant?: 'primary' | 'secondary' | 'outline'
  /** Size of the component */
  size?: 'sm' | 'md' | 'lg'
  /** Optional CSS classes */
  className?: string
  /** Child elements */
  children: React.ReactNode
  /** Click handler */
  onClick?: () => void
  /** Disabled state */
  disabled?: boolean
}

/**
 * Component description
 *
 * @example
 * <Component variant="primary" size="md">
 *   Click me
 * </Component>
 */
export default function Component({
  variant = 'primary',
  size = 'md',
  className = '',
  children,
  onClick,
  disabled = false
}: ComponentProps) {
  return (
    <button
      className={`component ${variant} ${size} ${className}`}
      onClick={onClick}
      disabled={disabled}
      aria-disabled={disabled}
    >
      {children}
    </button>
  )
}
```

## Accessibility Guidelines

### Semantic HTML
- Use proper HTML elements (`<button>`, `<nav>`, `<main>`, etc.)
- Add `<label>` for all form inputs
- Use `<fieldset>` and `<legend>` for form groups

### ARIA Attributes
- `aria-label` for buttons without text
- `aria-labelledby` for complex labels
- `aria-describedby` for descriptions
- `aria-expanded` for collapsible elements
- `aria-hidden` for decorative elements

### Keyboard Navigation
- Ensure all interactive elements are focusable
- Add keyboard event handlers (Enter, Space, Escape, Arrow keys)
- Maintain logical tab order
- Show visible focus indicators

### Screen Reader Support
- Provide text alternatives for images
- Use proper heading hierarchy
- Announce dynamic content changes
- Provide skip links for navigation

## Responsive Design

### Mobile-First Approach
```css
/* Base styles for mobile */
.component {
  padding: 0.5rem;
  font-size: 0.875rem;
}

/* Tablet and up */
@media (min-width: 768px) {
  .component {
    padding: 1rem;
    font-size: 1rem;
  }
}

/* Desktop and up */
@media (min-width: 1024px) {
  .component {
    padding: 1.5rem;
    font-size: 1.125rem;
  }
}
```

### Tailwind CSS Responsive Classes
```tsx
<div className="p-2 text-sm md:p-4 md:text-base lg:p-6 lg:text-lg">
  Responsive content
</div>
```

## Form Components

### Input with Validation
```typescript
interface InputProps {
  label: string
  name: string
  type?: string
  error?: string
  required?: boolean
  value: string
  onChange: (value: string) => void
}

export function Input({
  label,
  name,
  type = 'text',
  error,
  required = false,
  value,
  onChange
}: InputProps) {
  return (
    <div className="form-field">
      <label htmlFor={name}>
        {label}
        {required && <span aria-label="required">*</span>}
      </label>
      <input
        id={name}
        name={name}
        type={type}
        value={value}
        onChange={(e) => onChange(e.target.value)}
        required={required}
        aria-invalid={!!error}
        aria-describedby={error ? `${name}-error` : undefined}
      />
      {error && (
        <span id={`${name}-error`} className="error" role="alert">
          {error}
        </span>
      )}
    </div>
  )
}
```

## Styling Best Practices

- Use consistent spacing scale (4px, 8px, 16px, 24px, 32px, etc.)
- Maintain color contrast ratios (4.5:1 for text, 3:1 for large text)
- Use semantic color names (primary, secondary, success, error, etc.)
- Implement dark mode support
- Use CSS variables for theming
- Keep specificity low (avoid deep nesting)
- Follow BEM or similar naming convention