Skip to content
Borneo Design System

Resources

Design checklist

Run this before a screen ships. Most of it is not about how the screen looks — it is about the states, widths and access paths that a design file has no way to show.

Use it as a conversation, not a gate

The point of the list is to surface the questions early, while they are cheap to answer. A screen that fails a line is not blocked — it is a decision that should be made deliberately rather than by omission.

HierarchyPermalink to this section

Whether the screen tells someone what to do next.

5 checks
  • There is exactly one primary action, and it is the most visually prominent thing on the screen.
  • The heading order is sequential — h1, then h2, then h3 — with no level skipped for appearance.
  • The most important information is readable without scrolling on a 375px viewport.
  • Grouping is carried by spacing before it is carried by borders or background fills.
  • Nothing uses the brand accent except the primary action, the active navigation item and the focus ring.

StatesPermalink to this section

The five states design files most often omit. Each of them is a real screen someone will see.

6 checks
  • Empty — before anything exists, with an explanation and a way to start.
  • Loading — including what happens if it takes eight seconds rather than one.
  • Error — the request failed, distinguished from “there is nothing here”.
  • Partial — some data loaded and some did not.
  • Full — the longest realistic name, the largest realistic count, the most items.
  • Every interactive element has hover, pressed, focus-visible and disabled defined.

ContentPermalink to this section

Real content, at realistic lengths.

6 checks
  • No placeholder text anywhere — every string is what will actually ship.
  • The longest realistic value has been tested: a 60-character project name, a four-digit count.
  • Buttons are labelled with verbs that name their outcome, not “OK” or “Submit”.
  • Error messages say what is wrong and how to fix it.
  • Dates, numbers and currency use a consistent format across the screen.
  • Nothing depends on text that only appears on hover.

ResponsivePermalink to this section

Narrow layouts are designed, not derived. Check each breakpoint deliberately.

6 checks
  • 375px — the layout is designed for this width, not compressed into it.
  • 768px — the tablet layout is a deliberate arrangement, not an awkward middle state.
  • 1440px and above — content is capped and centred rather than stretching.
  • Wide content — tables and code blocks scroll inside their own container; the page body never scrolls sideways.
  • Touch targets reach 44×44px on coarse pointers.
  • The layout survives 200% zoom at a 320px viewport.

AccessibilityPermalink to this section

The checks that automated tooling cannot make. Run them by hand, every time.

9 checks
  • The whole screen is operable with the keyboard alone, mouse unplugged.
  • Focus order follows visual order, and focus is visible at every stop.
  • Every icon-only control has an accessible name that describes the action.
  • Colour is never the only carrier of meaning — status has a word or an icon too.
  • Body text clears 4.5:1; focus indicators and control boundaries clear 3:1.
  • Content that changes without a navigation is announced through a live region.
  • Dialogs and menus trap focus while open and return it to the trigger on close.
  • Nothing essential lives only inside a tooltip.
  • With reduced motion enabled, movement is removed rather than merely faster.

System fitPermalink to this section

Whether this screen made the system better or slightly worse.

5 checks
  • Every spacing value maps to a step on the scale.
  • Every colour is a semantic or component token — no hardcoded values.
  • Existing components are composed rather than restyled through className overrides.
  • Anything genuinely new has been raised as a proposal rather than built inline.
  • The screen looks like it belongs beside the rest of the product.

The five-minute versionPermalink to this section

When there is genuinely no time for the full list, these five checks catch most of what matters.

  1. Unplug the mouse and complete the main task with the keyboard.
  2. Resize to 375px and check that the layout was designed rather than squeezed.
  3. Empty the data and see what the screen says.
  4. Replace every name with a 60-character string.
  5. Take a greyscale screenshot and check that every state is still distinguishable.