pastel-ui/README.md

# Pastel UI

> A modern, interactive web application for color manipulation, palette generation, and accessibility analysis.

[![Next.js](https://img.shields.io/badge/Next.js-16-black?logo=next.js)](https://nextjs.org)
[![React](https://img.shields.io/badge/React-19-blue?logo=react)](https://react.dev)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind-4-38bdf8?logo=tailwind-css)](https://tailwindcss.com)
[![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6?logo=typescript)](https://www.typescriptlang.org)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Pastel UI is a beautiful, feature-rich interface powered by WebAssembly for **zero-latency, offline-first** color manipulation, palette generation, and accessibility testing.

## ⚡ Key Benefits

- **🚀 Zero Latency** - All operations run locally via WebAssembly (130KB)
- **📱 Offline First** - Works completely offline after initial load
- **🌐 No Backend** - Fully static, deploy anywhere (2.2MB total)
- **⚡ Fast** - Native-speed color operations in the browser
- **🎨 Feature-Rich** - 18 color operations, 6 palette types, accessibility tools

## Features

### 🎨 Color Playground
- **Interactive Color Picker** - Real-time color selection with live preview
- **Multi-Format Support** - Hex, RGB, HSL, HSV, Lab, OkLab, LCH, OkLCH, CMYK, Gray, and 148 named colors
- **Color Manipulation** - Lighten, darken, saturate, desaturate, rotate, complement, mix, grayscale
- **Format Conversion** - Convert between any color format with one click
- **Copy to Clipboard** - Quick copy for all formats

### 🎭 Palette Generation
- **Harmony Palettes** - Monochromatic, analogous, complementary, split-complementary, triadic, tetradic
- **Distinct Colors** - Generate visually distinct colors using simulated annealing algorithm
- **Gradient Creator** - Multi-stop gradients with color space selection (RGB, HSL, Lab, LCH, OkLab, OkLCH)
- **Export Options** - CSS, JSON, Tailwind config, SCSS, SVG, PNG

### ♿ Accessibility Tools
- **WCAG Contrast Checker** - AA/AAA compliance analysis for text and backgrounds
- **Color Blindness Simulator** - Protanopia, deuteranopia, tritanopia simulation
- **Text Color Optimizer** - Find optimal text color for any background
- **Batch Accessibility Testing** - Test entire palettes at once

### 🔍 Color Analysis
- **Perceptual Distance** - CIE76 and CIEDE2000 metrics
- **Color Sorting** - Sort by hue, brightness, luminance, chroma
- **Named Color Search** - Find nearest named color for any input
- **Color Information** - Comprehensive color data in all formats

### ⚡ Advanced Features
- **Batch Operations** - Upload CSV/JSON, process multiple colors, download results
- **Color History** - Track all colors used in your session
- **Saved Palettes** - Persistent storage of your favorite palettes
- **Command Palette** - Keyboard shortcuts (Cmd+K) for power users
- **Dark/Light Mode** - System preference + manual toggle
- **Shareable Links** - Share colors and palettes via URL

## Tech Stack

- **[Next.js 16](https://nextjs.org)** - React framework with App Router and Server Components
- **[React 19](https://react.dev)** - Latest React with improved concurrent features
- **[Tailwind CSS 4](https://tailwindcss.com)** - CSS-first utility framework with modern color spaces
- **[TypeScript](https://www.typescriptlang.org)** - Strict type safety throughout
- **[@valknarthing/pastel-wasm](https://www.npmjs.com/package/@valknarthing/pastel-wasm)** - WebAssembly color engine for zero-latency operations
- **[React Query](https://tanstack.com/query)** - Server state management and caching
- **[Zustand](https://github.com/pmndrs/zustand)** - Client state management
- **[Framer Motion](https://www.framer.com/motion/)** - Smooth animations and transitions
- **[Lucide React](https://lucide.dev)** - Beautiful icon set

## Quick Start

### Prerequisites

- **Node.js** 18+ (20+ recommended)
- **pnpm** 9+ (or npm/yarn)

### Installation

```bash
# Clone the repository
git clone git@github.com:valknarness/pastel-ui.git
cd pastel-ui

# Install dependencies
pnpm install

# Run development server
pnpm dev
```

Open [http://localhost:3000](http://localhost:3000) in your browser.

**Note**: All color operations run locally in WebAssembly - no backend API required!

## Development

### Available Commands

```bash
# Development
pnpm dev              # Start dev server (http://localhost:3000)
pnpm dev:turbo        # Start with Turbopack (faster)

# Building & Deployment
pnpm build            # Build static export (outputs to out/)
pnpm export           # Alias for build (static export)
pnpm serve            # Build and serve static files locally

# Code Quality
pnpm lint             # Run ESLint
pnpm lint:fix         # Fix ESLint issues automatically
pnpm format           # Format code with Prettier
pnpm type-check       # TypeScript type checking

# Testing
pnpm test             # Run unit tests (Vitest)
pnpm test:ui          # Vitest UI mode
pnpm test:e2e         # Run E2E tests (Playwright)
pnpm test:e2e:ui      # Playwright UI mode

# Analysis
pnpm analyze          # Analyze bundle size
```

### Project Structure

```
pastel-ui/
├── app/                    # Next.js App Router
│   ├── playground/        # Color manipulation tool
│   ├── palettes/          # Palette generation
│   ├── accessibility/     # Accessibility tools
│   ├── names/             # Named colors explorer
│   └── batch/             # Batch operations
├── components/
│   ├── ui/               # Base UI components
│   ├── color/            # Color-specific components
│   ├── tools/            # Tool components
│   └── layout/           # Layout components
├── lib/
│   ├── api/              # API client and queries
│   ├── utils/            # Utility functions
│   ├── hooks/            # Custom React hooks
│   └── stores/           # Zustand stores
└── tests/                # Unit and E2E tests
```

See [CLAUDE.md](CLAUDE.md) for detailed architecture documentation.

## Features Overview

### Color Playground (`/`)

The main interface for color manipulation:

- Input colors in any format
- View comprehensive color information
- Manipulate colors with intuitive controls
- Convert between formats instantly
- Copy values with one click

### Palette Generation (`/palettes`)

Create beautiful color palettes:

#### Harmony Palettes (`/palettes/harmony`)
Generate palettes based on color theory:
- **Monochromatic** - Variations of a single hue
- **Analogous** - Adjacent colors on the wheel
- **Complementary** - Opposite colors
- **Split-complementary** - Base + two adjacent to complement
- **Triadic** - Three evenly spaced colors
- **Tetradic** - Four colors in a rectangle

#### Distinct Colors (`/palettes/distinct`)
Generate visually distinct colors using advanced algorithms:
- Configurable count (2-100 colors)
- Distance metric selection (CIE76, CIEDE2000)
- Optional fixed colors to include
- Real-time progress indicator

#### Gradient Creator (`/palettes/gradient`)
Create smooth color gradients:
- Multiple color stops
- Configurable step count
- Color space selection for interpolation
- Live preview
- Export as CSS or color array

### Accessibility Tools (`/accessibility`)

Ensure your colors are accessible:

#### Contrast Checker (`/accessibility/contrast`)
- WCAG 2.1 compliance testing
- AA/AAA ratings for normal and large text
- Contrast ratio calculation
- Improvement recommendations

#### Color Blindness Simulator (`/accessibility/colorblind`)
- Simulate protanopia (red-blind)
- Simulate deuteranopia (green-blind)
- Simulate tritanopia (blue-blind)
- Side-by-side comparison
- Batch palette testing

### Named Colors Explorer (`/names`)

Browse and search 148 CSS/X11 named colors:
- Visual grid display
- Search by name or hex value
- Sort by hue, brightness, saturation, name
- Find nearest named color for any input
- Click to use in playground

### Batch Operations (`/batch`)

Process multiple colors efficiently:
- Upload CSV/JSON files
- Apply operations to all colors
- Bulk format conversion
- Visual preview of results
- Download in multiple formats

## Export Formats

Export your colors and palettes in various formats:

### CSS Variables
```css
:root {
  --color-primary: #ff0099;
  --color-secondary: #00ccff;
  --color-accent: #ffcc00;
}
```

### Tailwind Config
```javascript
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#ff0099',
        secondary: '#00ccff',
        accent: '#ffcc00',
      }
    }
  }
}
```

### JSON
```json
{
  "colors": [
    { "name": "primary", "hex": "#ff0099" },
    { "name": "secondary", "hex": "#00ccff" },
    { "name": "accent", "hex": "#ffcc00" }
  ]
}
```

### SCSS
```scss
$color-primary: #ff0099;
$color-secondary: #00ccff;
$color-accent: #ffcc00;
```

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Cmd/Ctrl + K` | Open command palette |
| `Cmd/Ctrl + C` | Copy current color (hex) |
| `Cmd/Ctrl + V` | Paste color from clipboard |
| `Cmd/Ctrl + Z` | Undo color change |
| `Cmd/Ctrl + Shift + Z` | Redo color change |
| `Cmd/Ctrl + D` | Toggle dark/light mode |
| `Cmd/Ctrl + /` | Show keyboard shortcuts |
| `Esc` | Close modals/dialogs |
| `Arrow Keys` | Navigate color history |
| `Space` | Toggle color picker |

## WebAssembly Integration

Pastel UI uses **[@valknarthing/pastel-wasm](https://www.npmjs.com/package/@valknarthing/pastel-wasm)** for all color operations, providing:

- **Zero Latency** - All operations run locally in the browser
- **Offline First** - Works completely offline after initial load
- **No Backend** - No API server required
- **132KB Bundle** - Optimized WASM binary
- **Type Safe** - Full TypeScript definitions

### Example Usage

```typescript
import { pastelWASM } from '@/lib/api/wasm-client';

// Get color information
const info = await pastelWASM.getColorInfo({ colors: ['#ff0099'] });

// Generate distinct colors
const distinct = await pastelWASM.generateDistinct({ count: 8, metric: 'ciede2000' });

// Create gradient
const gradient = await pastelWASM.generateGradient({
  stops: ['#ff0000', '#0000ff'],
  count: 10,
  colorspace: 'lch'
});
```

See [CLAUDE.md](CLAUDE.md) for detailed WASM integration documentation.

## Performance

Pastel UI is optimized for performance:

- **WebAssembly Engine** - Native-speed color operations (132KB WASM)
- **Zero Latency** - No network requests for color operations
- **Fast Initial Load** - < 350KB total initial bundle
- **Code Splitting** - Route-based automatic splitting
- **Image Optimization** - Next.js Image with AVIF/WebP
- **Offline Support** - Works completely offline after first load
- **Debounced Updates** - Smooth slider interactions

## Accessibility

Pastel UI meets WCAG 2.1 Level AAA standards:

- **Keyboard Navigation** - Full keyboard support
- **Screen Reader Support** - Comprehensive ARIA labels
- **Focus Management** - Logical focus order
- **Color Contrast** - AAA contrast throughout
- **Reduced Motion** - Respects user preferences
- **Semantic HTML** - Proper HTML structure

## Browser Support

- **Chrome/Edge** 90+
- **Firefox** 88+
- **Safari** 14+
- **Mobile Safari** 14+
- **Chrome Android** 90+

## Deployment

Pastel UI is a **fully static application** that requires no backend server. Deploy to any static hosting platform!

### Static Export (Recommended)

Build and deploy to any static hosting:

```bash
# Build static export
pnpm build

# Output in out/ directory (2.2MB total, 130KB WASM)
# Serve with any static file server
```

### Static Hosting Platforms

#### Vercel

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/valknarness/pastel-ui)

```bash
# Install Vercel CLI
pnpm add -g vercel

# Deploy
vercel

# Production deployment
vercel --prod
```

#### Netlify

```bash
# Build command: pnpm build
# Publish directory: out
```

#### Cloudflare Pages

```bash
# Build command: pnpm build
# Output directory: out
```

#### GitHub Pages

```bash
# Build static export
pnpm build

# Deploy out/ directory to gh-pages branch
```

#### Self-Hosted (Nginx/Apache)

```bash
# Build static export
pnpm build

# Copy out/ directory to web server
cp -r out/* /var/www/html/
```

### Serve Locally

Test the static build locally:

```bash
# Build
pnpm build

# Serve with any static file server
npx serve out
# or
python -m http.server -d out 8000
# or
cd out && python3 -m http.server
```

### Docker (Optional)

For containerized deployment using nginx:

```bash
# Build the image
docker build -t pastel-ui .

# Run container (serves on port 80)
docker run -p 80:80 pastel-ui

# Or use docker-compose
docker-compose up -d
```

The Docker image uses nginx to serve the static files (final image size: ~25MB).

**Note**: Docker is optional - the app is fully static and can be served by any HTTP server.

## Contributing

Contributions are welcome! Please read [CLAUDE.md](CLAUDE.md) for development guidelines.

### Development Workflow

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`pnpm test`)
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

### PR Checklist

- [ ] Tests pass (`pnpm test` and `pnpm test:e2e`)
- [ ] No linting errors (`pnpm lint`)
- [ ] No TypeScript errors (`pnpm type-check`)
- [ ] Code formatted (`pnpm format`)
- [ ] Documentation updated (if needed)
- [ ] Accessibility tested (keyboard, screen reader)
- [ ] Performance checked (`pnpm analyze`)

## Related Projects

- **[@valknarthing/pastel-wasm](https://www.npmjs.com/package/@valknarthing/pastel-wasm)** - WebAssembly color engine
- **[Pastel API](https://github.com/valknarness/pastel-api)** - Optional REST API for server-side operations
- **[Pastel CLI](https://github.com/sharkdp/pastel)** - Original command-line tool by David Peter

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Acknowledgments

- **[David Peter](https://github.com/sharkdp)** - Creator of the original [Pastel CLI](https://github.com/sharkdp/pastel)
- **[Vercel](https://vercel.com)** - Next.js framework and hosting platform
- **[Tailwind Labs](https://tailwindcss.com)** - Tailwind CSS framework
- Color science resources from [OkLab](https://bottosson.github.io/posts/oklab/) and [W3C](https://www.w3.org/WAI/WCAG21/)

## Support

- **Documentation**: [CLAUDE.md](CLAUDE.md)
- **API Docs**: [Pastel API](https://github.com/valknarness/pastel-api)
- **Issues**: [GitHub Issues](https://github.com/valknarness/pastel-ui/issues)
- **Discussions**: [GitHub Discussions](https://github.com/valknarness/pastel-ui/discussions)

---

**Built with** ❤️ **using** [Next.js](https://nextjs.org), [React](https://react.dev), [WebAssembly](https://webassembly.org), and [Tailwind CSS](https://tailwindcss.com)

**Project Status**: ✅ Production-ready with WASM integration
**Last Updated**: 2025-11-17