Build Assets
UI Component
Empty State
Designed placeholder when a list, table, or view has no content yet.
Platform: bothTags: empty-state, zero-state, onboarding, first-use
Purpose
Replaces a blank area when there is no content. Explains why the area is empty and gives users a clear path forward. First-time users see this on every new feature.
Anatomy
- Optional illustration: 80–120px, simple and on-brand (not generic stock)
- Heading: 16–18px semibold - states the condition, not the error
- Body: 14px secondary color - explains why + what to do
- Primary action: button leading to the first step
- Optional secondary link: docs or learn more
States
- First-use: user has never added content - focus on value promise
- No results: filtered/searched view returned nothing - show clear filter path
- Error: failed to load - show retry action
- Permissions: user lacks access - explain and link to request
Tokens
spacing
padding: 48px 24pxgap: 12pxillustrationGap: 20px
sizing
maxWidth: 360pxillustrationSize: 96px
Do
- Write the heading as a condition: "No projects yet" not "Error: no projects found"
- Make the primary action specific: "Create your first project" not "Add"
- Center-align the entire empty state within its container
- Vary the message between first-use and no-results states
Don't
- Leave any data view without a designed empty state
- Use generic "No data available" - explain the specific condition
- Make the empty state the same visual weight as content
- Show the empty state while data is still loading - use a skeleton
Accessibility
- Empty state should be announced to screen readers via aria-live when it appears dynamically
- Action button must have a descriptive label - not just "Add" or "Create"