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.mdnew file mode 100644index 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`.+@bhamodidiff --git a/apps/storybook/stories/StatusDot.stories.tsx b/apps/storybook/stories/StatusDot.stories.tsxindex 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.mjsindex 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 filediff --git a/packages/core/src/StatusDot/StatusDot.test.tsx b/packages/core/src/StatusDot/StatusDot.test.tsxindex 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.tsxindex 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 = (<spanref={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) {