MissingEmptyState [anti-pattern] v1.0.0

Rendering an empty container — a blank table, an unstyled <div>, or just the page chrome with nothing inside — when a list, search, or workspace returns zero items. The user is left wondering whether the page failed, the filter excluded everything, or the feature is broken.

Label

Blank Screen When Data Is Empty

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Trap

During development, the engineer is always working with seeded data and never sees the empty state. The first-render-empty case is hidden until a real user with no items arrives. AI agents writing list components routinely skip the data.length === 0 branch entirely because the prompt asked for 'a list of issues' and didn't specify zero-state.

Counter Examples

• @community/counter-example-empty-list-blank

Detection Heuristics

• List/table component renders only data.map(...) with no data.length === 0 check
• JSX has {items.length > 0 && <List items={items} />} but no else branch
• Empty container has no role='status' or aria announcement for screen readers
• First-run user lands on a blank page with no orientation or CTA
• Filter UI removes all results and leaves a silent blank area where the table was

Remediation

• Add a zero-state branch to every list/table component before merging.
• Differentiate three empty types: (1) zero-data first-run, (2) zero-results filter active, (3) zero-permission access denied.
• Use @community/pattern-empty-state — illustration + headline + body + CTA.
• First-run empty states get a CTA to create the first item; filter-empty get a 'Clear filter' button.
• Use @impeccable/template-empty-state as the canonical implementation.

Severity

high

MissingEmptyState [anti-pattern] v1.0.0

Rendering an empty container — a blank table, an unstyled <div>, or just the page chrome with nothing inside — when a list, search, or workspace returns zero items. The user is left wondering whether the page failed, the filter excluded everything, or the feature is broken.

Label

Blank Screen When Data Is Empty

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Trap

During development, the engineer is always working with seeded data and never sees the empty state. The first-render-empty case is hidden until a real user with no items arrives. AI agents writing list components routinely skip the data.length === 0 branch entirely because the prompt asked for 'a list of issues' and didn't specify zero-state.

Counter Examples

• @community/counter-example-empty-list-blank

Detection Heuristics

• List/table component renders only data.map(...) with no data.length === 0 check
• JSX has {items.length > 0 && <List items={items} />} but no else branch
• Empty container has no role='status' or aria announcement for screen readers
• First-run user lands on a blank page with no orientation or CTA
• Filter UI removes all results and leaves a silent blank area where the table was

Remediation

• Add a zero-state branch to every list/table component before merging.
• Differentiate three empty types: (1) zero-data first-run, (2) zero-results filter active, (3) zero-permission access denied.
• Use @community/pattern-empty-state — illustration + headline + body + CTA.
• First-run empty states get a CTA to create the first item; filter-empty get a 'Clear filter' button.
• Use @impeccable/template-empty-state as the canonical implementation.

Severity

high

Relations

related: [@community/counter-example-empty-list-blank, @community/pattern-empty-state, @impeccable/template-empty-state]

Label

Blank Screen When Data Is Empty

Meta

• License: Apache-2.0
• License Provenance: package-authorship-claim

Trap

During development, the engineer is always working with seeded data and never sees the empty state. The first-render-empty case is hidden until a real user with no items arrives. AI agents writing list components routinely skip the data.length === 0 branch entirely because the prompt asked for 'a list of issues' and didn't specify zero-state.

Counter Examples

• @community/counter-example-empty-list-blank

Detection Heuristics

• List/table component renders only data.map(...) with no data.length === 0 check
• JSX has {items.length > 0 && <List items={items} />} but no else branch
• Empty container has no role='status' or aria announcement for screen readers
• First-run user lands on a blank page with no orientation or CTA
• Filter UI removes all results and leaves a silent blank area where the table was

Remediation

• Add a zero-state branch to every list/table component before merging.
• Differentiate three empty types: (1) zero-data first-run, (2) zero-results filter active, (3) zero-permission access denied.
• Use @community/pattern-empty-state — illustration + headline + body + CTA.
• First-run empty states get a CTA to create the first item; filter-empty get a 'Clear filter' button.
• Use @impeccable/template-empty-state as the canonical implementation.

Severity

high