Skip to content

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

TypeScript

[Component Audit] EmptyState: remove blank optional-slot gaps (#7654)

Cindy Zhange2909cf48e4b
diff --git a/.changeset/empty-state-nonrendering-slots.md b/.changeset/empty-state-nonrendering-slots.md
new file mode 100644
index 0000000000..c2f3627dbd
--- /dev/null
+++ b/.changeset/empty-state-nonrendering-slots.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `EmptyState` no longer leaves blank icon or action spacing when those optional slots receive a boolean or an empty string. An empty description also omits its theme target. The docs now describe configurable heading levels and map the container anatomy to the public theme target.
+
+@cixzhang
diff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.json
index dc2cdcd95f..46757ed8f9 100644
--- a/apps/storybook/rtl-audit/verified-not-applicable.json
+++ b/apps/storybook/rtl-audit/verified-not-applicable.json
@@ -16,6 +16,10 @@
"component": "core/Field",
"reason": "The Core/Field stories use block-flow labels, controls, descriptions, and status text without directional icons, side-specific placement, order, scrolling, dragging, overlays, or keyboard behavior."
},
+ {
+ "component": "core/EmptyState",
+ "reason": "EmptyState is a centered block-flow status region. Its icon, text group, and action group stack only on the block axis; spacing is block-axis or logical, and text is centered. The component owns no directional glyph, contextual separator, side-specific placement or ordering, horizontal scrolling or dragging, overlay, or directional keyboard behavior. Caller-supplied icons and action controls retain their own RTL ownership."
+ },
{
"component": "core/FieldStatus",
"reason": "FieldStatus uses block-flow message layout and logical padding and corner radii. Its status glyphs are non-directional, and it has no side-specific placement, order, scrolling, dragging, overlays, or directional keyboard behavior."
diff --git a/apps/storybook/stories/EmptyState.stories.tsx b/apps/storybook/stories/EmptyState.stories.tsx
index 92f159962d..34abb7ca0f 100644
--- a/apps/storybook/stories/EmptyState.stories.tsx
+++ b/apps/storybook/stories/EmptyState.stories.tsx
@@ -40,6 +40,15 @@ export const TitleOnly: Story = {
},
};
+export const NonRenderingOptionalSlots: Story = {
+ args: {
+ title: 'Nothing here yet',
+ description: '',
+ icon: false,
+ actions: '',
+ },
+};
+
export const WithIcon: Story = {
args: {
icon: <span style={{fontSize: '48px'}}>📭</span>,
diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjs
index 1fcd7a7e9e..d0f75308e4 100644
--- a/packages/core/src/EmptyState/EmptyState.doc.mjs
+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs
@@ -12,7 +12,7 @@ export const docs = {
name: 'title',
type: 'string',
description:
- 'Primary message rendered as an <h3> heading inside the empty state.',
+ 'Primary message rendered as the configured heading level inside the empty state.',
required: true,
},
{
@@ -81,6 +81,7 @@ export const docs = {
{ guidance: false, description: 'Use an EmptyState for error messages that require immediate action; use a Banner instead.' },
],
anatomy: [
+ {name: 'Container', required: true, description: 'The centered status region that owns spacing, reading order, and the compact layout variant.'},
{name: 'Icon', required: false, description: 'A visual cue above the title that reinforces the context, like a search icon for no results.'},
{name: 'Title', required: true, description: 'Primary message explaining what is empty: "No projects yet" not "No data".'},
{name: 'Description', required: false, description: 'Additional context explaining why it is empty or what the user can do.'},
@@ -98,7 +99,7 @@ export const docsZh = {
name: 'title',
type: 'string',
description:
- '在空状态内部渲染为 <h3> 标题的主要信息。',
+ '在空状态内部按配置的标题级别渲染主要信息。',
required: true,
},
{
diff --git a/packages/core/src/EmptyState/EmptyState.spec.md b/packages/core/src/EmptyState/EmptyState.spec.md
new file mode 100644
index 0000000000..f03b9d4580
--- /dev/null
+++ b/packages/core/src/EmptyState/EmptyState.spec.md
@@ -0,0 +1,189 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:EmptyState
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility, testing]
+verified_by:
+ [
+ packages/core/src/EmptyState/EmptyState.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ packages/core/src/docPropReferences.test.ts,
+ ]
+modules: []
+families: []
+design_specs: []
+architecture:
+ [
+ architecture:public-component-api,
+ architecture:component-theming-surface,
+ architecture:component-test-sufficiency,
+ ]
+contributing: []
+system_specs: [spec:AST-020/FR1, spec:AST-029/FR3]
+---
+
+# EmptyState component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract | `EmptyState` renders a required title plus optional description, decorative icon, and caller-owned actions in one status region; callers choose heading level and compact layout. |
+| Behavior | Null, undefined, boolean, and empty-string optional values create no slot wrapper. Rendered content follows icon, text, then actions order; compact layout reduces spacing and stacks actions. |
+| End-user impact | A person reaches a named empty-content message and any next action without blank gaps from shallow-empty optional values; the title fits the surrounding document outline. |
+| Builder impact | Callers supply content and actions, select heading semantics, and may compose supported root props and styling. No additional setup is required. |
+| Compatibility/readiness | The released default is preserved. This draft observes shipped behavior plus the narrow scalar-slot remediation; it adds no API, default, or compatibility promise. |
+| Review checks | Reject a missing heading, an informative icon hidden as decorative, a shallow-empty optional scalar that still changes layout, a dropped root prop/ref/style, or a theme target without anatomy. |
+| Governing rules | `architecture:public-component-api` INV1 and INV5–INV9; `architecture:component-theming-surface` INV2–INV6; `architecture:component-test-sufficiency` INV1–INV7, INV10–INV11; WCAG 2.2. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+`EmptyState` gives an otherwise empty content area a semantic heading, supporting
+context, optional decorative visual, and optional caller-owned next actions.
+
+## Compatibility and migration
+
+- Released default preserved: yes
+- Compatibility class: observational and additive documentation; runtime remediation removes wrappers for nullish, boolean, and empty-string optional values
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- the status-region root, content order, heading element, and default/compact layout;
+- hiding the icon slot from assistive technology as decorative; and
+- whether optional slots create component-owned wrappers and spacing.
+
+**Does not own / non-goals**
+
+- the message copy, icon meaning, action controls, or action behavior — those belong to the product callsite and the components it supplies;
+- page-level heading order — the caller chooses `headingLevel` for its document; or
+- error, loading, or populated-content behavior.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| -------------- | ----------------------- | ------------------------------------------------------------------------- | ----------------------------------------- | -------- | ---------------------- | --------- | ------------------------------------------------------- |
+| title | string | The empty region's heading content. | all | required | `component:EmptyState` | stable | type rejection |
+| description | string or absent | Optional supporting context below the title. | all | absent | `component:EmptyState` | stable | nullish and empty-string values omit the part |
+| icon | React node or absent | Optional caller visual, exposed as decorative beside the textual message. | all | absent | product callsite | stable | nullish, boolean, and empty-string values omit the slot |
+| actions | React node or absent | Optional caller-owned next actions below the message. | all | absent | product callsite | stable | nullish, boolean, and empty-string values omit the slot |
+| heading level | `1` through `6` | The title's HTML heading level in the surrounding document outline. | all | `3` | product callsite | stable | type rejection |
+| layout variant | default, compact | Compact reduces spacing and stacks the action slot vertically. | all | default | `component:EmptyState` | stable | type rejection |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision. A `current` contract contains no unresolved rows.
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ |
+| FR1 | The component MUST render one status-region root containing the icon, text group, and actions in that reading order when present. | Current implementation and consumer docs; WCAG 2.2 SC 1.3.2 and SC 4.1.3 | verify |
+| FR2 | The required title MUST render at the caller-selected heading level without changing the component's visual type role. | Current implementation, tests, and consumer docs; WCAG 2.2 SC 1.3.1 and SC 2.4.6 | verify |
+| FR3 | Null, undefined, boolean, and empty-string optional values MUST NOT create a wrapper, layout gap, or assistive-technology node; containers that are shallowly non-empty remain wrapped. | React's direct-child rendering semantics; established public optional-slot interface | verify |
+| FR4 | The decorative icon wrapper MUST be absent when the slot is absent and hidden from assistive technology when rendered. | Current implementation and tests; WCAG 2.2 SC 1.1.1 | verify |
+| FR5 | Root DOM/data/ARIA/event props, ref, `className`, `style`, and `xstyle` MUST reach and compose on the status-region root. | `architecture:public-component-api` INV5–INV8 | verify |
+| FR6 | Compact layout MUST reduce component spacing and stack the actions slot while preserving content order and root semantics. | Current implementation, tests, and consumer docs | verify |
+
+### Allowed variation
+
+- **AV1 — Caller content.** Message wording, decorative artwork, and action
+ composition may vary at the product callsite.
+- **AV2 — Theme paint.** Theme-controlled paint and typography may vary through
+ the documented targets while anatomy and content order remain stable.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ----------------------------- | --------------------------------------------------------- | -------------------------------------- |
+| title only | status root and selected heading level remain present | message wording |
+| description | supporting text follows the title | text length and wrapping |
+| decorative icon | visual precedes text and is hidden from assistive tech | artwork supplied by the caller |
+| actions | caller controls follow the text group | one or more caller-owned controls |
+| compact | reduced spacing and vertical actions preserve semantics | theme paint and caller content |
+| shallow-empty optional scalar | nullish, boolean, and empty-string values emit no wrapper | which optional slot receives the value |
+
+### Transformation and precedence order
+
+- **ORD1 — Root composition.** Component semantics and theme metadata combine
+ with component styles, then consumer `xstyle`, `className`, and `style` under
+ the shared merge contract; component-owned `role="status"` remains authoritative.
+
+### Performance and resources
+
+- **PR1 — Render-only surface.** EmptyState owns no retained state, listener,
+ observer, timer, or external resource.
+
+## Accessibility contract
+
+- **AR1 — Heading semantics.** The title is a heading at the caller-selected level.
+- **AR2 — Decorative visual.** The icon slot is hidden from assistive technology;
+ callers keep all necessary meaning in the title or description.
+- **AR3 — Status exposure.** The root exposes the empty message as a status region
+ without moving focus; action controls keep their own names, roles, and behavior.
+
+## Design relationships
+
+No current design record governs EmptyState-specific representation. Visual
+judgment remains evidence, not product authority.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Container": {"target": "empty-state"},
+ "Icon": {
+ "none": {
+ "reason": "intentional: caller-supplied decorative content keeps its own styling and has no component-owned paint target"
+ }
+ },
+ "Title": {"target": "empty-state-title"},
+ "Description": {"target": "empty-state-description"},
+ "Actions": {
+ "none": {
+ "reason": "intentional: caller-supplied controls keep their own component targets and behavior"
+ }
+ }
+}
+```
+
+## Family and system relationships
+
+No current family record owns EmptyState-specific behavior.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------------- | ------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------------------- | ------------------------- |
+| FR1–FR4, AR1–3 | focused DOM tests plus required exact-head accessibility evidence | title only, all slots, absent/shallow-empty slots | order, heading, status, or decorative treatment regresses | `audit:EmptyState/a11y` |
+| FR5, ORD1 | focused root composition tests plus shared API guards | DOM/data/event/style inputs, ref, root target | accepted input is dropped or component semantics/styles are replaced | `audit:EmptyState/api` |
+| FR6 | compact target/DOM tests plus required exact-head rendered evidence | default and compact, wide and narrow | compact state, spacing, or action direction no longer applies | `audit:EmptyState/layout` |
+| PR1 | source review | every render path | a retained resource appears without a named owner | `audit:EmptyState/code` |
+
+## Decision log
+
+No component-local decision is approved in this draft.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.
diff --git a/packages/core/src/EmptyState/EmptyState.test.tsx b/packages/core/src/EmptyState/EmptyState.test.tsx
index 88933a6c24..e473394bc7 100644
--- a/packages/core/src/EmptyState/EmptyState.test.tsx
+++ b/packages/core/src/EmptyState/EmptyState.test.tsx
@@ -1,7 +1,8 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, vi} from 'vitest';
+import {fireEvent, render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
import {EmptyState} from './EmptyState';
import {defineTheme} from '../theme/defineTheme';
import {generateThemeCSS} from '../theme/generateThemeRules';
@@ -11,6 +12,12 @@ function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
return [prose, component].filter(Boolean).join('\n\n');
}
+const testStyles = stylex.create({
+ root: {
+ minWidth: '123px',
+ },
+});
+
describe('EmptyState', () => {
it('renders with title', () => {
render(<EmptyState title="No results found" />);
@@ -52,7 +59,7 @@ describe('EmptyState', () => {
/>,
);
expect(screen.getByText('Try adjusting your search.')).toBeInTheDocument();
- // Description renders as <div> (never <p>) so block content composes safely.
+ // Description keeps its stable target element instead of paragraph semantics.
expect(screen.getByText('Try adjusting your search.').tagName).toBe('DIV');
});
@@ -132,6 +139,70 @@ describe('EmptyState', () => {
expect(screen.getByTestId('empty-state')).toBeInTheDocument();
});
+ it('does not render empty optional slot wrappers', () => {
+ const {container} = render(
+ <EmptyState title="No results" description="" icon={false} actions="" />,
+ );
+ const root = screen.getByRole('status');
+ expect(root).toHaveTextContent('No results');
+ expect(root).toHaveTextContent(/^No results$/);
+ expect(root.children).toHaveLength(1);
+ expect(container.querySelector('[aria-hidden="true"]')).toBeNull();
+ expect(
+ container.querySelector('.astryx-empty-state-description'),
+ ).toBeNull();
+ });
+
+ it('composes root props and keeps component semantics authoritative', () => {
+ const onClick = vi.fn();
+ const expectedXstyleClass = stylex.props(testStyles.root).className;
+ if (expectedXstyleClass == null) {
+ throw new Error('Expected the test xstyle to produce a class name.');
+ }
+ render(
+ <EmptyState
+ title="No results"
+ role="region"
+ data-owner="consumer"
+ className="consumer-class"
+ style={{width: '321px'}}
+ xstyle={testStyles.root}
+ onClick={onClick}
+ />,
+ );
+
+ const root = screen.getByRole('status');
+ expect(root).toHaveClass('astryx-empty-state', 'consumer-class');
+ expect(root).toHaveClass(expectedXstyleClass);
+ expect(root).toHaveAttribute('data-owner', 'consumer');
+ expect(root).toHaveStyle({width: '321px'});
+ fireEvent.click(root);
+ expect(onClick).toHaveBeenCalledOnce();
+ });
+
+ it('reflects compact layout on the root and preserves slot order', () => {
+ render(
+ <EmptyState
+ title="No results"
+ description="Try again."
+ icon={<span data-testid="icon">Icon</span>}
+ actions={<button type="button">Retry</button>}
+ isCompact
+ />,
+ );
+
+ const root = screen.getByRole('status');
+ expect(root).toHaveAttribute('data-variant', 'compact');
+ expect(root.children).toHaveLength(3);
+ expect(root.children[0]).toContainElement(screen.getByTestId('icon'));
+ expect(root.children[1]).toContainElement(
+ screen.getByRole('heading', {name: 'No results'}),
+ );
+ expect(root.children[2]).toContainElement(
+ screen.getByRole('button', {name: 'Retry'}),
+ );
+ });
+
it('renders all slots together', () => {
render(
<EmptyState
diff --git a/packages/core/src/EmptyState/EmptyState.tsx b/packages/core/src/EmptyState/EmptyState.tsx
index 1fec136e78..7675cf5043 100644
--- a/packages/core/src/EmptyState/EmptyState.tsx
+++ b/packages/core/src/EmptyState/EmptyState.tsx
@@ -23,7 +23,7 @@ import {
typeScaleVars,
} from '../theme/tokens.stylex';
import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {isRenderable, mergeProps} from '../utils';
import {themeProps} from '../utils/themeProps';
const styles = stylex.create({
@@ -169,7 +169,7 @@ export function EmptyState({
className,
style,
)}>
- {icon != null && <div aria-hidden="true">{icon}</div>}
+ {isRenderable(icon) && <div aria-hidden="true">{icon}</div>}
<div {...stylex.props(styles.textGroup)}>
{createElement(
HeadingTag,
@@ -181,11 +181,7 @@ export function EmptyState({
),
title,
)}
- {description != null && (
- // Rendered as <div> (not <p>): description accepts ReactNode and a
- // <p> cannot legally contain block children, which causes hydration
- // mismatches. The StyleX style sets margin: 0, so appearance is
- // unchanged.
+ {isRenderable(description) && (
<div
{...mergeProps(
themeProps('empty-state-description', {
@@ -200,7 +196,7 @@ export function EmptyState({
</div>
)}
</div>
- {actions != null && (
+ {isRenderable(actions) && (
<div
{...stylex.props(styles.actions, isCompact && styles.actionsCompact)}>
{actions}