Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(ProgressBar): target marks render outside the progressbar so their labels stay exposed (#10193)

Cindy Zhang0a335a9be075
diff --git a/docs/specs/components/ProgressBar/ProgressBar.spec.md b/docs/specs/components/ProgressBar/ProgressBar.spec.md
index 4c0d416a17..359ca1c71d 100644
--- a/docs/specs/components/ProgressBar/ProgressBar.spec.md
+++ b/docs/specs/components/ProgressBar/ProgressBar.spec.md
@@ -97,11 +97,6 @@ Consumer migration instructions belong in consumer docs and release notes.
percentages differently read and see the English form, where
`architecture:internationalization` INV1a has Astryx-owned text come from
one catalog message.
-- **Marks are focusable without a role or name (FR7).** Each mark is a
- focusable `span` with no role and no accessible name; its label reaches
- assistive technology only as a description, and only once the tooltip code
- has loaded, so screen reader users land on an unnamed stop (WCAG 2.2 SC
- 4.1.2).
- **Caller `data-variant` replaces the reflected variant (FR8).** Caller props
spread after the root's theme attributes, so a caller `data-variant`
replaces the reflected value and theme rules for the real variant stop
@@ -172,7 +167,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR4 | The track is 8px high, fully rounded, in `--color-background-muted`, and clips the fill. The determinate fill spans the track and slides along it so its leading edge sits at the clamped percentage, mirrored by the bar's own writing direction, moving from where it is drawn over `--duration-medium` with the theme's easing when the value changes, under every pointer, a finger included (`spec:AST-094` FR45). Under a coarse primary pointer (`spec:AST-094` FR13), above zero it draws at least 16px long, a mark that length covers counts as on the fill (FR7), and at zero it paints nothing. `progress.fillTrackMs` (1000ms, UIKit's progress view for a whole-track change) and its linear curve, `progress.curves.fill`, stay in the generated motion role table as UIKit's measured reference, and no motion plays them (`spec:AST-094` FR4, DEC-5). Implementation gap: under a coarse primary pointer the fill still moves linearly for `progress.fillTrackMs` times the share of the track the value moved. Under reduced motion a new value lands at once on every pointer (`design:reduced-motion` DR1). The fill paints `--color-accent`, `--color-success`, `--color-warning`, or `--color-error`, or `--color-text-disabled` for `neutral` and disabled bars; a theme-added variant has a safe theme-independent fill (`architecture:component-theming-surface` INV14). Implementation gap: a theme-added variant paints no fill and no on-fill mark color until a theme styles it (Current-state impact). In forced colors the fill is sized to the value instead of sliding and keeps a 1px `CanvasText` outline so its shape stays visible (`architecture:theme-tokens` INV11). | Current source and tests; UIKit measurement (iOS 26.2 simulator); `component:ProgressBar/DEC-2` |
| FR5 | `isDisabled` mutes the fill, label, value text, and marks and adds no ARIA state. | Current source and tests |
| FR6 | `isIndeterminate` removes every value attribute and the value text. Without reduced motion, on every pointer, a 40% fill slides across the clipped track, eased, 1.5s a pass, mirrored by the bar's own rendered direction (`architecture:internationalization` INV11). Under reduced motion, on every pointer, the fill spans the whole track as one solid bar, with no segment and no travel, and only its opacity pulses: from 1 down to 0.84 and back, each way taking the `progress.reducedMotionPulseMs` role (2000ms) on the `timing.curves.move` curve; the track is unchanged. The pulse is a busy loop, so tempo does not scale it (`spec:AST-094` FR4, `spec:AST-108` FR4). It applies `design:reduced-motion` DR1's no-travel rule, replacing the travel with an opacity change, to a loop that record leaves to its component. At the 0.84 floor the fill keeps at least 3:1 against the track in both themes for every tone that reaches 3:1 at full opacity (AR4). Implementation gap: the slide, and the centering of marks, mirror under any right-to-left ancestor rather than the bar's own direction, so in a left-to-right region of a right-to-left page they run against the label (Current-state impact). | Current source and tests; `component:ProgressBar/DEC-2` |
-| FR7 | Each finite mark renders, outside the `progressbar` element, a tick at its clamped position whose tooltip shows its label on hover and focus; marks inside the filled part take the fill's contrasting color, and marks do not render while indeterminate. A focusable mark exposes its label as its accessible name (WCAG 2.2 SC 4.1.2). Implementation gap: marks are focusable `span`s with no role or name, labelled only as a description once the tooltip loads (Current-state impact). | Current source and tests |
+| FR7 | Each finite mark renders, outside the `progressbar` element so its label stays exposed, a tick at its clamped position whose tooltip shows its label on hover and focus; marks inside the filled part take the fill's contrasting color, and marks do not render while indeterminate. A focusable mark exposes its label as its accessible name (WCAG 2.2 SC 4.1.2). Each mark is an image named by its label. | Current source and tests |
| FR8 | The root carries `progress-bar` reflecting `variant`, the track `progress-bar-track`, the fill `progress-bar-fill` reflecting the resolved fill variant, and each mark `progress-bar-mark` reflecting the resolved fill variant and placement; the label and value text carry no target. Reflected state stays component-owned (`architecture:public-component-api` INV5). Implementation gap: a caller `data-variant` replaces the root's reflected variant (Current-state impact). | Current source and tests |
| FR9 | `ref` and `data-testid` reach the root; supported DOM, data, ARIA, and event props reach the root, while the reflected theme attributes stay component-owned (FR8); `xstyle`, `className`, and `style` compose after component styles. | Current source and tests; `architecture:public-component-api` INV5–INV8 |
@@ -192,7 +187,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| Label hidden | The bar keeps its accessible name. | — |
| Determinate, touch | Under a coarse primary pointer the fill moves from where it is drawn on the theme's duration and easing; at least 16px above zero; nothing at zero. | Variant. |
| Indeterminate | No value attributes; sliding fill; under reduced motion a full-width fill pulses its opacity in place, with no travel. | Variant. |
-| With marks | Ticks outside the `progressbar`, labelled by tooltip. | Mark labels. |
+| With marks | Ticks outside the `progressbar`, each an image named by its label; its tooltip shows the label. | Mark labels. |
### Transformation and precedence order
@@ -284,7 +279,7 @@ those parts stay untargeted.
| FR4 touch timing | `ProgressBarTouch.a11y.chromium.spec.ts`; the `ProgressBar.test.tsx` touch suite | Coarse vs fine pointer; 10% to 90%; a new value mid-move; 1% on a narrow track; zero; reduced motion | A move under any pointer that leaves the theme's eased duration or starts from the old value instead of the drawn position; a coarse-pointer non-zero fill shorter than 16px; or a painted fill at zero fails. | `audit:ProgressBar/behavior` |
| FR6 reduced motion | The reduced-motion pulse cases of `ProgressBarMotion.a11y.chromium.spec.ts`; the `ProgressBar.test.tsx` pulse suite | Every variant; coarse and fine pointer | A segment, any transform or travel, a fill narrower than the track, an animated property other than the fill's opacity, an opacity below 0.84, a period other than `progress.reducedMotionPulseMs` each way, or a changed track fails. | `audit:ProgressBar/behavior` |
| AR4 | The pulse-floor contrast case of `ProgressBarMotion.a11y.chromium.spec.ts` | Every variant; light and dark default themes; body and surface backgrounds | A tone that reaches 3:1 at full opacity and falls below 3:1 at the floor fails. Gap: warning and neutral in light are below 3:1 at full opacity (OQ1). | `audit:ProgressBar/a11y` |
-| FR7 | `ProgressBar.test.tsx` target-mark suite | None; one; many; clamped; non-finite; on fill; indeterminate; disabled; tooltip | A missing, misplaced, or clipped mark, a mark inside the `progressbar`, a lost tooltip, or a wrong on-fill color fails. Gap: the test asserts that marks have no role and no `aria-label`, which pins the FR7 gap. | `audit:ProgressBar/a11y` |
+| FR7 | `ProgressBar.test.tsx` target-mark suite; `ProgressBar.a11y.chromium.spec.ts` mark-name tests | None; one; many; clamped; non-finite; on fill; indeterminate; disabled; tooltip | A missing, misplaced, or clipped mark, a mark inside the `progressbar`, a mark that is not an image named by its label, a lost tooltip, or a wrong on-fill color fails. | `audit:ProgressBar/a11y` |
| FR8 | `ProgressBar.test.tsx` target-name and mark-target tests; `themingTargets.test.ts` | Four canonical targets | A missing or renamed target fails. Gap: no test covers a caller `data-variant`. `themingTargets.test.ts` catches only a renamed or undocumented target; no check fails if a part stops carrying its target. | `audit:ProgressBar/theming` |
| FR9 | `ProgressBar.test.tsx` ref and `data-testid` tests | Ref; test id | A ref that is not a `div` or a lost test id fails. Gap: the ref test checks only that the ref is a `div`, not that it is the root, and no test covers DOM props, `className`, `style`, or the `xstyle` merge order. | `audit:ProgressBar/api` |
| PR1 | Source review | Every state | Gap: no automated check fails if ProgressBar starts inspecting nearby content. | `audit:ProgressBar/behavior` |