Skip to content

Components ​

This page covers the rules for assembling PPP surfaces: how much space to leave, what buttons look like, which image styles fit the brand, and the data-visualisation conventions that keep charts consistent and accessible.

Browse the component Storybook

The canonical dashboard widget organisms — WidgetCard, WidgetDonut, WidgetButton and the feature widgets under PPP/Widgets/Dashboard/ — are published live and on-brand at /storybook/. Click through every variant without running the app; it is deployed alongside these docs and sits behind the same access gate.

Spacing system ​

MUI default 8px base unit. All spacing values are multiples.

ScalepxUsage
18pxTight internal padding
216pxItem gaps, small padding
324pxCard internal padding
432pxSection row gaps
540pxFooter top padding
648pxSection padding (mobile)
864pxSection padding (mobile large)
1080pxSection padding (desktop)

Container width ​

  • Max width xl (1536px) — header, footer, full-bleed sections
  • Max width lg (1200px) — content sections, main reading columns

Breakpoints (MUI defaults) ​

Namepx
xs0
sm600px
md900px
lg1200px
xl1536px

Buttons ​

PPP has two distinct button contexts — keep them separate and don't copy one's values into the other:

Marketing CTA buttons (website / landing pages) ​

Used on the public marketing site (instances/marketing/).

VariantStyleUsage
Primary CTAcontained, #177BE5, borderRadius: 12, px: 36, py: 12"Join the Waiting List", "Send"
Primary hoverbgcolor: #1268C4—
OutlinedborderColor: #1B1B1B, color: #1B1B1BSecondary actions
Mobile CTAborderRadius: 6, px: 24, py: 2, height: 36Responsive reduction
  • textTransform: none on all buttons — no ALL CAPS
  • fontWeight: 500 default, fontWeight: 600 for primary CTAs

Product UI buttons (the PPP app) ​

Every in-app button is an MUI <Button> styled centrally by the app theme (instances/ppp/src/themes/index.tsx → MuiButton). At the call site set only variant, color, size and fullWidth — never hardcode colour, radius, padding, font weight or textTransform. The theme owns those so every button stays consistent.

contained · primary — the one primary action
outlined — secondary / discard (muted grey)
text — low-emphasis / inline
outlined · color="error" — destructive (pairs with a confirm dialog)
disabled — action unavailable
size="small" — toolbars and dense rows

Variant — emphasis

VariantWhen to use
containedThe single primary action in a screen or section (Submit, Save, Add). One primary per context.
outlinedSecondary / discard actions (Cancel, Edit). Muted grey by default.
textLow-emphasis or inline actions; links rendered as buttons.

Colour — meaning (from the theme palette — never inline a hex)

colorMeaningExample
primary (#117BE5)Default call-to-actionSubmit, Save, Add
secondaryNeutral secondary action— (default outlined look)
errorDestructive / irreversibleReset (delete plan), Delete
success / warning / infoStatus-driven affordances—

Sizing & responsiveness

  • size="small" in toolbars and dense rows; default size otherwise.
  • On mobile, buttons grow to fit their label (minHeight, white-space: normal) — never truncate.
  • Use fullWidth for primary actions on mobile viewports.

States

  • Loading: startIcon={<CircularProgress size={16} />} and disabled while the action is in flight.
  • Disabled when the action is unavailable — be consistent (don't hide in one place and disable in another).

Rules

  • No ALL CAPS — textTransform: none (theme-enforced).
  • No hardcoded hex, radius, padding or weight on a button — the theme is the single source of truth (mirrors no-hardcoded-brand-values).
  • Destructive actions use color="error" and a confirmation dialog before acting (e.g. the CPD Plan Reset button → cpd.plan.reset.confirm-before-delete).

Cards and panels ​

  • borderRadius: 12–16 (MUI shape units)
  • Background: #FBFBFF (light) or rgba(255,255,255,0.08) (dark)
  • Subtle box shadow: rgba(149, 157, 165, 0.2) 0px 8px 24px
  • Hover: elevation lift with transition
  • Background: dark navy (AppBar)
  • Nav links: fontWeight: 300, fontSize: 0.8–0.875rem, color: white
  • Active state: fontWeight: 600
  • whiteSpace: nowrap to prevent wrapping
  • No underline on links
  • Horizontal row with | pipe separators
  • fontFamily: Nunito, fontWeight: 300, fontSize: 0.8125rem
  • Link colour: rgba(255,255,255,0.72) → white on hover
  • transition: color 0.15s

Dividers ​

  • Default dark backgrounds: rgba(255,255,255,0.12)
  • Light sections: MUI default

Form inputs ​

  • borderRadius: 12
  • fontSize: 13px
  • Disabled background: gray.50 (#F4F5F7)

Iconography and imagery ​

Illustration style ​

  • Clean, flat SVG icons aligned with the medical/performance theme
  • UI icons from @mui/icons-material
  • Custom section feature icons stored in instances/marketing/src/landing/icons/

Icon system rules ​

Our icons are simple, single-colour line or solid glyphs in brand blue, sitting inside a circular container that is either white or pale blue. This treatment is consistent across the website's Guiding Principles, Values, and feature panels — use the same approach in product UI, marketing collateral, and presentations.

  • Single colour only — a brand-blue glyph on a white or pale-blue circular background.
  • Consistent visual weight — choose icons from a single set (Lucide, Heroicons, or Material Symbols at the same stroke weight); never mix decorative styles within one page.
  • Circular containers should be 1.6–2× the size of the glyph itself to maintain breathing room.
  • Do not use emoji, multi-colour illustrations, or icons that imply a specific software brand (e.g. Office, Google) on primary brand surfaces.

Imagery do's & don'ts ​

Imagery should always serve the message of clarity, support, and progression. Avoid stock-photography clichés.

✓ Do✗ Don't
Show real clinical environments and diverse clinicians at varying career stages.Use stock images of overly-polished smiling doctors that look like ad clichés.
Use editorial-style illustrations for sensitive topics (burnout, suicidal ideation, mental health).Use photographs of distressed individuals to depict mental health — it stigmatises.
Maintain a cool colour grade aligned to our blue palette when colour-correcting.Apply warm orange/red filters or heavy contrast — it conflicts with our clinical tone.
Reflect the geographies we serve: Australia, New Zealand, the UK, and Canada.Default to imagery that only reflects one region or demographic.

Photography and app previews ​

The website hero uses a laptop and a phone mockup, stored in instances/marketing/public/assets/glass/devices/. Downloads are on Logo & Assets → Product imagery.

AssetUsage
laptop-device.pngHero — laptop mockup showing CPD Home
phone-device.pngHero — phone mockup showing CPD Home
laptop-ppp-home.pngPlain desktop screen used in the laptop mockup
mobile-cpd-home.pngPlain phone screen used in the phone mockup
shell-laptop.pngEmpty laptop frame (magenta screen)
shell-phone.pngEmpty phone frame (magenta screen)

Retired: home-app-preview-2.png, home-app-preview-cpd.webp, home-app-preview-*-blurred.png and burnout-to-breakthrough*.jpg are still in instances/marketing/public/assets/, but the website no longer uses them. Don't use them for new work.

Partner / support logos ​

Stored in /public/assets/support-*.svg. Always display on white/light backgrounds. Do not recolour.

LogoFile
Medical Board AHPRAsupport-medical-board-ahpra.svg
Australian Medical Councilsupport-australian-medical-council.svg
CSIROsupport-csiro.svg
Australian Governmentsupport-australian-govt.svg
Queensland Governmentsupport-queensland-govt.svg

Flags (inclusivity section) ​

Our public surfaces feature the Aboriginal flag, the Torres Strait Islander flag, and the Progress Pride flag where we acknowledge Country and celebrate diversity. This is a deliberate brand statement, not decoration.

  • Aboriginal Australians flag: flag-aboriginal-australians.svg
  • Torres Strait Islander flag: flag-torres-strait-islander.svg
  • Progress Pride flag: flag-progress-pride.svg

When using these flags:

  • Reproduce them in their official colours — never tint, recolour, or place them inside a coloured filter.
  • Display them at equivalent visual size, side by side, with consistent spacing.
  • Pair them with an Acknowledgement of Country or statement of inclusion — never as standalone decoration.

Dark section pattern ​

Sections with dark navy backgrounds (hero, footer, feature callouts):

bgcolor: #151D28  (gray.800)
color: white
Text opacity: 1.0 (headings) → 0.85 (body) → 0.65 (supporting) → 0.5 (metadata)

Background texture: url(/assets/footer-bg.svg) — used for the footer and selected dark sections.

Data visualisation patterns ​

PPP uses @mui/x-charts (v7) and amCharts 5. All chart colours are centralised in instances/ppp/src/components/widgets/constants/widgetConstants.ts — see Colour → Dashboard widget palette for the category hues.

CPD category colours (Option C — approved) ​

The AHPRA/RACS CPD framework defines 3 categories (with hour requirements) and 4 cross-cutting program-level requirements. Cultural Safety is a program-level requirement, not a standalone category — it must not appear as its own chart segment.

Categories (3 — shown on doughnut charts, wheels, pills):

CategoryPrimaryLight (doughnut fill, pill bg)Text (pill)Border
Education#167D62#E6F4EF#0F5A46#167D62
Measuring Outcomes#B35E18#FDF0E4#7C4211#B35E18
Reviewing Performance#0D6B9E#E4F0F7#094D72#0D6B9E

Program-level requirements (4 — cross-cutting, never chart segments):

  • Ethical Practice
  • Professionalism
  • Health Inequities
  • Culturally Safe Practice

Doughnut chart rule: use the light colour for segment fill, with a primary colour stroke/border. Do NOT use saturated MUI defaults.

Design reference: CPD palette comparison

Data trust level pattern — verified vs imported ​

Context: the surgical logbook supports importing historical cases from CSV/XLSX. These pre-platform cases must be visually distinct from cases recorded and verified on the platform.

Visual language ​

ElementVerified (platform)Imported (historical)
Chart fillSolid colourDiagonal hatched pattern (45°, 3px stroke, 8px spacing) over light background
Chart borderNone2px solid in category main colour
Card left border4px solid4px dashed
Card backgroundWhiteprimaryLight (#f5f9ff)
Chip variantFilled, green (#167D62)Outlined, dashed, primary blue (#003977)
Chip iconCheckmark (CheckIcon)Clock/history (HistoryIcon)
Stat boxSolid fill in category main colourDashed 2px border, light background
Tooltip label"Verified Platform""Imported Historical"

SVG hatch pattern definition ​

svg
<pattern id="imported-hatch" width="8" height="8" patternTransform="rotate(45)" patternUnits="userSpaceOnUse">
  <rect width="8" height="8" fill="{categoryLight}"/>
  <line x1="0" y1="0" x2="0" y2="8" stroke="{categoryMain}" stroke-width="3" opacity="0.5"/>
</pattern>

Referenced in MUI x-charts via color: 'url(#imported-hatch)' on the imported data series.

Stacked bar charts ​

  • Verified data anchored to the baseline (bottom of stack)
  • Imported data hatched on top
  • Tooltip shows explicit breakdown: "Verified Platform: X / Imported Historical: Y / Total: Z"

Accessibility (WCAG 2.1 AA) ​

  • Not colour-dependent — hatching pattern distinguishes data regardless of colour perception (safe for deuteranopia, protanopia, tritanopia)
  • Graphical contrast — hatch lines in category main colour on category light background exceed 3:1 ratio (WCAG 1.4.11)
  • Screen reader support — valueFormatter and aria-label attributes include "Verified" / "Imported" labels
  • Multiple cues — colour + pattern + border style + icon all reinforce the distinction

When to apply ​

This pattern applies wherever imported/historical data appears alongside verified data:

  • Surgical logbook charts (bar, pie, doughnut)
  • Case list views and case cards
  • Dashboard summary statistics
  • Any future module that supports data import (e.g. CPD activity imports)

Code conventions ​

Source of truth ​

  • Marketing colours: instances/marketing/src/themes/colors.ts
  • In-app theme: instances/ppp/src/themes/
  • Widget colours: instances/ppp/src/components/widgets/constants/widgetConstants.ts
  • Routes & sections: instances/marketing/src/landing/constants.ts

Import pattern ​

typescript
import COLORS from 'themes/colors';

// Use tokens, not raw hex in components
bgcolor: COLORS.ppp.primary; // ✅
bgcolor: '#117be5'; // ❌ (except in the theme file itself)

Comment style ​

Write plain, descriptive comments. Do not prefix comments with an emoji — the previous 🤗-prefix convention has been dropped.

typescript
// This explains what the code does

Internal documentation — org members only