Package Exports

@flowscape-ui/design-system-kit
@flowscape-ui/design-system-kit/color-picker
@flowscape-ui/design-system-kit/input
@flowscape-ui/design-system-kit/input-color-picker
@flowscape-ui/design-system-kit/input-hex
@flowscape-ui/design-system-kit/input-hex-with-preview
@flowscape-ui/design-system-kit/input-number-select
@flowscape-ui/design-system-kit/shared

Readme

🎨 @flowscape-ui/design-system-kit

Professional React UI components for color management and design systems

📚 Documentation • 🎨 Storybook • 🐛 Report Bug • ☕ Support

✨ Features

🎨 Multiple Color Formats — RGB, HSL, HSV, CMYK, HEX with alpha channel support
🌈 Gradient Support — Create and edit linear and radial gradients
🎯 Eye Dropper — Pick colors directly from the screen
🔢 Universal Input Component — Drag-to-change numeric input for all design properties
🎨 HEX Input Components — Specialized inputs with drag-to-change and alpha channel
🎛️ 5 Progression Types — Linear, arithmetic, geometric, paraboloid, exponential
🌓 Dark/Light Mode — Automatic theme detection with manual override
📦 Modular Architecture — Import only what you need (tree-shakeable)
⚡ Lightweight — From 1KB to 62KB per component
🔧 TypeScript — Full type definitions and IntelliSense support
🎪 Advanced Controls — Fine-tune colors with precision sliders

📦 Installation

npm install @flowscape-ui/design-system-kit

Peer Dependencies:

npm install react react-dom framer-motion lucide-react react-icons

🚀 Quick Start

Option 1: Import from main module (convenient)

import {
    ColorPicker,
    InputNumberSelect,
    InputColorPicker,
    InputHex,
    InputHexWithPreview,
} from '@flowscape-ui/design-system-kit'

Option 2: Modular imports (recommended for production)

// Tree-shakeable - only loads what you need
import { ColorPicker } from '@flowscape-ui/design-system-kit/color-picker'
import { InputNumberSelect } from '@flowscape-ui/design-system-kit/input-number-select'
import { InputColorPicker } from '@flowscape-ui/design-system-kit/input-color-picker'
import { InputHex } from '@flowscape-ui/design-system-kit/input-hex'
import { InputHexWithPreview } from '@flowscape-ui/design-system-kit/input-hex-with-preview'

📚 Components Overview

Component	Size	Description
ColorPicker	134 KB	Full-featured color picker with gradients, eye dropper, and all color formats
InputColorPicker	142 KB	Compact color input with popup picker
InputNumberSelect	12 KB	Universal drag-to-change numeric input
InputHexWithPreview	7.5 KB	HEX input with color preview and alpha support
InputHex	6.7 KB	Lightweight HEX input with alpha support
Input	847 B	Base input component

🎨 ColorPicker

Full-featured color picker supporting all color formats, gradients, and advanced controls.

import { useState } from 'react'
import { ColorPicker } from '@flowscape-ui/design-system-kit/color-picker'

function App() {
    const [color, setColor] = useState('rgba(175, 51, 242, 1)')
    return <ColorPicker value={color} onChange={setColor} />
}

Key Features:

✅ RGB, HSL, HSV, CMYK, HEX formats
✅ Linear and radial gradients
✅ Eye dropper tool
✅ Color presets
✅ Advanced sliders
✅ Dark/light themes

🔢 InputNumberSelect

Universal drag-to-change numeric input for all design properties.

import { InputNumberSelect } from '@flowscape-ui/design-system-kit/input-number-select'
import { RotateCw } from 'lucide-react'

// Opacity (0-100%)
<InputNumberSelect value={75} onChange={setOpacity} min={0} max={100} icon="%" />

// Angle with custom icon
<InputNumberSelect
  value={45}
  onChange={setAngle}
  min={0}
  max={360}
  unit="deg"
  showUnit
  icon={<RotateCw size={16} />}
/>

Key Features:

✅ Drag-to-change with mouse/keyboard
✅ 5 progression types (linear, arithmetic, geometric, paraboloid, exponential)
✅ Custom icons (string or React components)
✅ Unit display (px, %, rem, em, deg, etc.)
✅ Horizontal/vertical orientation
✅ Keyboard navigation (Arrow keys, Page Up/Down, Home/End)

🎨 InputColorPicker

Compact color input with popup picker and gradient support.

import { InputColorPicker } from '@flowscape-ui/design-system-kit/input-color-picker'

// Solid color
<InputColorPicker
  title="Background Color"
  value="rgba(255, 255, 255, 1)"
  onChange={setColor}
  showOpacity={true}
/>

// Gradient support
<InputColorPicker
  title="Gradient Background"
  value="linear-gradient(135deg, rgba(255, 107, 107, 1) 0%, rgba(78, 205, 196, 1) 100%)"
  onChange={setGradient}
  showOpacity={true}
  showGradient={true}
/>

Key Features:

✅ Solid colors and gradients support
✅ HEX input with alpha channel (8 symbols)
✅ Opacity control with drag slider
✅ Click gradient text to copy CSS
✅ Integrated ColorPicker popup
✅ Background visibility toggle
✅ Customizable gradient input width
✅ Dark/light theme support

Props:

interface InputColorPickerProps {
  value?: string                        // Color or gradient value
  onChange?: (color: string) => void    // Change callback
  onOpacityChange?: (opacity: number) => void
  title?: string                        // Picker header title
  className?: string                    // Container classes
  classNameGradientInput?: string       // Gradient input classes (override min-w-[187px])
  showOpacity?: boolean                 // Show opacity control (default: true)
  showGradient?: boolean                // Show gradient in picker (default: false)
  pickerSize?: number                   // Picker popup size (default: 250)
  onShowPicker?: (shown: boolean) => void
  onHideBackground?: (hidden: boolean) => void
  onDeleteBackground?: () => void
}

🔤 InputHex

Lightweight HEX color input with drag-to-change and alpha channel support.

import { InputHex } from '@flowscape-ui/design-system-kit/input-hex'

// Basic usage (6 symbols)
<InputHex hexColor="#FF5733" handleChange={setColor} />

// With alpha channel (8 symbols)
<InputHex hexColor="#FF5733DD" handleChange={setColor} showAlpha />

Key Features:

✅ Drag # icon to change color
✅ Alpha channel support (showAlpha prop)
✅ Real-time HEX validation
✅ Uppercase formatting
✅ Customizable callbacks (click, drag start/end)
✅ Dark/light theme support

🎨 InputHexWithPreview

HEX input with visual color preview and alpha channel support.

import { InputHexWithPreview } from '@flowscape-ui/design-system-kit/input-hex-with-preview'

// Basic usage
<InputHexWithPreview hexColor="#3498DB" handleChange={setColor} />

// With alpha channel
<InputHexWithPreview hexColor="#3498DBDD" handleChange={setColor} showAlpha />

Key Features:

✅ Everything from InputHex + visual preview
✅ Color preview square with alpha support
✅ Drag to change color, alpha preserved
✅ Customizable preview styles
✅ Compact size for forms

📋 API Reference

InputHex / InputHexWithPreview Props

interface InputHexProps {
    // Required
    hexColor: string // HEX color value
    handleChange: (hexColor: string) => void // Change callback

    // Alpha channel
    showAlpha?: boolean // Enable 8-symbol input (RRGGBBAA)

    // Styling
    className?: string // Container classes
    classNameInput?: string // Input field classes
    classNameIcon?: string // Icon classes
    classNamePreview?: string // Preview classes (InputHexWithPreview only)

    // Behavior
    disabled?: boolean // Disable component
    isDisabledMouseEvent?: boolean // Disable drag functionality

    // Callbacks
    onIconClick?: (hexColor: string) => void
    onIconPointerDown?: (hexColor: string) => void
    onIconPointerUp?: (hexColor: string) => void
}

Alpha Channel Behavior:

When showAlpha={true}, input accepts 8 symbols (RRGGBBAA)
Drag changes only first 6 symbols (base color), alpha is preserved
Alpha affects preview transparency automatically
Format: #RRGGBBAA where AA is alpha (00=transparent, FF=opaque)

Usage Examples

import { InputHex, InputHexWithPreview } from '@flowscape-ui/design-system-kit'

// Basic usage (6 symbols)
<InputHex hexColor="#FF5733" handleChange={setColor} />

// With alpha channel (8 symbols)
<InputHex hexColor="#FF5733DD" handleChange={setColor} showAlpha />

// With preview
<InputHexWithPreview hexColor="#2ECC71" handleChange={setColor} />

// With preview and alpha
<InputHexWithPreview hexColor="#2ECC71DD" handleChange={setColor} showAlpha />

// Custom callbacks
<InputHex
  hexColor={color}
  handleChange={setColor}
  onIconClick={(hex) => console.log('Clicked:', hex)}
  onIconPointerDown={(hex) => console.log('Drag start:', hex)}
  onIconPointerUp={(hex) => console.log('Drag end:', hex)}
/>

// Disabled drag (keyboard only)
<InputHex hexColor={color} handleChange={setColor} isDisabledMouseEvent />

// Custom styles
<InputHexWithPreview
  hexColor={color}
  handleChange={setColor}
  className="w-full"
  classNameInput="font-mono"
  classNamePreview="rounded-full"
/>

InputNumberSelect Props

interface InputNumberSelectProps {
    // Required
    value: number
    onChange?: (value: number) => void

    // Range
    min?: number // Default: 0
    max?: number // Default: 100
    step?: number // Default: 1
    precision?: number // Decimal places, default: 0

    // Progression type
    progression?:
        | 'linear'
        | 'arithmetic'
        | 'geometric'
        | 'paraboloid'
        | 'exponential'

    // Visual
    orientation?: 'horizontal' | 'vertical' // Default: 'horizontal'
    icon?: React.ReactNode | string // Custom icon or text
    unit?: 'px' | '%' | 'rem' | 'em' | 'deg' | 'none'
    showUnit?: boolean // Show unit after value

    // Styling
    className?: string
    classNameInput?: string
    classNameIcon?: string

    // Behavior
    disabled?: boolean
    isDisabledMouseEvent?: boolean
}

Progression Types:

linear — Linear change (default)
arithmetic — Arithmetic progression (×2)
geometric — Geometric progression (×1.05)
paraboloid — Parabolic acceleration
exponential — Exponential change

🎨 ColorPicker Advanced Configuration

Hide Components

<ColorPicker
    value={color}
    onChange={setColor}
    hideOpacity={false} // Hide opacity slider
    hidePresets={false} // Hide preset colors
    hideEyeDrop={false} // Hide eye dropper
    hideAdvancedSliders={false} // Hide advanced sliders
    hideGradientControls={false} // Hide all gradient controls
/>

Custom Presets & Styling

const presets = ['#ff0000', '#00ff00', '#0000ff']

<ColorPicker
  value={color}
  onChange={setColor}
  presets={presets}
  width={350}
  height={350}
  className="my-picker"
/>

🔧 Advanced: useColorPicker Hook

For custom implementations, use the useColorPicker hook:

import { useColorPicker } from '@flowscape-ui/design-system-kit'

const { setR, setG, setB, valueToHex, rgbaArr } = useColorPicker(
    color,
    setColor
)

ColorPicker Key Props

Prop	Type	Default	Description
`value`	`string`	Required	Color value (RGB, HEX, HSL, gradient)
`onChange`	`(value: string) => void`	Required	Change callback
`width` / `height`	`number`	`294`	Picker dimensions
`hideOpacity`	`boolean`	`false`	Hide opacity slider
`hidePresets`	`boolean`	`false`	Hide preset colors
`hideEyeDrop`	`boolean`	`false`	Hide eye dropper
`hideGradientControls`	`boolean`	`false`	Hide gradient controls
`presets`	`string[]`	`[]`	Custom preset colors
`className`	`string`	-	CSS class name

Supported Color Formats:

RGB/RGBA: rgb(255, 0, 0), rgba(255, 0, 0, 0.5)
HEX: #FF0000, #FF0000FF (with alpha)
HSL/HSLA: hsl(0, 100%, 50%), hsla(0, 100%, 50%, 0.5)
HSV: hsv(0, 100%, 100%)
CMYK: cmyk(0, 100%, 100%, 0)
Gradients: linear-gradient(90deg, #ff0000 0%, #0000ff 100%)

Browser Support

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build library
npm run build

# Run tests
npm test

Contributing

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

License

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

📝 Changelog

v1.2.0 (Latest)

🎨 Alpha Channel Support

✨ Alpha channel support for InputHex and InputHexWithPreview
🔤 showAlpha prop — Enable 8-symbol HEX input (RRGGBBAA)
🎨 Automatic preview — Alpha affects transparency in InputHexWithPreview
🖱️ Smart drag behavior — Drag changes base color, alpha preserved
🔄 Uppercase formatting — All HEX values in uppercase
📚 Enhanced documentation with alpha channel examples

Breaking Changes: None — fully backward compatible

v1.1.0

🎉 Specialized Input Components

✨ Universal InputNumberSelect component
🎛️ 5 progression types (linear, arithmetic, geometric, paraboloid, exponential)
🔄 Drag-to-change functionality
🎨 Theme support (light, dark, auto)
📐 Horizontal/vertical orientation
🔧 Modular architecture

v1.0.0

🎉 Initial release
🎨 Full-featured ColorPicker
🌈 Gradient support
🎯 Eye dropper tool
🔧 TypeScript support

JSPM