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.

List pageList page

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.

Dashboard pageDashboard page

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.

Detail pageDetail page

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

Settings pageSettings page

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.

Wizard pageWizard page

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.

StateShowComponent
LoadingA skeleton in the shape of what's coming (tiles, a chart block, table rows)Loading
EmptyWhy it's empty, and the next step ("Add customer", "Clear filters")Empty states
ErrorWhat went wrong and a Try again buttonCallouts
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.