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.
Patterns
Moments that come up again and again, handled the same way everywhere.
| Moment | Do this | Why |
|---|---|---|
| Loading a view | A skeleton shaped like the content | The layout doesn't jump when data lands. |
| Saving a change | Apply it at once. If the server refuses, roll it back and show a toast | Nobody waits on the network after every edit. |
| Editing long text | Autosave with a quiet saving/saved status | No save button to forget. |
| Editing a document together | Each person's cursor in their own colour, with their name on it, and the same colour ringing their avatar | You can see who is typing where, and nobody's work is overwritten. |
| Deleting | Confirm with the item's name and "This can't be undone." | A deliberate pause only where a mistake is permanent. |
| An empty list | Say what will be here and offer the first step | Someone looking at an empty list needs to know how to start. |
| Something the plan holds back | Keep it, show that it's there, and say what unlocks it, with the way to Billing for whoever can act | A locked form response is still theirs. Hiding it would look like losing it. |
| A form error | Inline, under the field, once it's been left | The fix is next to the problem. |
| Creating a record | The 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 fixed | The form reads like the record it makes, and nothing is marked wrong before you've finished. |
| Adding to a board | An Add button across the foot of each open column, opening the create dialog in that column's stage | You add work where you can see it will land. |
| Acting on a card or row | Quick actions in its bottom-right corner on hover, beside its select box | The everyday changes take one click, and the list stays calm until you reach for them. |
| A library the list draws on | A tab after List and Board (Templates), not a button in the header | It'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.
- 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.
- 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.
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 textgap-30.75remTight groups: toolbar buttons, chipsgap-41remThe default: grids, cards, form fieldsgap-82remRelated blocks within a sectiongap-164remBetween the sections of a page
- Use the Tailwind scale, and these five steps before any other.
- Design at 375px first. Nothing may scroll sideways on a phone.
- 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.3pxrounded-md5.8pxrounded-lg7.2pxrounded-xl10.1pxrounded-2xl13.0pxrounded-3xl15.8pxrounded-4xl18.7pxBreakpoints
Tailwind's defaults, mobile first: unprefixed classes are the phone layout.
| Prefix | From | What changes |
|---|---|---|
| None | < 640px | One column. Actions go full width. |
| sm | 640px | Two-column grids. |
| md | 768px | Page padding grows, and the app sidebar stops being a sheet (useIsMobile). |
| lg | 1024px | Three columns. Secondary panels, like this table of contents, appear. |
| xl | 1280px | Content stops growing at max-w-screen-xl. |
Page structure
The classes these guideline pages use.
| Role | Classes |
|---|---|
| Page width | mx-auto w-full max-w-screen-xl |
| Reading width | max-w-2xl (prose, descriptions) |
| Page padding | px-4 py-8 md:px-8 md:py-12 |
| Sections | flex flex-col gap-16 |
| Card grids | grid 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.
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.
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.
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.
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.
+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.
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.
4 members, 1 pending invitation
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.
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.
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.
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.
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.
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.
Empty
An empty list says what will be here and offers the first step.
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.