valknar/pastel-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ea44b592ddd6a2890aa6476ef75126d15fed83b0
pastel-ui/README.md
valknarness 75e21646b3 feat: add Docker support with GitHub Actions CI/CD 
Add comprehensive Docker deployment with automated builds:

**Docker Configuration:**
- Multi-stage Dockerfile for optimized Next.js production builds
  - Stage 1: Install dependencies with pnpm
  - Stage 2: Build application with standalone output
  - Stage 3: Minimal runtime image with non-root user
  - Includes health check endpoint
  - Final image size optimized
- .dockerignore for efficient build context
- Enable standalone output in next.config.ts for Docker

**GitHub Actions Workflow:**
- Automated Docker image builds on push to main and tags
- Multi-platform support (linux/amd64, linux/arm64)
- Push to GitHub Container Registry (ghcr.io)
- Smart tagging strategy:
  - `latest` for main branch
  - `vX.X.X` for semver tags
  - `main-SHA` for commit-specific images
- Build cache optimization with GitHub Actions cache
- Artifact attestation for supply chain security

**Docker Compose:**
- Combined stack for UI + API
- Environment variable configuration
- Health checks for both services
- Automatic restart policies
- Shared network configuration

**Documentation:**
- Updated README with Docker deployment instructions
- Pre-built image usage from GHCR
- Docker Compose setup guide
- Local build instructions
- Available image tags reference

**Production Ready:**
- Images automatically published to ghcr.io/valknarness/pastel-ui
- Supports both x64 and ARM64 architectures
- Health checks for container orchestration
- Environment-based configuration
- Non-root user for security

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-07 14:36:30 +01:00

471 lines
14 KiB
Markdown
Raw Blame History

# 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 for the [Pastel API](https://github.com/valknarness/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](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
- **[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)
- **Pastel API** running locally or remotely
### Installation
```bash
# 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](http://localhost:3000) in your browser.
### Environment Variables
```bash
# .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
```bash
# 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](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 |
## API Integration
Pastel UI communicates with the [Pastel API](https://github.com/valknarness/pastel-api) for all color operations. The API client is type-safe and includes automatic retries, caching, and error handling.
### Example API Usage
```typescript
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](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)
[![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
```
### Docker
#### Using Pre-built Image from GHCR
```bash
# 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:
```bash
# Using docker-compose
docker-compose up -d
# View logs
docker-compose logs -f
# Stop
docker-compose down
```
#### Building Locally
```bash
# 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
```bash
# 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](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](https://github.com/valknarness/pastel-api)** - REST API for color manipulation
- **[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), and [Tailwind CSS](https://tailwindcss.com)
**Project Status**: Design phase complete, ready for implementation
**Last Updated**: 2025-11-07
Reference in New Issue View Git Blame Copy Permalink