Dashboard design

Dashboard & Web App Design

Ship product UI that looks deliberate instead of generated. This skill covers the logged-in surface — dashboards, admin panels, SaaS product screens. For the marketing site, use landing-page-design.

Polish is what happens when persistence and taste meet the science of design. Agents have no eyes. You can only compensate with a checklist and a screenshot.

When to use which mode

Situation	Mode
New page or flow from scratch	Build — run the pipeline below in order
Existing UI feels off, generic, vibe-coded	Audit — go straight to references/audit-checklist.md
One narrow question (color? table? chart?)	Read the matching reference file only

What makes product UI different

Dashboards are not landing pages, and treating them the same is a common failure:

• Type scale is compressed — rarely anything above 24px, with small steps between sizes, because information density is high
• Grids are followed strictly, because you're using most or all of the available space
• Color comes from the data, not from decoration
• Motion is tame and user-focused compared to marketing sites
• Most of the functionality is not visible at rest

Build pipeline

Run in order. Most bad product UI is a structure problem wearing a color problem's clothes — do not start with the palette.

1. Intent before interface

What goes in the main area reflects what matters most to the user. A project management tool leads with project status. A financial tool leads with investments. If you can't say what belongs at the top, you don't yet understand the user.

Do one thing well. If your dashboard looks like it requires a PhD to operate, it's too complex. The failure mode looks like someone emptied a drawer onto the screen.

2. Structure

The sidebar is the spine of the product — it houses the persistent, globally relevant elements: navigation, profile management, search. Group links by relevance, push rarely-used items (settings, help) to the bottom, give the active item a real indicator, nest into dropdowns as the list grows.

Then lay out the page on a strict, simple grid. A two-column, two-row grid handles most dashboard homepages. See references/dashboard.md for full anatomy.

3. Let the data drive the form

This is the tell that separates people who have built a dashboard from people who have drawn one.

• Fixed set of values → chips, not plain text
• Numbers → right-aligned, so digits line up by place value
• Long text → truncated, to give breathing room to other columns
• Inactive rows → shaded out
• Time-delineated data → a timeline, not a time-sorted table

If the data has a shape, the UI should have that shape. Don't force everything into a table because a table is easy.

Color follows the same logic: a red icon in a chip because the action is urgent. An avatar because the eye matches a face faster than it reads a name in a column.

4. Type and space

• One sans-serif family. You will essentially never need a second.
• Compressed scale — small sizes, small steps. Compare to a landing page's tiles and you should see a clear difference.
• Large headings: letter-spacing -2% to -3%, line-height 110–120%.
• Space on a 4pt grid — everything stays halvable, which produces consistency.
• Group related items tightly; separate groups generously.

Full detail in references/foundations.md.

5. Color

Never accept a model's first palette — they trend bright, saturated and mutually hostile. Build four layers in order: neutral foundation → functional accent → semantic → theming. See references/color.md.

The rules that catch the most damage:

• Backgrounds stay in the background. Neutral, never a bright gradient.
• Icons need no color. Color is reserved for communicating status.
• Borders are light gray (~85% white), not black.
• Text uses grays — headings ~11%, body 15–20%, subtext 30–40% white.
• The more important a button is, the darker it is.
• Dark mode is not inverted light mode. Neutral steps need roughly double the distance (4–6% vs 2%), and surfaces get lighter as they elevate.

6. Choose the right container

Getting this wrong is a structural error no amount of styling fixes:

Container	Use when	Properties
Popover	Context is simple — display settings, a filter	Non-blocking; user can click away with no consequence
Modal	Context is complex but related to what's on screen — creating a record	Blocking; needs explicit confirm/cancel; follow with a toast since the user couldn't see the page
New page	Context is permanent or large — a detail view	Requires a back button or breadcrumb

7. States — the actual product

Designing only the happy path is what separates a mockup from a product.

Every button: default, hover, active, disabled, plus loading where the action hits the network. Inputs additionally need focus and error with a message.

Every view needs its empty states — and there are two different kinds, first-run and no-results, with different designs. Plus toasts for anything that happens behind a modal. See references/states-feedback.md.

8. Progressive disclosure and invisible UI

Show what's needed, reveal more as it becomes relevant. You aren't hiding functionality — you're sequencing it.

Every action sits on a spectrum of explicitness, from a global always-visible labeled button down to an icon that appears on hover. Place each one deliberately.

A large fraction of a working dashboard is UI you can't immediately see — hover actions, tooltips, copy affordances, comment indicators, overflow menus, bulk action bars. It is not a small amount, and the visible part doesn't function without it. This is the thing generated dashboards miss most completely.

9. Audit before you call it done

Run references/audit-checklist.md. If you can render or screenshot the page, look at it — balance, whitespace and unity cannot be evaluated from source code.

Hard rules

Only five things are worth refusing to negotiate. Everything else in this skill is guidance — apply judgement.

1. Destructive is red. Even when red is nowhere in the brand palette. A delete button in your brand color is a usability failure, not a brand win.
2. Numbers right-align. Enums become chips.
3. Every chart needs axes, gridlines and numbers. No rounded bar tops that obscure the value; the bar count must match the period shown.
4. Never ship a view without its empty and loading states.
5. No emoji as interface icons. Use a real set (Phosphor, Lucide, Heroicons) at one consistent stroke weight.

The critique vocabulary

Grade any screenshot against these eight — the ingredients of "I know it when I see it". Detailed treatment in references/foundations.md, applied rubric in references/audit-checklist.md.

Principle	Failing looks like
Contrast	No obvious focal point; everything competes equally
Hierarchy	Wordmark, section labels and card titles fight for the same attention
Alignment	Elements don't share edges or axes
Proximity	Related things not grouped; unrelated things jammed together
Repetition	Three type weights, two icon styles, four corner radii
Balance	Bottom-heavy or lopsided; one dense block dominates
Whitespace	Every pixel working; nothing breathes
Unity	Reads as a template with content poured in

Unity is what emerges when the other seven agree. If a page reads as generic, one of them is failing — find which.

Treat generated UI as a base to build on, never as the deliverable. The place where the least effort produces the biggest change is layout and cards — models are consistently weak at composing them. The 30-second tell list lives at the top of references/audit-checklist.md.

Design systems

A design system is how users build trust and speed with a product — not an aesthetic exercise.

• It is not about having hundreds of components. It's about making a decision you can stick to.
• The process of defining the rules — spacing, type scales, interaction patterns — is often more valuable than the visual output, because it gives you an architecture for expansion.
• Match the system to the team. A lean startup needs something lightweight and easy to scrap. Material Design is enormous because it spans dozens of products and billions of users. Copying that weight into a five-person team is waste.
• It isn't about making everything look the same — it's a shared language. And like any language, mastery means knowing when to bend it. You don't break the system by accident; you break it with intention.

The payoff compounds: once buttons, spacing, type and color are decided, every new screen is mostly assembly, and each one feels familiar even when the content is completely different.

Reference files

• references/foundations.md — the eight principles, hierarchy, spacing, type, icons, shadows, signifiers
• references/color.md — the four-layer color system, dark mode, semantic color, OKLCH for charts and theming
• references/dashboard.md — sidebar, page anatomy, tables, charts, the four components, containers, progressive disclosure, invisible UI
• references/states-feedback.md — element states, empty states, loading, errors, toasts, onboarding, optimistic UI, flows
• references/reference-ui.html — a working dashboard implementing the system (color ramps, table, chart, states, components). Open it when you need concrete structure rather than description
• references/audit-checklist.md — the full review rubric, including the 30-second tell list