Pastel UI

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

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 - React framework with App Router and Server Components
• React 19 - Latest React with improved concurrent features
• Tailwind CSS 4 - CSS-first utility framework with modern color spaces
• TypeScript - Strict type safety throughout
• @valknarthing/pastel-wasm - WebAssembly color engine for zero-latency operations
• React Query - Server state management and caching
• Zustand - Client state management
• Framer Motion - Smooth animations and transitions
• Lucide React - Beautiful icon set

Quick Start

Prerequisites

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

Installation

# 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 in your browser.

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

Development

Available Commands

# 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 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

:root {
  --color-primary: #ff0099;
  --color-secondary: #00ccff;
  --color-accent: #ffcc00;
}

Tailwind Config

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

JSON

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

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 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

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 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:

# Build static export
pnpm build

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

Static Hosting Platforms

Vercel

# Install Vercel CLI
pnpm add -g vercel

# Deploy
vercel

# Production deployment
vercel --prod

Netlify

# Build command: pnpm build
# Publish directory: out

Cloudflare Pages

# Build command: pnpm build
# Output directory: out

GitHub Pages

# Build static export
pnpm build

# Deploy out/ directory to gh-pages branch

Self-Hosted (Nginx/Apache)

# Build static export
pnpm build

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

Serve Locally

Test the static build locally:

# 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:

# 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 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 - WebAssembly color engine
• Pastel API - Optional REST API for server-side operations
• Pastel CLI - Original command-line tool by David Peter

License

MIT License - see LICENSE file for details.

Acknowledgments

• David Peter - Creator of the original Pastel CLI
• Vercel - Next.js framework and hosting platform
• Tailwind Labs - Tailwind CSS framework
• Color science resources from OkLab and W3C

Support

• Documentation: CLAUDE.md
• API Docs: Pastel API
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Built with ❤️ using Next.js, React, WebAssembly, and Tailwind CSS

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