docs: initial project setup and documentation
Add comprehensive documentation and planning for Pastel UI: - Complete architecture design using Next.js 16 and Tailwind CSS 4 - Detailed development guide (CLAUDE.md) with all patterns and conventions - Feature-rich README with keyboard shortcuts and export formats - Project structure and technology stack decisions Features planned: - Color playground with multi-format support - Palette generation (harmony, distinct, gradient) - Accessibility tools (WCAG, color blindness simulation) - Named colors explorer (148 CSS/X11 colors) - Batch operations with CSV/JSON import/export - Command palette (Cmd+K) and keyboard shortcuts - Dark/light mode with system preference detection - Shareable links with URL state Tech stack: - Next.js 16 with App Router and Server Components - React 19 with latest concurrent features - Tailwind CSS 4 with CSS-first configuration - TypeScript strict mode - React Query for server state - Zustand for client state - Framer Motion for animations Ready for implementation phase. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
429
README.md
Normal file
429
README.md
Normal file
@@ -0,0 +1,429 @@
|
||||
# Pastel UI
|
||||
|
||||
> A modern, interactive web application for color manipulation, palette generation, and accessibility analysis.
|
||||
|
||||
[](https://nextjs.org)
|
||||
[](https://react.dev)
|
||||
[](https://tailwindcss.com)
|
||||
[](https://www.typescriptlang.org)
|
||||
[](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)
|
||||
|
||||
[](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
|
||||
|
||||
```bash
|
||||
# Build
|
||||
docker build -t pastel-ui .
|
||||
|
||||
# Run
|
||||
docker run -p 3000:3000 -e NEXT_PUBLIC_API_URL=https://api.pastel.com pastel-ui
|
||||
```
|
||||
|
||||
### 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
Block a user