Skip to content

Commit 76fe2c2

Browse files
blunteshwarblunteshwar
authored
docs(color-loupe): update README for clarity and structure (#5700)
* docs(color-loupe): update README for clarity and structure * docs(color-loupe): enhance README with accessibility details and touch interaction improvements * docs(color-loupe): expand README with new tabbed interface examples for color selection components
1 parent 67c3481 commit 76fe2c2

File tree

1 file changed

+200
-5
lines changed

1 file changed

+200
-5
lines changed

‎packages/color-loupe/README.md

Lines changed: 200 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
## Description
1+
## Overview
22

33
An `<sp-color-loupe>` shows the output color that would otherwise be covered by a cursor, stylus, or finger during color selection.
44

@@ -7,23 +7,28 @@ An `<sp-color-loupe>` shows the output color that would otherwise be covered by
77
[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/color-loupe?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/color-loupe)
88
[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/color-loupe?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/color-loupe)
99

10-
```
10+
```bash
1111
yarn add @spectrum-web-components/color-loupe
1212
```
1313

1414
Import the side effectful registration of `<sp-color-loupe>` via:
1515

16-
```
16+
```javascript
1717
import '@spectrum-web-components/color-loupe/sp-color-loupe.js';
1818
```
1919

2020
When looking to leverage the `ColorLoupe` base class as a type and/or for extension purposes, do so via:
2121

22-
```
22+
```javascript
2323
import { ColorLoupe } from '@spectrum-web-components/color-loupe';
2424
```
2525

26-
## Example
26+
### Anatomy
27+
28+
The color loupe consists of:
29+
30+
- A floating loupe element positioned above the interaction point
31+
- A color preview that reflects the color currently sampled by its parent color component
2732

2833
```html
2934
<div style="padding: 100px 0 0;">
@@ -32,3 +37,193 @@ import { ColorLoupe } from '@spectrum-web-components/color-loupe';
3237
</div>
3338
</div>
3439
```
40+
41+
### Options
42+
43+
#### Color
44+
45+
The color property sets the visual color displayed within the loupe. This accepts any valid CSS color format.
46+
47+
For a complete list of supported color formats, see the [ColorController documentation](/tools/color-controller#supported-color-formats).
48+
49+
Transparency Support: When using transparent colors, the handle displays an opacity checkerboard pattern background to clearly show the transparency level.
50+
51+
```html
52+
<div
53+
style="display: flex; flex-direction: row; justify-content: space-between; align-items: flex-start; width: 100%;;"
54+
>
55+
<!-- Yellow color loupe -->
56+
<div style="padding: 100px 0 0; position: relative; min-width: 120px;">
57+
<div style="position: relative;">
58+
<sp-color-loupe color="yellow" open dir="ltr"></sp-color-loupe>
59+
</div>
60+
</div>
61+
62+
<!-- Red color loupe -->
63+
<div style="padding: 100px 0 0; position: relative; min-width: 120px;">
64+
<div style="position: relative;">
65+
<sp-color-loupe color="#ff0000" open dir="ltr"></sp-color-loupe>
66+
</div>
67+
</div>
68+
69+
<!-- Blue color loupe -->
70+
<div style="padding: 100px 0 0; position: relative; min-width: 120px;">
71+
<div style="position: relative;">
72+
<sp-color-loupe
73+
color="rgba(44, 62, 224, 0.81)"
74+
open
75+
dir="ltr"
76+
></sp-color-loupe>
77+
</div>
78+
</div>
79+
80+
<!-- Green color loupe -->
81+
<div style="padding: 100px 0 0; position: relative; min-width: 120px;">
82+
<div style="position: relative;">
83+
<sp-color-loupe
84+
color="hsl(111, 82%, 56%)"
85+
open
86+
dir="ltr"
87+
></sp-color-loupe>
88+
</div>
89+
</div>
90+
</div>
91+
```
92+
93+
### States
94+
95+
#### Open
96+
97+
The `open` attribute controls whether the loupe is visible. When `open` is present, the loupe displays the color preview.
98+
99+
```html
100+
<div style="display: flex; flex-direction: row; gap: 20px;">
101+
<!-- Loupe is visible -->
102+
<div style="padding: 100px 0 0; margin-left:20%">
103+
<div style="position:relative">
104+
<sp-color-loupe open="" dir="ltr"></sp-color-loupe>
105+
<p id="color-context" style="margin-top: 40px">
106+
This loupe above this text is visible.
107+
</p>
108+
</div>
109+
</div>
110+
111+
<!-- Loupe is hidden -->
112+
<div style="padding: 100px 0 0;">
113+
<div style="position:relative">
114+
<sp-color-loupe dir="ltr"></sp-color-loupe>
115+
<p id="color-context" style="margin-top: 40px">
116+
This loupe above this text is not visible.
117+
</p>
118+
</div>
119+
</div>
120+
</div>
121+
```
122+
123+
### Behaviors
124+
125+
The color loupe is typically managed by its parent color component (such as `<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`). The loupe automatically appears when the user interacts with the parent component and disappears when the interaction ends.
126+
127+
#### Automatic behavior
128+
129+
- **Touch input**: The loupe automatically appears during touch interactions with any color component (`<sp-color-area>`, `<sp-color-slider>`, or `<sp-color-wheel>`) to prevent the finger from obscuring the selected color
130+
- **Mouse/Stylus input**: The loupe remains hidden by default for precision pointing devices
131+
- **Parent control**: The loupe's visibility is managed by the parent color component
132+
- **Accessibility**: The loupe ensures that users can see the selected color even when their finger covers the interaction point
133+
134+
### Accessibility
135+
136+
The `<sp-color-loupe>` is designed to work as part of accessible color selection components. The loupe automatically appears during touch interactions with any of these components to ensure the selected color remains visible:
137+
138+
<sp-tabs selected="color-area" auto label="ColorArea">
139+
<sp-tab value="color-area">Color-Area</sp-tab>
140+
<sp-tab-panel value="color-area">
141+
142+
```html
143+
<div
144+
style="display: flex; flex-direction: row; justify-content: space-between; width: 100%;"
145+
>
146+
<sp-color-area
147+
aria-label="Saturation and brightness selector - adjust color intensity and lightness"
148+
aria-describedby="color-context"
149+
></sp-color-area>
150+
</div>
151+
```
152+
153+
</sp-tab-panel>
154+
<sp-tab value="color-slider">Color-Slider</sp-tab>
155+
<sp-tab-panel value="color-slider">
156+
157+
```html
158+
<div
159+
style="display: flex; flex-direction: row; justify-content: space-between; width: 100%;"
160+
>
161+
<sp-color-slider
162+
aria-label="Hue slider - adjust the base color"
163+
aria-describedby="color-context"
164+
></sp-color-slider>
165+
</div>
166+
```
167+
168+
</sp-tab-panel>
169+
<sp-tab value="color-wheel">Color-Wheel</sp-tab>
170+
<sp-tab-panel value="color-wheel">
171+
172+
```html
173+
<div
174+
style="display: flex; flex-direction: row; justify-content: space-between; width: 100%;"
175+
>
176+
<sp-color-wheel
177+
aria-label="Color wheel - select from the full color spectrum"
178+
aria-describedby="color-context"
179+
></sp-color-wheel>
180+
</div>
181+
```
182+
183+
</sp-tab-panel>
184+
</sp-tabs>
185+
186+
#### Screen reader support
187+
188+
The color loupe is rendered as a visual indicator and does not directly interface with screen readers. Accessibility is provided through the parent color component's ARIA implementation.
189+
190+
#### Focus management
191+
192+
Focus is managed by the parent color component, with the loupe reflecting the focused state visually when its parent component has keyboard focus.
193+
194+
#### Touch accessibility
195+
196+
- **Automatic loupe display**: During touch interactions with any color component, the loupe automatically appears to ensure the selected color remains visible
197+
- **Finger coverage prevention**: The loupe prevents the user's finger from obscuring the color they're selecting
198+
- **Touch interaction support**: Color components support touch interactions with proper pointer event handling
199+
- **Visual feedback**: The loupe provides immediate visual feedback during touch interactions
200+
201+
#### Best practices
202+
203+
- Ensure the parent color component (for example, `sp-color-area`, `sp-color-slider`, or `sp-color-wheel`) provides appropriate labeling via visible text or ARIA
204+
- Avoid conveying meaning through color alone; pair color with text, labels, or other indicators as appropriate
205+
- The loupe is visual-only and should not receive focus. Manage focus on the interactive parent control
206+
- Test touch interactions on mobile devices to ensure the loupe appears correctly and provides adequate visual feedback
207+
208+
#### Accessible example
209+
210+
Provide clear context for what the loupe displays. The loupe itself is presentational and is typically managed by its parent color component. During touch interactions, the loupe automatically appears to ensure the selected color remains visible. The loupe is a visual-only element and doesn't require ARIA attributes since it doesn't provide interactive functionality.
211+
212+
```html
213+
<div
214+
role="region"
215+
aria-label="Color selection interface"
216+
style="padding: 100px 0 0;"
217+
>
218+
<div
219+
style="position: relative; display: flex; flex-direction: column; align-items: center;"
220+
>
221+
<sp-color-loupe open dir="ltr"></sp-color-loupe>
222+
</div>
223+
<p id="color-context" style="margin-top: 8px; text-align: center;">
224+
The loupe above shows the color currently selected. During touch
225+
interactions, it automatically appears to prevent your finger from
226+
covering the selected color.
227+
</p>
228+
</div>
229+
```

0 commit comments

Comments
 (0)