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.mjsnew file mode 100644index 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.tsxsimilarity index 53%rename from packages/cli/templates/blocks/components/EmptyState/EmptyStateWithActions.tsxrename to packages/cli/templates/blocks/components/EmptyState/EmptyStateActions.tsxindex 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.mjsindex 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.tsxindex 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsdeleted file mode 100644index 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.mjsdeleted file mode 100644index 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.tsxdeleted file mode 100644index 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.mjsindex 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: {