Skip to content

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

TypeScript

fix(avatar): pair each status-dot variant with a distinct shape (#4157)

AK433a57ea89a2
diff --git a/.changeset/avatar-status-dot-shapes.md b/.changeset/avatar-status-dot-shapes.md
new file mode 100644
index 0000000000..55ecc1eae3
--- /dev/null
+++ b/.changeset/avatar-status-dot-shapes.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] AvatarStatusDot: pair each variant with a distinct built-in shape — success stays a filled dot, neutral renders as a ring, error gets a minus bar — so status no longer relies on colour alone (WCAG 2.1 SC 1.4.1, #4143). A rendered `icon` replaces the shape glyph at sizes where icons fit; themes can target the new stable `astryx-avatar-status-dot-glyph` class and its `data-shape` attribute — a stroked inline `<svg>` painted from the dot's `currentColor`.
+@AKnassa
diff --git a/apps/storybook/stories/Avatar.stories.tsx b/apps/storybook/stories/Avatar.stories.tsx
index 2c4768ef28..18a1a89317 100644
--- a/apps/storybook/stories/Avatar.stories.tsx
+++ b/apps/storybook/stories/Avatar.stories.tsx
@@ -77,7 +77,7 @@ const meta: Meta<typeof Avatar> = {
control: 'boolean',
description: 'Show status indicator dot',
mapping: {
- true: <AvatarStatusDot />,
+ true: <AvatarStatusDot label="Online" />,
false: undefined,
},
},
@@ -248,27 +248,27 @@ export const StatusAcrossAllSizes: Story = {
<Avatar
name="TY"
size="xsm"
- status={<AvatarStatusDot variant="success" />}
+ status={<AvatarStatusDot variant="success" label="Online" />}
/>
<Avatar
name="XS"
size="sm"
- status={<AvatarStatusDot variant="success" />}
+ status={<AvatarStatusDot variant="success" label="Online" />}
/>
<Avatar
name="SM"
size="md"
- status={<AvatarStatusDot variant="success" />}
+ status={<AvatarStatusDot variant="success" label="Online" />}
/>
<Avatar
name="MD"
size="lg"
- status={<AvatarStatusDot variant="success" />}
+ status={<AvatarStatusDot variant="success" label="Online" />}
/>
<Avatar
name="LG"
size="xl"
- status={<AvatarStatusDot variant="success" />}
+ status={<AvatarStatusDot variant="success" label="Online" />}
/>
</div>
@@ -278,37 +278,37 @@ export const StatusAcrossAllSizes: Story = {
src="https://i.pravatar.cc/150?img=30"
name="U1"
size={20}
- status={<AvatarStatusDot variant="success" />}
+ status={<AvatarStatusDot variant="success" label="Online" />}
/>
<Avatar
src="https://i.pravatar.cc/150?img=31"
name="U2"
size={32}
- status={<AvatarStatusDot variant="success" />}
+ status={<AvatarStatusDot variant="success" label="Online" />}
/>
<Avatar
src="https://i.pravatar.cc/150?img=32"
name="U3"
size={48}
- status={<AvatarStatusDot variant="error" />}
+ status={<AvatarStatusDot variant="error" label="Busy" />}
/>
<Avatar
src="https://i.pravatar.cc/150?img=33"
name="U4"
size={72}
- status={<AvatarStatusDot variant="neutral" />}
+ status={<AvatarStatusDot variant="neutral" label="Offline" />}
/>
<Avatar
src="https://i.pravatar.cc/150?img=34"
name="U5"
size={96}
- status={<AvatarStatusDot variant="success" />}
+ status={<AvatarStatusDot variant="success" label="Online" />}
/>
<Avatar
src="https://i.pravatar.cc/150?img=35"
name="U6"
size={128}
- status={<AvatarStatusDot variant="success" />}
+ status={<AvatarStatusDot variant="success" label="Online" />}
/>
</div>
@@ -342,10 +342,55 @@ export const StatusWithSizes: Story = {
<div {...stylex.props(styles.storyWrapper)}>
<h4 {...stylex.props(styles.heading)}>Status with Different Sizes</h4>
<div {...stylex.props(styles.row)}>
- <Avatar name="AB" size="md" status={<AvatarStatusDot />} />
- <Avatar name="CD" size="lg" status={<AvatarStatusDot />} />
- <Avatar name="EF" size="xl" status={<AvatarStatusDot />} />
- <Avatar name="GH" size={72} status={<AvatarStatusDot />} />
+ <Avatar name="AB" size="md" status={<AvatarStatusDot label="Online" />} />
+ <Avatar name="CD" size="lg" status={<AvatarStatusDot label="Online" />} />
+ <Avatar name="EF" size="xl" status={<AvatarStatusDot label="Online" />} />
+ <Avatar name="GH" size={72} status={<AvatarStatusDot label="Online" />} />
+ </div>
+ </div>
+ ),
+};
+
+export const StatusShapesAtSmallSizes: Story = {
+ name: 'Status Shapes at Small Sizes',
+ render: () => (
+ <div {...stylex.props(styles.storyWrapper)}>
+ <h4 {...stylex.props(styles.heading)}>
+ Each variant pairs colour with a distinct shape (filled, ring, minus) so
+ status never relies on colour alone — including the smallest sizes,
+ where icons cannot render
+ </h4>
+ <div {...stylex.props(styles.row)}>
+ <Avatar
+ name="ON"
+ size="xsm"
+ status={<AvatarStatusDot variant="success" label="Online" />}
+ />
+ <Avatar
+ name="OF"
+ size="xsm"
+ status={<AvatarStatusDot variant="neutral" label="Offline" />}
+ />
+ <Avatar
+ name="BU"
+ size="xsm"
+ status={<AvatarStatusDot variant="error" label="Busy" />}
+ />
+ <Avatar
+ name="ON"
+ size="md"
+ status={<AvatarStatusDot variant="success" label="Online" />}
+ />
+ <Avatar
+ name="OF"
+ size="md"
+ status={<AvatarStatusDot variant="neutral" label="Offline" />}
+ />
+ <Avatar
+ name="BU"
+ size="md"
+ status={<AvatarStatusDot variant="error" label="Busy" />}
+ />
</div>
</div>
),
diff --git a/packages/cli/templates/blocks/components/Avatar/AvatarShowcase.tsx b/packages/cli/templates/blocks/components/Avatar/AvatarShowcase.tsx
index 4ef61b90d5..870a114645 100644
--- a/packages/cli/templates/blocks/components/Avatar/AvatarShowcase.tsx
+++ b/packages/cli/templates/blocks/components/Avatar/AvatarShowcase.tsx
@@ -28,7 +28,7 @@ export default function AvatarShowcase() {
src="https://lookaside.facebook.com/assets/astryx/DATA-Nam-Tran.png"
name="Nam Tran"
size="xl"
- status={<AvatarStatusDot variant="error" label="Online" />}
+ status={<AvatarStatusDot variant="error" label="Busy" />}
/>
</Stack>
);
diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjs
index 89f0d2a73d..96ffac0c25 100644
--- a/packages/core/src/Avatar/Avatar.doc.mjs
+++ b/packages/core/src/Avatar/Avatar.doc.mjs
@@ -22,13 +22,14 @@ export const docs = {
{name: 'Photo', required: false, description: 'The profile image, loaded from the src URL. Shown when available.'},
{name: 'Initials', required: false, description: 'One or two letters extracted from the name. Shown when no photo is available.'},
{name: 'Default icon', required: false, description: 'A generic person silhouette. Shown when there is no photo or name.'},
- {name: 'Status dot', required: false, description: 'A small indicator in the bottom-right corner showing availability (online, away, busy).'},
+ {name: 'Status dot', required: false, description: 'A small indicator in the bottom-right corner showing availability (online, away, busy). Each variant pairs colour with a distinct shape so status does not rely on colour alone.'},
],
},
theming: {
targets: [
{className: 'astryx-avatar', visualProps: ['size']},
{className: 'astryx-avatar-status-dot', visualProps: ['variant']},
+ {className: 'astryx-avatar-status-dot-glyph', visualProps: ['shape']},
],
},
description: 'Displays a user avatar with image, initials fallback, and optional status indicator.',
@@ -65,9 +66,10 @@ export const docs = {
description: 'Corner content for status indicators.',
slotElements: [
{
- __element: 'StatusDot',
+ __element: 'AvatarStatusDot',
props: {
- variant: 'online',
+ variant: 'success',
+ label: 'Online',
},
},
],
diff --git a/packages/core/src/Avatar/AvatarStatusDot.doc.mjs b/packages/core/src/Avatar/AvatarStatusDot.doc.mjs
index 2f79a2f9c1..9fbf055ea6 100644
--- a/packages/core/src/Avatar/AvatarStatusDot.doc.mjs
+++ b/packages/core/src/Avatar/AvatarStatusDot.doc.mjs
@@ -7,23 +7,27 @@ export const docs = {
subComponentOf: 'Avatar',
displayName: 'Avatar Status Dot',
isHiddenFromOverview: true,
- description: 'Size-aware status indicator dot that reads avatar size from context and scales proportionally.',
+ description:
+ 'Size-aware status indicator dot that reads avatar size from context and scales proportionally. Each variant pairs a colour with a distinct built-in shape (filled, ring, minus) so status is never conveyed by colour alone (WCAG 1.4.1).',
props: [
{
name: 'variant',
type: "'success' | 'neutral' | 'error'",
- description: 'Semantic color variant of the dot.',
+ description:
+ 'Semantic variant pairing colour with a distinct shape: success = filled green dot, neutral = grey ring, error = red dot with a minus bar.',
default: "'success'",
},
{
name: 'label',
type: 'string',
- description: 'Accessible label for screen readers.',
+ description:
+ 'Accessible label describing the status. Not announced inside an Avatar today (the Avatar root is role="img", which prunes child semantics) — pass it anyway; an Avatar-level name-composition fix is planned.',
},
{
name: 'icon',
type: 'ReactNode',
- description: 'Icon centered inside the dot (hidden at tiny sizes).',
+ description:
+ 'Icon centered inside the dot (hidden at tiny sizes). A rendered icon replaces the built-in shape glyph, so use a different icon per status.',
slotElements: [
{
__element: 'Icon',
@@ -41,23 +45,27 @@ export const docsZh = {
name: 'AvatarStatusDot',
isHiddenFromOverview: true,
displayName: 'Avatar Status Dot',
- description: '尺寸感知的状态指示点,从上下文中读取头像尺寸并等比缩放。',
+ description:
+ '尺寸感知的状态指示点,从上下文中读取头像尺寸并等比缩放。每个变体将颜色与独特形状(实心、圆环、横杠)配对,确保状态不仅靠颜色传达(WCAG 1.4.1)。',
props: [
{
name: 'variant',
type: "'success' | 'neutral' | 'error'",
- description: '状态点的语义颜色变体。',
+ description:
+ '语义变体,颜色与形状配对:success = 绿色实心点,neutral = 灰色圆环,error = 带横杠的红色点。',
default: "'success'",
},
{
name: 'label',
type: 'string',
- description: '屏幕阅读器的无障碍标签。',
+ description:
+ '描述状态的无障碍标签。目前在 Avatar 内不会被朗读(Avatar 根元素为 role="img",会裁剪子元素语义)——仍请传入;Avatar 层面的名称合成修复已在计划中。',
},
{
name: 'icon',
type: 'ReactNode',
- description: '居中显示在状态点内的图标(tiny 尺寸时隐藏)。',
+ description:
+ '居中显示在状态点内的图标(tiny 尺寸时隐藏)。渲染的图标会替换内置形状标记,请为每个状态使用不同的图标。',
},
],
};
@@ -66,10 +74,13 @@ export const docsDense = {
name: 'AvatarStatusDot',
isHiddenFromOverview: true,
displayName: 'Avatar Status Dot',
- description: 'size-aware status dot, reads avatar size from context + scales proportionally',
+ description:
+ 'size-aware status dot, reads avatar size from context + scales proportionally; variants pair colour with shape (filled/ring/minus) per WCAG 1.4.1',
propDescriptions: {
- variant: 'semantic color variant',
- label: 'accessible label for screen readers',
- icon: 'icon centered in dot (hidden at tiny sizes)',
+ variant:
+ 'colour + shape variant: success filled, neutral ring, error minus',
+ label:
+ 'accessible status label (not yet announced inside Avatar — role="img" prunes children)',
+ icon: 'icon centered in dot (hidden at tiny sizes); replaces the built-in shape glyph — differ it per status',
},
};
diff --git a/packages/core/src/Avatar/AvatarStatusDot.test.tsx b/packages/core/src/Avatar/AvatarStatusDot.test.tsx
new file mode 100644
index 0000000000..fad8a7268d
--- /dev/null
+++ b/packages/core/src/Avatar/AvatarStatusDot.test.tsx
@@ -0,0 +1,284 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+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 {Avatar} from './Avatar';
+import {AvatarStatusDot, type AvatarStatusDotVariant} from './AvatarStatusDot';
+
+const GLYPH_SELECTOR = '.astryx-avatar-status-dot-glyph';
+const DOT_SELECTOR = '.astryx-avatar-status-dot';
+
+/**
+ * Renders an AvatarStatusDot inside an Avatar of the given numeric size and
+ * returns the dot root element. Size tiers: <=36 -> 10px dot (no icons),
+ * 40-72 -> 20px dot, >=96 -> 32px dot.
+ */
+function renderDot(
+ dotProps: React.ComponentProps<typeof AvatarStatusDot>,
+ avatarSize: 36 | 48 | 128 = 48,
+) {
+ const {container} = render(
+ <Avatar
+ name="Ada Lovelace"
+ size={avatarSize}
+ status={<AvatarStatusDot {...dotProps} />}
+ />,
+ );
+ const dot = container.querySelector(DOT_SELECTOR);
+ expect(dot).not.toBeNull();
+ return dot as HTMLElement;
+}
+
+describe('AvatarStatusDot', () => {
+ describe('shape glyphs (WCAG 1.4.1 — colour is not the only signal)', () => {
+ it('renders no glyph for success: the plain filled dot is the reference shape', () => {
+ const dot = renderDot({variant: 'success'});
+ expect(dot.querySelector(GLYPH_SELECTOR)).toBeNull();
+ });
+
+ it('renders a ring glyph for neutral', () => {
+ const dot = renderDot({variant: 'neutral'});
+ const glyph = dot.querySelector(GLYPH_SELECTOR);
+ expect(glyph).not.toBeNull();
+ expect(glyph).toHaveAttribute('data-shape', 'ring');
+ });
+
+ it('renders a minus glyph for error', () => {
+ const dot = renderDot({variant: 'error'});
+ const glyph = dot.querySelector(GLYPH_SELECTOR);
+ expect(glyph).not.toBeNull();
+ expect(glyph).toHaveAttribute('data-shape', 'minus');
+ });
+
+ it('hides the glyph from assistive tech: it is a visual redundancy of the status', () => {
+ const dot = renderDot({variant: 'error'});
+ expect(dot.querySelector(GLYPH_SELECTOR)).toHaveAttribute(
+ 'aria-hidden',
+ 'true',
+ );
+ });
+
+ it('renders glyphs at every size tier', () => {
+ for (const size of [36, 48, 128] as const) {
+ const dot = renderDot({variant: 'neutral'}, size);
+ expect(dot.querySelector(GLYPH_SELECTOR)).not.toBeNull();
+ }
+ });
+
+ it('draws the glyph as an inline svg sized to the dot inner field', () => {
+ // The glyph is a stroked <svg>, matching how the rest of the system
+ // draws marks (Icon's defaultIcons, the CheckboxInput checkmark).
+ // Its viewBox is 1 user unit per px of the dot's inner field
+ // (dot minus both borders), so stroke widths below are literal px.
+ const cases = [
+ [36, 8],
+ [48, 16],
+ [128, 24],
+ ] as const;
+ for (const [avatarSize, field] of cases) {
+ const glyph = renderDot({variant: 'neutral'}, avatarSize).querySelector(
+ GLYPH_SELECTOR,
+ ) as SVGElement;
+ expect(glyph.tagName.toLowerCase(), `avatar ${avatarSize}`).toBe('svg');
+ expect(glyph.getAttribute('viewBox'), `avatar ${avatarSize}`).toBe(
+ `0 0 ${field} ${field}`,
+ );
+ expect(glyph.getAttribute('width'), `avatar ${avatarSize}`).toBe(
+ String(field),
+ );
+ expect(glyph.getAttribute('height'), `avatar ${avatarSize}`).toBe(
+ String(field),
+ );
+ }
+ });
+
+ it('strokes the ring at the system glyph weight, not a quarter of the field', () => {
+ // stroke ~= field / 12, floored at 1px for the smallest tier, which
+ // puts these on the icon family's 1 / 1.5 / 2 ladder (~6-12% of the
+ // field) instead of the 25% band a CSS box cutout produced.
+ const cases = [
+ // avatar size, field, stroke, radius = (field - stroke) / 2
+ [36, 8, 1, 3.5],
+ [48, 16, 1.5, 7.25],
+ [128, 24, 2, 11],
+ ] as const;
+ for (const [avatarSize, field, stroke, radius] of cases) {
+ const circle = renderDot(
+ {variant: 'neutral'},
+ avatarSize,
+ ).querySelector(`${GLYPH_SELECTOR} circle`) as SVGCircleElement;
+ expect(circle, `avatar ${avatarSize}`).not.toBeNull();
+ expect(
+ circle.getAttribute('stroke-width'),
+ `avatar ${avatarSize}`,
+ ).toBe(String(stroke));
+ // Radius is to the stroke centreline, so the ring's outer edge lands
+ // exactly on the inner field and never clips against the border.
+ expect(circle.getAttribute('r'), `avatar ${avatarSize}`).toBe(
+ String(radius),
+ );
+ expect(circle.getAttribute('cx'), `avatar ${avatarSize}`).toBe(
+ String(field / 2),
+ );
+ expect(circle.getAttribute('cy'), `avatar ${avatarSize}`).toBe(
+ String(field / 2),
+ );
+ expect(circle.getAttribute('fill'), `avatar ${avatarSize}`).toBe(
+ 'none',
+ );
+ }
+ });
+
+ it('strokes the minus bar at the same weight, spanning 75% of the field with round caps', () => {
+ // Ends are inset by half the stroke so the round caps land inside the
+ // 75% span rather than overhanging it.
+ const cases = [
+ // avatar size, field, stroke, x1, x2
+ [36, 8, 1, 1.5, 6.5],
+ [48, 16, 1.5, 2.75, 13.25],
+ [128, 24, 2, 4, 20],
+ ] as const;
+ for (const [avatarSize, field, stroke, x1, x2] of cases) {
+ const line = renderDot({variant: 'error'}, avatarSize).querySelector(
+ `${GLYPH_SELECTOR} line`,
+ ) as SVGLineElement;
+ expect(line, `avatar ${avatarSize}`).not.toBeNull();
+ expect(line.getAttribute('stroke-width'), `avatar ${avatarSize}`).toBe(
+ String(stroke),
+ );
+ expect(line.getAttribute('x1'), `avatar ${avatarSize}`).toBe(
+ String(x1),
+ );
+ expect(line.getAttribute('x2'), `avatar ${avatarSize}`).toBe(
+ String(x2),
+ );
+ expect(line.getAttribute('y1'), `avatar ${avatarSize}`).toBe(
+ String(field / 2),
+ );
+ expect(line.getAttribute('y2'), `avatar ${avatarSize}`).toBe(
+ String(field / 2),
+ );
+ expect(
+ line.getAttribute('stroke-linecap'),
+ `avatar ${avatarSize}`,
+ ).toBe('round');
+ }
+ });
+
+ it('paints both glyphs from currentColor so the dot owns the ink colour', () => {
+ for (const variant of ['neutral', 'error'] as const) {
+ const mark = renderDot({variant}, 48).querySelector(
+ `${GLYPH_SELECTOR} circle, ${GLYPH_SELECTOR} line`,
+ ) as SVGElement;
+ expect(mark.getAttribute('stroke'), variant).toBe('currentColor');
+ }
+ });
+
+ it('fills the ring variant with surface and inks it with the variant colour', () => {
+ // A ring only reads as hollow if its interior is not the variant
+ // colour, so `neutral` inverts: surface fill, coloured stroke.
+ // StyleX atomic classes are deterministic, so a local probe pins it.
+ const probe = stylex.create({
+ ring: {
+ backgroundColor: colorVars['--color-background-surface'],
+ color: colorVars['--color-text-secondary'],
+ },
+ });
+ const dot = renderDot({variant: 'neutral'}, 48);
+ const atomicClasses = (stylex.props(probe.ring).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);
+ }
+ });
+
+ it('lets a user icon inherit the dot ink instead of hard-coding surface', () => {
+ // Surface ink on the surface-filled ring variant would be invisible.
+ const probe = stylex.create({
+ surfaceInk: {color: colorVars['--color-background-surface']},
+ });
+ renderDot(
+ {variant: 'neutral', icon: <svg data-testid="user-icon" />},
+ 48,
+ );
+ const iconWrapper = screen.getByTestId('user-icon')
+ .parentElement as HTMLElement;
+ const surfaceInkClasses = (stylex.props(probe.surfaceInk).className ?? '')
+ .split(' ')
+ .filter(cls => !cls.includes('__'));
+ expect(surfaceInkClasses.length).toBeGreaterThan(0);
+ for (const cls of surfaceInkClasses) {
+ expect(iconWrapper.className).not.toContain(cls);
+ }
+ });
+
+ it('renders no glyph for custom augmented variants (documented: they must bring their own non-colour mark)', () => {
+ const dot = renderDot({variant: 'away' as AvatarStatusDotVariant});
+ expect(dot.querySelector(GLYPH_SELECTOR)).toBeNull();
+ });
+ });
+
+ describe('glyph and icon interplay', () => {
+ it('suppresses the glyph when a user icon renders: the icon is the non-colour mark', () => {
+ const dot = renderDot(
+ {variant: 'error', icon: <svg data-testid="user-icon" />},
+ 48,
+ );
+ expect(screen.getByTestId('user-icon')).toBeInTheDocument();
+ expect(dot.querySelector(GLYPH_SELECTOR)).toBeNull();
+ });
+
+ it('keeps the glyph at the smallest tier where icons never render', () => {
+ const dot = renderDot(
+ {variant: 'error', icon: <svg data-testid="user-icon" />},
+ 36,
+ );
+ expect(screen.queryByTestId('user-icon')).not.toBeInTheDocument();
+ expect(dot.querySelector(GLYPH_SELECTOR)).not.toBeNull();
+ });
+
+ it('keeps the glyph for non-renderable icons: booleans from `cond && <Icon />` render nothing', () => {
+ for (const nonRenderable of [true, false, ''] as const) {
+ const dot = renderDot({variant: 'error', icon: nonRenderable}, 48);
+ expect(
+ dot.querySelector(GLYPH_SELECTOR),
+ `icon={${JSON.stringify(nonRenderable)}}`,
+ ).not.toBeNull();
+ }
+ });
+ });
+
+ describe('existing contract', () => {
+ it('exposes role="img" with the label as accessible name when label is provided', () => {
+ const dot = renderDot({variant: 'success', label: 'Online'});
+ expect(dot).toHaveAttribute('role', 'img');
+ expect(dot).toHaveAttribute('aria-label', 'Online');
+ });
+
+ it('has no img role without a label', () => {
+ const dot = renderDot({variant: 'success'});
+ expect(dot).not.toHaveAttribute('role');
+ });
+
+ it('reflects the variant as a data attribute for theming', () => {
+ const dot = renderDot({variant: 'neutral'});
+ expect(dot).toHaveAttribute('data-variant', 'neutral');
+ });
+
+ it('renders the user icon at tiers with room for it, hidden from assistive tech', () => {
+ renderDot(
+ {variant: 'success', icon: <svg data-testid="user-icon" />},
+ 128,
+ );
+ const icon = screen.getByTestId('user-icon');
+ expect(icon).toBeInTheDocument();
+ expect(icon.parentElement).toHaveAttribute('aria-hidden', 'true');
+ });
+ });
+});
diff --git a/packages/core/src/Avatar/AvatarStatusDot.tsx b/packages/core/src/Avatar/AvatarStatusDot.tsx
index 0bb5005829..19f22e382e 100644
--- a/packages/core/src/Avatar/AvatarStatusDot.tsx
+++ b/packages/core/src/Avatar/AvatarStatusDot.tsx
@@ -20,37 +20,49 @@ import type {BaseProps} from '../BaseProps';
import * as stylex from '@stylexjs/stylex';
import {colorVars, radiusVars} from '../theme/tokens.stylex';
import {AvatarSizeContext} from './AvatarSizeContext';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
import {themeProps} from '../utils/themeProps';
/**
- * Resolves the status dot size, border width, and icon size based on the
- * avatar size.
+ * Discrete size tier of the status dot, derived from the avatar size.
+ * Keys the built-in shape glyph's stroke weight — see `GLYPH_STROKE_WIDTH`.
+ */
+type StatusDotSizeTier = 'small' | 'medium' | 'large';
+
+/**
+ * Resolves the status dot size, border width, icon size, and size tier
+ * based on the avatar size.
*
* Uses discrete size tiers rather than a continuous ratio so the dot
* looks intentional at every avatar size:
*
- * | Avatar size | Dot | Border | Icon |
- * |--------------|------|--------|------|
- * | ≤ 36px | 10px | 1px | — |
- * | 40–72px | 20px | 2px | 12px |
- * | ≥ 96px | 32px | 4px | 18px |
+ * | Avatar size | Tier | Dot | Border | Icon | Field | Glyph stroke |
+ * |--------------|--------|------|--------|------|-------|--------------|
+ * | ≤ 36px | small | 10px | 1px | — | 8px | 1px |
+ * | 40–72px | medium | 20px | 2px | 12px | 16px | 1.5px |
+ * | ≥ 96px | large | 32px | 4px | 18px | 24px | 2px |
+ *
+ * "Field" is the dot's inner field — the dot minus both borders — that the
+ * shape glyph is drawn into; see `GLYPH_STROKE_WIDTH` for the stroke ladder.
*
* Icons are not rendered at the smallest tier — there isn't enough
- * room for them to be legible.
+ * room for them to be legible. The built-in shape glyphs (see
+ * `glyphShapeMap`) do render there, so status stays distinguishable
+ * without colour at every size.
*/
function resolveStatusDotSize(avatarSize: number): {
dotSize: number;
borderWidth: number;
iconSize: number;
+ tier: StatusDotSizeTier;
} {
if (avatarSize <= 36) {
- return {dotSize: 10, borderWidth: 1, iconSize: 0};
+ return {dotSize: 10, borderWidth: 1, iconSize: 0, tier: 'small'};
}
if (avatarSize <= 72) {
- return {dotSize: 20, borderWidth: 2, iconSize: 12};
+ return {dotSize: 20, borderWidth: 2, iconSize: 12, tier: 'medium'};
}
- return {dotSize: 32, borderWidth: 4, iconSize: 18};
+ return {dotSize: 32, borderWidth: 4, iconSize: 18, tier: 'large'};
}
/**
@@ -65,6 +77,13 @@ function resolveStatusDotSize(avatarSize: number): {
* }
* }
* ```
+ *
+ * Custom variants render no background fill, no ink colour, and no built-in
+ * shape glyph — the theme must supply the fill and, if it passes an `icon`,
+ * a `color` for it to paint with. It should also supply a non-colour mark
+ * so the status is not distinguishable by colour alone (a WCAG 1.4.1
+ * failure): pass `icon`, or theme a glyph onto the dot via
+ * `.astryx-avatar-status-dot[data-variant="..."]` (e.g. a `::before` mark).
*/
export interface AvatarStatusDotVariantMap {
success: true;
@@ -80,12 +99,14 @@ export type AvatarStatusDotVariant = keyof AvatarStatusDotVariantMap;
export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
ref?: React.Ref<HTMLDivElement>;
/**
- * The semantic color variant of the dot.
- * - `success` — green dot (e.g. online, accepted)
- * - `neutral` — gray dot (e.g. offline, pending)
- * - `error` — red dot (e.g. busy, rejected)
+ * The semantic variant of the dot. Each variant pairs a colour with a
+ * distinct built-in shape so status is never conveyed by colour alone
+ * (WCAG 2.1 SC 1.4.1):
+ * - `success` — filled green dot (e.g. online, accepted)
+ * - `neutral` — grey ring (e.g. away, offline, pending)
+ * - `error` — red dot with a minus bar (e.g. busy, do not disturb)
*
- * Matches the `variant` convention from `StatusDot`.
+ * Matches the `variant` naming convention from `StatusDot`.
* @default 'success'
*/
variant?: AvatarStatusDotVariant;
@@ -93,6 +114,11 @@ export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
* Accessible label for the status dot.
* Describes the meaning of the indicator for screen readers
* (e.g. "Online", "Accepted", "John Doe is busy").
+ *
+ * Note: inside an Avatar the label is currently not announced — the
+ * Avatar root is `role="img"`, which prunes descendant semantics.
+ * Pass it anyway; composing status into the avatar's accessible name
+ * is a planned Avatar-level fix.
*/
label?: string;
/**
@@ -101,6 +127,14 @@ export interface AvatarStatusDotProps extends BaseProps<HTMLDivElement> {
* The icon is automatically sized to fit the dot and hidden
* at the smallest avatar sizes where there isn't enough room.
*
+ * A rendered icon replaces the variant's built-in shape glyph, so use a
+ * different icon per status — the same icon on every variant leaves the
+ * statuses distinguishable by colour alone (WCAG 1.4.1). At the smallest
+ * avatar sizes the built-in glyph still shows instead of the icon.
+ * Booleans and empty strings are ignored (safe for `cond && <Icon />`),
+ * but a component that renders nothing still counts as an icon and
+ * suppresses the glyph.
+ *
* @example
* ```
* <AvatarStatusDot variant="success" label="Verified" icon={<CheckIcon />} />
@@ -119,20 +153,29 @@ const styles = stylex.create({
alignItems: 'center',
justifyContent: 'center',
},
+ // Each variant sets both the plate colour and the ink colour. Everything
+ // drawn on the dot — the shape glyph and any user `icon` — paints from
+ // `currentColor`, so the two can never drift out of contrast.
success: {
backgroundColor: colorVars['--color-success'],
+ color: colorVars['--color-background-surface'],
},
+ // The ring variant inverts: a hollow shape only reads as hollow if its
+ // interior is not the variant colour, so the plate is surface and the
+ // colour moves to the stroke. This also keeps a user `icon` legible on
+ // it — surface ink on a surface plate would be invisible.
neutral: {
- backgroundColor: colorVars['--color-text-secondary'],
+ backgroundColor: colorVars['--color-background-surface'],
+ color: colorVars['--color-text-secondary'],
},
error: {
backgroundColor: colorVars['--color-error'],
+ color: colorVars['--color-background-surface'],
},
icon: {
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
- color: colorVars['--color-background-surface'],
lineHeight: 0,
},
});
@@ -157,10 +200,112 @@ const variantStyleMap: Partial<
error: styles.error,
};
+/**
+ * Built-in shape glyph per variant, so each status differs by shape and not
+ * only by colour (WCAG 2.1 SC 1.4.1). The glyph is a stroked inline SVG
+ * painted in `currentColor`:
+ * - `ring` — a stroked circle on a surface plate; the dot reads as hollow
+ * (away/offline).
+ * - `minus` — a round-capped bar across the filled dot; the dot reads as
+ * "do not disturb" (busy).
+ *
+ * `success` stays the plain filled dot — filled, hollow, and barred are the
+ * three distinct fill topologies. Custom augmented variants have no entry
+ * and render no glyph; see the `AvatarStatusDotVariantMap` docs.
+ */
+type AvatarStatusDotGlyphShape = 'ring' | 'minus';
+
+const glyphShapeMap: Partial<
+ Record<AvatarStatusDotVariant, AvatarStatusDotGlyphShape>
+> = {
+ neutral: 'ring',
+ error: 'minus',
+};
+
+/**
+ * Glyph stroke weight per tier, in px of the dot's inner field.
+ *
+ * Roughly `field / 12`, floored at 1px so the smallest tier stays visible.
+ * That lands on the 1 / 1.5 / 2 ladder the rest of the system draws with —
+ * `Icon`'s default set strokes at 1.5 in a 24 viewBox, as does the
+ * `CheckboxInput` checkmark — rather than the 25% band a CSS box cutout
+ * produced, which was several times heavier than any other glyph we ship.
+ */
+const GLYPH_STROKE_WIDTH: Record<StatusDotSizeTier, number> = {
+ small: 1,
+ medium: 1.5,
+ large: 2,
+};
+
+/** Fraction of the inner field the minus bar spans, cap to cap. */
+const MINUS_BAR_SPAN = 0.75;
+
+/**
+ * The built-in shape glyph, drawn as a stroked inline SVG in `currentColor`.
+ *
+ * Stroking (rather than a CSS box) is what buys sub-pixel control and round
+ * line caps, so the mark stays intentional at every tier — including the
+ * 10px dot, where a box cutout can only land on whole pixels.
+ *
+ * `viewBox` is one user unit per px of the inner field, so every value here
+ * is literal px.
+ */
+function StatusDotGlyph({
+ shape,
+ field,
+ stroke,
+}: {
+ shape: AvatarStatusDotGlyphShape;
+ field: number;
+ stroke: number;
+}) {
+ const center = field / 2;
+ return (
+ <svg
+ aria-hidden="true"
+ viewBox={`0 0 ${field} ${field}`}
+ width={field}
+ height={field}
+ fill="none"
+ {...themeProps('avatar-status-dot-glyph', {shape})}>
+ {shape === 'ring' ? (
+ // Radius is to the stroke centreline, so the ring's outer edge lands
+ // exactly on the inner field and never clips against the border.
+ <circle
+ cx={center}
+ cy={center}
+ r={(field - stroke) / 2}
+ fill="none"
+ stroke="currentColor"
+ strokeWidth={stroke}
+ />
+ ) : (
+ // Ends inset by half the stroke so the round caps land inside the
+ // span rather than overhanging it.
+ <line
+ x1={(field * (1 - MINUS_BAR_SPAN)) / 2 + stroke / 2}
+ y1={center}
+ x2={(field * (1 + MINUS_BAR_SPAN)) / 2 - stroke / 2}
+ y2={center}
+ stroke="currentColor"
+ strokeWidth={stroke}
+ strokeLinecap="round"
+ />
+ )}
+ </svg>
+ );
+}
+
/**
* A status indicator dot that automatically scales to match the parent
* Avatar's size.
*
+ * Each variant pairs a colour with a distinct built-in shape (filled dot,
+ * ring, minus bar) so status stays distinguishable without colour
+ * perception (WCAG 2.1 SC 1.4.1). Themes can target the shape glyph via
+ * the `astryx-avatar-status-dot-glyph` class and its `data-shape`
+ * attribute.
+ *
* Must be used inside an Avatar's `status` prop so it can read
* the avatar size from context.
*
@@ -189,7 +334,12 @@ export function AvatarStatusDot({
...props
}: AvatarStatusDotProps) {
const avatarSize = use(AvatarSizeContext);
- const {dotSize, borderWidth, iconSize} = resolveStatusDotSize(avatarSize);
+ const {dotSize, borderWidth, iconSize, tier} =
+ resolveStatusDotSize(avatarSize);
+ const showsIcon = isRenderable(icon) && iconSize > 0;
+ // A rendered icon is itself a non-colour mark; overlaying both cutouts in
+ // the dot's small inner field would make each illegible.
+ const glyphShape = showsIcon ? undefined : glyphShapeMap[variant];
return (
<div
@@ -207,13 +357,20 @@ export function AvatarStatusDot({
className,
style,
)}>
- {icon && iconSize > 0 && (
+ {showsIcon && (
<span
aria-hidden="true"
{...stylex.props(styles.icon, dynamicStyles.iconSize(iconSize))}>
{icon}
</span>
)}
+ {glyphShape && (
+ <StatusDotGlyph
+ shape={glyphShape}
+ field={dotSize - borderWidth * 2}
+ stroke={GLYPH_STROKE_WIDTH[tier]}
+ />
+ )}
</div>
);
}