Page patterns
On this page
Most app pages are one of five kinds: a list, a dashboard, a detail page, a settings form or a wizard. Pick the pattern that matches the view and keep its order, so every app feels familiar. Each pattern below is built only from kit components.
Every page
.ph-page
[.ph-breadcrumbs] only on pages below the first level
.ph-page-header h1 title, one-line description, actions (primary last)
[callout] page-level errors or notices
content cards, 16px apart
List
For records people browse, search and act on: customers, products, bookings.


Figure 1: A list page with search, filter chips, a sortable table and paging
header title, the count in the description ("26 customers"), Export CSV, primary "Add customer"
card .ph-card--flush
toolbar search, filter chips or selects, a menu of bulk actions
table first column names the record and links to it; status as badges;
numbers right-aligned (.ph-num); relative dates with the full date in title=
paging the kit's or the server's
Once the data can pass a few hundred rows, page, sort and filter on the server and return one page
at a time, for example GET api/customers?page=2&size=25&q=ale&sort=-lastOrder returning
{ items, total }. For thousands of rows already in the browser, use the
data grid.
Dashboard
For numbers at a glance.


Figure 2: A dashboard with KPI tiles, two chart cards and a heatmap
header title, the period in the description, a period selector (.ph-segmented) and Export
.ph-grid-4 KPI tiles (phApp.kpi with a delta and sparkline)
.ph-grid-2 chart cards (title, and a description with the unit and period)
full width the detail table or a heatmap
- At most 4 KPIs in a row, and about 6 charts on a page. Each chart answers one question in its title.
- Every chart card states the period and the unit. Totals and deltas use the same period.
- Load the whole dashboard with one request (
api/dashboard?period=week).
Detail
For one record.


Figure 3: A detail page with a summary column, facts and activity
breadcrumbs List > Record name
header record name, a status badge in the description, actions (Edit is primary; Delete in a menu)
.ph-split
side summary card (.ph-stat or .ph-dl)
main cards with .ph-dl facts, related tables, and a .ph-timeline of activity
Settings form


Figure 4: A narrow settings page with one card per group of settings
.ph-page--narrow
header title, and what these settings affect
cards one per group of settings, each a .ph-form with its own Save button
- Labels above inputs, hints under them, errors under the field.
- The Save button says what it saves ("Save room settings"). Set
aria-busy="true"on it while saving, and show a toast when it's done. - Warn before leaving with unsaved changes (only when the form has changed).
Wizard
For a few ordered steps that set something up.


Figure 5: A wizard on its second step
.ph-page--narrow
header title, and what it sets up
.ph-steps progress
card one per step: fields, then Back (ghost) and Continue (primary)
- The last step's button names the outcome ("Create site"), not "Finish".
- Validate each step before Continue, and show a summary before the final action.
- Keep each step's answers in the browser until the final submit, or save drafts on the server.
Loading, empty and error states
Every view that fetches data has three states besides the content. Never show a blank screen, a spinner on its own for long, or a stack trace.
| State | Show | Component |
|---|---|---|
| Loading | A skeleton in the shape of what's coming (tiles, a chart block, table rows) | Loading |
| Empty | Why it's empty, and the next step ("Add customer", "Clear filters") | Empty states |
| Error | What went wrong and a Try again button | Callouts |
const content = document.getElementById('content');
function showSkeleton() {
content.innerHTML = '<div class="ph-skeleton ph-skeleton-block" style="height: 240px"></div>';
}
function showError(error) {
content.innerHTML = '';
const callout = document.createElement('div');
callout.className = 'ph-callout ph-callout--danger';
callout.setAttribute('role', 'alert');
callout.innerHTML =
'<div class="ph-callout-body"><p class="ph-callout-title">Couldn\u2019t load orders</p><p></p></div>' +
'<button type="button" class="ph-btn ph-btn--sm ph-callout-action">Try again</button>';
callout.querySelector('p:not(.ph-callout-title)').textContent = error.message; // never innerHTML with server text
callout.querySelector('button').addEventListener('click', load);
content.append(callout);
}
async function load() {
showSkeleton();
try {
const data = await phApp.fetchJSON('api/orders', { query: { page: 1 } });
data.items.length ? render(data) : showEmpty();
} catch (error) {
showError(error);
}
}
document.addEventListener('DOMContentLoaded', load);
- Keep showing the old data during a refresh; if the refresh fails, show a toast instead of replacing the page with an error.
- Put server text on the page with
textContent, never by building HTML from it.