designing with it
Start from what the person needs to do, not from a layout. The principles decide what the screen does and what it leaves out; the patterns give it a page layout; the components fill it in.
from a need to a screen
- Name the principle. Read the principles first. Most screens are decided by the first two: what can the system do on its own, and what is the one status a person needs to see?
- Write down the words for each state. Before you draw anything, list the states the objects on the screen can be in, and give each one of the five meanings; see status vocabulary. The tabs, the counts, the toasts and the empty states all follow from that list.
- Pick a page layout. A list of things that need doing is a worklist; a start page of apps is the home page; settings follow forms and settings. Every screen sits under the same top bar.
- Build it from components. Each component page says when to use the component and when to use something else, and what that is. If no component fits, say so in the review rather than drawing a new one.
- Write the words. Two voices: the monospace chrome in lowercase, the text people read in sentence case; short, true and in the person's words. See content & voice. A button starts with a verb and names what it acts on.
- Check the other states. Loading, empty, nothing found, failed, can't be known: see empty states and message handling. Then the way through with the keyboard, and the screen at phone width.
the tools
There is no kit for a design tool yet. The components themselves are the reference: every kind and state is live on the React subsite, where each component has a playground for trying its settings. The examples on this site are the same components, drawn from the same code.
The colours, text styles and spacing steps are named the way the tokens name them, so a design and its code can say the same thing.
the test
If a screen would look at home in a tmux pane, it is on. If it looks like a SaaS landing page, start over. Put plainly: a screen should feel like a well-kept terminal window, not like a website that is selling something. In practice:
- One emphasized action per view, toolbar or dialog. Everything else is a standard or quiet button, or sits in a menu.
- Colour only where it means something: a state, a link, the one emphasized action. Never for decoration.
- Square frames: no rounded corners, no pill shapes, no shadows on panels.
- Monospace for names and values, Inter for sentences.
- No big header images, no marketing words, and no illustrations except the drawings in empty states.
handing over
A design is ready to build when it says, in the system's own names:
| what | how to name it | for example |
|---|---|---|
| Each component | The component's name, as on its page | Data table, selection toolbar, banner |
| Its kind and size | The kind and size, as in the component's specs | The emphasized button, small; a dense table |
| Each object's status | A row of the status vocabulary: the system's value, its meaning, its words | failed → error → “needs attention” |
| Colour, type and space | The token's name, never a colour code or a size off the scale | The muted text grey, the section title style, the 16 step |
| The words | The exact words, as they should be read: lowercase in monospace, sentence case in the body face | “grab 8 selected”, “nothing missing”, “Every aired episode is in the library.” |
| Empty, loading and error states | Which kind, and its words | The search kind · “no matches” · “clear filters” |
| Keyboard and focus | Anything beyond the components' own behaviour | Where the focus goes after a dialog closes |
The specs at the end of each component page give the names that the code uses, so a developer can find each one.
in a review
- Name the principle a screen breaks: “This goes against 2: it says completed, but it won't play.”
- Check each component's “when to use something else”: most findings in a review are a component doing another one's job.
- Check the “Today:” notes on the pages of the components you use. A limitation may need a word on the screen.
- Read the screen aloud. A message that only makes sense next to its icon or its colour needs more words.
specs
The same hand-over, in the names the code uses:
| what | for example |
|---|---|
| Each component | DataTable, SelectionToolbar, Banner |
| Kind and size | variant="primary", size="sm", dense |
| Colour, type and space | --fg-muted, h2, --s-4 |