Color Picker Control Family

Project Overview

Designed and implemented a new color picker control family for Charm FUI, a TypeScript and Lit-based web-component library aligned with Fluent UI.

The control family includes:

• fui-color-picker

• fui-color-area

• fui-color-slider

• fui-alpha-slider

Code Plan

The implementation plan followed a four-pass architecture process:

1. Public API

   • Use HSV as the shared color model:

     { h: number; s: number; v: number; a?: number }

   • Provide separate controls for the color area, hue/value/saturation sliders, and alpha.

   • Support standalone child controls as well as nested controls inside the main picker.

2. State and Communication

   • Keep canonical color state in fui-color-picker.

   • Treat child controls as interaction surfaces.

   • Use slotted child components and bubbling native-style input and change events.

   • Re-emit picker-level color-input and color-change events with channel metadata.

3. Repository Consistency

   • Follow existing composite-component patterns from combobox, tabs, and tree.

   • Use CharmElement, Lit decorators, per-component styles, registration files, test harnesses, and Storybook stories.

   • Keep public components in flat sibling folders under components.

4. Testing and Documentation

   • Add browser-based tests using @open-wc/testing and Playwright.

   • Support Chromium, Firefox, and WebKit.

   • Add HTML Storybook stories and narrative MDX documentation.

   • Document how consumers read the selected color through properties and events.

Implementation

The parent picker owns and normalizes the HSV color state. It synchronizes the state to its slotted children and ignores invalid or disabled child events.

The child components provide specialized interaction:

• fui-color-area maps pointer coordinates to saturation and value.

• fui-color-slider supports hue, saturation, and value channels.

• fui-alpha-slider controls transparency with a checkerboard track.

The color area uses pointer capture so dragging continues even when the pointer leaves the visible color surface. The slider tracks use separate decorative elements from the native range inputs, allowing the thumbs to overhang the visible track edges like Fluent UI.

Iterative Improvements

During visual comparison with Fluent UI, the implementation was refined to include:

• Fluent-style rounded corners and borders

• Layered gray and white thumb rings

• Thumb drop shadows

• Solid thumb colors instead of transparent fills

• Alpha-aware thumb transparency

• Dynamic saturation and value gradients

• Slider thumbs that overhang the track at minimum and maximum values

• Slider widths aligned with the color area

• Design-token corrections based on the repository's actual theme definitions

A structural correction also moved the child controls from nested folders into flat sibling folders, matching the existing repository convention and generated React wrapper paths.

Validation

The implementation was validated with:

• TypeScript compilation

• ESLint

• Custom Elements Manifest generation

• Storybook HTML build

• Browser tests in Chromium, Firefox, and WebKit

• Manual Storybook visual inspection

• Direct browser measurements for slider and track alignment

The parent color-picker tests pass across all three browsers. The child component tests also pass functionally, although their small standalone test suites still need additional cases to consistently meet the repository's branch-coverage threshold.

Documentation

Added Storybook documentation covering:

• Default color picker usage

• Usage without transparency

• Saturation and value sliders

• Disabled state

• Reading the selected color through:

  • the color property

  • color-input

  • color-change

The implementation intentionally does not include Hex/RGB text fields or a built-in preview swatch. Those values remain available programmatically so consumers can choose their own output UI.

Outcome

The result is a composable, event-driven color picker family that follows the repository's architecture while providing a foundation for future features such as keyboard support for the two-dimensional color area, richer color-format utilities, and optional consumer-provided value displays.