Handfish Design System

Toggle Switch

A boolean toggle control that replaces <input type="checkbox">.

<toggle-switch
    name="darkMode"
    label="Dark Mode"
    checked
></toggle-switch>

Attribute	Type	Default	Description
checked	boolean	false	Current checked state
label	string	''	Label text
name	string	''	Form field name
disabled	boolean	false	Disabled state

Slider Value

A range slider with editable numeric value display. Uses display: contents to participate in parent grid layouts. Click the value to type an exact number.

<slider-value
    name="volume"
    min="0"
    max="100"
    value="50"
    step="1"
    type="int"
></slider-value>

Attribute	Type	Default	Description
min	number	0	Minimum value
max	number	100	Maximum value
value	number	0	Current value
step	number	0.01	Step increment
type	string	'float'	Value type: int or float
name	string	''	Form field name
disabled	boolean	false	Disabled state

Events

• input
• change

Select Dropdown

A custom dropdown select with keyboard navigation and search.

<select-dropdown name="effect" value="blur">
    <option value="none">None</option>
    <option value="blur">Blur</option>
    <option value="glow">Glow</option>
</select-dropdown>

Attribute	Type	Default	Description
value	string	''	Selected option value
name	string	''	Form field name
disabled	boolean	false	Disabled state

Features:

• Type-ahead search when focused
• Arrow key navigation
• Auto-switches to dialog mode with 6+ options
• Escape to close

Dropdown Menu

A trigger button with a dropdown menu for actions.

<dropdown-menu label="Options" icon="more_vert">
    <dropdown-item value="edit" icon="edit">Edit</dropdown-item>
    <dropdown-item value="duplicate" icon="content_copy">Duplicate</dropdown-item>
    <dropdown-item divider></dropdown-item>
    <dropdown-item value="delete" destructive icon="delete">Delete</dropdown-item>
</dropdown-menu>

Attribute	Type	Default	Description
label	string	''	Trigger button text
icon	string	''	Material Symbols icon name
align	string	'left'	Menu alignment: left or right
value	string	''	Currently selected value (selectable mode)
disabled	boolean	false	Disabled state

<dropdown-item> attributes: value, icon, divider, destructive

Events

• change (detail: { value })

Justify Button Group

A segmented control for text alignment selection.

<justify-button-group
    name="alignment"
    value="center"
></justify-button-group>

Attribute	Type	Default	Description
value	string	'left'	Current value: left, center, right
name	string	''	Form field name
disabled	boolean	false	Disabled state

Color Picker

A dropdown color picker with swatch trigger.

<color-picker
    name="fillColor"
    value="#a5b8ff"
    alpha="1"
    mode="hsv"
></color-picker>

Attribute	Type	Default	Description
value	string	'#000000'	Hex color value
alpha	number	1	Alpha/opacity (0-1)
mode	string	'hsv'	Color mode: hsv, oklab, or oklch
inline	boolean	false	Always show wheel (no dropdown)
name	string	''	Form field name
required	boolean	false	Required field
disabled	boolean	false	Disabled state

Events

• input
• change
• colorinput (detail: { value, alpha, rgb, hsv, oklch })
• open
• close

Color Wheel

The full color wheel interface (used inside Color Picker). Supports three color modes: HSV, OkLab, and OKLCH.

<color-wheel
    value="#6bffa5"
    mode="hsv"
></color-wheel>

Attribute	Type	Default	Description
value	string	'#000000'	Hex color value
alpha	number	1	Alpha/opacity (0-1)
mode	string	'hsv'	Color mode: hsv, oklab, or oklch
name	string	''	Form field name
required	boolean	false	Required field
disabled	boolean	false	Disabled state

Methods

• getColor() — Returns { value, alpha, rgb, hsv, oklch }
• setColor({ value, alpha, mode }) — Set color programmatically

Events

• input — Fires during color selection
• change — Fires when selection is finalized
• colorinput — Fires with detail: { value, alpha, rgb, hsv, oklch }

Color Swatch

A single color display with selection and tooltip.

<color-swatch
    color="#a5b8ff"
    size="32"
    selected
    show-tooltip
></color-swatch>

Attribute	Type	Default	Description
color	string	'#000000'	Hex color value
size	number	32	Swatch size in pixels
selected	boolean	false	Selected state (shows outline ring)
editable	boolean	false	Enable double-click to edit
show-tooltip	boolean	false	Show hex tooltip on hover
disabled	boolean	false	Disabled state

Events

• select (detail: { color })
• edit (detail: { color })

Gradient Stops

Draggable color stop handles for positioning colors in a gradient.

<gradient-stops></gradient-stops>

Attribute	Type	Default	Description
disabled	boolean	false	Disabled state

Methods

• setStops(colors, positions) — Set colors (RGB 0-1 arrays) and positions (0-1)
• getPositions() — Get current position array
• getSelectedIndex() — Get selected stop index
• setSelectedIndex(index) — Set selected stop

Events

• select (detail: { index })
• input (detail: { index, position, positions })
• change (detail: { index, positions })
• delete (detail: { index, positions, colors })

Vector 2D Picker

A 2D vector picker with interactive XY pad and sliders in a dialog modal.

<vector2d-picker
    value="0.5,0.5"
    min="-1"
    max="1"
    step="0.01"
    normalized
></vector2d-picker>

Attribute	Type	Default	Description
value	string	'0,0'	Comma-separated X,Y values
min	number	-1	Minimum axis value
max	number	1	Maximum axis value
step	number	0.01	Step increment
normalized	boolean	false	Normalize to unit vector
name	string	''	Form field name
disabled	boolean	false	Disabled state

Events

• input
• change

Vector 3D Picker

A 3D vector picker with interactive sphere gizmo and XYZ sliders in a dialog modal.

<vector3d-picker
    value="0,1,0"
    min="-1"
    max="1"
    step="0.01"
    normalized
></vector3d-picker>

Attribute	Type	Default	Description
value	string	'0,0,1'	Comma-separated X,Y,Z values
min	number	-1	Minimum axis value
max	number	1	Maximum axis value
step	number	0.01	Step increment
normalized	boolean	false	Normalize to unit vector
name	string	''	Form field name
disabled	boolean	false	Disabled state

Events

• input
• change

Code Editor

A code editor with line numbers and pluggable syntax highlighting.

<code-editor
    value="// Hello world"
    placeholder="Enter code..."
    line-numbers
></code-editor>

Attribute	Type	Default	Description
value	string	''	Editor content
placeholder	string	''	Placeholder text
readonly	boolean	false	Read-only mode
disabled	boolean	false	Disabled state
spellcheck	boolean	false	Enable spell check
line-numbers	boolean	true	Show line numbers
font-family	string	—	Override font
font-size	string	—	Override font size
background-color	string	—	Override background
background-opacity	string	—	Override background opacity
text-color	string	—	Override text color
caret-color	string	—	Override caret color
selection-color	string	—	Override selection color

Methods

• setTokenizer(fn) — Set a syntax highlighting function: (line: string) => Array<{type, text}>
• get/set value — Editor content

Events

• input (detail: { value })
• forcerecompile

// Use with DSL tokenizer
import { dslTokenizer } from 'handfish'
editor.setTokenizer(dslTokenizer)

Image Magnifier

A zoomed-in view of a canvas under the cursor for precise color picking. Shows crosshairs and the hex value of the center pixel.

<image-magnifier zoom="8" size="120"></image-magnifier>

Attribute	Type	Default	Description
active	boolean	false	Show/hide the magnifier
zoom	number	8	Zoom level
size	number	120	Magnifier diameter in pixels

Methods

• attachToCanvas(canvas) — Set the source canvas to magnify
• update(x, y) — Update magnifier position and render

Toast Notifications

Lightweight notification toasts with auto-dismiss. Exported as standalone functions (not a custom element).

import { showToast, showSuccess, showError, showWarning, showInfo } from 'handfish'

showSuccess('Palette saved')
showError('Failed to load', { duration: 6000 })
showWarning('Unsaved changes')
showInfo('Copied to clipboard')

• showToast(message, { type, duration }) — General toast (type: info, success, error, warning)
• showSuccess(message, options) — Success toast (default 2s)
• showError(message, options) — Error toast (default 6s)
• showWarning(message, options) — Warning toast (default 2s)
• showInfo(message, options) — Info toast (default 2s)

Escape Handler

Stack-based escape key management for closing modals and dropdowns in the correct order.

import { registerEscapeable, unregisterEscapeable, initEscapeHandler } from 'handfish'

initEscapeHandler()
registerEscapeable(element, () => closeMyModal())
unregisterEscapeable(element)

Exports: registerEscapeable, unregisterEscapeable, closeTopmost, hasOpenEscapeables, initEscapeHandler

Tooltips

Hover tooltips for any element with a data-title attribute.

import { initializeTooltips } from 'handfish'

initializeTooltips()

<button data-title="Save palette">Save</button>

Color Conversions

Comprehensive color conversion utilities. All RGB objects use {r, g, b} with 0-255 values.

import { rgbToHex, parseHex, rgbToHsv, hsvToRgb, rgbToOklch, oklchToRgb } from 'handfish'