🎨 Pastel Color Picker

📋 Summary

A comprehensive React color picker component with multiple variants, pastel color support, and alpha channel control. Built with Radix UI primitives and modern CSS architecture.

Key Features:

• 🎯 Multiple Variants - Button, Circles, and Random selection modes
• 🌈 Pastel & Vivid Colors - Smart color generation for different aesthetics
• 💧 Alpha Channel Support - Transparency control with visual feedback
• ♿ WCAG 2.1 AA Compliant - Full accessibility with screen reader support
• 🔧 TypeScript Ready - Complete type safety with detailed interfaces
• ⚡ Modern Stack - Built with Radix UI primitives and BEM CSS methodology
• 📦 Flexible Installation - Self-contained, headless, or source import options

📑 Table of Contents

• ✨ Features
• 🎯 How It Works
• 🚀 Demo
• 📦 Installation
• 🎯 Quick Start
• 🔧 API Reference
  • 🔍 Import Clarification
  • ColorPickerProps
  • Event Callbacks
  • ColorValue Interface
  • ColorMode Enum
• 🎨 Variants
  • Button Variant
  • Circles Variant
  • Random Variant
  • Variant Comparison
• 🌈 Color Modes
• 🎨 Styling
• ♿ Accessibility
• 🤝 Contributing
• 📝 License
• 🙏 Acknowledgments

✨ Features

• 🎯 Multiple Variants: Button, Circles, and Random color selection modes
• 🌈 Pastel & Vivid Colors: Toggle between soft pastel and vibrant color palettes
• 💧 Alpha Channel Support: Control transparency with optional alpha slider
• 📱 Responsive Design: Works perfectly on both small and large screens
• 🎨 Custom Presets: Define your own color palettes
• ♿ Accessibility: Full keyboard navigation and screen reader support
• 🔧 TypeScript: Complete type safety with detailed interfaces
• ⚡ Modern Stack: Built with Radix UI primitives and BEM CSS methodology

🎯 How It Works

The color picker uses the HSV (Hue, Saturation, Value) color model, which provides an intuitive way to select colors by separating color properties:

🌈 Color Theory

HSV Color Model Components:

• Hue (H): The color type (0-360°) - Red, Orange, Yellow, Green, Blue, Purple, etc.
• Saturation (S): Color intensity (0-100%) - Gray to Vivid
• Value (V): Brightness (0-100%) - Black to Bright

🎨 Color Variants

• 2D Color Area (optional): Interactive canvas for selecting saturation and value simultaneously
• Individual Sliders (default): Separate controls for precise adjustment
• Random Mode: Generate colors within pastel or vivid ranges

🚀 Demo

Live Demo →

📦 Installation

From npm (Recommended)

npm install @marcosfreitas/pastel-color-picker

Peer Dependencies

npm install react react-dom

Note: All other dependencies (Radix UI, Lucide React, etc.) are bundled with the package for optimal compatibility.

🎯 Quick Start

// Runtime imports (from .js files)
import { ColorPicker, ColorModeEnum } from '@marcosfreitas/pastel-color-picker';
// Type imports (from .d.ts files)
import type { ColorValue } from '@marcosfreitas/pastel-color-picker';
// CSS import
import '@marcosfreitas/pastel-color-picker/style.css';
import { useState } from 'react';

function App() {
  const [color, setColor] = useState<ColorValue>();

  return (
    <ColorPicker
      defaultColor={color}
      onColorChange={setColor}
      variant="button"
      colorMode={ColorModeEnum.PASTEL}  // Use enum for runtime
      // OR colorMode="pastel"         // Use string literal
      showAlpha={true}
    />
  );
}

🔧 API Reference

🔍 Import Clarification

Important: Types (ColorValue, ColorMode, etc.) must be imported separately from runtime values:

// ✅ Correct - Import types separately
import { ColorPicker, ColorModeEnum } from '@marcosfreitas/pastel-color-picker';
import type { ColorValue, ColorMode } from '@marcosfreitas/pastel-color-picker';

// ❌ Incorrect - Types don't exist in JS runtime
import { ColorPicker, ColorValue, ColorMode } from '@marcosfreitas/pastel-color-picker';

ColorPickerProps

Event Callbacks

ColorValue Interface

interface ColorValue {
  hexa: string;                              // Hex color (#FF0000)
  rgba: { r: number; g: number; b: number; a: number }; // RGBA values
  hsva: { h: number; s: number; v: number; a: number }; // HSVA values
}

ColorMode Enum

enum ColorMode {
  PASTEL = 'pastel',
  VIVID = 'vivid'
}

🎨 Variants

Button Variant (Default)

Displays a colored button that opens a full-featured color picker dialog.

<ColorPicker 
  variant="button" 
  size="md"
  colorMode={ColorMode.PASTEL}
  onColorChange={(color) => console.log(color)}
/>

Circles Variant

Shows preset color circles with an option to open the full picker.

<ColorPicker 
  variant="circles" 
  presets={['#FF6B6B', '#4ECDC4', '#45B7D1']}
  colorMode={ColorMode.VIVID}
  onColorChange={(color) => console.log(color)}
/>

Note: The label and children props are not rendered in circles variant - it uses preset circles instead.

Random Variant

Generates random colors with a colored bottom border indicator.

<ColorPicker 
  variant="random" 
  colorMode={ColorMode.PASTEL}
  onColorChange={(color) => console.log(color)}
  label="Generate Random Color"
/>

Note: The presets prop is not used in random variant - it generates colors based on colorMode only.

🎯 Variant Comparison

Choose your variant:

• Button: When you need full control and all color picker features
• Circles: When you want quick preset selection with dialog fallback
• Random: When you want simple random color generation for creative workflows

🌈 Color Modes

Pastel Colors

When colorMode="pastel":

• Saturation: 70-100%
• Value: 75-90%
• Perfect for soft, elegant designs

Vivid Colors

When colorMode="vivid":

• Saturation: 50-100%
• Value: 40-80%
• Great for bold, energetic designs

🎨 Styling

The component uses a modern CSS architecture with BEM methodology and scoped variables. You can customize the appearance by overriding CSS custom properties:

:root {
  --pcp-color-border: 0 0% 10%;
  --pcp-color-background: 0 0% 100%;
  --pcp-color-foreground: 222.2 84% 4.9%;
  --pcp-color-primary: 222.2 47.4% 11.2%;
  --pcp-color-primary-foreground: 210 40% 98%;
  --pcp-radius: 0.5rem;
}

♿ Accessibility

This color picker provides comprehensive accessibility support that exceeds WCAG 2.1 AA standards:

✅ Complete Implementation

• 🎯 Advanced Keyboard Navigation - 2D color area navigation, grid-based preset selection, shortcuts (Home/End/PageUp/PageDown)
• 🔊 Screen Reader Excellence - Live region announcements, descriptive color names, context-aware feedback
• 👁️ Enhanced Focus Management - Dual-outline system with soft black focus rings for optimal visibility
• 🎨 Color Independence - Information conveyed through text, ARIA labels, and multiple formats (HEX, RGB)
• ⚡ High Contrast Mode - Automatic detection with enhanced outlines and pure black indicators
• 🌊 Reduced Motion Support - Respects user motion preferences
• 📱 Responsive Design - Accessible at all zoom levels and screen sizes

🏆 WCAG 2.1 AA Compliant

• All success criteria met with automated testing verification
• Compatible with NVDA, JAWS, VoiceOver, and Orca screen readers
• Lighthouse accessibility score: 100%
• Zero accessibility violations detected by axe-core

📚 Detailed Documentation

For comprehensive accessibility implementation details, testing procedures, and contribution guidelines, see our Accessibility Guide.

This component sets the standard for accessible color picker implementations.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Radix UI primitives
• Icons from Lucide React

Made with ❤️ by Marcos Freitas