Pastel UI

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

Pastel UI is a beautiful, feature-rich interface for the Pastel API, providing intuitive tools for color manipulation, palette generation, and accessibility testing.

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
• 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)
• Pastel API running locally or remotely

Installation

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

# Install dependencies
pnpm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your Pastel API URL

# Run development server
pnpm dev

Open http://localhost:3000 in your browser.

Environment Variables

# .env.local
NEXT_PUBLIC_API_URL=http://localhost:3000  # Your Pastel API URL
NEXT_PUBLIC_APP_URL=http://localhost:3000  # This app's URL (for sharing)

Development

Available Commands

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

# Building
pnpm build            # Production build
pnpm start            # Start production server

# 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

API Integration

Pastel UI communicates with the Pastel API for all color operations. The API client is type-safe and includes automatic retries, caching, and error handling.

Example API Usage

import { pastelAPI } from '@/lib/api/client';

// Get color information
const info = await pastelAPI.getColorInfo(['#ff0099']);

// Generate distinct colors
const distinct = await pastelAPI.generateDistinct(8, 'ciede2000');

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

See CLAUDE.md for detailed API integration documentation.

Performance

Pastel UI is optimized for performance:

• Fast Initial Load - < 200KB initial bundle
• Code Splitting - Route-based automatic splitting
• Image Optimization - Next.js Image with AVIF/WebP
• API Caching - React Query with smart cache invalidation
• Debounced Updates - Smooth slider interactions
• Web Workers - Heavy calculations off main thread

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

Vercel (Recommended)

# Install Vercel CLI
pnpm add -g vercel

# Deploy
vercel

# Production deployment
vercel --prod

Docker

Using Pre-built Image from GHCR

# Pull the latest image
docker pull ghcr.io/valknarness/pastel-ui:latest

# Run the container
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL=http://localhost:3001 \
  ghcr.io/valknarness/pastel-ui:latest

Docker Compose (UI + API)

Run both Pastel UI and Pastel API together:

# Using docker-compose
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Building Locally

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

# Run locally built image
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL=http://localhost:3001 \
  pastel-ui

Available Docker Images

Images are automatically built and published to GitHub Container Registry:

• ghcr.io/valknarness/pastel-ui:latest - Latest main branch
• ghcr.io/valknarness/pastel-ui:v1.0.0 - Specific version
• ghcr.io/valknarness/pastel-ui:main-abc1234 - Commit SHA

Supported platforms: linux/amd64, linux/arm64

Static Export

# Build static export
pnpm build

# Output in out/ directory
# Deploy to any static hosting (Netlify, Cloudflare Pages, etc.)

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

• Pastel API - REST API for color manipulation
• 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, and Tailwind CSS

Project Status: Design phase complete, ready for implementation Last Updated: 2025-11-07