Skip to content

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

TypeScript

fix(EmptyState, Badge): hardening — heading level, dot mode fixes (#793)

Cindy Zhang69f7ed551e0f
diff --git a/apps/storybook/stories/Badge.stories.tsx b/apps/storybook/stories/Badge.stories.tsx
index 067aa495b5..c05f83115d 100644
--- a/apps/storybook/stories/Badge.stories.tsx
+++ b/apps/storybook/stories/Badge.stories.tsx
@@ -11,9 +11,14 @@ const meta: Meta<typeof XDSBadge> = {
options: ['neutral', 'info', 'success', 'warning', 'error'],
description: 'Visual style variant',
},
- children: {
+ label: {
control: 'text',
- description: 'Badge content',
+ description: 'Badge label text',
+ },
+ shape: {
+ control: 'select',
+ options: ['pill', 'dot'],
+ description: 'Visual shape of the badge',
},
},
};
@@ -23,18 +28,18 @@ type Story = StoryObj<typeof XDSBadge>;
export const Default: Story = {
args: {
- children: 'Badge',
+ label: 'Badge',
},
};
export const Variants: Story = {
render: () => (
<div style={{display: 'flex', gap: '8px', alignItems: 'center'}}>
- <XDSBadge variant="neutral" label='Neutral' />
- <XDSBadge variant="info" label='Info' />
- <XDSBadge variant="success" label='Success' />
- <XDSBadge variant="warning" label='Warning' />
- <XDSBadge variant="error" label='Error' />
+ <XDSBadge variant="neutral" label="Neutral" />
+ <XDSBadge variant="info" label="Info" />
+ <XDSBadge variant="success" label="Success" />
+ <XDSBadge variant="warning" label="Warning" />
+ <XDSBadge variant="error" label="Error" />
</div>
),
};
@@ -43,7 +48,7 @@ export const Counts: Story = {
render: () => (
<div style={{display: 'flex', gap: '8px', alignItems: 'center'}}>
<XDSBadge variant="info" label={3} />
- <XDSBadge variant="error" label='99+' />
+ <XDSBadge variant="error" label="99+" />
<XDSBadge variant="success" label={12} />
</div>
),
@@ -52,11 +57,11 @@ export const Counts: Story = {
export const DotIndicators: Story = {
render: () => (
<div style={{display: 'flex', gap: '8px', alignItems: 'center'}}>
- <XDSBadge variant="neutral" />
- <XDSBadge variant="info" />
- <XDSBadge variant="success" />
- <XDSBadge variant="warning" />
- <XDSBadge variant="error" />
+ <XDSBadge variant="neutral" shape="dot" label="Neutral" />
+ <XDSBadge variant="info" shape="dot" label="Info" />
+ <XDSBadge variant="success" shape="dot" label="Online" />
+ <XDSBadge variant="warning" shape="dot" label="Away" />
+ <XDSBadge variant="error" shape="dot" label="Busy" />
</div>
),
};
@@ -64,10 +69,10 @@ export const DotIndicators: Story = {
export const StatusLabels: Story = {
render: () => (
<div style={{display: 'flex', gap: '8px', alignItems: 'center'}}>
- <XDSBadge variant="success" label='Active' />
- <XDSBadge variant="warning" label='Pending' />
- <XDSBadge variant="error" label='Failed' />
- <XDSBadge variant="neutral" label='Draft' />
+ <XDSBadge variant="success" label="Active" />
+ <XDSBadge variant="warning" label="Pending" />
+ <XDSBadge variant="error" label="Failed" />
+ <XDSBadge variant="neutral" label="Draft" />
</div>
),
};
diff --git a/packages/core/src/Badge/XDSBadge.test.tsx b/packages/core/src/Badge/XDSBadge.test.tsx
index dfd619111a..d65bf50138 100644
--- a/packages/core/src/Badge/XDSBadge.test.tsx
+++ b/packages/core/src/Badge/XDSBadge.test.tsx
@@ -22,11 +22,46 @@ describe('XDSBadge', () => {
expect(screen.getByText('Info')).toBeInTheDocument();
});
- it('renders as dot when no label provided', () => {
- const {container} = render(<XDSBadge variant="success" />);
- const badge = container.querySelector('span');
- expect(badge).toBeInTheDocument();
- expect(badge?.textContent).toBe('');
+ it('renders as dot with shape="dot"', () => {
+ render(<XDSBadge variant="success" shape="dot" label="Online" />);
+ // Label is in the DOM as visually hidden text for screen readers
+ expect(screen.getByText('Online')).toBeInTheDocument();
+ });
+
+ it('dot shape has accessible label via visually hidden text', () => {
+ render(
+ <XDSBadge
+ variant="error"
+ shape="dot"
+ label="3 unread"
+ data-testid="dot-badge"
+ />,
+ );
+ const badge = screen.getByTestId('dot-badge');
+ expect(screen.getByText('3 unread')).toBeInTheDocument();
+ // The visually hidden span is inside the badge
+ expect(badge.textContent).toBe('3 unread');
+ });
+
+ it('dot shape suppresses icon', () => {
+ render(
+ <XDSBadge
+ label="Status"
+ icon={<span data-testid="icon">*</span>}
+ shape="dot"
+ data-testid="dot-badge"
+ />,
+ );
+ const badge = screen.getByTestId('dot-badge');
+ expect(badge.querySelector('[data-testid="icon"]')).toBeNull();
+ });
+
+ it('includes shape in xdsClassName', () => {
+ const {container} = render(
+ <XDSBadge variant="info" label="New" shape="dot" />,
+ );
+ const root = container.firstElementChild!;
+ expect(root.className).toContain('dot');
});
it('renders with icon', () => {
diff --git a/packages/core/src/Badge/XDSBadge.tsx b/packages/core/src/Badge/XDSBadge.tsx
index 39226de44a..1422422f71 100644
--- a/packages/core/src/Badge/XDSBadge.tsx
+++ b/packages/core/src/Badge/XDSBadge.tsx
@@ -47,7 +47,22 @@ const styles = stylex.create({
whiteSpace: 'nowrap',
},
dot: {
- paddingInline: spacingVars['--spacing-1'],
+ width: spacingVars['--spacing-2'],
+ height: spacingVars['--spacing-2'],
+ paddingInline: 0,
+ paddingBlock: 0,
+ borderRadius: '50%',
+ },
+ visuallyHidden: {
+ position: 'absolute',
+ width: '1px',
+ height: '1px',
+ padding: 0,
+ margin: '-1px',
+ overflow: 'hidden',
+ clip: 'rect(0, 0, 0, 0)',
+ whiteSpace: 'nowrap',
+ borderWidth: 0,
},
});
@@ -113,15 +128,31 @@ export interface XDSBadgeProps extends XDSBaseProps<HTMLSpanElement> {
*/
variant?: XDSBadgeVariant;
/**
- * The content to display in the badge.
- * If omitted (and no icon), renders as a small dot indicator.
+ * The badge label. Displayed as visible text for pill badges.
+ * Used as the accessible name (visually hidden) for dot badges.
*/
- label?: ReactNode;
+ label: ReactNode;
/**
* Optional icon to display before the label.
*/
icon?: ReactNode;
+
+ /**
+ * Visual shape of the badge.
+ * - `'pill'`: Default rounded pill shape for text/icon content
+ * - `'dot'`: Small circular indicator with no content
+ *
+ * When using `shape="dot"`, the `label` is rendered as visually hidden
+ * text for screen reader accessibility.
+ * @default 'pill'
+ *
+ * @example
+ * ```
+ * <XDSBadge variant="error" shape="dot" label="Unread" />
+ * ```
+ */
+ shape?: 'pill' | 'dot';
}
/**
@@ -132,29 +163,30 @@ export interface XDSBadgeProps extends XDSBaseProps<HTMLSpanElement> {
*
* @example
* ```
- * <XDSBadge label="Default" />
+ * <XDSBadge label="Active" />
* <XDSBadge variant="success" label="Active" />
* <XDSBadge variant="error" label="3" />
- * <XDSBadge variant="info" />
+ * <XDSBadge variant="info" shape="dot" label="New" />
* ```
*/
export function XDSBadge({
variant = 'neutral',
label,
icon,
+ shape = 'pill',
xstyle,
className,
style,
ref,
...props
}: XDSBadgeProps) {
- const isDot = label == null && icon == null;
+ const isDot = shape === 'dot';
return (
<span
ref={ref}
{...mergeProps(
- xdsClassName('badge', {variant}),
+ xdsClassName('badge', {variant, shape}),
stylex.props(
styles.base,
variants[variant],
@@ -165,8 +197,9 @@ export function XDSBadge({
style,
)}
{...props}>
- {icon}
- {label}
+ {isDot && <span {...stylex.props(styles.visuallyHidden)}>{label}</span>}
+ {!isDot && icon}
+ {!isDot && label}
</span>
);
}
diff --git a/packages/core/src/EmptyState/XDSEmptyState.test.tsx b/packages/core/src/EmptyState/XDSEmptyState.test.tsx
index b3855df782..9c6b43ef84 100644
--- a/packages/core/src/EmptyState/XDSEmptyState.test.tsx
+++ b/packages/core/src/EmptyState/XDSEmptyState.test.tsx
@@ -8,9 +8,31 @@ describe('XDSEmptyState', () => {
expect(screen.getByText('No results found')).toBeInTheDocument();
});
- it('renders title as a heading element', () => {
+ it('renders title as h3 by default', () => {
render(<XDSEmptyState title="No data" />);
- expect(screen.getByRole('heading', {name: 'No data'})).toBeInTheDocument();
+ const heading = screen.getByRole('heading', {name: 'No data'});
+ expect(heading).toBeInTheDocument();
+ expect(heading.tagName).toBe('H3');
+ });
+
+ it('renders custom heading level', () => {
+ render(<XDSEmptyState title="No data" headingLevel={2} />);
+ const heading = screen.getByRole('heading', {name: 'No data'});
+ expect(heading.tagName).toBe('H2');
+ });
+
+ it('renders all heading levels', () => {
+ const levels = [1, 2, 3, 4, 5, 6] as const;
+ for (const level of levels) {
+ const {unmount} = render(
+ <XDSEmptyState title={`Level ${level}`} headingLevel={level} />,
+ );
+ const heading = screen.getByRole('heading', {
+ name: `Level ${level}`,
+ });
+ expect(heading.tagName).toBe(`H${level}`);
+ unmount();
+ }
});
it('renders with description', () => {
diff --git a/packages/core/src/EmptyState/XDSEmptyState.tsx b/packages/core/src/EmptyState/XDSEmptyState.tsx
index 7f7da01528..dfa7523ca2 100644
--- a/packages/core/src/EmptyState/XDSEmptyState.tsx
+++ b/packages/core/src/EmptyState/XDSEmptyState.tsx
@@ -11,7 +11,7 @@
* - /apps/storybook/stories/EmptyState.stories.tsx (storybook stories)
*/
-import {type ReactNode} from 'react';
+import {type ReactNode, createElement} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {
@@ -57,7 +57,6 @@ const styles = stylex.create({
fontWeight: fontWeightVars['--font-weight-normal'],
lineHeight: lineHeightVars['--leading-base'],
color: colorVars['--color-text-secondary'],
- maxWidth: '360px',
},
descriptionCompact: {
fontSize: typeScaleVars['--text-supporting-size'],
@@ -66,6 +65,7 @@ const styles = stylex.create({
display: 'flex',
flexDirection: 'column',
alignItems: 'center',
+ maxWidth: '360px',
},
actions: {
display: 'flex',
@@ -100,6 +100,12 @@ export interface XDSEmptyStateProps {
* Laid out horizontally by default, stacked vertically when `isCompact`.
*/
actions?: ReactNode;
+ /**
+ * Semantic heading level for the title element.
+ * Controls the rendered HTML tag (h1–h6) to fit the document outline.
+ * @default 3
+ */
+ headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
/**
* Use compact variant for constrained spaces with reduced spacing.
* @default false
@@ -158,6 +164,7 @@ export function XDSEmptyState({
description,
icon,
actions,
+ headingLevel = 3,
isCompact = false,
xstyle,
className,
@@ -165,6 +172,7 @@ export function XDSEmptyState({
ref,
...props
}: XDSEmptyStateProps) {
+ const HeadingTag = `h${headingLevel}` as const;
return (
<div
ref={ref}
@@ -182,9 +190,11 @@ export function XDSEmptyState({
{...props}>
{icon != null && <div aria-hidden="true">{icon}</div>}
<div {...stylex.props(styles.textGroup)}>
- <h3 {...stylex.props(styles.title, isCompact && styles.titleCompact)}>
- {title}
- </h3>
+ {createElement(
+ HeadingTag,
+ stylex.props(styles.title, isCompact && styles.titleCompact),
+ title,
+ )}
{description != null && (
<p
{...stylex.props(