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.mdnew file mode 100644index 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.++@cixzhangdiff --git a/.changeset/status-dot-icon-role.md b/.changeset/status-dot-icon-role.mdnew file mode 100644index 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.++@cixzhangdiff --git a/docs/specs/components/StatusDot/StatusDot.spec.md b/docs/specs/components/StatusDot/StatusDot.spec.mdindex 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 Tooltipwhose 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.mjsindex 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.tsxindex 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.tsxindex 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.mjsindex 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>',],[