Skip to content

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

TypeScript

Improve EmptyState docs page and block examples (#1579)

rubyycheung3eec2257f445
diff --git a/packages/cli/templates/blocks/components/EmptyState/EmptyStateActions.doc.mjs b/packages/cli/templates/blocks/components/EmptyState/EmptyStateActions.doc.mjs
new file mode 100644
index 0000000000..797182e242
--- /dev/null
+++ b/packages/cli/templates/blocks/components/EmptyState/EmptyStateActions.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'EmptyState — Actions',
+ description:
+ 'Full empty state with icon, message, and action buttons. Use when a search returns no results, a filter clears all items, or a list has been emptied. The buttons give the user a way forward — go back, clear filters, or try a different query.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['EmptyState', 'Button', 'Icon'],
+};
diff --git a/packages/cli/templates/blocks/components/EmptyState/EmptyStateWithActions.tsx b/packages/cli/templates/blocks/components/EmptyState/EmptyStateActions.tsx
similarity index 53%
rename from packages/cli/templates/blocks/components/EmptyState/EmptyStateWithActions.tsx
rename to packages/cli/templates/blocks/components/EmptyState/EmptyStateActions.tsx
index 62df593c4b..5e0220c01d 100644
--- a/packages/cli/templates/blocks/components/EmptyState/EmptyStateWithActions.tsx
+++ b/packages/cli/templates/blocks/components/EmptyState/EmptyStateActions.tsx
@@ -2,13 +2,15 @@
import {XDSEmptyState} from '@xds/core/EmptyState';
import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {MagnifyingGlassIcon} from '@heroicons/react/24/outline';
-export default function EmptyStateWithActions() {
+export default function EmptyStateActions() {
return (
<XDSEmptyState
- icon={<span style={{fontSize: '48px'}}>🔍</span>}
+ icon={<XDSIcon icon={MagnifyingGlassIcon} size="lg" />}
title="No results found"
- description="Try adjusting your search or filters."
+ description="Try adjusting your search terms or clearing filters to see more results."
actions={
<>
<XDSButton label="Go back" variant="secondary" />
diff --git a/packages/cli/templates/blocks/components/EmptyState/EmptyStateCompact.doc.mjs b/packages/cli/templates/blocks/components/EmptyState/EmptyStateCompact.doc.mjs
index afe19425d4..175e6bcb30 100644
--- a/packages/cli/templates/blocks/components/EmptyState/EmptyStateCompact.doc.mjs
+++ b/packages/cli/templates/blocks/components/EmptyState/EmptyStateCompact.doc.mjs
@@ -3,8 +3,8 @@ export const doc = {
type: 'block',
name: 'EmptyState — Compact',
description:
- 'Compact empty state with reduced spacing and action buttons for inline use',
+ 'Smaller empty state with reduced spacing for constrained areas. Use inside sidebar panels, card widgets, or notification drawers where a full-size empty state would overwhelm the layout.',
isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['EmptyState', 'Button'],
+ aspectRatio: 16 / 9,
+ componentsUsed: ['EmptyState', 'Button', 'Layout', 'Icon'],
};
diff --git a/packages/cli/templates/blocks/components/EmptyState/EmptyStateCompact.tsx b/packages/cli/templates/blocks/components/EmptyState/EmptyStateCompact.tsx
index 52ad40e133..8f09d76f22 100644
--- a/packages/cli/templates/blocks/components/EmptyState/EmptyStateCompact.tsx
+++ b/packages/cli/templates/blocks/components/EmptyState/EmptyStateCompact.tsx
@@ -2,17 +2,21 @@
import {XDSEmptyState} from '@xds/core/EmptyState';
import {XDSButton} from '@xds/core/Button';
+import {XDSHStack} from '@xds/core/Layout';
+import {XDSIcon} from '@xds/core/Icon';
+import {InboxIcon} from '@heroicons/react/24/outline';
export default function EmptyStateCompact() {
return (
<XDSEmptyState
- title="No data"
- description="Add some data to get started."
+ icon={<XDSIcon icon={InboxIcon} size="lg" />}
+ title="No notifications"
+ description="You're all caught up. New notifications will appear here."
actions={
- <>
- <XDSButton label="Import" variant="secondary" />
- <XDSButton label="Add item" variant="primary" />
- </>
+ <XDSHStack gap={2}>
+ <XDSButton label="Settings" variant="secondary" size="sm" />
+ <XDSButton label="Refresh" variant="primary" size="sm" />
+ </XDSHStack>
}
isCompact
/>
diff --git a/packages/cli/templates/blocks/components/EmptyState/EmptyStateContainer.doc.mjs b/packages/cli/templates/blocks/components/EmptyState/EmptyStateContainer.doc.mjs
new file mode 100644
index 0000000000..8f215f46a5
--- /dev/null
+++ b/packages/cli/templates/blocks/components/EmptyState/EmptyStateContainer.doc.mjs
@@ -0,0 +1,10 @@
+/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ name: 'EmptyState — Container',
+ description:
+ 'Empty state wrapped in a Card for first-time setup or onboarding. Use when the user has not created any items yet — like a project list, team roster, or dashboard widget that will fill with data once they take action.',
+ isReady: true,
+ aspectRatio: 16 / 9,
+ componentsUsed: ['EmptyState', 'Button', 'Card', 'Icon'],
+};
diff --git a/packages/cli/templates/blocks/components/EmptyState/EmptyStateContainer.tsx b/packages/cli/templates/blocks/components/EmptyState/EmptyStateContainer.tsx
new file mode 100644
index 0000000000..1ae8cc1eb8
--- /dev/null
+++ b/packages/cli/templates/blocks/components/EmptyState/EmptyStateContainer.tsx
@@ -0,0 +1,25 @@
+'use client';
+
+import {XDSEmptyState} from '@xds/core/EmptyState';
+import {XDSButton} from '@xds/core/Button';
+import {XDSCard} from '@xds/core/Card';
+import {XDSIcon} from '@xds/core/Icon';
+import {FolderPlusIcon} from '@heroicons/react/24/outline';
+
+export default function EmptyStateContainer() {
+ return (
+ <XDSCard>
+ <XDSEmptyState
+ icon={<XDSIcon icon={FolderPlusIcon} size="lg" />}
+ title="No projects yet"
+ description="Create your first project to start organizing your work. You can invite team members after."
+ actions={
+ <>
+ <XDSButton label="Import" variant="secondary" />
+ <XDSButton label="Create project" variant="primary" />
+ </>
+ }
+ />
+ </XDSCard>
+ );
+}
diff --git a/packages/cli/templates/blocks/components/EmptyState/EmptyStateFullExample.doc.mjs b/packages/cli/templates/blocks/components/EmptyState/EmptyStateFullExample.doc.mjs
deleted file mode 100644
index 019fdbee50..0000000000
--- a/packages/cli/templates/blocks/components/EmptyState/EmptyStateFullExample.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'EmptyState — Notifications Panel',
- description:
- 'Full empty state with icon, description, and actions inside a bordered container',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['EmptyState', 'Button'],
-};
diff --git a/packages/cli/templates/blocks/components/EmptyState/EmptyStateFullExample.tsx b/packages/cli/templates/blocks/components/EmptyState/EmptyStateFullExample.tsx
deleted file mode 100644
index d72413bc7e..0000000000
--- a/packages/cli/templates/blocks/components/EmptyState/EmptyStateFullExample.tsx
+++ /dev/null
@@ -1,27 +0,0 @@
-'use client';
-
-import {XDSEmptyState} from '@xds/core/EmptyState';
-import {XDSButton} from '@xds/core/Button';
-
-export default function EmptyStateFullExample() {
- return (
- <div
- style={{
- border: '1px dashed #ccc',
- borderRadius: 12,
- maxWidth: 480,
- }}>
- <XDSEmptyState
- icon={<span style={{fontSize: '48px'}}>📬</span>}
- title="No notifications"
- description="When you receive notifications, they will appear here. Check back later!"
- actions={
- <>
- <XDSButton label="Settings" variant="secondary" />
- <XDSButton label="Refresh" variant="primary" />
- </>
- }
- />
- </div>
- );
-}
diff --git a/packages/cli/templates/blocks/components/EmptyState/EmptyStateWithActions.doc.mjs b/packages/cli/templates/blocks/components/EmptyState/EmptyStateWithActions.doc.mjs
deleted file mode 100644
index df6cf7c2b7..0000000000
--- a/packages/cli/templates/blocks/components/EmptyState/EmptyStateWithActions.doc.mjs
+++ /dev/null
@@ -1,10 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'EmptyState — With Actions',
- description:
- 'Empty state with action buttons for navigation or clearing filters',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['EmptyState', 'Button'],
-};
diff --git a/packages/cli/templates/blocks/components/EmptyState/EmptyStateWithIcon.doc.mjs b/packages/cli/templates/blocks/components/EmptyState/EmptyStateWithIcon.doc.mjs
deleted file mode 100644
index 16fdba1c60..0000000000
--- a/packages/cli/templates/blocks/components/EmptyState/EmptyStateWithIcon.doc.mjs
+++ /dev/null
@@ -1,9 +0,0 @@
-/** @type {import('../../../../../core/src/docs-types').TemplateDoc} */
-export const doc = {
- type: 'block',
- name: 'EmptyState — With Icon',
- description: 'Empty state with an emoji icon for visual context',
- isReady: true,
- aspectRatio: 4 / 3,
- componentsUsed: ['EmptyState'],
-};
diff --git a/packages/cli/templates/blocks/components/EmptyState/EmptyStateWithIcon.tsx b/packages/cli/templates/blocks/components/EmptyState/EmptyStateWithIcon.tsx
deleted file mode 100644
index e62fbe9b42..0000000000
--- a/packages/cli/templates/blocks/components/EmptyState/EmptyStateWithIcon.tsx
+++ /dev/null
@@ -1,13 +0,0 @@
-'use client';
-
-import {XDSEmptyState} from '@xds/core/EmptyState';
-
-export default function EmptyStateWithIcon() {
- return (
- <XDSEmptyState
- icon={<span style={{fontSize: '48px'}}>📭</span>}
- title="No messages"
- description="You're all caught up!"
- />
- );
-}
diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjs
index c6d66cdd55..0549754b76 100644
--- a/packages/core/src/EmptyState/EmptyState.doc.mjs
+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs
@@ -56,18 +56,20 @@ export const docs = {
],
},
usage: {
- description: 'An empty state placeholder that provides guidance when there is no data to display. Use for null states, failed loading states, or when search and filter results return nothing. Always include a clear message and a call to action so users know how to proceed.',
+ description: 'EmptyState shows a placeholder when a content area has no data. Use it for empty lists, zero search results, first-time setups, or cleared inboxes. Always include a title and a next step so the user is not stuck.',
bestPractices: [
{ guidance: true, description: 'Include a clear title and a call-to-action button so users know how to proceed.' },
{ guidance: true, description: 'Use an illustration or icon that reinforces the context of the empty state.' },
+ { guidance: true, description: 'Use the compact variant inside cards or sidebars where space is limited.' },
{ guidance: false, description: 'Leave an empty state without guidance — always explain what happened and what the user can do next.' },
- { guidance: false, description: 'Use an EmptyState for error messages that require immediate action — use an alert instead.' },
+ { guidance: false, description: 'Use a generic message like "No data" — be specific about what is empty and why.' },
+ { guidance: false, description: 'Use an EmptyState for error messages that require immediate action — use a Banner instead.' },
],
anatomy: [
- {name: 'Illustration', required: false, description: 'Visual cue that reinforces the empty state context.'},
- {name: 'Title', required: true, description: 'Primary message explaining the empty state.'},
- {name: 'Subtitle', required: false, description: 'Additional context or explanation.'},
- {name: 'Call to action', required: false, description: 'Buttons guiding the user to a next step.'},
+ {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.'},
+ {name: 'Actions', required: false, description: 'One or two buttons guiding the user to a next step, like "Create project" or "Clear filters".'},
],
},
};
@@ -128,18 +130,14 @@ export const docsZh = {
],
},
usage: {
- description: 'An empty state placeholder that provides guidance when there is no data to display. Use for null states, failed loading states, or when search and filter results return nothing. Always include a clear message and a call to action so users know how to proceed.',
+ description: 'EmptyState shows a placeholder when a content area has no data. Use it for empty lists, zero search results, first-time setups, or cleared inboxes. Always include a title and a next step so the user is not stuck.',
bestPractices: [
{ guidance: true, description: 'Include a clear title and a call-to-action button so users know how to proceed.' },
{ guidance: true, description: 'Use an illustration or icon that reinforces the context of the empty state.' },
+ { guidance: true, description: 'Use the compact variant inside cards or sidebars where space is limited.' },
{ guidance: false, description: 'Leave an empty state without guidance — always explain what happened and what the user can do next.' },
- { guidance: false, description: 'Use an EmptyState for error messages that require immediate action — use an alert instead.' },
- ],
- anatomy: [
- {name: 'Illustration', required: false, description: 'Visual cue that reinforces the empty state context.'},
- {name: 'Title', required: true, description: 'Primary message explaining the empty state.'},
- {name: 'Subtitle', required: false, description: 'Additional context or explanation.'},
- {name: 'Call to action', required: false, description: 'Buttons guiding the user to a next step.'},
+ { guidance: false, description: 'Use a generic message like "No data" — be specific about what is empty and why.' },
+ { guidance: false, description: 'Use an EmptyState for error messages that require immediate action — use a Banner instead.' },
],
},
};
@@ -147,20 +145,12 @@ export const docsZh = {
/** @type {import('../docs-types').TranslationDoc} */
export const docsDense = {
description:
- 'Empty state placeholder for content areas w/ no data. Displays icon/illustration, title, optional description + action buttons.',
+ 'placeholder when a content area has no data — icon, title, description, action buttons',
usage: {
- description: 'An empty state placeholder that provides guidance when there is no data to display. Use for null states, failed loading states, or when search and filter results return nothing. Always include a clear message and a call to action so users know how to proceed.',
+ description: 'EmptyState shows a placeholder for empty lists, zero search results, first-time setups. Always include a title and next step.',
bestPractices: [
- { guidance: true, description: 'Include a clear title and a call-to-action button so users know how to proceed.' },
- { guidance: true, description: 'Use an illustration or icon that reinforces the context of the empty state.' },
- { guidance: false, description: 'Leave an empty state without guidance — always explain what happened and what the user can do next.' },
- { guidance: false, description: 'Use an EmptyState for error messages that require immediate action — use an alert instead.' },
- ],
- anatomy: [
- {name: 'Illustration', required: false, description: 'Visual cue that reinforces the empty state context.'},
- {name: 'Title', required: true, description: 'Primary message explaining the empty state.'},
- {name: 'Subtitle', required: false, description: 'Additional context or explanation.'},
- {name: 'Call to action', required: false, description: 'Buttons guiding the user to a next step.'},
+ { guidance: true, description: 'Clear title + CTA button. Icon for context. Compact variant in tight spaces.' },
+ { guidance: false, description: 'No generic "No data" — be specific. Not for errors — use Banner.' },
],
},
propDescriptions: {