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.mdnew file mode 100644index 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`.+@AKnassadiff --git a/apps/storybook/stories/Avatar.stories.tsx b/apps/storybook/stories/Avatar.stories.tsxindex 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 = {<Avatarname="TY"size="xsm"- status={<AvatarStatusDot variant="success" />}+ status={<AvatarStatusDot variant="success" label="Online" />}/><Avatarname="XS"size="sm"- status={<AvatarStatusDot variant="success" />}+ status={<AvatarStatusDot variant="success" label="Online" />}/><Avatarname="SM"size="md"- status={<AvatarStatusDot variant="success" />}+ status={<AvatarStatusDot variant="success" label="Online" />}/><Avatarname="MD"size="lg"- status={<AvatarStatusDot variant="success" />}+ status={<AvatarStatusDot variant="success" label="Online" />}/><Avatarname="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" />}/><Avatarsrc="https://i.pravatar.cc/150?img=31"name="U2"size={32}- status={<AvatarStatusDot variant="success" />}+ status={<AvatarStatusDot variant="success" label="Online" />}/><Avatarsrc="https://i.pravatar.cc/150?img=32"name="U3"size={48}- status={<AvatarStatusDot variant="error" />}+ status={<AvatarStatusDot variant="error" label="Busy" />}/><Avatarsrc="https://i.pravatar.cc/150?img=33"name="U4"size={72}- status={<AvatarStatusDot variant="neutral" />}+ status={<AvatarStatusDot variant="neutral" label="Offline" />}/><Avatarsrc="https://i.pravatar.cc/150?img=34"name="U5"size={96}- status={<AvatarStatusDot variant="success" />}+ status={<AvatarStatusDot variant="success" label="Online" />}/><Avatarsrc="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.tsxindex 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.mjsindex 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.mjsindex 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.tsxnew file mode 100644index 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.tsxindex 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 && (<spanaria-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>);}