fix(AvatarStatusDot): resolve WCAG 2.1 SC 1.4.1 use-of-color failure

[gonzoblasco]

Summary

Resolves #4143

The AvatarStatusDot component relied on colour alone to convey status meaning (green=success, gray=neutral, red=error), which fails WCAG 2.1 Success Criterion 1.4.1 (Use of Color).

Users with colour vision deficiencies (deuteranopia, protanopia, tritanopia, achromatopsia) cannot distinguish between the three status states, and screen readers have no way to announce the status when no label is provided.

Solution

Two-pronged approach to ensure status is never conveyed by colour alone:

1. Default icons per variant (shape differentiation)

When no icon prop is provided, a default SVG icon is rendered inside the dot based on the variant:

Variant	Default icon	Shape conveys
success	✓ checkmark	positive/accepted
neutral	− dash	neutral/pending
error	✕ cross	negative/rejected

These icons are rendered at medium+ avatar sizes (≥ 40px) where there is enough room. At the smallest tier (≤ 36px, dotSize=10px), icons are not legible, so shape differentiation falls back to the accessible label.

2. Default accessible labels per variant (screen reader support)

When no label prop is provided, a default label is derived from the variant ("Success", "Neutral", "Error"). This ensures:

• Screen readers always announce the status meaning
• At the smallest avatar tier (where icons can't render), the label still conveys meaning
• The role="img" attribute is always set when there's a label

Backward compatibility

• Explicit label prop still takes precedence over the default
• Explicit icon prop still takes precedence over the default
• icon={null} explicitly suppresses the default icon
• Consumers already passing these props see zero change

What this fixes

Before (WCAG 1.4.1 fail):

// Colour alone — no shape, no label, screen reader silent
<AvatarStatusDot variant="success" />

After (WCAG 1.4.1 pass):

// Same call, now renders a checkmark icon + "Success" label automatically
<AvatarStatusDot variant="success" />

Testing

Added 8 test cases covering:

• Default label per variant (success, neutral, error)
• Explicit label overriding default
• Default icon rendering at medium+ sizes
• No default icon at smallest avatar tier
• icon={null} suppression
• Different icons rendered for different variants

Checklist

• Changes are backward compatible
• No new dependencies (inline SVGs, no icon library needed)
• Tests added
• JSDoc updated with WCAG rationale
• Follows existing code patterns (StyleX, variant map, module augmentation)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
astryx	Ready	Preview, Comment	Jul 22, 2026 11:04pm