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.
| Scale | px | Usage |
|---|---|---|
1 | 8px | Tight internal padding |
2 | 16px | Item gaps, small padding |
3 | 24px | Card internal padding |
4 | 32px | Section row gaps |
5 | 40px | Footer top padding |
6 | 48px | Section padding (mobile) |
8 | 64px | Section padding (mobile large) |
10 | 80px | Section 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)
| Name | px |
|---|---|
xs | 0 |
sm | 600px |
md | 900px |
lg | 1200px |
xl | 1536px |
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/).
| Variant | Style | Usage |
|---|---|---|
| Primary CTA | contained, #177BE5, borderRadius: 12, px: 36, py: 12 | "Join the Waiting List", "Send" |
| Primary hover | bgcolor: #1268C4 | — |
| Outlined | borderColor: #1B1B1B, color: #1B1B1B | Secondary actions |
| Mobile CTA | borderRadius: 6, px: 24, py: 2, height: 36 | Responsive reduction |
textTransform: noneon all buttons — no ALL CAPSfontWeight: 500default,fontWeight: 600for 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 actionoutlined — secondary / discard (muted grey)text — low-emphasis / inlineoutlined · color="error" — destructive (pairs with a confirm dialog)disabled — action unavailablesize="small" — toolbars and dense rowsVariant — emphasis
| Variant | When to use |
|---|---|
contained | The single primary action in a screen or section (Submit, Save, Add). One primary per context. |
outlined | Secondary / discard actions (Cancel, Edit). Muted grey by default. |
text | Low-emphasis or inline actions; links rendered as buttons. |
Colour — meaning (from the theme palette — never inline a hex)
color | Meaning | Example |
|---|---|---|
primary (#117BE5) | Default call-to-action | Submit, Save, Add |
secondary | Neutral secondary action | — (default outlined look) |
error | Destructive / irreversible | Reset (delete plan), Delete |
success / warning / info | Status-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
fullWidthfor primary actions on mobile viewports.
States
- Loading:
startIcon={<CircularProgress size={16} />}anddisabledwhile 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) orrgba(255,255,255,0.08)(dark) - Subtle box shadow:
rgba(149, 157, 165, 0.2) 0px 8px 24px - Hover: elevation lift with
transition
Navigation — header
- Background: dark navy (AppBar)
- Nav links:
fontWeight: 300,fontSize: 0.8–0.875rem,color: white - Active state:
fontWeight: 600 whiteSpace: nowrapto prevent wrapping- No underline on links
Navigation — footer
- Horizontal row with
|pipe separators fontFamily: Nunito,fontWeight: 300,fontSize: 0.8125rem- Link colour:
rgba(255,255,255,0.72)→whiteon hover transition: color 0.15s
Dividers
- Default dark backgrounds:
rgba(255,255,255,0.12) - Light sections: MUI default
Form inputs
borderRadius: 12fontSize: 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.
| Asset | Usage |
|---|---|
laptop-device.png | Hero — laptop mockup showing CPD Home |
phone-device.png | Hero — phone mockup showing CPD Home |
laptop-ppp-home.png | Plain desktop screen used in the laptop mockup |
mobile-cpd-home.png | Plain phone screen used in the phone mockup |
shell-laptop.png | Empty laptop frame (magenta screen) |
shell-phone.png | Empty 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.
| Logo | File |
|---|---|
| Medical Board AHPRA | support-medical-board-ahpra.svg |
| Australian Medical Council | support-australian-medical-council.svg |
| CSIRO | support-csiro.svg |
| Australian Government | support-australian-govt.svg |
| Queensland Government | support-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):
| Category | Primary | Light (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
| Element | Verified (platform) | Imported (historical) |
|---|---|---|
| Chart fill | Solid colour | Diagonal hatched pattern (45°, 3px stroke, 8px spacing) over light background |
| Chart border | None | 2px solid in category main colour |
| Card left border | 4px solid | 4px dashed |
| Card background | White | primaryLight (#f5f9ff) |
| Chip variant | Filled, green (#167D62) | Outlined, dashed, primary blue (#003977) |
| Chip icon | Checkmark (CheckIcon) | Clock/history (HistoryIcon) |
| Stat box | Solid fill in category main colour | Dashed 2px border, light background |
| Tooltip label | "Verified Platform" | "Imported Historical" |
SVG hatch pattern definition
<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 —
valueFormatterandaria-labelattributes 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
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.
// This explains what the code does