# EmptyState A calm full-region placeholder that centers a title, optional description, icon, and recovery action when an area has nothing to show. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: source-derived Source: packages/design-system/src/components/status/EmptyState/EmptyState.tsx ## Guidance { "summary": "A calm full-region placeholder that centers a title, optional description, icon, and recovery action when an area has nothing to show.", "guidance": [ { "heading": "Overview", "body": "A full-region placeholder for when a whole area has nothing to show — a title, optional description\nand icon, and an optional recovery `action`." }, { "heading": "When to use", "body": "Reach for `EmptyState` when an entire region is empty and you want to explain why and offer a way\nforward — a cleared queue, a search with no hits, a list before its first item. Pass an `action`\n(usually a `Button`) when there's a recovery path.\n\n- Content IS present and you're annotating it (a note or warning alongside real data)? Use `Banner`.\n- The region isn't empty, it's still loading? Use `Skeleton` to preserve the layout while it loads." } ], "usage": [], "examples": [], "source": "packages/design-system/src/components/status/EmptyState/EmptyState.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." } ## Contract and public API ```json { "props": [ { "name": "title", "type": "string", "declared_type": "string", "required": true, "description": "Headline naming what is missing. Renders as an `h3`.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 14 } }, { "name": "description", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "Optional supporting line beneath the title.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 16 } }, { "name": "icon", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "Optional visual shown above the title.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 18 } }, { "name": "action", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "Optional action slot, usually a Button.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 20 } }, { "name": "align", "type": "EmptyStateAlign | undefined", "declared_type": "EmptyStateAlign", "required": false, "description": "Text alignment and horizontal placement of the block. Defaults to `center`.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 22 }, "values": [ "center", "start" ], "values_complete": true, "default": "'center'", "default_kind": "source-expression" }, { "name": "padding", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Outer padding token. Defaults to `32`.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 24 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true, "default": "32", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 25 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 26 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 28 } } ], "prop_shapes": {}, "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "EmptyState", "public_path": "EmptyState", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "EmptyState", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 35 }, "props_type": "EmptyStateProps", "props": [ { "name": "title", "type": "string", "declared_type": "string", "required": true, "description": "Headline naming what is missing. Renders as an `h3`.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 14 } }, { "name": "description", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "Optional supporting line beneath the title.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 16 } }, { "name": "icon", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "Optional visual shown above the title.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 18 } }, { "name": "action", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": false, "description": "Optional action slot, usually a Button.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 20 } }, { "name": "align", "type": "EmptyStateAlign | undefined", "declared_type": "EmptyStateAlign", "required": false, "description": "Text alignment and horizontal placement of the block. Defaults to `center`.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 22 }, "values": [ "center", "start" ], "values_complete": true, "default": "'center'", "default_kind": "source-expression" }, { "name": "padding", "type": "0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48 | 56 | 64 | 72 | 80 | 96 | 120 | 240 | undefined", "declared_type": "CdsSpace", "required": false, "description": "Outer padding token. Defaults to `32`.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 24 }, "values": [ 0, 12, 120, 16, 20, 24, 240, 32, 4, 40, 48, 56, 64, 72, 8, 80, 96 ], "values_complete": true, "default": "32", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 25 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 26 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector.", "source": { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 28 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 7, "name": "EmptyStateAlign", "code": "export type EmptyStateAlign = 'center' | 'start';" }, { "path": "packages/design-system/src/components/status/EmptyState/EmptyState.tsx", "line": 12, "name": "EmptyStateProps", "code": "export interface EmptyStateProps {\n /** Headline naming what is missing. Renders as an `h3`. */\n title: string;\n /** Optional supporting line beneath the title. */\n description?: React.ReactNode;\n /** Optional visual shown above the title. */\n icon?: React.ReactNode;\n /** Optional action slot, usually a Button. */\n action?: React.ReactNode;\n /** Text alignment and horizontal placement of the block. Defaults to `center`. */\n align?: EmptyStateAlign;\n /** Outer padding token. Defaults to `32`. */\n padding?: CdsSpace;\n className?: string;\n style?: React.CSSProperties;\n /** Optional test selector. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/tokens/CdsSpace.ts", "line": 8, "name": "PUI_SPACES", "code": "PUI_SPACES = [0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64, 72, 80, 96, 120, 240] as const" }, { "path": "packages/design-system/src/tokens/CdsSpace.ts", "line": 13, "name": "CdsSpace", "code": "export type CdsSpace = (typeof PUI_SPACES)[number];" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "EmptyState", "status": "preview", "version": "1.0.0", "summary": "A calm full-region placeholder that centers a title, optional description, icon, and recovery action when an area has nothing to show." }, "parts": [ { "id": "root", "label": "Root", "description": "Column that stacks the icon, copy, and action with outer padding.", "required": true }, { "id": "icon", "label": "Icon", "description": "Optional round visual above the title." }, { "id": "copy", "label": "Copy", "description": "Title plus optional description." }, { "id": "action", "label": "Action", "description": "Optional recovery control, usually a Button." } ], "allowedDesignChoices": { "variants": { "placeholder": { "label": "Placeholder", "description": "The single empty/no-results treatment." } }, "sizes": {}, "alignments": { "center": { "label": "Center", "description": "Centers the block and its text." }, "start": { "label": "Start", "description": "Left-aligns the block and its text inside a panel." } } }, "variants": [ { "id": "placeholder", "label": "Placeholder", "description": "Centered empty-region treatment.", "platforms": [ "ios", "android", "web" ] } ], "sizes": [], "measurements": [ { "id": "content-gap", "label": "Content gap", "kind": "exact", "token": "--cds-space-16", "value": 16, "unit": "px", "appliesTo": [ "root" ] }, { "id": "icon-size", "label": "Icon container size", "kind": "exact", "token": "--cds-size-56", "value": 56, "unit": "px", "appliesTo": [ "icon" ] }, { "id": "default-padding", "label": "Default outer padding", "kind": "exact", "token": "--cds-space-32", "value": 32, "unit": "px", "appliesTo": [ "root" ], "notes": "The padding prop selects a spacing step; 32 is the default." } ], "layout": { "alignment": "Icon, copy, and action stack vertically; alignment controls horizontal placement and text alignment.", "flow": "A single column with a max-width copy block capped at 320.", "notes": [ "Use Banner to annotate content that is present rather than a whole empty region." ] }, "typographyAndColor": { "typography": [ { "label": "Title", "description": "Uses the h4 ramp.", "token": "--cds-type-h4-size" }, { "label": "Description", "description": "Uses the body ramp.", "token": "--cds-type-body-size" } ], "colors": [ { "label": "Title", "description": "Primary text for the title.", "token": "--cds-text-primary" }, { "label": "Description", "description": "Secondary text for supporting copy and the icon.", "token": "--cds-text-secondary" }, { "label": "Icon surface", "description": "The icon sits on a raised surface disc.", "token": "--cds-bg-surface" } ] }, "states": [ { "id": "center", "label": "Centered", "description": "Content centered on both the horizontal axis and text." }, { "id": "start", "label": "Start aligned", "description": "Content left-aligned inside a panel." }, { "id": "with-icon", "label": "With icon", "description": "Shows the round icon disc above the title." }, { "id": "with-action", "label": "With action", "description": "Shows a recovery action below the copy." } ], "behavior": [ { "label": "Alignment", "description": "Set align to center for standalone screens or start for in-panel placeholders." }, { "label": "Recovery action", "description": "Offer an action only when the user can meaningfully resolve the empty state." } ], "accessibility": [ { "label": "Heading", "description": "The title renders as a heading so the empty region is announced." }, { "label": "Actionable copy", "description": "Describe the next step in the description rather than relying on the icon." } ], "contentAdaptation": [ { "label": "Copy width", "description": "The copy column caps its width so long descriptions stay readable." }, { "label": "Optional slots", "description": "Icon, description, and action each render only when provided." } ], "motionHaptics": { "motion": [ { "label": "Static", "description": "EmptyState does not animate on appearance." } ], "haptics": [ { "label": "No feedback", "description": "The container requests no haptics; its action button owns any feedback." } ] }, "platformDifferences": [] }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "tokens": [ { "name": "--cds-space-16", "light": "16px", "dark": "16px" }, { "name": "--cds-size-56", "light": "56px", "dark": "56px" }, { "name": "--cds-space-32", "light": "32px", "dark": "32px" }, { "name": "--cds-type-h4-size", "light": "1.25rem", "dark": "1.25rem" }, { "name": "--cds-type-body-size", "light": "1rem", "dark": "1rem" }, { "name": "--cds-text-primary", "light": "#141410", "dark": "#f3f1ed" }, { "name": "--cds-text-secondary", "light": "#646260", "dark": "#ffffff99" }, { "name": "--cds-bg-surface", "light": "#ffffff", "dark": "#1b1b18" } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ] } ``` ## Visual states - [Playground](/storybook/iframe.html?id=cloaked-design-system-status-emptystate--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/status/EmptyState/EmptyState.stories.tsx - [Default](/storybook/iframe.html?id=cloaked-design-system-status-emptystate--default&viewMode=story) | export: Default | source: packages/design-system/src/components/status/EmptyState/EmptyState.stories.tsx - [With Icon](/storybook/iframe.html?id=cloaked-design-system-status-emptystate--with-icon&viewMode=story) | export: WithIcon | source: packages/design-system/src/components/status/EmptyState/EmptyState.stories.tsx - [With Action](/storybook/iframe.html?id=cloaked-design-system-status-emptystate--with-action&viewMode=story) | export: WithAction | source: packages/design-system/src/components/status/EmptyState/EmptyState.stories.tsx - [Start Aligned](/storybook/iframe.html?id=cloaked-design-system-status-emptystate--start-aligned&viewMode=story) | export: StartAligned | source: packages/design-system/src/components/status/EmptyState/EmptyState.stories.tsx - [Padded](/storybook/iframe.html?id=cloaked-design-system-status-emptystate--padded&viewMode=story) | export: Padded | source: packages/design-system/src/components/status/EmptyState/EmptyState.stories.tsx - [Long Content](/storybook/iframe.html?id=cloaked-design-system-status-emptystate--long-content&viewMode=story) | export: LongContent | source: packages/design-system/src/components/status/EmptyState/EmptyState.stories.tsx - [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-status-emptystate--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/status/EmptyState/EmptyState.stories.tsx Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.