Source: https://www.hype-stack.dev/stacks/how-to-design-a-web-app

# How to Design a Web App: Pick a Shell, Then Design Three Screens

> Most of a web app is the same dozen screens every other app has. The design work that is yours is two or three of
> them, plus a short list of decisions that the rest inherit.

Search for how to design a web app and you get a process: discovery, personas, wireframes, mockups, a design system,
usability testing. It suits a team with a designer and a quarter to spend. For a founder or a developer working alone,
it describes months of work before the first screen exists, and it treats every screen as a blank page.

They are not blank pages. Sign in, a sidebar with navigation, a list, a detail view, a form, settings, an empty state,
an error state: users have met all of these hundreds of times and expect them to behave the way they did everywhere
else. For a first version, design is mostly choosing a shell and a set of tokens, then spending your real attention on
the screens no other product has.

One caveat. If the look is the product (a consumer app competing on feel, a brand-led marketing site) then hire a
designer and follow the long process. What follows is for apps people use to get work done.

## The decisions every screen inherits

Web app design goes wrong less often on individual screens than on the few choices made once and applied everywhere.
Make these first and write them down.

**Decide once**

- **The shell** Where navigation lives and what surrounds the content: a sidebar that collapses to icons, a top bar, a drawer on phones. A sidebar suits many destinations and long sessions, a top bar suits three or four. Changing it later touches every page.
- **Navigation depth** Count the levels. Two levels needs a rule for where the second one renders: nested under the parent, as tabs across the page, or in a second rail. Three is usually two products sharing one sidebar.
- **Density** A tool someone lives in all day wants compact rows and many records visible. A tool opened once a week wants room and larger targets. Pick one and hold it, because a dense table inside a spacious page reads as a bug.
- **Type** One typeface, two weights, and four or five sizes cover a whole application: body, metadata, page title, section title. Each size after that needs a reason.
- **Colour as roles, not values** Name colours by the job they do: background, card, border, primary, muted text, destructive. A button is 'primary', never a specific blue. This is what makes dark mode a second set of values instead of a second design.

_Each one is cheap on day one and expensive after thirty screens depend on the old answer._

## The states nobody draws

A mockup shows a screen with tidy sample data in it. A running app spends much of its life in other conditions, and each
one is a design decision whether or not anyone made it deliberately.

**For every list, detail view and form**

- **Empty** The first thing a new user sees is a list with nothing in it. Say what belongs here and put the action that creates the first record on the page itself.
- **Loading** Decide between a skeleton and a spinner once. Show cached data while it refreshes instead of blanking a screen that already had content.
- **Error** What failed, whether the user's input survived, and what to do next. A red toast that vanishes is not an answer.
- **Destructive** Every delete needs a confirmation that names the thing being deleted. Use the same dialog for all of them so the pattern is learned once.

_If there is time for one of these beyond your core screens, design the empty states. They are the onboarding._

## What to leave to a component library

Buttons, inputs, dialogs, dropdown menus, date pickers and tables are solved problems with details hiding inside them:
focus rings, keyboard navigation, screen reader labels, what a menu does near the edge of the window. Designing your own
costs weeks and usually ends up less accessible than what a maintained library ships.

Take the primitives from a library and restyle them through tokens. shadcn/ui and Radix exist for this, and each is
somebody else's project with its own conventions to learn. Your effort goes into composition: which parts appear on a
page, in what order, with what copy.

> If you are drawing a custom dropdown before you have drawn the screen that makes your product different, the effort is
>   in the wrong place.

## Designing with a coding agent

An agent writing interface code works by imitation. It reads the files near the one it is editing and produces more of
the same. If the codebase has a page scaffold and named colour roles, the tenth screen looks like the first. If it has
three ad hoc pages with hard-coded greys, the agent copies one of them and adds a fourth variation.

That makes a consistent token system worth more with an agent than without one. Keep every colour in a single
stylesheet, and write the rule down in a file the agent loads: use the role names, no raw palette classes, build pages
from the shared scaffold.

## The order that works

1. **List your screens and cross out the generic ones** — Write every screen the first version needs. Strike sign in, sign up, password reset, settings, members, billing and the admin view. What survives is your design work, and it is usually two or three screens.
2. **Choose the shell and the tokens** — Navigation position, depth, density, type scale, colour roles, corner radius, light and dark. Judge the options in a browser, not from a description.
3. **Design your screens on paper or in a rough tool** — Boxes and real copy. Decide what the user is looking at, what they do next, and what the screen looks like in each of the states above. Fidelity can wait.
4. **Build them inside the shell with library primitives** — Now the screens meet real data and real widths. Expect to change them.
5. **Put five people in front of it** — Give each one a task and stay quiet. Where they hesitate is your list of fixes.

## How we approach the shell and the tokens

Steps two and four are the part Hype Stack covers. It is a codebase you own, not a design tool, and the relevant pieces
are layout packs and a theme system.

A **layout pack** is the shell as source code: sidebar, header, user menu, mobile navigation and the content area. There
are five. `layout-basic` is a classic dashboard with a sidebar that collapses to an icon rail, and it is free. The paid
ones are `layout-crm` (compact and dense, with second-level navigation as horizontal tabs), `layout-glass` (a frosted
sidebar over an opaque content card), `layout-joyful` (a floating sidebar painted in the brand colour) and
`layout-native-app-shell` (one shell for web and Electron with primary, secondary and tertiary navigation). You install
one. They are interchangeable because each ships the same four components under `components/layouts/shells/`:
`PageShell`, `DetailPageShell`, `DialogShell` and `ConfirmShell`. Feature code imports those and never checks which
layout is installed, so the page, detail, dialog and confirm patterns have one implementation each. Primitives are
shadcn/ui components in `src/components/ui/`, and the sidebar tree is one file, `src/constants/nav.constants.ts`.

The **theme** is colour only and lives in `apps/frontend/assets/styles.css` as OKLCH custom properties: `:root` for
light, `.dark` for dark, and an `@theme inline` block that exposes them as Tailwind classes such as `bg-primary`. The
CLI ships fourteen palettes and applies one at `create` with `--theme`. Corner radius is a separate `--radius` flag, so
changing palette does not reshape buttons. The template also carries a theming rule among the agent rules files, which
tells a coding agent to use the semantic tokens instead of raw palette colours. To build a palette of your own from one
brand colour, the free [shadcn theme generator](/tools/shadcn-theme-generator) writes both blocks in OKLCH.

To compare shells before choosing, each layout pack's store page shows screenshots and a demo video in both light and
dark.

The Better Studio template is the combination this page recommends starting from: a SaaS starter, `layout-glass` by
default, Stripe billing, the `ocean` palette in dark mode, plus a landing page and re-skinned sign-in screens.

**See the shells running before you pick one** Each template is a working app on one of the layout packs, with a theme applied. Open a few and compare navigation, density and dark mode on real screens.

[Browse the templates](https://www.hype-stack.dev/templates)

## What is not in the box

There is no designer in it and no brand. The palettes are generic by intent: you get a coherent set of colour roles, not
a logo, an illustration style, or a voice. If you need those, that is still a person's job.

The screens specific to your product are not in it either. The shells give your list and detail pages a consistent
frame, and the frame is empty. What goes on your main screen, in what order, with which states, is the design work this
guide started with, and you do it yourself. Layout packs also need a starter pack installed, because the shell renders
the signed-in user, so this is not a kit you drop into an existing unrelated codebase.

The sections below show the template on screen and list what the stack installs.



The build this design feeds is in [How to Build a Web App, Decision by Decision](/stacks/how-to-build-a-web-app), and
worked examples of the shells in [Web App Example](/stacks/web-app-example).
