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/materialcatalogue 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-iconandaria-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-widthcontainer; 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
| Rule | Do | Don't |
|---|---|---|
| Sentence case everywhere | Add customer | Add Customer |
| Australian/British spelling | organisation, colour, centre, cancelled, analyse | organization, color, center |
| Buttons say what happens | Save changes, Export CSV | OK, Submit |
| Errors say what happened and what to do | Couldn't load orders. Check your connection, then try again. | Error 500 |
| Empty states say what to do next | No customers yet. Add your first customer to get started. | No data |
Format with phApp.format | 1,234 · $48,210.00 · 17 Nov 2026 | 1234 · 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-hiddenwhen it can't be visible),alton images, andaria-labelon 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,nfor new), or Shift with a letter. Show them with<kbd>.
Speed
| Rule | Target |
|---|---|
| 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 paint | Within 2.5 seconds |
| Requests | One per view: an endpoint that returns what the view needs |
| Search inputs | Debounced (250 ms) |
| Long lists | More 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 getno-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 /healthzreturns 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.
-
/healthzanswers; server validates input and returns readable errors.