Skip to content

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

TypeScript

fix(core): StatusDot status dots paint their icon role (#10204)

Cindy Zhang47949436a104
diff --git a/.changeset/status-dot-icon-role-docs.md b/.changeset/status-dot-icon-role-docs.md
new file mode 100644
index 0000000000..8bbeadcd83
--- /dev/null
+++ b/.changeset/status-dot-icon-role-docs.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] The CLI's bundled colour token docs say the status icon colours (`--color-icon-<status>`) paint status marks on the page or a card, such as a StatusDot.
+
+@cixzhang
diff --git a/.changeset/status-dot-icon-role.md b/.changeset/status-dot-icon-role.md
new file mode 100644
index 0000000000..2b3916869a
--- /dev/null
+++ b/.changeset/status-dot-icon-role.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `StatusDot`'s `success`, `warning` and `error` dots paint their status icon role (`--color-icon-<status>`) instead of the strong status fill, so the dot keeps 3:1 or more against the page and card surfaces; the warning dot used to read near 1.8:1 on a muted card. Success and error dots change colour too: they take their status icon colour, which is darker in light mode in the default theme. An `icon` inside a status dot now paints in the surface colour.
+
+@cixzhang
diff --git a/docs/specs/components/StatusDot/StatusDot.spec.md b/docs/specs/components/StatusDot/StatusDot.spec.md
index a6d6b0f42e..a80db70cb8 100644
--- a/docs/specs/components/StatusDot/StatusDot.spec.md
+++ b/docs/specs/components/StatusDot/StatusDot.spec.md
@@ -56,7 +56,10 @@ optional pulse, optional inner mark, and its accessible name.
## Compatibility and migration
- Released default preserved: `yes`
-- Compatibility class: no public prop, default, or styling output change; with a
+- Compatibility class: no public prop or default change. FR2's status dots
+ (`success`, `warning`, `error`) repaint from the strong status fill to the
+ status icon role, with the surface as ink, a visible color change in every
+ theme whose icon and fill roles differ; with a
`tooltip`, a standalone dot becomes a button named by `label` inside Tooltip
whose press pins the tooltip, adopted once `useTooltip`'s `show()` and
`hide()` (`component:Tooltip` DEC-1) ship, and a dot inside a button, link, menu item, or option
@@ -126,7 +129,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| ID | Invariant | Basis |
| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| FR1 | StatusDot always renders one inline-flex `span` dot, 8 by 8 CSS pixels, fully rounded, that does not shrink in a flex row, carrying the `status-dot` target and only that target. | Current source and tests |
-| FR2 | `success`, `warning`, and `error` are strong status fills: under `architecture:theme-tokens` INV11 each paints `--color-<status>` with `--color-on-<status>` ink and keeps a visible `CanvasText` border in forced-colors mode. `accent` paints `--color-accent` with `--color-on-accent` ink, and `neutral` paints `--color-icon-secondary` with the surface color as ink; these two are not INV11 status roles, and no current record sets their forced-colors treatment (OQ1). The target reflects `variant` for every value, and an extensible tone has a safe theme-independent baseline (`architecture:component-theming-surface` INV14). Implementation gap: a theme-added value the active theme does not paint receives no component plate or ink, leaving a transparent 8px box (Current-state impact). | Current source and tests |
+| FR2 | `success`, `warning`, and `error` are status marks on the page: under `architecture:theme-tokens` INV11 each paints its status icon role, `--color-icon-<status>`, with the surface color as ink, and keeps a visible `CanvasText` border in forced-colors mode. `accent` paints `--color-accent` with `--color-on-accent` ink, and `neutral` paints `--color-icon-secondary` with the surface color as ink; these two are not INV11 status roles, and no current record sets their forced-colors treatment (OQ1). The target reflects `variant` for every value, and an extensible tone has a safe theme-independent baseline (`architecture:component-theming-surface` INV14). Implementation gap: a theme-added value the active theme does not paint receives no component plate or ink, leaving a transparent 8px box (Current-state impact). | Current source and tests |
| FR3 | `isPulsing` animates the dot's opacity from 1 to 0.5 and back over 2 seconds, ease-in-out, indefinitely; under `prefers-reduced-motion: reduce` the animation is removed and the dot rests. | Current source and tests |
| FR4 | A renderable `icon` renders in a wrapper centered inside the dot and filling its 8px field; it paints from `currentColor`, the variant's ink. A non-renderable value leaves the dot childless. | Current source and tests |
| FR5 | A non-empty `tooltip` renders by placement; without one, no tooltip renders. A standalone dot is wrapped in Tooltip with that text and is a button trigger whose press pins it, named by `label`, so hover and keyboard focus preview the tooltip and a tap, click, Enter, or Space pins it (`component:Tooltip` FR9), and keyboard users reach it (WCAG 2.2 2.1.1). StatusDot adopts the pin through `useTooltip`'s `show()` and `hide()` (`component:Tooltip` FR12), as `component:InfoTip` does, so a standalone dot's tooltip stays reachable on touch. A dot inside an interactive element (a button, link, menu item, or option) is a non-interactive image wrapped in Tooltip without the pin, because a control cannot nest another control: its tooltip previews on hover only, and its tooltip text joins the host's accessible name, so the host carries the status for screen readers (`architecture:interaction-modality` INV4). A host named by `aria-label` takes no name from its content, so its caller includes the status in that label. Implementation gap: the dot has no tab stop and uses Tooltip's default touch trigger, so the tooltip opens on hover and touch only (Current-state impact). | Current source and tests; `component:Tooltip` DEC-1, FR9, FR12 |
@@ -222,7 +225,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| FR1, FR6 | `StatusDot.test.tsx` render, ref, test-id, and target suites | Every tone | Removing the dot, a lost ref or test id, or a second target fails. Gap: the 8px size test asserts presence only, and no test fails if the styling order (ORD1) changes; size is visible in `StatusDot.stories.tsx`. | `audit:StatusDot/anatomy` |
-| FR2 | `StatusDot.test.tsx` variant-ink suite; `extensibleAxes.test.ts` | Warning plate and ink; map wiring | Dropping `variant` reflection fails. The warning-ink test pins the `--color-warning` plate with `--color-on-warning` ink, and the forced-colors test asserts the compiled `CanvasText` outline. Gap: other tones' paint and the unthemed fallback have no automated check. | `audit:StatusDot/theming` |
+| FR2 | `StatusDot.test.tsx` variant-ink suite; `extensibleAxes.test.ts` | Status plates and ink; map wiring | Dropping `variant` reflection fails. The variant-ink test pins each status's `--color-icon-<status>` plate with the surface ink, and the forced-colors test asserts the compiled `CanvasText` outline. Gap: other tones' paint and the unthemed fallback have no automated check. | `audit:StatusDot/theming` |
| FR3, AR5 | `StatusDot.stories.tsx` in a browser, with and without reduced motion | Resting and pulsing | Gap: the pulsing unit tests assert presence only; a missing pulse or reduced-motion rule is visible only in the rendered fixture. | `audit:StatusDot/motion` |
| FR4, AR3 | `StatusDot.test.tsx` custom-icon suite | Icon, falsy values | Exposing the icon or rendering a wrapper for a falsy value fails. | `audit:StatusDot/anatomy` |
| FR5, AR1, AR2 | `StatusDot.test.tsx` focusability and accessible-name suites; evidence gap until built: standalone toggle cases and the coarse-pointer hit area; a dot with a tooltip inside a Button and inside a MenuItem | Every tone, with and without tooltip; a standalone dot with a tooltip; a dot inside a Button and inside a MenuItem | A missing name, a tab stop on a dot without a tooltip, or a name that depends on the tooltip fails. Gap: the tooltip test asserts only that the dot renders, so dropping the Tooltip wrap passes, and no test covers a caller `role` or `aria-label` override. Once FR5 is built, a standalone dot with a tooltip that is not a named button, that a tap, click, Enter, or Space does not pin, fails. A dot inside a Button or a MenuItem that renders a nested button or tab stop, opens its tooltip on a tap, or whose host's accessible name lacks the status, fails. A standalone dot with a tooltip whose coarse-pointer hit area stays under 44 px where its neighbors leave room, or reaches a neighbor's target, fails. | `audit:StatusDot/a11y` |
diff --git a/packages/cli/assets/docs/tree/tokens-color.doc.mjs b/packages/cli/assets/docs/tree/tokens-color.doc.mjs
index df492d10f9..6512b5b3a5 100644
--- a/packages/cli/assets/docs/tree/tokens-color.doc.mjs
+++ b/packages/cli/assets/docs/tree/tokens-color.doc.mjs
@@ -45,7 +45,7 @@ export const docs = {
],
[
"--color-icon-<status>",
- "Status icons on the page or a card. Defaults to the text colour.",
+ "Status icons and marks on the page or a card, such as a StatusDot. Defaults to the text colour.",
"—"
],
[
@@ -55,7 +55,7 @@ export const docs = {
],
[
"--color-<status>",
- "Strong status fill, such as a Badge or StatusDot.",
+ "Strong status fill, such as a Badge.",
"--color-on-<status>"
],
[
diff --git a/packages/core/src/StatusDot/StatusDot.test.tsx b/packages/core/src/StatusDot/StatusDot.test.tsx
index 4f4de56f80..7a2b867a69 100644
--- a/packages/core/src/StatusDot/StatusDot.test.tsx
+++ b/packages/core/src/StatusDot/StatusDot.test.tsx
@@ -144,26 +144,37 @@ describe('StatusDot', () => {
});
describe('variant ink (a passed icon paints from currentColor)', () => {
- it('pairs the warning plate with the dedicated dark on-warning ink', () => {
- // The regression this guards: a light surface ink on the yellow warning
- // plate lands near 2:1, while `--color-on-warning` is the fixed dark
- // ink (~9.6:1). An icon inherits the ink via `currentColor`, so the
- // pairing is what keeps custom icons legible.
+ it('paints each status plate in its icon role with the surface as ink', () => {
+ // A status dot is a mark on the page: the icon role holds 3:1 or more
+ // against the page and card surfaces, where the strong warning fill
+ // lands near 1.8:1 on a muted card. An icon inherits the ink via
+ // `currentColor`; the surface ink keeps the same pair the other way
+ // round.
const probe = stylex.create({
+ success: {
+ backgroundColor: colorVars['--color-icon-success'],
+ color: colorVars['--color-background-surface'],
+ },
warning: {
- backgroundColor: colorVars['--color-warning'],
- color: colorVars['--color-on-warning'],
+ backgroundColor: colorVars['--color-icon-warning'],
+ color: colorVars['--color-background-surface'],
+ },
+ error: {
+ backgroundColor: colorVars['--color-icon-error'],
+ color: colorVars['--color-background-surface'],
},
});
- const dot = renderDot({variant: 'warning', label: 'Degraded'});
- const atomicClasses = (stylex.props(probe.warning).className ?? '')
- .split(' ')
- // Dev mode prepends a per-file `File__style.key` debug class that
- // legitimately differs between the probe and the component.
- .filter(cls => !cls.includes('__'));
- expect(atomicClasses.length).toBeGreaterThan(0);
- for (const cls of atomicClasses) {
- expect(dot.className).toContain(cls);
+ for (const variant of ['success', 'warning', 'error'] as const) {
+ const dot = renderDot({variant, label: variant});
+ const atomicClasses = (stylex.props(probe[variant]).className ?? '')
+ .split(' ')
+ // Dev mode prepends a per-file `File__style.key` debug class that
+ // legitimately differs between the probe and the component.
+ .filter(cls => !cls.includes('__'));
+ expect(atomicClasses.length).toBeGreaterThan(0);
+ for (const cls of atomicClasses) {
+ expect(dot.className, variant).toContain(cls);
+ }
}
});
});
diff --git a/packages/core/src/StatusDot/StatusDot.tsx b/packages/core/src/StatusDot/StatusDot.tsx
index 9a89f3159c..3b7037e1ce 100644
--- a/packages/core/src/StatusDot/StatusDot.tsx
+++ b/packages/core/src/StatusDot/StatusDot.tsx
@@ -79,16 +79,16 @@ const styles = stylex.create({
*
* Each variant sets both the plate colour and an ink colour: a user-supplied
* `icon` paints from `currentColor`, so plate and ink can never drift out of
- * contrast (same contract as AvatarStatusDot). The ink is each plate's
- * dedicated `--color-on-*` pairing (the Badge precedent), not the surface
- * colour: on-warning is a fixed dark ink, which keeps an icon legible on the
- * yellow plate (~9.6:1) where a light surface ink lands near 2:1. Neutral has
- * no `--color-on-*` token; its mid-grey plate takes the surface ink.
+ * contrast (same contract as AvatarStatusDot). A status dot is a mark on the
+ * page, so its plate is the status icon role, which holds 3:1 or more against
+ * the page and card surfaces; the strong fill does not (the warning fill lands
+ * near 1.8:1 on a muted card). The ink is the surface colour, the same pair
+ * the other way round, as the neutral dot's is. Accent keeps its own pair.
*/
const variants = stylex.create({
success: {
- backgroundColor: colorVars['--color-success'],
- color: colorVars['--color-on-success'],
+ backgroundColor: colorVars['--color-icon-success'],
+ color: colorVars['--color-background-surface'],
// Forced colors replace status fills with Canvas; this boundary keeps the
// fill's shape visible (architecture:theme-tokens INV11).
outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
@@ -100,8 +100,8 @@ const variants = stylex.create({
outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
},
warning: {
- backgroundColor: colorVars['--color-warning'],
- color: colorVars['--color-on-warning'],
+ backgroundColor: colorVars['--color-icon-warning'],
+ color: colorVars['--color-background-surface'],
// Forced colors replace status fills with Canvas; this boundary keeps the
// fill's shape visible (architecture:theme-tokens INV11).
outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
@@ -113,8 +113,8 @@ const variants = stylex.create({
outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
},
error: {
- backgroundColor: colorVars['--color-error'],
- color: colorVars['--color-on-error'],
+ backgroundColor: colorVars['--color-icon-error'],
+ color: colorVars['--color-background-surface'],
// Forced colors replace status fills with Canvas; this boundary keeps the
// fill's shape visible (architecture:theme-tokens INV11).
outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
diff --git a/scripts/generate-token-docs.mjs b/scripts/generate-token-docs.mjs
index 03981dfa2b..4f3fd2561a 100644
--- a/scripts/generate-token-docs.mjs
+++ b/scripts/generate-token-docs.mjs
@@ -140,7 +140,7 @@ const groups = [
],
[
'--color-icon-<status>',
- 'Status icons on the page or a card. Defaults to the text colour.',
+ 'Status icons and marks on the page or a card, such as a StatusDot. Defaults to the text colour.',
'—',
],
[
@@ -150,7 +150,7 @@ const groups = [
],
[
'--color-<status>',
- 'Strong status fill, such as a Badge or StatusDot.',
+ 'Strong status fill, such as a Badge.',
'--color-on-<status>',
],
[