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"