docs(color-handle): enhance README with detailed component overview #5663

blunteshwar · 2025-08-04T05:02:32Z

Overview

This PR reorganizes the color-handle README.md to follow the established documentation standards structure, improving accessibility and consistency with other components.

Changes Made

Structure Reorganization

Overview: Replaced "Description" with "Overview" section and expanded component description to better explain its role within color selection interfaces
Usage: Updated import code blocks with proper language syntax highlighting (bash, javascript)
Anatomy: Added new section describing the component's key parts and basic usage
Options: Created comprehensive properties documentation including:
- Color property with multiple format examples
- Open property behavior
States: Reorganized existing content into proper states section:
- Standard state
- Disabled state
- Added Focused state documentation
Behaviors: Added new section documenting:
- Pointer interactions and touch handling
- Color display with transparency support
Accessibility: Added comprehensive new section with:
- Keyboard support explanation
- Screen reader integration details
- Touch accessibility features
- Focus management information

Content Improvements

Enhanced component description to clarify its relationship with parent color components
Added documentation for previously undocumented properties (color, focused)
Provided comprehensive color format examples (hex, rgb, rgba, hsl, named colors)
Added JavaScript code examples for programmatic interaction
Included information about automatic loupe behavior for touch input
Documented pointer capture behavior for smooth dragging

Accessibility Enhancements

Clarified that keyboard accessibility is provided through parent components
Documented touch-specific features like automatic loupe display
Explained focus management delegation to parent components
Added information about appropriate touch target sizing

Testing

Verified all existing content is preserved
Confirmed proper markdown syntax and formatting
Checked consistency with documentation standards
Reviewed accessibility improvements

Related Documentation

Follows structure outlined in Adding a Component Documentation Standards
Maintains consistency with accordion, button, meter, progress bar, progress circle, and tooltip README files
References PR #5640 (color-wheel documentation reorganization) as a model

This reorganization makes the color-handle documentation more accessible, easier to navigate, and consistent with the established documentation standards across the Spectrum Web Components library.

…nd usage examples

changeset-bot · 2025-08-04T05:02:36Z

⚠️ No Changeset found

Latest commit: ffb0126

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2025-08-04T05:04:15Z

📚 Branch Preview

🔍 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-5663

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

github-actions · 2025-08-04T05:07:13Z

Tachometer results

Currently, no packages are changed by this PR...

Rajdeepc · 2025-08-04T06:11:53Z

packages/color-handle/README.md

+
+#### Keyboard Support
+
+While the color handle itself is not directly keyboard accessible, it works in conjunction with its parent components (`<sp-color-area>`, `<sp-color-slider>`, `<sp-color-wheel>`) which provide comprehensive keyboard navigation.


Can we add a small example to surface this usage to our customers?

instead of an example here bringing in another component, I would like to suggest that we link to the other components docs to see it in use

Rajdeepc · 2025-08-04T06:14:02Z

packages/color-handle/README.md

+<sp-table>
+    <sp-table-head>
+        <sp-table-head-cell>Format</sp-table-head-cell>
+        <sp-table-head-cell>Example Values</sp-table-head-cell>
+        <sp-table-head-cell>Description</sp-table-head-cell>
+    </sp-table-head>
+    <sp-table-body>
+        <sp-table-row>
+            <sp-table-cell>Hex3</sp-table-cell>
+            <sp-table-cell><code>#f00</code>, <code>#0a5</code></sp-table-cell>
+            <sp-table-cell>3-digit hexadecimal</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>Hex4</sp-table-cell>
+            <sp-table-cell><code>#f00f</code>, <code>#0a58</code></sp-table-cell>
+            <sp-table-cell>3-digit hexadecimal + alpha</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>Hex6</sp-table-cell>
+            <sp-table-cell><code>#ff0000</code>, <code>#00aa55</code></sp-table-cell>
+            <sp-table-cell>6-digit hexadecimal</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>Hex8</sp-table-cell>
+            <sp-table-cell><code>#ff0000ff</code>, <code>#00aa5580</code></sp-table-cell>
+            <sp-table-cell>6-digit hexadecimal + alpha</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>RGB</sp-table-cell>
+            <sp-table-cell><code>rgb(255, 0, 0)</code>, <code>rgb(0, 170, 85)</code></sp-table-cell>
+            <sp-table-cell>Red, Green, Blue values (0-255)</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>RGBA</sp-table-cell>
+            <sp-table-cell><code>rgba(255, 0, 0, 1)</code>, <code>rgba(0, 170, 85, 0.5)</code></sp-table-cell>
+            <sp-table-cell>RGB + Alpha channel (0-1)</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>HSL</sp-table-cell>
+            <sp-table-cell><code>hsl(0, 100%, 50%)</code>, <code>hsl(150, 100%, 33%)</code></sp-table-cell>
+            <sp-table-cell>Hue (0-360°), Saturation, Lightness</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>HSLA</sp-table-cell>
+            <sp-table-cell><code>hsla(0, 100%, 50%, 1)</code>, <code>hsla(150, 100%, 33%, 0.5)</code></sp-table-cell>
+            <sp-table-cell>HSL + Alpha channel (0-1)</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>HSV</sp-table-cell>
+            <sp-table-cell><code>hsv(0, 100%, 100%)</code>, <code>hsv(150, 100%, 67%)</code></sp-table-cell>
+            <sp-table-cell>Hue (0-360°), Saturation, Value</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>HSVA</sp-table-cell>
+            <sp-table-cell><code>hsva(0, 100%, 100%, 1)</code>, <code>hsva(150, 100%, 67%, 0.5)</code></sp-table-cell>
+            <sp-table-cell>HSV + Alpha channel (0-1)</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>Named Colors</sp-table-cell>
+            <sp-table-cell><code>red</code>, <code>rebeccapurple</code>, <code>darkseagreen</code></sp-table-cell>
+            <sp-table-cell>CSS color keywords (<a href="https://developer.mozilla.org/en-US/docs/Web/CSS/named-color">full list</a>)</sp-table-cell>
+        </sp-table-row>
+    </sp-table-body>
+</sp-table>


The UI is a bit off. Also can you add a note what this table is suggesting. Not sure we need 3 columns. But please cross check.

…ce README for clarity

caseyisonit · 2025-08-05T19:32:05Z

packages/color-handle/README.md


-The `<sp-color-handle>` is used to select a colour on an `<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`. It functions similarly to the handle on an `<sp-slider>`.
+The `<sp-color-handle>` is used to select a color on an `<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`. It functions similarly to the handle on an `<sp-slider>`, providing a draggable control point for precise color selection within color components.


Can we highlight the functional difference between the color-handle and the handle in sp-slider? If there is no difference, I would remove the reference to sp-slider, as that causes confusion.

Should we highlight that this is an atomic level component or maybe discuss the language we would like to use for internal/dumb components?

cc @nikkimk

Done!
I added a note
**Note**: is a primitive component designed to be used within other color selection components. It's not typically used directly in applications, but rather as part of higher-level color components like, , or .

caseyisonit · 2025-08-05T19:35:05Z

packages/color-handle/README.md

+
+### States
+
+#### Standard


I dont think this is necessary...? @nikkimk are we showing default states in all components?

I include the default if I used tabs for a visual comparison, and typically for variants more than states, but it's not necessarily a hill to die on for me.

I think adding a default let the users compare what is the difference b/w default and other states

caseyisonit · 2025-08-05T19:39:53Z

packages/color-handle/README.md

+The color handle can receive keyboard focus when used within interactive color components. The focused state is managed automatically by the parent component and is indicated visually:
+
+```html
+<sp-color-handle focused></sp-color-handle>


since this is handled in the parent, should this example show more of the implementation pattern versus the output in the DOM?

cc @nikkimk

I think it's good to include to show what focused state looks like and how it works within the component.

caseyisonit · 2025-08-05T19:41:39Z

packages/color-handle/README.md

+#### Touch Accessibility
+
+- **Color Loupe**: Automatically appears for touch input to ensure the selected color remains visible
+- **Large Touch Target**: The handle provides an appropriately sized touch target for mobile interaction


What is the size of the touch target?

The size of sp-color-loupe

packages/color-handle/README.md

caseyisonit · 2025-08-05T19:52:26Z

packages/color-handle/README.md

+<sp-color-handle></sp-color-handle>
+```
+
+**Internal Structure**: The component renders an inner div with the background color and an `<sp-color-loupe>` element that appears when the `open` property is true and the component is not disabled.


this call out can be removed with the suggestion above, just added these details to the bullet points

caseyisonit · 2025-08-05T19:52:48Z

packages/color-handle/README.md

+</div>
+```
+
+**Transparency Support**: When using transparent colors, the handle displays an opacity checkerboard pattern background to clearly show the transparency level.


Move this above the example

caseyisonit · 2025-08-05T19:54:00Z

packages/color-handle/README.md

+
+#### Color
+
+The `color` property sets the visual color displayed within the handle. This accepts any valid CSS color format. The default color is `rgba(255, 0, 0, 0.5)` (semi-transparent red).


We should add a table of the colors accepted OR we should add a line about how color uses the color-controller and link to the color-controller docs with the table

caseyisonit · 2025-08-05T19:57:01Z

packages/color-handle/README.md


-When the `<sp-color-handle>` uses the `open` property, the `<sp-color-loupe>` component can be used above the handle to show the selected color that would otherwise be covered by a mouse, stylus, or finger on the down/touch state. This can be customized to appear only on finger-input, or always appear regardless of input type.
+When the `open` property is set, the `<sp-color-loupe>` component appears above the handle to show the selected color that would otherwise be covered by a mouse, stylus, or finger on the down/touch state. The loupe automatically appears for touch input (`pointerType === 'touch'`) and can be manually controlled for other input types.


we should show an example of how to set up the other input types

caseyisonit · 2025-08-05T19:58:08Z

packages/color-handle/README.md


 ```html
 <div style="height: 72px"></div>
 <sp-color-handle open></sp-color-handle>
 ```
+
+**Automatic Behavior**: The loupe automatically opens when touched and closes when the touch interaction ends. For mouse and stylus input, the loupe remains hidden by default unless explicitly set to `open="true"`.


This shouldnt be needed, all details should be covered in the first paragraph, make updates there if you feel the wording needs updating

actually looking in to how this is implemented in other components, this is not automatically configured. we should make sure the examples and docs throughout accurately explain how to use this in a parent component.

color-area implementation of color-handle:

We are not exposing this to users The streamingListener for internal use only

but isnt the streamingListener how a consumer using handle to make a new component would set it up for the event handlers? there is not functional code in handle that sets them up

caseyisonit

left a number of comments and happy to discuss further if anything was unclear :)

nikkimk

This is going to be so helpful and timely for the other audit we're having done. Thanks!

Most of my changes are around making the ColorController docs also follow the same heading structure as other components.

nikkimk · 2025-08-05T20:14:31Z

packages/color-handle/README.md


-The `<sp-color-handle>` is used to select a colour on an `<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`. It functions similarly to the handle on an `<sp-slider>`.
+The `<sp-color-handle>` is used to select a color on an `<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`. It functions similarly to the handle on an `<sp-slider>`, providing a draggable control point for precise color selection within color components.


I'd recommend revering to them my name and not stag unless you are referring to the code that creates them.

Suggested change

The `<sp-color-handle>` is used to select a color on an `<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`. It functions similarly to the handle on an `<sp-slider>`, providing a draggable control point for precise color selection within color components.

The color handle is used to select a color on a [color area](../color-area/), [color slider](../color-slider/), or [color wheel](../color-wheel/). It provides a draggable control point for precise color selection within color components.

nikkimk · 2025-08-05T20:16:08Z

packages/color-handle/README.md

+- A visual handle element that indicates the current position
+- An optional color loupe that appears above the handle when active
+- Touch-responsive interaction areas
+- Color display showing the current selected color
+- Opacity checkerboard pattern for transparent colors


Suggested change

- A visual handle element that indicates the current position

- An optional color loupe that appears above the handle when active

- Touch-responsive interaction areas

- Color display showing the current selected color

- Opacity checkerboard pattern for transparent colors

A visual handle element that indicates the current position

- Touch-responsive interaction areas

- Color display showing the current selected color

- Opacity checkerboard pattern for transparent colors

- An optional color loupe that appears above the handle when active

packages/color-handle/README.md

nikkimk · 2025-08-05T20:20:03Z

packages/color-handle/README.md

+
+### States
+
+#### Standard


I include the default if I used tabs for a visual comparison, and typically for variants more than states, but it's not necessarily a hill to die on for me.

nikkimk · 2025-08-05T20:22:44Z

packages/color-handle/README.md

+The color handle can receive keyboard focus when used within interactive color components. The focused state is managed automatically by the parent component and is indicated visually:
+
+```html
+<sp-color-handle focused></sp-color-handle>


I think it's good to include to show what focused state looks like and how it works within the component.

nikkimk · 2025-08-05T20:28:38Z

tools/reactive-controllers/color-controller.md

-   **`hue`**: Gets or sets the hue value of the current color.
+- **`color`**: Gets or sets the current color value. The color can be provided in various formats, including strings, objects, or instances of the `Color` class.
+- **`colorValue`**: Gets the color value in various formats based on the original color input.
+- **`hue`**: Gets or sets the hue value of the current color.

 ### Methods


Move color formats below the color options.

Suggested change

### Methods

#### Supported Color Formats

The `ColorController` supports a wide range of color formats for input and output:

<sp-table>

<sp-table-head>

<sp-table-head-cell>Format</sp-table-head-cell>

<sp-table-head-cell>Example Values</sp-table-head-cell>

<sp-table-head-cell>Description</sp-table-head-cell>

</sp-table-head>

<sp-table-body>

<sp-table-row>

<sp-table-cell>Hex3</sp-table-cell>

<sp-table-cell><code>#f00</code>, <code>#0a5</code></sp-table-cell>

<sp-table-cell>3-digit hexadecimal</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>Hex4</sp-table-cell>

<sp-table-cell><code>#f00f</code>, <code>#0a58</code></sp-table-cell>

<sp-table-cell>3-digit hexadecimal + alpha</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>Hex6</sp-table-cell>

<sp-table-cell><code>#ff0000</code>, <code>#00aa55</code></sp-table-cell>

<sp-table-cell>6-digit hexadecimal</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>Hex8</sp-table-cell>

<sp-table-cell><code>#ff0000ff</code>, <code>#00aa5580</code></sp-table-cell>

<sp-table-cell>6-digit hexadecimal + alpha</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>RGB</sp-table-cell>

<sp-table-cell><code>rgb(255, 0, 0)</code>, <code>rgb(0, 170, 85)</code></sp-table-cell>

<sp-table-cell>Red, Green, Blue values (0-255)</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>RGBA</sp-table-cell>

<sp-table-cell><code>rgba(255, 0, 0, 1)</code>, <code>rgba(0, 170, 85, 0.5)</code></sp-table-cell>

<sp-table-cell>RGB + Alpha channel (0-1)</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>HSL</sp-table-cell>

<sp-table-cell><code>hsl(0, 100%, 50%)</code>, <code>hsl(150, 100%, 33%)</code></sp-table-cell>

<sp-table-cell>Hue (0-360°), Saturation, Lightness</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>HSLA</sp-table-cell>

<sp-table-cell><code>hsla(0, 100%, 50%, 1)</code>, <code>hsla(150, 100%, 33%, 0.5)</code></sp-table-cell>

<sp-table-cell>HSL + Alpha channel (0-1)</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>HSV</sp-table-cell>

<sp-table-cell><code>hsv(0, 100%, 100%)</code>, <code>hsv(150, 100%, 67%)</code></sp-table-cell>

<sp-table-cell>Hue (0-360°), Saturation, Value</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>HSVA</sp-table-cell>

<sp-table-cell><code>hsva(0, 100%, 100%, 1)</code>, <code>hsva(150, 100%, 67%, 0.5)</code></sp-table-cell>

<sp-table-cell>HSV + Alpha channel (0-1)</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>Named Colors</sp-table-cell>

<sp-table-cell><code>red</code>, <code>rebeccapurple</code>, <code>darkseagreen</code></sp-table-cell>

<sp-table-cell>CSS color keywords (<a href="https://developer.mozilla.org/en-US/docs/Web/CSS/named-color">full list</a>)</sp-table-cell>

</sp-table-row>

</sp-table-body>

</sp-table>

#### Behaviors

We can do that in color-controller's docs audit ticket

nikkimk · 2025-08-05T20:34:24Z

tools/reactive-controllers/color-controller.md

+```

+## Supported Color Formats
+
+The `ColorController` supports a wide range of color formats for input and output:
+
+<sp-table>
+    <sp-table-head>
+        <sp-table-head-cell>Format</sp-table-head-cell>
+        <sp-table-head-cell>Example Values</sp-table-head-cell>
+        <sp-table-head-cell>Description</sp-table-head-cell>
+    </sp-table-head>
+    <sp-table-body>
+        <sp-table-row>
+            <sp-table-cell>Hex3</sp-table-cell>
+            <sp-table-cell><code>#f00</code>, <code>#0a5</code></sp-table-cell>
+            <sp-table-cell>3-digit hexadecimal</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>Hex4</sp-table-cell>
+            <sp-table-cell><code>#f00f</code>, <code>#0a58</code></sp-table-cell>
+            <sp-table-cell>3-digit hexadecimal + alpha</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>Hex6</sp-table-cell>
+            <sp-table-cell><code>#ff0000</code>, <code>#00aa55</code></sp-table-cell>
+            <sp-table-cell>6-digit hexadecimal</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>Hex8</sp-table-cell>
+            <sp-table-cell><code>#ff0000ff</code>, <code>#00aa5580</code></sp-table-cell>
+            <sp-table-cell>6-digit hexadecimal + alpha</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>RGB</sp-table-cell>
+            <sp-table-cell><code>rgb(255, 0, 0)</code>, <code>rgb(0, 170, 85)</code></sp-table-cell>
+            <sp-table-cell>Red, Green, Blue values (0-255)</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>RGBA</sp-table-cell>
+            <sp-table-cell><code>rgba(255, 0, 0, 1)</code>, <code>rgba(0, 170, 85, 0.5)</code></sp-table-cell>
+            <sp-table-cell>RGB + Alpha channel (0-1)</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>HSL</sp-table-cell>
+            <sp-table-cell><code>hsl(0, 100%, 50%)</code>, <code>hsl(150, 100%, 33%)</code></sp-table-cell>
+            <sp-table-cell>Hue (0-360°), Saturation, Lightness</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>HSLA</sp-table-cell>
+            <sp-table-cell><code>hsla(0, 100%, 50%, 1)</code>, <code>hsla(150, 100%, 33%, 0.5)</code></sp-table-cell>
+            <sp-table-cell>HSL + Alpha channel (0-1)</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>HSV</sp-table-cell>
+            <sp-table-cell><code>hsv(0, 100%, 100%)</code>, <code>hsv(150, 100%, 67%)</code></sp-table-cell>
+            <sp-table-cell>Hue (0-360°), Saturation, Value</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>HSVA</sp-table-cell>
+            <sp-table-cell><code>hsva(0, 100%, 100%, 1)</code>, <code>hsva(150, 100%, 67%, 0.5)</code></sp-table-cell>
+            <sp-table-cell>HSV + Alpha channel (0-1)</sp-table-cell>
+        </sp-table-row>
+        <sp-table-row>
+            <sp-table-cell>Named Colors</sp-table-cell>
+            <sp-table-cell><code>red</code>, <code>rebeccapurple</code>, <code>darkseagreen</code></sp-table-cell>
+            <sp-table-cell>CSS color keywords (<a href="https://developer.mozilla.org/en-US/docs/Web/CSS/named-color">full list</a>)</sp-table-cell>
+        </sp-table-row>
+    </sp-table-body>
+</sp-table>
 ```


Move this section above color properties.

Suggested change

```

## Supported Color Formats

The `ColorController` supports a wide range of color formats for input and output:

<sp-table>

<sp-table-head>

<sp-table-head-cell>Format</sp-table-head-cell>

<sp-table-head-cell>Example Values</sp-table-head-cell>

<sp-table-head-cell>Description</sp-table-head-cell>

</sp-table-head>

<sp-table-body>

<sp-table-row>

<sp-table-cell>Hex3</sp-table-cell>

<sp-table-cell><code>#f00</code>, <code>#0a5</code></sp-table-cell>

<sp-table-cell>3-digit hexadecimal</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>Hex4</sp-table-cell>

<sp-table-cell><code>#f00f</code>, <code>#0a58</code></sp-table-cell>

<sp-table-cell>3-digit hexadecimal + alpha</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>Hex6</sp-table-cell>

<sp-table-cell><code>#ff0000</code>, <code>#00aa55</code></sp-table-cell>

<sp-table-cell>6-digit hexadecimal</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>Hex8</sp-table-cell>

<sp-table-cell><code>#ff0000ff</code>, <code>#00aa5580</code></sp-table-cell>

<sp-table-cell>6-digit hexadecimal + alpha</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>RGB</sp-table-cell>

<sp-table-cell><code>rgb(255, 0, 0)</code>, <code>rgb(0, 170, 85)</code></sp-table-cell>

<sp-table-cell>Red, Green, Blue values (0-255)</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>RGBA</sp-table-cell>

<sp-table-cell><code>rgba(255, 0, 0, 1)</code>, <code>rgba(0, 170, 85, 0.5)</code></sp-table-cell>

<sp-table-cell>RGB + Alpha channel (0-1)</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>HSL</sp-table-cell>

<sp-table-cell><code>hsl(0, 100%, 50%)</code>, <code>hsl(150, 100%, 33%)</code></sp-table-cell>

<sp-table-cell>Hue (0-360°), Saturation, Lightness</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>HSLA</sp-table-cell>

<sp-table-cell><code>hsla(0, 100%, 50%, 1)</code>, <code>hsla(150, 100%, 33%, 0.5)</code></sp-table-cell>

<sp-table-cell>HSL + Alpha channel (0-1)</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>HSV</sp-table-cell>

<sp-table-cell><code>hsv(0, 100%, 100%)</code>, <code>hsv(150, 100%, 67%)</code></sp-table-cell>

<sp-table-cell>Hue (0-360°), Saturation, Value</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>HSVA</sp-table-cell>

<sp-table-cell><code>hsva(0, 100%, 100%, 1)</code>, <code>hsva(150, 100%, 67%, 0.5)</code></sp-table-cell>

<sp-table-cell>HSV + Alpha channel (0-1)</sp-table-cell>

</sp-table-row>

<sp-table-row>

<sp-table-cell>Named Colors</sp-table-cell>

<sp-table-cell><code>red</code>, <code>rebeccapurple</code>, <code>darkseagreen</code></sp-table-cell>

<sp-table-cell>CSS color keywords (<a href="https://developer.mozilla.org/en-US/docs/Web/CSS/named-color">full list</a>)</sp-table-cell>

</sp-table-row>

</sp-table-body>

</sp-table>

```

We can do that in color-controller's docs audit ticket

nikkimk · 2025-08-05T20:39:13Z

tools/reactive-controllers/color-controller.md

@@ -118,5 +118,74 @@ class Host extends LitElement {
    }

 }
+```


Move the Example after the anatomy section and before the options section.

We can do that in color-controller's docs audit ticket

nikkimk · 2025-08-05T20:40:40Z

tools/reactive-controllers/color-controller.md

+- **Color Management**: The `ColorController` allows you to manage color values in multiple formats, including RGB, HSL, HSV, and Hex.
+- **Validation**: It provides methods to validate color strings and ensure they conform to the expected formats.
+- **Conversion**: The class can convert colors between different color spaces, making it versatile for various applications.
+- **State Management**: It maintains the current color state and allows saving and restoring previous color values.



Move the example to the Anatomy section.

Suggested change

#### Example

```js

import { LitElement } from 'lit';

import {ColorController} from '@spectrum-web-components/reactive-controllers/src/ColorController.js';

class Host extends LitElement {

/**

* Gets the current color value from the color controller.

*

* @returns {ColorTypes} The current color value.

*/

@property({ type: String })

public get color(): ColorTypes {

return this.colorController.colorValue;

}

/**

* Sets the color for the color controller.

*

* @param {ColorTypes} color - The color to be set.

*/

public set color(color: ColorTypes) {

this.colorController.color = color;

}

private colorController = new ColorController(this, { manageAs: 'hsv' });

}

```

The color Controller could also be initialised in the constructor as shown below

```js

import { LitElement } from 'lit';

import {ColorController} from '@spectrum-web-components/reactive-controllers/src/ColorController.js';

class Host extends LitElement {

/**

* Gets the current color value from the color controller.

*

* @returns {ColorTypes} The current color value.

*/

@property({ type: String })

public get color(): ColorTypes {

return this.colorController.colorValue;

}

/**

* Sets the color for the color controller.

*

* @param {ColorTypes} color - The color to be set.

*/

public set color(color: ColorTypes) {

this.colorController.color = color;

}

private colorController: ColorController; ;

constructor() {

super();

this.colorController = new ColorController(this, { manageAs: 'hsv' });

}

}

```

We can do that in color-controller's docs audit ticket

nikkimk · 2025-08-05T20:41:12Z

tools/reactive-controllers/color-controller.md

-   **`restorePreviousColor(): void`**:  
-    Restores the previous color.
+- **`restorePreviousColor(): void`**:  
+  Restores the previous color.

 ## Usage


Move the Usage section to above Anatomy

We can do that in color-controller's docs audit ticket

Co-authored-by: Casey Eickhoff <[email protected]> Co-authored-by: Nikki Massaro <[email protected]>

blunteshwar · 2025-08-06T14:48:27Z

Since the scope of this ticket is to audit and update the Docs for sp-color-handle we can take up the audit/update of color-controller docs in a separate ticket and separate PR

nikkimk

LGTM

.

docs(color-handle): enhance README with detailed component overview a…

36522c6

…nd usage examples

blunteshwar requested a review from a team as a code owner August 4, 2025 05:02

Rajdeepc reviewed Aug 4, 2025

View reviewed changes

Rajdeepc changed the title ~~docs(color-handle): enhance README with detailed component overview a…~~ docs(color-handle): enhance README with detailed component overview Aug 4, 2025

blunteshwar added 2 commits August 5, 2025 19:09

docs(color-controller): add supported color formats section and enhan…

00b5b62

…ce README for clarity

Merge branch 'main' into SWC-368

189b75e

blunteshwar requested a review from Rajdeepc August 5, 2025 14:30

caseyisonit reviewed Aug 5, 2025

View reviewed changes

packages/color-handle/README.md Outdated Show resolved Hide resolved

caseyisonit reviewed Aug 5, 2025

View reviewed changes

caseyisonit previously requested changes Aug 5, 2025

View reviewed changes

nikkimk requested changes Aug 5, 2025

View reviewed changes

blunteshwar and others added 3 commits August 6, 2025 19:07

chore: minor fix

f3ef3a0

Apply suggestions from code review

6726c92

Co-authored-by: Casey Eickhoff <[email protected]> Co-authored-by: Nikki Massaro <[email protected]>

chore: minor fix

e7e43b5

blunteshwar requested review from nikkimk and caseyisonit August 6, 2025 14:46

Merge branch 'main' into SWC-368

ffb0126

nikkimk approved these changes Aug 6, 2025

View reviewed changes

Rajdeepc approved these changes Aug 7, 2025

View reviewed changes

blunteshwar merged commit 396c12b into main Aug 7, 2025
24 checks passed

blunteshwar deleted the SWC-368 branch August 7, 2025 07:21


		#### Keyboard Support

		While the color handle itself is not directly keyboard accessible, it works in conjunction with its parent components (`<sp-color-area>`, `<sp-color-slider>`, `<sp-color-wheel>`) which provide comprehensive keyboard navigation.


		The `<sp-color-handle>` is used to select a colour on an `<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`. It functions similarly to the handle on an `<sp-slider>`.
		The `<sp-color-handle>` is used to select a color on an `<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`. It functions similarly to the handle on an `<sp-slider>`, providing a draggable control point for precise color selection within color components.


		#### Color

		The `color` property sets the visual color displayed within the handle. This accepts any valid CSS color format. The default color is `rgba(255, 0, 0, 0.5)` (semi-transparent red).


		When the `<sp-color-handle>` uses the `open` property, the `<sp-color-loupe>` component can be used above the handle to show the selected color that would otherwise be covered by a mouse, stylus, or finger on the down/touch state. This can be customized to appear only on finger-input, or always appear regardless of input type.
		When the `open` property is set, the `<sp-color-loupe>` component appears above the handle to show the selected color that would otherwise be covered by a mouse, stylus, or finger on the down/touch state. The loupe automatically appears for touch input (`pointerType === 'touch'`) and can be manually controlled for other input types.

	The `<sp-color-handle>` is used to select a color on an `<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`. It functions similarly to the handle on an `<sp-slider>`, providing a draggable control point for precise color selection within color components.
	The color handle is used to select a color on a [color area](../color-area/), [color slider](../color-slider/), or [color wheel](../color-wheel/). It provides a draggable control point for precise color selection within color components.

@@ @@ -118,5 +118,74 @@ class Host extends LitElement { @@
                   }
               }
+              ```

+#### Example
+```js
+import { LitElement } from 'lit';
+import {ColorController} from '@spectrum-web-components/reactive-controllers/src/ColorController.js';
+class Host extends LitElement {
+    /**
+     * Gets the current color value from the color controller.
+     *
+     * @returns {ColorTypes} The current color value.
+     */
+    @property({ type: String })
+    public get color(): ColorTypes {
+        return this.colorController.colorValue;
+    }
+    /**
+     * Sets the color for the color controller.
+     *
+     * @param {ColorTypes} color - The color to be set.
+     */
+    public set color(color: ColorTypes) {
+        this.colorController.color = color;
+    }
+    private colorController = new ColorController(this, { manageAs: 'hsv' });
+}
+```
+The color Controller could also be initialised in the constructor as shown below
+```js
+import { LitElement } from 'lit';
+import {ColorController} from '@spectrum-web-components/reactive-controllers/src/ColorController.js';
+class Host extends LitElement {
+    /**
+     * Gets the current color value from the color controller.
+     *
+     * @returns {ColorTypes} The current color value.
+     */
+    @property({ type: String })
+    public get color(): ColorTypes {
+        return this.colorController.colorValue;
+    }
+    /**
+     * Sets the color for the color controller.
+     *
+     * @param {ColorTypes} color - The color to be set.
+     */
+    public set color(color: ColorTypes) {
+        this.colorController.color = color;
+    }
+    private colorController: ColorController; ;
+    constructor() {
+        super();
+        this.colorController = new ColorController(this, { manageAs: 'hsv' });
+    }
+}
+```

docs(color-handle): enhance README with detailed component overview #5663

docs(color-handle): enhance README with detailed component overview #5663

Uh oh!

Conversation

blunteshwar commented Aug 4, 2025

Overview

Changes Made

Uh oh!

changeset-bot bot commented Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented Aug 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview

🔍 Visual Regression Test Results

Uh oh!

github-actions bot commented Aug 4, 2025

Tachometer results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

caseyisonit left a comment

Choose a reason for hiding this comment

Uh oh!

nikkimk left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

changeset-bot bot commented Aug 4, 2025 •

edited

Loading

github-actions bot commented Aug 4, 2025 •

edited

Loading