@flowscape-ui/design-system-kit

v1.3.1

Published

3 months ago

Professional React UI components for color management and design systems. Features ColorPicker with gradients, InputColorPicker, InputHex with alpha channel, InputNumberSelect, and more. Built with TypeScript.

🎨 @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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🎨 @flowscape-ui/design-system-kit

✨ Features

📦 Installation

🚀 Quick Start

Option 1: Import from main module (convenient)

Option 2: Modular imports (recommended for production)

📚 Components Overview

🎨 ColorPicker

🔢 InputNumberSelect

🎨 InputColorPicker

🔤 InputHex

🎨 InputHexWithPreview

📋 API Reference

InputHex / InputHexWithPreview Props

Usage Examples

InputNumberSelect Props

🎨 ColorPicker Advanced Configuration

Hide Components

Custom Presets & Styling

🔧 Advanced: useColorPicker Hook

ColorPicker Key Props

Browser Support

Development

Contributing

License

Links

📝 Changelog

v1.2.0 (Latest)

v1.1.0

v1.0.0