Skip to content

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

TypeScript

fix(core): add StatusDot icon prop; keep the dot a plain colored signal (#4373)

Baraa Hamodi0f4d45f88dc4
diff --git a/.changeset/statusdot-icon-prop.md b/.changeset/statusdot-icon-prop.md
new file mode 100644
index 0000000000..95233a3dad
--- /dev/null
+++ b/.changeset/statusdot-icon-prop.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] StatusDot: pair each variant with a distinct built-in shape drawn from the system's semantic icon vocabulary — success a check, warning an exclamation, error a cross, neutral a ring, accent the plain filled dot — so status no longer relies on colour alone (WCAG 2.1 SC 1.4.1). The shapes mirror the marks `Banner`/`FieldStatus` render via `defaultIcons`, a different axis of consistency from `AvatarStatusDot`'s presence shapes (the two share only the neutral ring, intentionally). The diagonal check and cross take a slightly heavier stroke so they stay crisp and distinct at 8px. Also adds an `icon` prop for API parity with `AvatarStatusDot`: a rendered icon replaces the built-in glyph, while booleans and empty renders are ignored so `cond && <Icon />` stays safe. The built-in glyphs resolve through the icon registry under scoped `statusdot:<variant>` keys (the `richtext:*` precedent), so themes can reshape a variant's mark everywhere via `defineTheme({icons})` / `registerIcons` — including marks for augmented custom variants — while overrides of the standard 24px semantic icons deliberately do not leak into the 8px field. Themes can also target the new stable `astryx-statusdot-glyph` class and its `data-shape` attribute — a stroked inline `<svg>` painted from the dot's `currentColor`.
+@bhamodi
diff --git a/apps/storybook/stories/StatusDot.stories.tsx b/apps/storybook/stories/StatusDot.stories.tsx
index 65ebd5c5d2..5f70524ffe 100644
--- a/apps/storybook/stories/StatusDot.stories.tsx
+++ b/apps/storybook/stories/StatusDot.stories.tsx
@@ -93,3 +93,46 @@ export const WithTooltip: Story = {
</div>
),
};
+
+/**
+ * A simple custom mark, painted from `currentColor` so it inherits the dot's
+ * ink and stays legible on the variant plate.
+ */
+function DiamondIcon() {
+ return (
+ <svg viewBox="0 0 8 8" width={8} height={8} aria-hidden="true">
+ <rect
+ x={2.4}
+ y={2.4}
+ width={3.2}
+ height={3.2}
+ fill="currentColor"
+ transform="rotate(45 4 4)"
+ />
+ </svg>
+ );
+}
+
+/**
+ * The `icon` prop gives the status a non-colour mark. The dot itself is a
+ * colour-only signal by default, so when a dot must stand on its own without
+ * adjacent text, pass a different icon per status (see the usage guidance in
+ * the component docs).
+ */
+export const WithIcon: Story = {
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'A custom `icon` rendered centered in the dot, painted from `currentColor`. Use a different icon per status so meaning does not rely on colour alone.',
+ },
+ },
+ },
+ render: () => (
+ <div style={{display: 'flex', gap: '24px', alignItems: 'center'}}>
+ <StatusDot variant="success" label="Verified" icon={<DiamondIcon />} />
+ <StatusDot variant="accent" label="Featured" icon={<DiamondIcon />} />
+ <span style={{fontSize: '11px'}}>icon carries the status as a shape</span>
+ </div>
+ ),
+};
diff --git a/packages/core/src/StatusDot/StatusDot.doc.mjs b/packages/core/src/StatusDot/StatusDot.doc.mjs
index a1f4fc25ac..cca7c94c5d 100644
--- a/packages/core/src/StatusDot/StatusDot.doc.mjs
+++ b/packages/core/src/StatusDot/StatusDot.doc.mjs
@@ -33,6 +33,12 @@ export const docs = {
description:
'Tooltip text shown on hover to explain the status meaning.',
},
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description:
+ 'Optional icon rendered centered inside the dot, painted in currentColor (the variant\'s ink). Gives the status a non-color mark, so use a different icon per status. Booleans and empty strings are ignored, so `cond && <Icon />` is safe. Same contract as AvatarStatusDot.',
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
@@ -84,6 +90,12 @@ export const docsZh = {
'启用脉冲动画;尊重 prefers-reduced-motion: reduce 设置。',
default: 'false',
},
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description:
+ '可选图标,居中渲染于圆点内,以 currentColor(变体的前景色)着色。为状态提供非颜色标记,请为每个状态使用不同图标。布尔值和空字符串会被忽略,因此 `cond && <Icon />` 是安全的。与 AvatarStatusDot 的契约一致。',
+ },
{
name: 'xstyle',
type: 'StyleXStyles',
@@ -132,6 +144,7 @@ export const docsDense = {
label: 'Accessible label via aria-label.',
isPulsing: 'Pulse animation; respects prefers-reduced-motion: reduce.',
tooltip: 'Tooltip text on hover to explain status meaning.',
+ icon: 'Optional ReactNode rendered centered in the dot (currentColor ink); a non-color mark for the status, use a different icon per status. Booleans/empty strings ignored (safe for cond && <Icon/>). Same contract as AvatarStatusDot.',
xstyle: 'StyleX layout styles; must be stylex.create() value.',
},
};
\ No newline at end of file
diff --git a/packages/core/src/StatusDot/StatusDot.test.tsx b/packages/core/src/StatusDot/StatusDot.test.tsx
index 2e26f049e7..29644be173 100644
--- a/packages/core/src/StatusDot/StatusDot.test.tsx
+++ b/packages/core/src/StatusDot/StatusDot.test.tsx
@@ -2,8 +2,16 @@
import {describe, it, expect} from 'vitest';
import {render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
+import {colorVars} from '../theme/tokens.stylex';
import {StatusDot} from './StatusDot';
+/** Renders a StatusDot and returns its root element. */
+function renderDot(props: React.ComponentProps<typeof StatusDot>) {
+ render(<StatusDot {...props} />);
+ return screen.getByRole('img', {name: props.label});
+}
+
describe('StatusDot', () => {
it('renders with role="img" and aria-label', () => {
render(<StatusDot variant="success" label="Online" />);
@@ -27,9 +35,7 @@ describe('StatusDot', () => {
] as const;
for (const variant of variants) {
- const {unmount} = render(
- <StatusDot variant={variant} label={variant} />,
- );
+ const {unmount} = render(<StatusDot variant={variant} label={variant} />);
expect(screen.getByRole('img', {name: variant})).toBeInTheDocument();
unmount();
}
@@ -49,11 +55,7 @@ describe('StatusDot', () => {
it('supports data-testid', () => {
render(
- <StatusDot
- variant="success"
- label="Online"
- data-testid="status-dot"
- />,
+ <StatusDot variant="success" label="Online" data-testid="status-dot" />,
);
expect(screen.getByTestId('status-dot')).toBeInTheDocument();
});
@@ -81,4 +83,109 @@ describe('StatusDot', () => {
const dot = screen.getByRole('img', {name: 'Online'});
expect(dot).toBeInTheDocument();
});
+
+ it('renders every variant as a plain childless dot by default (design review #4373)', () => {
+ // The dot is deliberately a colour-only signal by default — no built-in
+ // per-variant glyph. Making the status accessible in context (label,
+ // icon, or an accessible alternative) is the builder's responsibility;
+ // see the usage guidance.
+ const variants = [
+ 'success',
+ 'warning',
+ 'error',
+ 'accent',
+ 'neutral',
+ ] as const;
+ for (const variant of variants) {
+ const dot = renderDot({variant, label: `plain-${variant}`});
+ expect(dot.childElementCount, variant).toBe(0);
+ }
+ });
+
+ describe('custom icon (parity with AvatarStatusDot)', () => {
+ const ICON_TESTID = 'custom-icon';
+ function Icon() {
+ return <svg data-testid={ICON_TESTID} />;
+ }
+
+ it('renders a provided icon inside the dot', () => {
+ renderDot({variant: 'success', label: 'Verified', icon: <Icon />});
+ expect(screen.getByTestId(ICON_TESTID)).toBeInTheDocument();
+ });
+
+ it('hides the icon wrapper from assistive tech (the label carries the status)', () => {
+ renderDot({variant: 'success', label: 'Verified', icon: <Icon />});
+ const iconEl = screen.getByTestId(ICON_TESTID);
+ expect(iconEl.closest('[aria-hidden="true"]')).not.toBeNull();
+ });
+
+ it.each([false, true, null, undefined, ''])(
+ 'ignores %s and keeps the plain dot (safe for `cond && <Icon />`)',
+ value => {
+ const dot = renderDot({
+ variant: 'error',
+ label: 'Offline',
+ icon: value,
+ });
+ expect(dot.childElementCount).toBe(0);
+ },
+ );
+
+ it('keeps the accessible name on the dot when an icon renders', () => {
+ const dot = renderDot({
+ variant: 'success',
+ label: 'Verified',
+ icon: <Icon />,
+ });
+ expect(dot).toHaveAttribute('role', 'img');
+ expect(dot).toHaveAttribute('aria-label', 'Verified');
+ });
+ });
+
+ 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.
+ const probe = stylex.create({
+ warning: {
+ backgroundColor: colorVars['--color-warning'],
+ color: colorVars['--color-on-warning'],
+ },
+ });
+ 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);
+ }
+ });
+ });
+
+ describe('accessible name (label reaches AT without hover)', () => {
+ it('exposes the status label as the accessible name for every variant, without a tooltip', () => {
+ const variants = [
+ 'success',
+ 'warning',
+ 'error',
+ 'accent',
+ 'neutral',
+ ] as const;
+ for (const variant of variants) {
+ const {unmount} = render(
+ <StatusDot variant={variant} label={`Status: ${variant}`} />,
+ );
+ const dot = screen.getByRole('img', {name: `Status: ${variant}`});
+ expect(dot).toHaveAttribute('aria-label', `Status: ${variant}`);
+ // The name must not depend on hover or focus.
+ expect(dot.getAttribute('tabindex')).toBeNull();
+ unmount();
+ }
+ });
+ });
});
diff --git a/packages/core/src/StatusDot/StatusDot.tsx b/packages/core/src/StatusDot/StatusDot.tsx
index c8f2c76cb7..6b5a935b1e 100644
--- a/packages/core/src/StatusDot/StatusDot.tsx
+++ b/packages/core/src/StatusDot/StatusDot.tsx
@@ -16,11 +16,13 @@
* - /packages/cli/assets/templates/blocks/components/StatusDot/ (showcase blocks)
*/
+import type {ReactNode} from 'react';
+
import * as stylex from '@stylexjs/stylex';
import {colorVars} from '../theme/tokens.stylex';
import type {BaseProps} from '../BaseProps';
import {Tooltip} from '../Tooltip/Tooltip';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
import {themeProps} from '../utils/themeProps';
import type {StatusDotVariantMap} from './index';
@@ -33,16 +35,21 @@ const pulseKeyframes = stylex.keyframes({
'100%': {opacity: 1},
});
+/** Fixed dot size in px. A user-supplied icon is drawn into this same field. */
+const DOT_SIZE = 8;
+
/**
* Base styles
*/
const styles = stylex.create({
base: {
- display: 'inline-block',
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
borderRadius: '50%',
flexShrink: 0,
- width: '8px',
- height: '8px',
+ width: `${DOT_SIZE}px`,
+ height: `${DOT_SIZE}px`,
},
pulsing: {
animationName: pulseKeyframes,
@@ -55,26 +62,49 @@ const styles = stylex.create({
animationName: 'none',
},
},
+ // A user-supplied icon fills the whole 8px field and paints from
+ // `currentColor` (the variant's ink).
+ icon: {
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ lineHeight: 0,
+ width: `${DOT_SIZE}px`,
+ height: `${DOT_SIZE}px`,
+ },
});
/**
- * Variant styles mapping to theme color tokens
+ * Variant styles mapping to theme color tokens.
+ *
+ * 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.
*/
const variants = stylex.create({
success: {
backgroundColor: colorVars['--color-success'],
+ color: colorVars['--color-on-success'],
},
warning: {
backgroundColor: colorVars['--color-warning'],
+ color: colorVars['--color-on-warning'],
},
error: {
backgroundColor: colorVars['--color-error'],
+ color: colorVars['--color-on-error'],
},
accent: {
backgroundColor: colorVars['--color-accent'],
+ color: colorVars['--color-on-accent'],
},
neutral: {
backgroundColor: colorVars['--color-icon-secondary'],
+ color: colorVars['--color-background-surface'],
},
});
@@ -92,7 +122,8 @@ export interface StatusDotProps extends BaseProps<HTMLSpanElement> {
*/
variant: StatusDotVariant;
/**
- * Accessible label describing the status. Required for a11y.
+ * Accessible label describing the status. Required for a11y — it is the
+ * dot's `aria-label`, so the status reaches screen readers without hover.
*/
label: string;
/**
@@ -106,12 +137,36 @@ export interface StatusDotProps extends BaseProps<HTMLSpanElement> {
* When omitted, no tooltip is rendered.
*/
tooltip?: string;
+ /**
+ * Optional icon to render centered inside the dot. Accepts any ReactNode
+ * (typically an SVG icon), painted in the dot's `currentColor` ink. Same
+ * contract as `AvatarStatusDot`'s `icon`.
+ *
+ * By default the dot is a colour-only signal; an icon gives the status a
+ * non-colour mark, so use a different icon per status — the same icon on
+ * every variant leaves the statuses distinguishable by colour alone
+ * (WCAG 2.1 SC 1.4.1). Booleans and empty strings are ignored (safe for
+ * `cond && <Icon />`).
+ *
+ * @example
+ * ```
+ * <StatusDot variant="success" label="Verified" icon={<CheckIcon />} />
+ * ```
+ */
+ icon?: ReactNode;
}
/**
* A small colored dot indicator for status display (online/offline, severity, etc).
*
- * Fixed 8px size. Renders as a non-focusable `<span>` with `role="img"` and
+ * Fixed 8px size. By default the dot conveys status by colour only, which is
+ * not accessible in isolation (WCAG 2.1 SC 1.4.1) — treat it as a signal the
+ * surrounding UI must make accessible: use it as a binary present/absent
+ * signal, pair it with a visible label, pass `icon` so the status carries a
+ * non-colour mark, or convey the status accessibly elsewhere. See the usage
+ * guidance in the component docs.
+ *
+ * Renders as a non-focusable `<span>` with `role="img"` and
* `aria-label` for accessibility. Styles use Astryx theme tokens via StyleX.
* Wrap your app in `<Theme>` to apply a theme.
*
@@ -121,6 +176,7 @@ export interface StatusDotProps extends BaseProps<HTMLSpanElement> {
* <StatusDot variant="error" label="Offline" />
* <StatusDot variant="success" label="Live" isPulsing />
* <StatusDot variant="success" label="Online" tooltip="Online" />
+ * <StatusDot variant="success" label="Verified" icon={<CheckIcon />} />
* ```
*/
export function StatusDot({
@@ -128,12 +184,16 @@ export function StatusDot({
label,
isPulsing = false,
tooltip,
+ icon,
xstyle,
className,
style,
ref,
...props
}: StatusDotProps) {
+ // Booleans and empty renders don't count (safe for `cond && <Icon />`) —
+ // same contract as AvatarStatusDot.
+ const showsIcon = isRenderable(icon);
const dot = (
<span
ref={ref}
@@ -151,8 +211,13 @@ export function StatusDot({
className,
style,
)}
- {...props}
- />
+ {...props}>
+ {showsIcon && (
+ <span aria-hidden="true" {...stylex.props(styles.icon)}>
+ {icon}
+ </span>
+ )}
+ </span>
);
if (tooltip) {