Skip to content

UI/UX

The principles every screen follows, the spacing and layout it sits on, and live examples of the @workspace/ui components. Toggle the theme in the header to check both modes.

Experience

People running a business use the product all day. It has to respond at once, never lose their work and behave the same way every time.

Principles

What every screen should do, whatever it shows.

Instant
A change shows the moment someone makes it, and the server catches up (optimistic updates). While something loads, show a skeleton of what's coming, never a blank page.
Never lose work
Editors autosave about a second after the last keystroke and say so. Nothing a person typed disappears because they navigated away.
One way to do each thing
An action works the same from a button, the command palette or a shortcut, because they all run the same operation. Learn it once.
Keyboard as well as pointer
⌘K reaches anything, and D switches theme. Every control is reachable by Tab, with a visible focus ring.
Say what happened
An error appears next to what caused it and says how to fix it. The change itself shows success. Add a toast only when the result is off-screen.
Shareable state
Open dialogs, tabs and filters live in the URL, so a link lands a colleague exactly where you are.

Patterns

Moments that come up again and again, handled the same way everywhere.

MomentDo thisWhy
Loading a viewA skeleton shaped like the contentThe layout doesn't jump when data lands.
Saving a changeApply it at once. If the server refuses, roll it back and show a toastNobody waits on the network after every edit.
Editing long textAutosave with a quiet saving/saved statusNo save button to forget.
Editing a document togetherEach person's cursor in their own colour, with their name on it, and the same colour ringing their avatarYou can see who is typing where, and nobody's work is overwritten.
DeletingConfirm with the item's name and "This can't be undone."A deliberate pause only where a mistake is permanent.
An empty listSay what will be here and offer the first stepSomeone looking at an empty list needs to know how to start.
Something the plan holds backKeep it, show that it's there, and say what unlocks it, with the way to Billing for whoever can actA locked form response is still theirs. Hiding it would look like losing it.
A form errorInline, under the field, once it's been leftThe fix is next to the problem.
Creating a recordThe name as a large heading, a description, then every other field as one row of chips, stage first. Check it on submit, and clear each error as it's fixedThe form reads like the record it makes, and nothing is marked wrong before you've finished.
Adding to a boardAn Add button across the foot of each open column, opening the create dialog in that column's stageYou add work where you can see it will land.
Acting on a card or rowQuick actions in its bottom-right corner on hover, beside its select boxThe everyday changes take one click, and the list stays calm until you reach for them.
A library the list draws onA tab after List and Board (Templates), not a button in the headerIt's another view of the same work, so it sits with the other views.

Accessibility

WCAG 2.2 AA, checked in both themes. It's the minimum, not a feature.

Do
  • Keep body text at 4.5:1 contrast and UI boundaries at 3:1.
  • Label every control, and give icon-only buttons an aria-label and the same words in a tooltip.
  • Keep focus visible, and return it where it was when a dialog closes.
  • Honour reduced motion, and make targets at least 24px (44px on touch).
  • Make Skip to content the first Tab stop, and keep paste working in every field.
Don't
  • Use colour alone to carry meaning.
  • Hide essential information in tooltips or on hover.
  • Trap focus outside dialogs, or remove outlines without a replacement.

Interface details

The small things that make a screen feel finished. The full checklist, and what the components already do for each rule, is user-interface-cheatsheet.md at the root of the repository.

Surfaces
Nest radii concentrically: the outer radius is the inner one plus the padding. Align by eye, not by the box. Give images a faint inset outline and icons the stroke of the text beside them. Every record card sits on the same surface.
Motion
Grow from the trigger, leave more quietly than you arrive and name the properties you transition. Buttons dip slightly when pressed, except one that spans a whole row, which holds still. Hover and other frequent changes are instant or nearly so.
Type
Tabular numbers wherever digits change. Balanced headings, 60–75 characters a line for long text, real ellipses and dashes, and the full text a tap away whenever it's truncated.
Colour
Semantic tokens in components, never raw palette steps. Dark mode has its own palette, switched one way only. Check contrast against what's directly behind.
Access
Native elements, a visible focus ring, a skip link first, labels on every input, a tooltip naming every icon-only button and paste always allowed. Errors are announced with the field they belong to, and focus moves to the first one.
Words
Buttons start with a verb and say what will happen. One label moves you on through a flow. Toggles name what happens when they're on, and empty views offer one way to start.

Foundations

Tailwind's scale, kept small: five gaps, one radius family, five breakpoints.

Spacing

Reach for gap-4 first. Space with gap on the parent, not margins on children.

  • gap-1.50.375remLabel to input, icon to text
  • gap-30.75remTight groups: toolbar buttons, chips
  • gap-41remThe default: grids, cards, form fields
  • gap-82remRelated blocks within a section
  • gap-164remBetween the sections of a page
Do
  • Use the Tailwind scale, and these five steps before any other.
  • Design at 375px first. Nothing may scroll sideways on a phone.
Don't
  • Arbitrary values like p-[13px] to nudge something into place.
  • Nest max-width containers, or pad a card's children instead of the card.

Radii

Every radius is a multiple of --radius (0.45rem). Buttons and badges use rounded-2xl. Cards and dialogs go up to 24px.

rounded-sm4.3px
rounded-md5.8px
rounded-lg7.2px
rounded-xl10.1px
rounded-2xl13.0px
rounded-3xl15.8px
rounded-4xl18.7px

Breakpoints

Tailwind's defaults, mobile first: unprefixed classes are the phone layout.

PrefixFromWhat changes
None< 640pxOne column. Actions go full width.
sm640pxTwo-column grids.
md768pxPage padding grows, and the app sidebar stops being a sheet (useIsMobile).
lg1024pxThree columns. Secondary panels, like this table of contents, appear.
xl1280pxContent stops growing at max-w-screen-xl.

Page structure

The classes these guideline pages use.

RoleClasses
Page widthmx-auto w-full max-w-screen-xl
Reading widthmax-w-2xl (prose, descriptions)
Page paddingpx-4 py-8 md:px-8 md:py-12
Sectionsflex flex-col gap-16
Card gridsgrid gap-4 sm:grid-cols-2 lg:grid-cols-3

Actions

Everything a person presses. One primary action per view.

Button

Default (orange) for the one primary action. Outline or secondary for the rest, ghost in toolbars, and destructive only for what can't be undone. An icon-only button names itself in a tooltip on hover, in the same words as its label.

Button feedback

A save or submit button answers in movement, never colour: it lifts with a tick when the save lands and shakes with an alert when it doesn't, then goes back to its label. In a dialog, the tick holds for a beat before the dialog closes (closeAfterSuccess), so it's plain the save worked. Wire a form's button with submitState; the error itself is still said in words, above the buttons. Press them to see.

Button sizes

Default (h-8) almost everywhere. Use sm and xs in dense rows, and lg only for a lone call to action.

Badge

Short status and counts. Secondary or outline by default, so the orange stays for what needs attention.

NewDraftProposal sentOverdue12

Visibility badge

On a task, doc or file card that isn't open to the whole organisation: Private for the people it's shared with, Personal for you alone. Public content gets no badge. Use the compact form where a card has no room for the word.

PrivatePersonal

Star rating

For showing a score someone has earned rather than asking for one, such as how engaged a contact is with your email. Whole and half stars, read out as the score in words. Where there's no score yet, say why in words instead of showing empty stars. To ask for a rating, use the rating input.

Button group

Related actions joined into one control.

Toggle group and segmented control

Toggle groups for formatting and multi-select. To switch between views, use the segmented control and nothing else. An option that doesn't fit yet stays in view, disabled, with the reason in a line under the control.

Forms

React Hook Form and Zod do the work underneath. These are the controls on top.

Field and input

Every input sits in a Field with a label. Errors appear under their own field, never in a list at the bottom of the form.

As it should appear on proposals.

Input group

An input with an icon, prefix or unit attached.

%

Select and textarea

Select for one of a known list. Textarea for anything longer than a line.

Checkbox, radio, switch and slider

Checkboxes for independent options, radios for one of a few, switches for settings that apply at once.

File drop input

For choosing files to send with a form. One button that opens the picker and takes a drop, with what's chosen listed under it. Say what's allowed in the hint, and put a refusal in the field's own error.

  • brief.pdf471 KB

Rating input

For asking how good something was. Stars or a slider for a score, thumbs for yes or no, faces for a feeling. Each star and face is a button named for what it means, and pressing the chosen one again takes the answer back.

1Not rated yet10

Suggestion input

For a field that takes anything typed but has likely answers to offer: an email address, with the organisation's own to pick from. Use a select where only the listed answers are allowed.

Email text editor

For text that will be emailed: a reply, or a signature. Bold, italic, underline and links only, because that is what every mail client shows. Given merge tags, it adds Insert merge tag and shows each tag as a chip, filled in for whoever it goes to. Use the full editor for the app's own documents.

Dialog

For one decision that needs the reader's full attention before they carry on. A title that names it, a line or two on what happens, then the buttons: the way out on the left, the action on the right. If it can be undone or read later, it belongs inline, not in a dialog.

Multistep dialog

For making something that takes a few separate choices. Each step has its own title, the bar and Step N of M say how far along the reader is, and the footer moves them on: Cancel then Continue on the first step, Back then Continue after it, and the real action only on the last.

Form dialog

For a short form in a dialog: making or renaming something. A title, one line on what it does, the fields, then Cancel and the submit button. A field's error goes under the field. A failure about the whole request goes above the buttons.

Field chips

On a card and in a create form, a field is a ghost chip that opens its picker: an icon and the value, or the field's name in muted text while it's empty. A date close to today says Yesterday, Today or Tomorrow, and a due date turns yellow for tomorrow, amber for today and red once it has passed. Blocked by and Blocks are the same two chips on a task and a milestone. On a card or a header the stage is its pie alone, named in a tooltip. In a form or a table, where a column is read down, it carries its name.

The same stage on a card or a header: its pie alone, named on hover.

Create dialog

For making a record: a task, project, deal, contact, milestone or Planner task, a Brain Space launch, a logged activity. The name is the heading, large and bare, with the dialog's title kept for screen readers. Then the description, in rich text where the record keeps a document, and every other field as one row of chips, stage first. Nothing is marked wrong until you submit. Then each error shows under its field (a chip's under the row) and goes as soon as it's fixed.

Layout

The containers that hold content.

Card

Frosted glass with the orange top rule. Title in serif, description muted, actions in the footer.

Brand refresh
Northwind · due 14 March
x
7 of 11 tasks done
Pipeline value
£48,200

+12%vs last month

Tabs

Different views of the same thing. Keep labels to one or two words. Default (pill) tabs switch views inside a card or panel. Line tabs head a whole page or dialog, as in settings. The pill or line slides to the tab you pick. A library the list draws on, such as Templates, is a tab after List and Board rather than a button in the header.

Default
The project at a glance.
Line
The project at a glance.
List, board and library

Accordion

Secondary detail a reader may not need. Never hide what they must read.

Item

A row in a list: media, title, description and actions.

Team

4 members, 1 pending invitation

SAR

Integration grid

Integrations as tiles, all one size and at most three across: the logo above the name and where it stands, centred, with a check mark in the corner once connected. A tile opens that integration's settings. One that can't be added says why in words, not just by fading.

Record card

Tasks, projects, deals, docs and files share one surface: a hairline border on the card colour that firms up, with a soft shadow, on hover. The top row is the stage and the name, then a compact priority flag and whoever owns it. Dates sit on the left of the next row and counts on the right, each count named in a tooltip. Who can see it and its tags sit at the card's edge, and the select box waits in the bottom-right corner, with delete beside it for whoever may. Docs, files and proposals lead with their icon on a bordered tile. Everything edits in place: double-click a name to rename it.

Private
Design
Retainer
S
Yesterday, 16:20
Personal
Brand

Board column

An open column shows a full-width Add button across its foot while it's hovered, and always on a touch screen. It floats over the cards on a blurred backing and opens the create dialog in that column's stage. A button that spans a whole row or column holds still on hover and press, because a press across that width reads as a lurch. The column's corners are the card's radius plus its padding, so the curves run together. Hover the column to try it.

Proposal sent1
Retainer

List row

A row of a list is one button that opens it, and it holds still on hover and press. Its quick actions (mark read or unread, archive, and delete for whoever may) appear in its bottom-right corner on hover, each named in a tooltip.

Greeting

The dashboard opens on the reader's day: the date and time as the eyebrow, a greeting for the time of day with their first name, and one line on what's due. Today's plan sits beside it, straight on the page rather than in a card: what's on right now and what's up next, with View planner in the corner.

Email

What an email to many people is written in and checked with.

Email builder

For an email sent to many people: a newsletter or a template. The writing area shows the email as it will look: the organisation's background, card, fonts, accent, buttons and corners. Type / for headings, buttons, pictures, columns, coloured sections, the organisation's logo and links, and merge tags, which show as chips (anything else in double braces is underlined as a mistake): the same menu, and the same formatting menu, as in Docs. With both logos set in brand settings, the logo block shows the one for light surfaces, and the one for dark surfaces where the reader's mail app is dark. A selected picture or section has a menu for its size, place or colour. Preview shows it at desktop and phone widths, light or dark. The footer under the body is added to every email and can't be edited. Use the email text editor for a one-to-one reply.

You're receiving this because you subscribed to emails from Acme.
Acme, 1 High Street, Leeds LS1 1AA · Unsubscribe

Type / for a heading, a button, a picture, a section or your links. Select text to style it or add a link.

Email preview

An email as its reader sees it, read-only, in a frame of its own so nothing in it can touch the page. Switch between desktop and phone widths, and light and dark. Given the whole email as the server drew it, Dark shows the email's own dark scheme.

You're receiving this because you subscribed to emails from Acme.
Acme, 1 High Street, Leeds LS1 1AA · Unsubscribe

Marketing

What the marketing site's sections are built from.

Section header

The words that open a section: eyebrow, heading, lead, then one or two actions. Every part is optional. The heading's size and its level in the page outline are set apart.

Planning

Plan the week in minutes

See every project's next step in one place, and move it with a drag.

Centred, and a size smaller

Drawn at heading 3, still an h2 in the outline.

Bento grid

Cards in mixed sizes. One column on a phone, two from 640px, three from 1024px. Small cards fill the gaps, so keep each card independent of its neighbours.

Mission Control
Large: two columns and two rows. The one thing the section is about.
Tasks
Default: one cell.
Chat
Default: one cell.
Planner
Wide: two columns, for something that reads across.
Proposals
Tall: two rows, for something that reads down.
Contacts
Default: one cell.

Media frame

The box every image, video and embed sits in. A fixed shape crops the media to cover it; original keeps the media's own shape.

Landscape, 16:9
Square, 1:1
Portrait, 4:5

Section backdrop

Brand artwork behind a section a page is built around (the hero, the pricing plans, the closing call to action): the glow, the dot field from Brain Space, or the dot-matrix Earth or Moon from Mission Control. Never on adjacent sections, and never two in view at once.

Glow

Dot field

Earth

Moon

Feedback

How the app tells people what's happening.

Alert

Inline, persistent messages about the thing in front of the reader. Always an icon, a title and what to do.

Toast

A short-lived confirmation of something that happened off-screen, or a failure. Name the thing and keep it to one sentence.

Skeleton and spinner

Skeletons, shaped like what's coming, for views and sections. A spinner only inside a button or inline, for an action in progress.

x

Empty

An empty list says what will be here and offers the first step.

No projects yet
Projects collect the tasks, files and notes for a piece of work.

Tooltip

Every icon-only button has one, in the same words as its label: the editor toolbars, the inbox's actions, a card's counts. Never the only place information lives.

Copyright 2026 53 Degrees App LTD. Company number: 16727854. All rights reserved. Made with ♥ in Yorkshire 53.8008°N, 1.5491°W