|
| 1 | +<!-- Generated breadcrumbs - DO NOT EDIT --> |
| 2 | + |
| 3 | +[CONTRIBUTOR-DOCS](../../../README.md) / [Project planning](../../README.md) / [Components](../README.md) / Color Loupe / Color loupe accessibility migration analysis |
| 4 | + |
| 5 | +<!-- Document title (editable) --> |
| 6 | + |
| 7 | +# Color loupe accessibility migration analysis |
| 8 | + |
| 9 | +<!-- Generated TOC - DO NOT EDIT --> |
| 10 | + |
| 11 | +<details open> |
| 12 | +<summary><strong>In this doc</strong></summary> |
| 13 | + |
| 14 | +- [Overview](#overview) |
| 15 | + - [Also read](#also-read) |
| 16 | + - [What it is](#what-it-is) |
| 17 | +- [ARIA and WCAG context](#aria-and-wcag-context) |
| 18 | + - [Pattern in the APG](#pattern-in-the-apg) |
| 19 | + - [Guidelines that apply](#guidelines-that-apply) |
| 20 | +- [Related 1st-gen accessibility (Jira)](#related-1st-gen-accessibility-jira) |
| 21 | +- [Recommendations: `<swc-color-loupe>`](#recommendations-swc-color-loupe) |
| 22 | + - [ARIA roles, states, and properties](#aria-roles-states-and-properties) |
| 23 | + - [Shadow DOM and cross-root ARIA Issues](#shadow-dom-and-cross-root-aria-issues) |
| 24 | + - [Accessibility tree expectations](#accessibility-tree-expectations) |
| 25 | + - [Keyboard and focus](#keyboard-and-focus) |
| 26 | + - [Story and test examples](#story-and-test-examples) |
| 27 | +- [Known 1st-gen issues](#known-1st-gen-issues) |
| 28 | + - [Non-text contrast on loupe chrome (WCAG 1.4.11)](#non-text-contrast-on-loupe-chrome-wcag-1411) |
| 29 | +- [Testing](#testing) |
| 30 | + - [Automated tests](#automated-tests) |
| 31 | +- [Summary checklist](#summary-checklist) |
| 32 | +- [References](#references) |
| 33 | + |
| 34 | +</details> |
| 35 | + |
| 36 | +<!-- Document content (editable) --> |
| 37 | + |
| 38 | +## Overview |
| 39 | + |
| 40 | +This doc explains how **`swc-color-loupe`** should work for **accessibility**. It supports **WCAG 2.2 Level AA** as the team target, while recording **known** limitations for **non-text contrast** on the loupe chrome. Until **`swc-color-loupe`** ships, use **`1st-gen/packages/color-loupe/src/ColorLoupe.ts`** (`<sp-color-loupe>`) as the behavioral reference. |
| 41 | + |
| 42 | +### Also read |
| 43 | + |
| 44 | +- [Color field migration roadmap](../color-field/rendering-and-styling-migration-analysis.md)—the loupe is almost always used **with** a color **field** or similar **picker** UI, not alone. |
| 45 | + |
| 46 | +### What it is |
| 47 | + |
| 48 | +- A **visual magnifier** that shows the **picked color** (including **transparency** over an **opacity checkerboard**) inside a **loupe** shape with **inner** / **outer** borders. |
| 49 | +- It is **not** the primary control for choosing a color; it **reflects** the current sample. |
| 50 | + |
| 51 | +--- |
| 52 | + |
| 53 | +## ARIA and WCAG context |
| 54 | + |
| 55 | +### Pattern in the APG |
| 56 | + |
| 57 | +- The [APG](https://www.w3.org/WAI/ARIA/apg/) does **not** define a standalone “color loupe” widget. Treat the loupe as **supporting UI** for **color selection**, with **accessibility** carried by the **surrounding** pattern (**label**, **inputs**, **live** value text where appropriate). |
| 58 | + |
| 59 | +### Guidelines that apply |
| 60 | + |
| 61 | +| Idea | Plain meaning | |
| 62 | +|------|----------------| |
| 63 | +| [Non-text contrast (WCAG 1.4.11)](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast) | **Borders** and other **non-text** parts needed to **perceive** the loupe shape against **adjacent** colors should meet **at least 3:1** contrast. The loupe sits over **variable** content; **1st-gen** styling often **does not** meet **3:1** for the loupe **chrome**—see **Known 1st-gen issues** and [SWC-1193](https://jira.corp.adobe.com/browse/SWC-1193). | |
| 64 | +| [Non-text content (WCAG 1.1.1)](https://www.w3.org/WAI/WCAG22/Understanding/non-text-content) | **1st-gen** marks the **SVG** **`aria-hidden="true"`**—the graphic is **decorative** relative to assistive tech **if** the **parent** pattern exposes the **color** and **purpose** in text or other accessible names. | |
| 65 | +| [Use of color (WCAG 1.4.1)](https://www.w3.org/TR/WCAG22/#use-of-color) | The **loupe** shows **color**; meaning must **not** rely on the loupe **alone**. The **field** / **slider** / **hex** input must **state** what is being adjusted. | |
| 66 | + |
| 67 | +**Bottom line:** Pair **`swc-color-loupe`** with a **fully labeled** color **workflow**. Accept **documented** **1.4.11** limitations on loupe **chrome** per **SWC-1193** unless design finds a **conformant** approach that still meets product goals. |
| 68 | + |
| 69 | +--- |
| 70 | + |
| 71 | +## Related 1st-gen accessibility (Jira) |
| 72 | + |
| 73 | +| Jira | Type | Status (snapshot) | Resolution (snapshot) | Summary | |
| 74 | +|------|------|-------------------|-------------------------|---------| |
| 75 | +| [SWC-1193](https://jira.corp.adobe.com/browse/SWC-1193) | Bug | Done | Working As Designed | [Accessibility] Graphical object lacks 3:1 contrast ratio — `sp-color-loupe` (Color Loupe Example) | |
| 76 | + |
| 77 | +--- |
| 78 | + |
| 79 | +## Recommendations: `<swc-color-loupe>` |
| 80 | + |
| 81 | +### ARIA roles, states, and properties |
| 82 | + |
| 83 | +| Topic | What to do | |
| 84 | +|-------|------------| |
| 85 | +| **Non-text contrast (1.4.11)** | Aim for **3:1** on **loupe** **borders** / **edges** vs **adjacent** UI where **feasible**. Where **variable color** constraints make **3:1** **unrealistic** for all states, record the **[SWC-1193](https://jira.corp.adobe.com/browse/SWC-1193)** **decision** and keep **audit** language aligned with SWC-1196's **[comment](https://jira.corp.adobe.com/browse/SWC-1193?focusedId=51301299&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-51301299)** on practical limits. | |
| 86 | +| **Docs** | State that the loupe is a **visual aid**, not a **standalone** **accessible** color **control**. Point authors to **color field** / **picker** docs for **labels**, **keyboard**, and **values**. | |
| 87 | + |
| 88 | +### Shadow DOM and cross-root ARIA Issues |
| 89 | + |
| 90 | +None |
| 91 | + |
| 92 | +### Accessibility tree expectations |
| 93 | + |
| 94 | +- With **1st-gen** **`aria-hidden`** **SVG**, assistive technologies typically **ignore** the **vector** graphic; users rely on **paired** **controls** and **text** for **color** and **context**. |
| 95 | +- If **`open`** is **false**, the loupe is **hidden** visually; behavior should stay **consistent** with **CSS** / **display** and **not** trap **focus** in a **closed** loupe. |
| 96 | + |
| 97 | +### Keyboard and focus |
| 98 | + |
| 99 | +**Not focusable.** Keyboard navigation should skip this component and move to the next focusable element. |
| 100 | + |
| 101 | +### Story and test examples |
| 102 | + |
| 103 | +- **Stories** and **automated tests** should show **`swc-color-loupe`** / **`<sp-color-loupe>`** **in context** with **other** components (for example a **color field**, **sliders**, **labels**, **help text**), **not** as a **lone** widget on an empty canvas—unless the story’s **only** goal is a **narrow** **visual** check. |
| 104 | +- Examples must be **fully accessible**: **correct** **`label`** / **`aria-labelledby`** / **`aria-label`** where needed, **descriptive** strings (no **placeholder-only** meaning), and **layouts** that resemble **real** product **usage** so **docs**, **VRT**, and **a11y** tests **exercise** realistic **trees**. |
| 105 | + |
| 106 | +--- |
| 107 | + |
| 108 | +## Known 1st-gen issues |
| 109 | + |
| 110 | +### Non-text contrast on loupe chrome (WCAG 1.4.11) |
| 111 | + |
| 112 | +- **1st-gen** **`<sp-color-loupe>`** **border** / **loupe** **outline** styling often **does not** achieve the **minimum 3:1** **contrast ratio** against **adjacent** colors required by [**WCAG 2.2 Success Criterion 1.4.11** (Non-text contrast, Level AA)](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast). |
| 113 | +- **[SWC-1193](https://jira.corp.adobe.com/browse/SWC-1193)** (Adobe **internal** Jira): **Najika** notes that meeting **1.4.11** for this control **realistically** may **not** be **achievable** given how the loupe **overlays** **arbitrary** **content** and **Spectrum** **visual** **intent**. Treat that ticket as the **product** / **a11y** **decision** record for **exceptions** or **risk** **acceptance** until **design** **changes** or **new** **techniques** land. |
| 114 | + |
| 115 | +--- |
| 116 | + |
| 117 | +## Testing |
| 118 | + |
| 119 | +### Automated tests |
| 120 | + |
| 121 | +| Kind of test | What to check | |
| 122 | +|--------------|----------------| |
| 123 | +| **Unit** | **`open`** / **`color`** do **not** break **parent** **label** associations; **SVG** **`aria-hidden`** matches implementation. | |
| 124 | +| **aXe + Storybook** | Run on **composite** stories (loupe **+** **field** / **sliders**), **not** only **isolated** loupe frames. | |
| 125 | +| **Contrast** | Where **policy** requires, measure **loupe** **chrome** at **representative** backgrounds; **document** **gaps** **per** **SWC-1193** when **3:1** is **not** met. | |
| 126 | +| **Integration** | **E2E** / **snapshots** use **realistic** **pages**: **labels**, **focus order**, and **values** on **surrounding** **controls**. | |
| 127 | + |
| 128 | +--- |
| 129 | + |
| 130 | +## Summary checklist |
| 131 | + |
| 132 | +- [ ] **Stories** place the loupe **in** **real** **picker** **contexts** with **accessible** **siblings**, not **only** the loupe **on** **gray** **canvas**. |
| 133 | +- [ ] **Copy** is **descriptive**; **no** **token-only** **labels** as the **sole** **accessible** **name** for **user-facing** **steps**. |
| 134 | +- [ ] **Color field** (or **equivalent**) **owns** **name**, **value**, and **keyboard**; loupe does **not** **stand** **in** for **that**. |
| 135 | +- [ ] **SWC-1193** **position** on **1.4.11** is **reflected** in **internal** **audit** / **release** **notes** where **needed**. |
| 136 | +- [ ] **Contrast** **measurements** for **loupe** **chrome** are **attempted** on **key** **themes**; **failures** are **known** **issues**, **not** **silent**. |
| 137 | + |
| 138 | +--- |
| 139 | + |
| 140 | +## References |
| 141 | + |
| 142 | +- [WCAG 2.2 Success Criterion 1.4.11: Non-text contrast (understanding)](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast) |
| 143 | +- [WCAG 2.2](https://www.w3.org/TR/WCAG22/) |
| 144 | +- [Using ARIA (read this first)](https://www.w3.org/WAI/ARIA/apg/practices/read-me-first/) |
| 145 | +- [SWC-1193](https://jira.corp.adobe.com/browse/SWC-1193) (Adobe internal Jira—non-text contrast / realistic constraints for color loupe) |
| 146 | +- [Color field migration roadmap](../color-field/rendering-and-styling-migration-analysis.md) |
0 commit comments