Guidelines

On this page

These rules keep apps built with the kit consistent with Performance Hub and with each other. They apply to apps, dashboards, reports and tools. Websites, landing pages and other design-led work don't need to follow them.

Use the kit first

  • Use the kit's components, classes and optional modules wherever they cover what you need. In React, the rest of the @mui/material catalogue comes next.
  • When neither covers it, any other library is fine. Prefer one that can be themed, and style it with kit tokens so it matches in light and dark.
  • Don't add a second full CSS framework (Bootstrap, a Tailwind CDN build) for one widget: its global reset restyles the kit's components.

Look and feel

  • Colours only from tokens: rgb(var(--ph-…)) in CSS, ph-* classes in Tailwind. Hard-coded white, black or hex colours break dark mode.
  • Icons: inline SVG line icons with .ph-icon and aria-hidden="true". No emoji in titles, buttons, labels, tabs or statuses.
  • Page structure: .ph-page > .ph-page-header (title, one-line description, actions with the primary action last) > content in .ph-cards, with a toolbar above every table. Start from the page patterns.
  • Use the full width. Dashboards, lists, reports and tools fill the window. Don't wrap them in a max-width container; put more side by side on wide screens. Only settings forms and wizards use .ph-page--narrow.
  • Light and dark both look right. Check every screen in both.
  • Responsive from 360px: grids collapse, tables scroll inside .ph-table-wrap, the page never scrolls sideways, and touch targets are at least 32px.
  • Three states for everything that loads: a skeleton first, an empty state that says what to do next, and an error callout with a Try again button. Never a blank screen, a long spinner on its own, or a stack trace.

Copy

RuleDoDon't
Sentence case everywhereAdd customerAdd Customer
Australian/British spellingorganisation, colour, centre, cancelled, analyseorganization, color, center
Buttons say what happensSave changes, Export CSVOK, Submit
Errors say what happened and what to doCouldn't load orders. Check your connection, then try again.Error 500
Empty states say what to do nextNo customers yet. Add your first customer to get started.No data
Format with phApp.format1,234 · $48,210.00 · 17 Nov 20261234 · 48210 · 2026-11-17

Numbers in tables use .ph-num so they line up.

Accessibility

  • <html lang="en">, a <title>, the viewport meta tag and one <h1> per page.
  • A label for every input (.ph-visually-hidden when it can't be visible), alt on images, and aria-label on icon-only buttons.
  • Colour is never the only signal: pair it with text or an icon.
  • Real <button>s and <a>s, never clickable <div>s. Keep the kit's focus styles.
  • Use kit dialogs and menus; they trap focus, close with Escape and handle arrow keys.
  • White text on the brand blue and red (primary and danger buttons) is below 4.5:1 contrast, here as in Performance Hub. Don't recolour them.

Keyboard

  • Everything works with the keyboard alone.
  • Never bind Ctrl/Cmd+K, Ctrl/Cmd+J, Ctrl/Cmd+I or Alt+Ctrl/Cmd+L; they belong to Performance Hub.
  • App shortcuts are single keys when focus isn't in a field (/ to search, n for new), or Shift with a letter. Show them with <kbd>.

Speed

RuleTarget
The app's own JavaScript on first load, gzipped (kit files don't count)50 KB for plain pages, 200 KB for React
Largest contentful paintWithin 2.5 seconds
RequestsOne per view: an endpoint that returns what the view needs
Search inputsDebounced (250 ms)
Long listsMore than a few hundred rows: page, sort and filter on the server, or use the data grid
  • Serve production builds. Never serve an app people use from a dev server (vite, next dev, hot reload, Flask debug, python -m http.server).
  • Compress HTML, CSS, JS, JSON and SVG with gzip or brotli.
  • Cache content-hashed files for a year (Cache-Control: public, max-age=31536000, immutable). HTML and unhashed files get no-cache, so they revalidate.
  • Nothing jumps: charts reserve their height, images have a width and height.
  • Load heavy, rarely used parts lazily. On plain pages, add optional kit scripts only to the pages that use them.

Production readiness

  • GET /healthz returns 200 {"ok":true} quickly, without waiting on slow dependencies.
  • Validate every input on the server. Errors return 4xx JSON ({"error": "what to fix"}), and the page shows that message next to the field or in a callout.
  • Secrets never go in code, HTML or config files that are committed.
  • Store and send times in UTC (ISO 8601); show them in local time.
  • Relative URLs only, so the app works wherever it opens.
  • No third-party CDNs for scripts, styles or fonts: bundle them or use the kit.

Checklist

  • Kit stylesheet and script are loaded; optional scripts only where used.
  • Every screen checked in light and dark, at 1280px and 375px wide.
  • No hard-coded colours, no emoji, sentence case throughout.
  • Every loading view has a skeleton, an empty state and an error state with Try again.
  • Tables have a toolbar, sortable headers and right-aligned numbers.
  • Destructive actions ask for confirmation; saves confirm with a toast.
  • Everything works with the keyboard; Performance Hub shortcuts aren't bound.
  • URLs are relative; API calls use fetchJSON.
  • Production build, compressed and cached; first-load JavaScript within budget.
  • /healthz answers; server validates input and returns readable errors.