building-product-empty-states

Create a setup detection logic with createSetupDetectionLogic, build a SceneProductEmptyState config in your product's emptyState directory, then declare emptyState on the scene's SceneExport. The app shell's ProductEmptyStateGate handles rendering, so the scene itself contains no empty-state branching.

Replace full-scene ProductIntroduction uses with the ProductEmptyState system by writing detection logic and a scene-level emptyState declaration. Entity-list empties map to entity-count detection with a primaryAction create button, and has_seen_product_intro_for dismissals are superseded by local skip.

It supports loading, unknown, needs-setup, waiting-for-data, and has-data. Detection logic must handle failure paths so a failing query never strands the status on loading; fail open to unknown so the gate renders the real scene.

Yes, skip is enabled by default and stored locally in localStorage keyed by team and product, never persisted to the backend. Creation-first products can set skippable: false on the config to remove the escape hatch.

Previews use hidden checkbox or radio inputs with :checked ~ selectors and CSS keyframes so interactions need no JS and ambient motion stays continuous. This keeps visual-regression snapshots stable and lets prefers-reduced-motion guard all animation.

Append ?empty_state=1 to the scene URL to force the setup screen, or ?empty_state=waiting-for-data for the middle mode. This overrides detection and local skip without requiring you to empty a project.