Skip to content

Design System ​

Feature Overview ​

Global brand and design-token concerns that apply across the whole PPP app, not scoped to any single module: colour tokens, typography, spacing, and shared component standards (buttons, cards, inputs). The brand reference lives in the docs site under Brand — docs/site/brand/; this spec holds the testable, app-facing acceptance criteria.

The single source of truth for component styling is the MUI theme at instances/ppp/src/themes/index.tsx, driven by tokens in instances/ppp/src/themes/tokens.ts and colors.ts. Call sites set semantic props (variant, color, size), never raw style values.

Layering contract ​

The atomic-design L3 push (epic #9176) makes the implicit layering explicit so it can be enforced and migration progress measured. This contract is the canonical statement of the layers; the guards (#9178, #9181) and the inventory (#9177) all cite it.

The primitive layer ​

The canonical primitive layer is the MUI theme — instances/ppp/src/themes/index.tsx wiring the design tokens in instances/ppp/src/themes/tokens.ts and instances/ppp/src/themes/colors.ts (plus icons.ts). All colour, spacing, radius, typography and elevation values originate here. These token-definition files are the only place raw colour/spacing literals are allowed to live.

The shared primitive components that consume the theme and are reusable across every feature are:

  • The @ppp-org/core-ui package exports (ActionDialog, Autocomplete, AvatarUploader, DataListTable, DatePicker, DateRangePicker, DialogExitGuard, FileDropZone, FilterBox, Illustration, ImgAvatar, MonthRangeFilter, MultiSelect, NumberInput, Picker, ReportDataGrid, RouteLink, SampleButton, SignatureUploader, Spinner, TextFieldClear, EditableDisplayField, InlineFieldEditor, and the autocomplete/exit-guard hooks).
  • The local shared kit under instances/ppp/src/components: FormLayout (Section/Row/Field/Actions), SectionCard, PageLayout, the buttons/ kit, and the filters/ kit (PillDateRangeFilter, GenericFilterBar).

There are no literal atoms/ or molecules/ directories. The vestigial components/atoms/ (EmailField, PasswordField) and components/molecules/ (LoginFormFooter) — which held only three login-form fields and never reflected a real atomic-design taxonomy — were retired in #9177 and relocated to a feature-honest components/auth/. They are feature components (the login surface), not design-system primitives.

The no-raw-literal rule ​

Feature code carries no raw colour or spacing literals. Anything under instances/ppp/src/modules, src/forms, src/slots, and feature components must source colour from COLORS / SEMANTIC_COLORS tokens and spacing/typography from the SPACING / FORM_SPACING / TYPOGRAPHY_SCALE / FONT_SIZE token sets — never an inline hex or px string. The reproducible baseline of current violations (regenerated by scripts/raw-literal-inventory.mjs into docs/site/architecture/raw-literal-inventory.md) is the measure migration drives down (target density below 2.0). The earlier reported baseline of 6.60 was inflated: the detector counted every #NNNN GitHub issue reference in a comment as a raw hex colour. Counting only real string-literal colour/spacing values, the honest baseline is 0.88 (#10070). The migration and its build-failing guard land in #9178.

The dependency-direction rule ​

Primitives must not depend on feature concerns. A shared primitive (@ppp-org/core-ui export or the local FormLayout/SectionCard/PageLayout/buttons/filters kit) must not import data-access or app-state modules — specifically utils/trpc, the tRPC router, or any store module — because doing so turns a reusable primitive into a feature component. Presentational navigation primitives (react-router-dom's Link, used by PageLayout and core-ui's RouteLink) are not barred — they carry no data/state coupling. This direction is enforced by the no-restricted-imports layering guard in #9181.

Open Questions ​

All questions have been answered.

Acceptance Criteria ​

Brand tokens ​

  • ✅ design-system.brand.primary-consistent — the brand primary colour is sourced from COLORS.ppp.primary; no production component hardcodes a different brand primary (e.g. #1976D2). Interactive elements using primary meet WCAG AA contrast on white. (#4735)
  • ✅ design-system.brand.no-urbanist-override — the brand typeface is Nunito; no production component reintroduces an inline fontFamily override that names Urbanist, and the FONT_FAMILY body/heading/mono tokens never reference Urbanist. Guards the residual leftover after the Urbanist→Nunito migration where the dashboard root Box hardcoded Urbanist and silently fell back to Inter. ‡ (#7786, 1 Jun)
  • ✅ design-system.brand.logo-wordmark-nunito — the logo wordmark is set in Nunito (the brand typeface), not Urbanist; every logo SVG (ppp-full-black-text, ppp-full-white-text, both vertical lockups) embeds a Nunito subset @font-face and names 'Nunito' in font-family, and no logo SVG references Urbanist. The initial P of each word is font-weight: 700, the remainder 400, preserving the "PPP" rhythm. † ‡ (#8185, 3 Jun)
  • ✅ design-system.brand.logo-vertical-lockup — a vertical logo lockup (emblem above a three-line stacked wordmark, bold initial P of each line aligned into a "PPP" column) is published in black-text and white-text variants and documented on the Brand → Logo & Assets page with downloadable SVGs. † ‡ (#8185, 3 Jun)
  • ✅ design-system.brand.logo-side-lockup — a side-text lockup (unmodified emblem on the left, three-line stacked wordmark on the right — Professional / Performance / Portfolio, bold initial P per line) is published in black-text and white-text variants, documented on the Brand → Logo & Assets page, and rendered by the app sidebar header in place of the former inline 'DM Sans' brand text (removing the last off-brand inline brand-font override from the header). Derived 1:1 from the vertical lockup: same embedded Nunito subset and emblem PNG, 17px emblem→wordmark gap (matching the horizontal lockup), Nunito 30px on a 40px line rhythm, 290×106 canvas. The lockup recombines only approved brand elements; the new arrangement is an engineering default pending Matt's sign-off (for-discussion on #10151). † ‡ (#10151, 7 Jul)

Layout spacing ​

  • ✅ design-system.layout.sticky-topbar-clearance — in-page section headings clear the sticky topbar instead of being crowded against, or clipped beneath, it. The app shell applies LAYOUT.sectionScrollMargin as scroll-margin-top to headings and [id] anchors; the token is at least the sticky topbar height plus breathing room. † (#7767, 27 May)
  • ✅ design-system.form-spacing.global-tokens — every form (WBA, CPD, Wellness, etc.) consumes a single FORM_SPACING standard from instances/ppp/src/themes/tokens.ts for fieldGap / groupGap / sectionGap / dialogPaddingX / dialogPaddingY; forms never inline per-form SPACING.base magic numbers for between-field gaps or modal padding. The WBA create modal and the shared FieldGroupContainer both consume FORM_SPACING. † ‡ (#7829, 28 May)
  • ✅ design-system.form-layout.compose-from-kit — every PPP form composes from the shared components/FormLayout kit (FormLayout.Section / Row / Field / Actions) + FORM_SPACING tokens + shared field objects (FormFieldContainer / FieldGroupContainer); no form under instances/ppp/src/forms hand-rolls a bespoke gridTemplateColumns or display: 'grid' form root, and no form inlines per-form spacing literals. Enforced by the check-form-layout.mjs CI gate (a narrow, issue-tracked allowlist covers the residual not-yet-migrated forms in #8161). Capstone of the #8111 forms-standardisation epic that migrated all in-scope forms onto the kit. † ‡ (#8137, 2 Jun)
  • ✅ design-system.form-actions.sticky-mobile — on mobile, a long form's primary action bar (Save / Submit / Edit / Discard) stays pinned and reachable above the on-screen keyboard instead of scrolling away or hiding behind it on the last fields. The shared FormLayout.Actions sticky primitive pins the row (position: sticky; bottom: 0) and reserves env(safe-area-inset-bottom) below the controls so they clear the keyboard / home indicator. Sticky positioning only pins against a bounded scroll ancestor, so the host dialogs that mount a long form (Logbook case + review, CPD add/view, WBA create/review, the linked reflection/WBA/feedback modals, and the Work-Queue record dialog) open with scroll="paper" — making MUI DialogContent the bounded scroll container — instead of scroll="body" (which scrolls the whole document and gives sticky nothing to pin against). The long forms (logbook case, ManualCPD, WBA, Reflection, Give/Received Feedback, logbook review) pass sticky on their primary FormLayout.Actions row; the shared FormActionsSection defaults sticky=true. Worst case before the fix: the Logbook case form, where a surgeon could not reach Save on a phone. † ‡ (#9324)
  • ✅ design-system.pill-date-filter.global-style — every "range pill" switcher (PPP Pulse, WBA, CPD, Wellness) reads its visual rules (pill shape, padding, border, active background, active text) from a single PILL_TOGGLE / PILL_TOGGLE_SX token block in instances/ppp/src/themes/tokens.ts; no surface inlines a hex/px for these styles. The shared PillDateRangeFilter primitive and Pulse ScoreHistoryChart both spread PILL_TOGGLE_SX into their <ToggleButtonGroup>. † ‡ (#7834, 28 May)

Widget sizing ​

  • ✅ design-system.widget.tokenised-sizing — dashboard widgets size to their content via a tokenised sizing scale, not a single hard-coded height. The shared components/widgets/BaseWidget primitive resolves its minimum height from a WIDGET_HEIGHT token set in instances/ppp/src/themes/tokens.ts (auto / sm / md / lg / xl) exposed through a size prop that defaults to auto (content-fit), so a sparse stat/donut tile (e.g. the Timesheet "Missed Lunch Breaks" widget — a single donut) no longer reserves a fixed ~400px card of empty whitespace. Before this, BaseWidget defaulted height = 400 (applied as minHeight) and each Timesheet/Surgical/WBA widget passed its own raw px (380 / 400 / 580 / 300) while wrapping its chart in a Box locked to a literal height: '400px' — every tile was forced to ~400px regardless of content density. The sparse Timesheet donut widgets (Missed Lunch Breaks, Fatigue Shifts, Overtime Shifts, Recall Hours) drop their fixed inner height and fall through to the content-fit default; chart-heavy widgets opt into a named size token (sm/lg/xl) that preserves their existing footprint, so no widget that legitimately needs the height shrinks. Widget height/sizing is sourced from tokens — no raw px literal sets a BaseWidget height. Found during the demo rehearsal. † ‡ (#9191)

Typography ​

  • ✅ design-system.typography.rem-scale — the MUI theme wires a single rem-based type scale (TYPOGRAPHY_SCALE in instances/ppp/src/themes/tokens.ts) into every typography variant — h1–h6, subtitle1/2, body1/2, button, caption, overline — with each fontSize derived from the existing px FONT_SIZE tokens (px ÷ 16 = rem) plus an explicit lineHeight/fontWeight, and no variant falls below the MIN_READABLE_FONT_SIZE 12px (0.75rem) floor. The theme export is wrapped in MUI responsiveFontSizes() so heading sizes scale down at small breakpoints. Because every variant now resolves to a shared rem value (not MUI's stock defaults plus per-feature inline px), two previously-divergent screens render matching heading/body sizes at the same zoom, and a lint guard errors on new raw inline numeric fontSize in src/modules so call sites adopt the scale. The T1–T5 migration of existing offenders (#9077/#9079/#9080/#9081/#9082) plus the T6 capstone (#9083) eliminated all inline numeric fontSize literals in src/modules; decorative icon sizes use the ICON_SIZE token set and PDF point sizes use SEMANTIC_COLORS.pdf.fontSize. With the migration complete, the no-restricted-syntax guard was promoted from 'warn' to 'error' (#9083) so any reintroduced literal blocks CI at Tier 1. † ‡ (#8940, #9083)
  • ✅ design-system.page-header.canonical-title — every screen renders its page title through the shared components/PageHeader atom as a single semantic <h1>, styled token-driven at 24px (FONT_SIZE.lg) / bold (FONT_WEIGHT.bold) / text.primary; no page hand-rolls a page title at a different size or non-h1 level. The atom previously rendered the title at MUI variant="h5" (~18px), so consumer pages were undersized while the dashboard hand-rolled a 24px title — the same cross-feature heading drift as design-system.typography.rem-scale. The audit-and-migration pass moved My Profile, Wellness, Action Items, User Guide and the CPD Dashboard greeting onto the standard and added the missing title to Timesheet and PPP Passport. The atom exposes an optional description and right-aligned actions slot (used to carry help buttons, autosave status, date pickers); its title row stacks (xs: column) on mobile. † ‡ (#9213)

  • ✅ design-system.page-header.help-first-in-actions — the contextual Help affordance (components/HelpButton) is owned by the PageHeader atom, not hand-placed per page: a page passes helpGuideSection and PageHeader renders <HelpButton> itself, immediately beside the heading text (one gap unit, inside the title Box) — structurally separate from the right-aligned actions Stack, and never hand-rolled by a page after the title Typography. Superseded the original #9213 placement (#9887): Help was first standardised as "the first child the page threads into actions=", which put both the placement and the ordering guarantee in every caller and let it drift one page at a time. #9887 moved it out of actions entirely — on wide screens a far-right help icon reads as detached from the heading it explains — and moved the render into the atom, so the guarantee is now about ownership rather than ordering: a page declares the guide section and cannot place the button wrongly. A page that still hand-rolls </Typography><HelpButton> is bypassing the atom and is treated as a violation, which is the drift this AC exists to catch. Before this drive the Help button was placed inconsistently across screens: inline after the page title on some pages (My Profile, Billing, Plans & Pricing, CPD Activities, the Hospital admin dashboards, Notifications), buried in a secondary meta row beneath the title (CPD Plan), or duplicated on a second sub-header (Timesheet, Action Items). Standardising on "Help = first child of actions" gives the help control one predictable position on every screen, so a doctor learns where to find help once. † ‡ (#9213)

Layering (atomic-design L3) ​

  • ✅ design-system.layering.primitive-contract — the spec documents the canonical layering contract: the MUI theme (themes/index.tsx + tokens.ts/colors.ts) is the canonical primitive layer and the only place raw colour/spacing literals may live; the shared primitive components are the @ppp-org/core-ui exports plus the local FormLayout/SectionCard/PageLayout/buttons/filters kit; feature code carries no raw colour/spacing literals; and a primitive must not import data/store/router modules (utils/trpc, the tRPC router, a store). The vestigial literal components/atoms/ + components/molecules/ dirs (which held only the three login-form fields) are retired and relocated to a feature-honest components/auth/. The reproducible inventory at docs/site/architecture/raw-literal-inventory.md (regenerated by scripts/raw-literal-inventory.mjs) fixes the migration baseline (target density below 2.0; honest string-literal baseline 0.88 after the #10070 counting fix — the original 6.60 counted GitHub issue refs in comments as hex) so #9178 can track its delta, and the no-raw-literal + dependency-direction rules are the spec anchors the #9178 (token migration + raw-value guard) and #9181 (layering import guard) build against. The "Layering contract" section above is the canonical statement. † ‡ (#9177)

  • ✅ design-system.no-raw-literals.guarded — raw hex colour literals in CSS colour properties (color / backgroundColor / background / borderColor / bgcolor / fill / stroke) inside src/modules production files are build-failing at CI Tier 1. The no-restricted-syntax guard added in instances/ppp/eslint.config.mjs (scoped to src/modules/**/*.{ts,tsx}, tests/stories excluded) targets identifier-key and string-literal-key property forms; it errors when the value starts with #. PDF-local PDF_COLOR consts are deliberately exempt — their object keys are descriptive names (black, brandNavy), not CSS property identifiers, so the selector never fires on them. All pre-existing violations were migrated to SEMANTIC_COLORS tokens from themes/tokens.ts in migration chunks #9297–#9307; three new accent tokens (dangerStrong #d32f2f, warningStrong #ed6c02, teal #00897b) were added to SEMANTIC_COLORS.accent to cover MUI palette shades that had no existing entry. A standalone CI script (.github/scripts/check-raw-literals.mjs, wired into ci.yml after the primitive-layering guard) proves the rule via negative + positive fixtures before scanning the real module tree — identical to the check-primitive-layering.mjs (#9181) pattern. Any reintroduced raw hex in a CSS colour property now blocks the lint job. Mirrors design-system.typography.rem-scale (#9083) where the equivalent fontSize guard was promoted warn → error. † ‡ (#9308)

Mobile touch affordances ​

  • ✅ design-system.disabled-reason.visible-on-touch — a disabled (or otherwise unavailable) control's reason is visible without hover on mobile. The shared components/DisabledHint primitive wraps a disabled control and renders its reason as a hover Tooltip on desktop and as visible caption text directly below the control on xs, because MUI's hover Tooltip never fires on touch — so the historical "tooltip-only-disabled" pattern (e.g. the greyed Wellness "Refresh now" button, which only said "Connect at least one data source first" in a tooltip) left a touch user staring at a dead control with no explanation. Its always-enabled sibling components/DisabledHint/InfoHint does the same for informational badges/chips that carried their "why" only in a hover tooltip (the Wellness readiness "Estimated from phone data" and intra-night "updated" chips). Rolled out to the Wellness dashboard Refresh button and the readiness info chips. † ‡ (#9331)

  • ✅ design-system.disabled-reason.aria-describedby — the reason text rendered by DisabledHint/InfoHint is programmatically associated with its control via aria-describedby, so a screen-reader user on the control hears both the label and the reason (e.g. "Refresh now, button, Connect at least one data source first, dimmed."). The reason element receives a stable useId()-generated id; the sibling control wrapper references it with aria-describedby. The visible caption is kept — no aria-label is added that would diverge from the visible text (#7773). (#9370) ‡

  • ✅ design-system.autocomplete.mobile-not-clipped — searchable pickers in mobile dialogs are not clipped by the on-screen keyboard and have ≥44pt option rows. The shared components/MobileSafeAutocomplete/useMobileAutocompleteProps hook returns the props that make a disablePortal MUI <Autocomplete> mobile-safe: on xs it drops disablePortal so the listbox portals to <body> and floats above the dialog/keyboard instead of being clipped inside the short dialog DOM, caps the popup paper max-height so a long list scrolls within a bounded area, and gives every option row a minHeight of the 44px touch target (COMPONENT.touchTarget.minSize); on desktop it preserves the original in-dialog disablePortal: true behaviour unchanged. Rolled out to the logbook hospital/consultant pickers, the assessment assessor/hospital pickers and the settings surgery lookup. † ‡ (#9331)

Tables (responsive) ​

  • ✅ design-system.table.mobile-card-fallback — data tables collapse to a card / stacked-row layout on mobile with all row actions reachable, and never side-scroll on a phone. The canonical primitive is components/PppDataTable (built in #9250): a single generic, headless-TanStack-Table-powered molecule that renders a real columnar <table> on desktop/tablet and STACKED label-value cards (one card per row, header = label, cell = value) below the down('sm') breakpoint — one component, two renders. Authors attach mobile metadata through the standard TanStack meta slot (mobileLabel, align, hideOnMobile). Consumers that page server-side or render a short fixed list pass disablePagination; with pagination off the footer-range calc falls back to a single all-rows window rather than reading the (now-undefined) pagination state. Every data-table surface in the app adopts this primitive (or, for a reference table with a complex multi-row header that is not a flat columnar fit, a bespoke one-card-per-row mobile branch driven off the same down('sm') query) so no table forces a horizontal scroll on a phone and no row action is dropped at narrow widths. † ‡ (#9250, #9263, #9282, #9326)

  • ✅ design-system.table.wide-table-rollout — the wide tables the mobile audit flagged with NO card fallback (a horizontal side-scroll on a phone) are migrated onto the canonical responsive table so every column and every row action stays reachable on a narrow viewport: Attendance history (cert-download action preserved), Additional Medical Registrations (the profile-accordion list), the MCR rating-scale reference table (6-col side-scroll → one stacked card per supervision level), DailyInputs metrics (4-col), the Approver-portal detailed time-entries (8-col, grand-total preserved as a summary line below), and the Admin Users list — whose mobile view previously dropped the hospital-role toggles and the break-glass reset-link (a feature cut-off vs the desktop DataGrid). Those role toggles (Admin / Hosp. Super / Hosp. Admin) and the reset-link are restored on mobile so a super-admin on a phone has the same role-management reach as on desktop. † ‡ (#9326)

  • ✅ design-system.table.grid-overflow-and-density — the shared MUI-DataGrid primitive components/DataGrid/DefaultStyledDataGrid (DSDG) neither silently clips overflowing columns, holds a fixed dead-whitespace band when empty, nor crushes every column at narrow widths. Three foundation behaviours, all in the one primitive (#9893): (1) an always-visible horizontal overflow scrollbar — the grid's virtual scroller is styled (scrollbar-width: thin + a styled ::-webkit-scrollbar that opts the scroller out of overlay/auto-hiding behaviour) so that when columns overflow the container the overflow is an honest, visible scroll and never a silent clip with no affordance; (2) a compact empty state — when the grid has no rows and is not loading it collapses to a compact EMPTY_DATAGRID_TABLE_HEIGHT (200px) instead of holding the fixed BASE_DATAGRID_TABLE_HEIGHT (700px) or an explicit height, killing the ~500px dead band under a short/empty table; a content-sized height="auto" grid already shrinks to its content when empty, so it is never force-collapsed (which would otherwise cause a load-time height jump on a grid that starts empty then populates); a caller can opt out with collapseWhenEmpty={false} where a layout deliberately reserves a fixed table slot; (3) an additive responsive column-priority model — a column may declare hideBelow?: 'sm' | 'md' | 'lg' and DSDG filters it out via useMediaQuery when the viewport is below that breakpoint, so low-priority columns drop out on narrow containers instead of all columns being crushed to their minimum width; a column without hideBelow behaves exactly as today. This is the primitive-level fix; per-table adoption of hideBelow in each column definition is an ongoing wave-2 sweep — PR #10059 adopted it on 4 of the ~20 flagged tables (WBA, Feedback, Reflection, Timesheet); the remaining tables and the rest of wave 2 (mobile card consistency, hospital-list pagination, hydration fix, WBA access-denied query, DatePicker prop leak, re-audit) stay tracked under #9893. † ‡ (#9893)

Buttons (Product UI) ​

The full button standard is documented at Brand → Components → Buttons.

  • ✅ design-system.button.theme-centralised — every in-app <Button> is styled by the MuiButton theme block (radius, padding, font weight, textTransform, mobile sizing). Call sites set only variant / color / size / fullWidth; colour, radius, padding and textTransform are never hardcoded on a button (mirrors no-hardcoded-brand-values). † (27 May)
  • ✅ design-system.button.no-all-caps — buttons never render ALL CAPS; textTransform: none is enforced by the theme for contained, outlined and text variants. † (27 May)
  • ✅ design-system.button.variant-emphasis — contained = the single primary action per context; outlined = secondary / discard (muted grey by default); text = low-emphasis / inline. † (27 May)
  • ✅ design-system.button.destructive-error-colour — destructive / irreversible buttons use color="error" and render in the error palette colour (COLORS.ppp.error, red), not the muted discard grey. The theme declares an outlined + error variant after the generic outlined variant so the error colour wins. Destructive buttons must also be gated by a confirmation dialog. Proven by the CPD Plan Reset button (see cpd.md → cpd.plan.reset.*). † (27 May)
  • ✅ design-system.submit-button.single-fire — submitting a form disables the primary action and shows a pending state (spinner + a loading label) until the mutation settles; a rapid double-tap fires the mutation at most once (no duplicate record). The reusable SubmitButton form-primitive (instances/ppp/src/components/SubmitButton/) wraps MUI Button with { isPending, disabled, loadingLabel } — while isPending it disables the button (a disabled button cannot fire onClick) and hard-guards the handler, so an unguarded mobile double-tap on Save/Submit can no longer create a duplicate record. Rolled out to every primary create/update action that previously lacked an in-flight guard: Timesheet Save + Submit-for-Approval, WBA / Reflection / Feedback Save + Submit, CPD-plan Save, and the settings CRUD Submit/Save. † ‡ (#9323)

Evidence uploads ​

  • ✅ design-system.file-upload.camera-capture — evidence uploads on mobile offer a camera-capture path ("Take photo") alongside the library/file pick (the broad library option is never suppressed), and show per-file upload progress while a file uploads. One shared FileUpload molecule (components/FileUploadButton) owns the behaviour: it renders the existing library button plus a CameraCaptureInput affordance (a dedicated hidden input type=file with capture="environment" accept="image/*") that appears when useCameraSupport().isMobile is true, and a determinate/indeterminate spinner driven by an isUploading/uploadProgress prop pair. The molecule is rolled out to the three evidence surfaces — CPD evidence (FileUploadButton via ManualCPDFormView), Passport documents (DocumentForm) and immunisations (ImmunisationsCard), the latter two embedding the same CameraCaptureInput next to their bespoke library pick — so a doctor photographing a certificate on their phone gets a camera path and visible upload feedback on every surface. † ‡ (#9327)

Form controls (mobile) ​

  • ✅ design-system.date-picker.mobile-native — on mobile (below the sm breakpoint), date and date-time fields open a native picker (a wheel / calendar modal) rather than a typeable desktop field with a popover calendar. A single shared primitive, components/PppDatePicker (exporting PppDatePicker + PppDateTimePicker), renders the MUI MobileDatePicker / MobileDateTimePicker variant below sm and the desktop variant at sm and up, preserving every caller prop (disableFuture, format, ampm, value/onChange, and slotProps error/helperText/placeholder wiring). The open-picker adornment button is floored at a 44px touch target. Every user-facing date field — logbook (Date, patient DOB), CPD (Manual CPD), WBA (CBD/CEX/MCR/QMF/SSAPBA), Reflection (incl. EOY/Review), Feedback (Give/Received), MCR, MSF, PPP360, profile (Work & Pay, Surgical Cadence), audit events, and the Timesheet entry Start/End date-time + Submit-for-Approval — composes from this primitive rather than the raw @mui/x-date-pickers picker. † ‡ (#9325)
  • ✅ design-system.form-field.label-readable-on-mobile — the shared components/FormFieldContainer field label and helper text render at ≥16px on a mobile viewport (below the sm breakpoint) and step down to the compact desktop sizes only at sm and up, so desktop sizing is unchanged. Those label/helper strings carry the clinical question text in MSF/WBA/CPD forms, so the previous hard-coded 13px label / 12px helper were both unreadably small on a phone and, sitting below 16px next to an input, could trigger an iOS Safari/WKWebView focus-zoom that scrolls the field out of frame. The label (both the semantic <label> and the <span> fallback) and the helper Typography now render mobile-first at FONT_SIZE.md (16px) and drop to FONT_SIZE.sm (13px) / FONT_SIZE.xs (12px) respectively inside a theme.breakpoints.up('sm') block. † ‡ (#9535)

Mobile a11y enforcement ​

  • ✅ design-system.a11y.mobile-gate — Mobile touch-target + accessibility rules are enforced in CI, so the #9342 form touch-target floors and the #7773 semantic-control rule cannot silently regress: a sub-44pt interactive control or a non-semantic onClick fails the build. Two layers. (1) A PR-blocking jsx-a11y gate (scripts/check-jsx-a11y.mjs, wired as the PPP Mobile a11y Gate CI job and surfaced through the blocking CI Summary) runs the strict eslint-plugin-jsx-a11y preset tree-wide over all of instances/ppp/src + e2e (pnpm lint:a11y:all) — a <div onClick> without a role/keyboard handler, an unlabelled control, or an invalid ARIA role errors out, whether the offending file was touched by the PR or not. The gate was originally diff-scoped (#9332) because instances/ppp lints with its own .eslintrc-ide-base.json (not packages/config-eslint) so the strict preset was never enforced here and turning it on tree-wide surfaced ~40 pre-existing violations (mostly jsx-a11y/no-autofocus on long-standing dialog first-fields); #9423 burned that debt down — fixing the genuine violations and eslint-disable-ing the autofocus sites with a per-site written justification where autofocus is correct dialog/edit-in-place focus management — so the gate is now tree-wide, also catching regressions that reach untouched files via a shared-component or codemod change. (2) A nightly axe target-size + 44px-floor suite (instances/ppp/e2e/storybook-a11y/form-target-size.spec.ts) runs @axe-core/playwright's target-size (+ label, color-contrast) rule over every form-component primitive's mobile render AND measures each interactive control's bounding box against the 44px floor (COMPONENT.touchTarget.minSize) — axe's rule only enforces the weaker WCAG 2.5.8 24px floor, so the explicit measurement is what locks in the #9342 44pt (WCAG 2.5.5 / Apple HIG) floor. A negative fixture proves both gates trip: a committed jsx-a11y violation fixture exits the gate non-zero (unit-tested in scripts/check-jsx-a11y.test.ts), and the axe suite asserts a deliberately sub-44pt control is flagged. On the native side, eslint-plugin-react-native-a11y structural rules (valid accessibilityRole/state/value, no nested touchables) are enforced at error in mobile/ppp. † † ‡ (#9332, #9423)

Documentation & Storybook ​

  • ✅ design-system.docs.storybook-published — the docs site publishes the component Storybook at /storybook/ and links to it. † ‡ (#8269, 3 Jun)
  • ✅ design-system.primitive.tested — every shared primitive carries at least one render (visual-regression) assertion AND at least one accessibility (axe) assertion. A Storybook-driven Playwright suite (instances/ppp/e2e/storybook-a11y/primitives.spec.ts) discovers every primitive story from the published Storybook index — each @ppp-org/core-ui export plus the local FormLayout / SectionCard / PageLayout kit — renders each one in a headless browser (render assertion + VR screenshot artefact) and runs @axe-core/playwright over each primitive's default render, asserting zero serious/critical violations. The suite runs as a non-Tier-1 / nightly job (storybook-nightly.yml) so it never gates the merge queue. Closes audit dimension 5 (primitive testing) — tests.primitive_test_files is now non-zero against the shared layer. Pre-existing shared-theme/third-party findings the suite surfaced (primary-blue #117be5 contrast 4.2:1; @easepick month-nav buttons unnamed) were allowlisted with a tracking issue (#9277) rather than masked, then driven to zero in #9277 — the interactive primary was darkened to #0F6FD3 (4.96:1, WCAG AA) and the DateRangePicker nav arrows were labelled, so the PRE_EXISTING_PRIMITIVE_A11Y allowlist is now empty. The clear-button accessible-name gap on the TextFieldClear primitive was fixed in the same change. † ‡ (#9179)
Open GitHub Issues ​

Open issues on label:feature:design-system — no open issues. Fetched at: 2026-10-13T07:29:49Z — live list on GitHub.

Change Log ​
DateChangePR/IssueReason
2026-10-04Added a sitewide :focus-visible outline (2px solid brand primary, 2px offset, from COMPONENT.focusOutline) to the MUI CssBaseline overrides, covering links, buttons, summary, tab/menuitem/link/button roles and positive-tabindex elements.#0, #12698No control showed a keyboard focus ring anywhere in the app, which capped every design-review at the DESIGN.md accessibility floor (R6). The rule is a static CssBaseline object because MUI emits a function value under a CssBaseline key as literal text; the existing body callback in the same override is affected the same way and is tracked separately.
2026-08-12Re-pointed the design-system and onboarding BDD file-assertions at the paths their guarded code actually occupies after the ADR-0003 bounded-context move, and reworded AC design-system.page-header.help-first-in-actions to describe the shipped #9887 pattern — PageHeader renders HelpButton from its own helpGuideSection prop ahead of the actions slot — instead of the superseded #9213 wording that required each page to thread Help in as the first child of actions=.#11526, #11515, #11530The assertions had been dead on uat since the reorganisation but nothing executed them, so nothing reported it (the #11320 defect class — a green BDD check is not full coverage). PR #11526's @requires-backend tagging sweep pulled them into the bounded per-PR job for the first time and they failed immediately on ENOENT/ENOTDIR and on stale structural expectations. Every target was re-verified to still contain the behaviour its assertion guards before re-pointing, so the scenarios now pass for the right reason rather than by pointing at a trivially-clean file; none was deleted or silenced to go green. The AC rewording follows the standard rather than the reverse: #9887 deliberately moved the ordering guarantee out of every caller and into the atom, so the outcome a doctor sees is unchanged while a page can no longer get the order wrong. The remaining HealthSettings.tsx violation is a genuine product gap tracked separately as #11534 and was left failing rather than masked.
2026-07-07New side-text logo lockup (unmodified emblem left, three-line stacked Nunito wordmark right, bold initial P per line) published as ppp-side-black-text-v1.svg + ppp-side-white-text-v1.svg and documented on Brand → Logo & Assets; the app sidebar header now renders it in place of the emblem PNG + inline 'DM Sans' Typography. New AC design-system.brand.logo-side-lockup.#10157, #10151The sidebar header wordmark was set in 'DM Sans' — not the brand typeface (Nunito, Brand Guidelines v1.0) and not an approved logo asset. The lockup is derived 1:1 from the vertical lockup masters (same embedded Nunito subset and emblem PNG, 17px gap matching the horizontal lockup, 30px/40px line rhythm) so at the 42px header height the three stacked lines stay legible where the single-line horizontal wordmark would be ~7px tall. The arrangement recombines only approved brand elements and ships as an engineering default pending Matt's sign-off (for-discussion on #10151).
2026-07-06Raw-literal inventory now counts hex/px only inside string/template literals, not in comments — fixing a detector that scored every #NNNN GitHub issue reference as a raw hex colour. The scanner also gained nested template-literal interpolation support and regex-literal-aware parsing (including character classes) after PR review found both could silently drop or corrupt real literal counts.#10077, #10070, #9178The #9177 inventory ran #[0-9a-fA-F]{3,8} over raw file text, so ~97% of the reported "raw hex" was issue-ref noise in comments and the headline density (4.64) measured comments, not colours. Independent review of the initial fix found two further scanner defects that also under-counted real literals — a nested template interpolation (e.g. a ternary of two backtick strings inside ${}) closed the outer template early, and a regex literal containing an escaped closing-delimiter slash (e.g. /^https:\/\//) or a quote character inside a character class (e.g. /['"]/, a real pattern in passwordValidation.ts) desynced the scanner and swallowed subsequent real literals. Both are fixed and locked in by 5 new regression tests. Counting only real string-literal colour/spacing values, the honest frontend-wide baseline is hex 194, px 1135, density 0.88 — so #9178's density &lt; 2.0 AC is honestly already met. Corrects the cited baseline; the epic stays open for consolidated review.
2026-07-05Wave-2 DSDG responsive column adoption (slice 1 of ~20 flagged tables) — WBA, Feedback, Reflection, and Timesheet tables.#10059, #9893Four table consumers had crushed/clipped columns at common viewport widths. Added hideBelow responsive priorities to low-priority columns and reduced inflated widths (e.g. Feedback Hospital 750px→250px, Status 620px→160px). Advances the "per-table follow-up" in the grid-overflow-and-density AC — the remaining ~16 tables and the rest of wave 2 (mobile card consistency, hospital-list pagination, hydration fix, WBA access-denied query, DatePicker prop leak, re-audit) are still outstanding under #9893.
2026-07-04Hardened the shared DefaultStyledDataGrid primitive — always-visible horizontal overflow scrollbar, compact empty state (fixed/explicit-height grids collapse to 200px when empty and not loading; content-sized height="auto" grids are never force-collapsed, so they don't jump on load; opt out with collapseWhenEmpty={false}), and an additive hideBelow responsive column-priority model.#10027, #9893A 150-capture Playwright table audit found DSDG the systemic root cause of the table defects — silent column clipping with no scroll affordance, a fixed 700–800px empty-grid whitespace band, and no responsive column model. Foundation PR hardens the primitive; per-table hideBelow adoption is a tracked follow-up.
2026-06-27Burned down the ~40 pre-existing jsx-a11y violations under instances/ppp/src so the #9332 PR-blocking gate could be promoted from diff-scoped to tree-wide. Fixed the two genuine violations (invalid role="legend" → role="group" on the surgical-logbook TargetGaugeWidget colour key; aria-label="Competence area" on the unlabelled corner &lt;th&gt; of the 360-review rating table) and eslint-disabled the ~24 no-autofocus sites with a per-site written justification, because autofocusing a dialog's first field / primary action, an edit-in-place inline field, or the sole input of a single-purpose search/redeem surface is correct focus management. Registered jsx-a11y (rules off) in .eslintrc.no-any.js so the disable directives resolve under lint:no-any instead of erroring Definition for rule not found (the config already did this for react/react-hooks). Promoted the PPP Mobile a11y Gate CI job to run pnpm lint:a11y:all over all of src + e2e. Updated the design-system.a11y.mobile-gate AC to note the gate is tree-wide, added a .sources/issue-9423.json fragment, and added a @regression @issue-9423 BDD scenario proving the tree is clean and the gate runs tree-wide.#9625, #9423The #9332 gate was deliberately diff-scoped (strategy b) to block NEW regressions without an unbounded fix while the pre-existing debt was tracked separately. With the debt cleared, the gate now also catches regressions reaching untouched files (e.g. via a shared-component or codemod change), closing the gap.
2026-06-26Enforce mobile a11y in CI so the #9342 form touch-target floors and the #7773 semantic-control rule can't silently regress. Added a PR-blocking jsx-a11y gate (instances/ppp/scripts/check-jsx-a11y.mjs, wired as the active PPP Mobile a11y Gate CI job and surfaced through the blocking CI Summary) that runs the strict eslint-plugin-jsx-a11y preset over the CHANGED instances/ppp .ts/.tsx files of a PR — a new non-semantic &lt;div onClick&gt; or unlabelled control errors out. Added a nightly axe target-size + 44px-floor suite (e2e/storybook-a11y/form-target-size.spec.ts) that runs @axe-core/playwright's target-size (+ label/contrast) over every form-component primitive's mobile render AND measures each control's bounding box against the 44px floor (axe's rule only enforces the weaker WCAG 2.5.8 24px floor; the measurement locks in the #9342 44pt floor). A committed negative fixture proves both gates trip (scripts/check-jsx-a11y.test.ts + the axe suite). On the native side, eslint-plugin-react-native-a11y structural rules now run at error in mobile/ppp, and the 14 surfaced violations on touched screens were fixed. Added the design-system.a11y.mobile-gate and mobile.a11y.native-lint ACs, a .sources/issue-9332.json fragment, and a @regression @issue-9332 negative-fixture BDD scenario with 5 bound step defs.#9417, #9332Lock-in for epic #9320 — #9342 added the mobile 44pt floors for radios/checkboxes/small-buttons/rating chips, but nothing in CI stopped a future change dropping a control back below 44pt or re-introducing a non-semantic onClick. jsx-a11y was "wired" via packages/config-eslint (#7773) but instances/ppp lints with its own .eslintrc-ide-base.json, so the strict preset was never enforced here; turning it on tree-wide surfaces ~40 pre-existing violations (mostly jsx-a11y/no-autofocus), so the gate is diff-scoped to block NEW regressions without an unbounded fix (strategy b), with the pre-existing web debt burned down separately.
2026-06-25Made the #8787 sticky FormLayout.Actions bar actually pin on mobile and rolled it out to the long forms. Hardened the shared primitive once — FormLayout.Actions sticky now reserves env(safe-area-inset-bottom) below the pinned controls so Save/Submit clears the on-screen keyboard / home indicator, and the bounded-scroll-ancestor contract is documented. The host dialogs that mount a long form switched scroll="body" → scroll="paper" so MUI DialogContent is the bounded scroll container the sticky bar needs (LogbookCaseDialogs case + review, CPDActivities + CPDHomeV2 add/view, WBA create + review, the linked reflection/WBA/feedback modals, and the Work-Queue BaseRecordDialog; the non-form Operating-List scanner keeps scroll="body"). The long forms (ManualCPDFormView, WBAForm, ReflectionForm, GiveFeedbackForm, ReceivedFeedbackForm, ReviewLogbookCaseForm) pass sticky on their primary action row; the logbook case forms already default sticky via FormActionsSection. Added the design-system.form-actions.sticky-mobile AC plus logbook/cpd-activities/appraisals-wba form-spec cross-references, a @regression BDD scenario with three static-source step defs, and FormLayout unit tests.#9356, #9324The sticky action bar (#8787) needs a bounded scroll ancestor, but the host dialogs opened with scroll="body" so the whole document scrolled and the bar scrolled away / hid behind the keyboard on the last fields. Worst case was the Logbook case form — a surgeon could not reach Save on a phone (#9324, child of #9320).
2026-06-25Added the reusable SubmitButton form-primitive (components/SubmitButton/) wrapping MUI Button with { isPending, disabled, loadingLabel } — while pending it disables the button and hard-guards onClick, so a rapid mobile double-tap fires the create/update mutation at most once (no duplicate record). Rolled it out to every previously-unguarded primary action — Timesheet Save + Submit-for-Approval, WBA / Reflection / Feedback Save + Submit, CPD-plan Save, and the settings CRUD Submit/Save — threading each mutation's in-flight flag (TanStack Query v4 isLoading). New AC design-system.submit-button.single-fire; referencing ACs timesheets.submit.single-fire and wba.form.single-fire-save.#9352, #9323Child of the mobile-optimisation epic #9320. Multiple primary form actions lacked an in-flight disable, so a mobile double-tap created DUPLICATE records — a data-integrity bug. The atomic-design fix is ONE reusable primitive rolled out across the unguarded surfaces, not a per-form patch.
2026-06-25Added a shared PppDatePicker / PppDateTimePicker primitive (components/PppDatePicker.tsx) that renders the MUI MobileDatePicker / MobileDateTimePicker variant (native wheel / calendar modal) below the sm breakpoint and the desktop variant at sm+, preserving every caller prop (disableFuture, format, ampm, value/onChange, slotProps error/helperText/placeholder wiring) and flooring the open-picker adornment at a 44px touch target. Rolled the primitive out across every user-facing date field — logbook (Date, patient DOB), CPD (Manual CPD), WBA (CBD/CEX/MCR/QMF/SSAPBA), Reflection (incl. EOY/Review), Feedback (Give/Received), MCR, MSF, PPP360, profile (Work & Pay, Surgical Cadence), audit events, and the Timesheet entry Start/End date-time + Submit-for-Approval — replacing the raw desktop @mui/x-date-pickers picker.#9351, #9325Every date field used the desktop DatePicker (typeable text + popover calendar), which is fiddly and error-prone in a phone WebView; free-text dd/MM/yyyy HH:mm on the Timesheet Start/End was the single most error-prone mobile input (#9325, child of #9320). One wrapper primitive renders the native mobile picker below sm so doctors on phones get a wheel/calendar modal instead of typing dates by hand. Adds the design-system.date-picker.mobile-native acceptance criterion.
2026-06-25Visible-on-touch disabled reasons (DisabledHint/InfoHint) + mobile-safe Autocomplete wrapper (portal + bounded paper + 44pt option rows on xs), rolled out to Wellness Refresh/readiness chips and the logbook/assessment/settings pickers.#9331, #9320MUI hover Tooltips never fire on touch, so tooltip-only disabled reasons (greyed "Refresh now") and disablePortal searchable Autocompletes clipped behind the mobile keyboard left touch users with dead controls and unreachable options.
2026-06-25Added a camera-capture path and per-file upload progress to the shared FileUpload molecule (components/FileUploadButton). On mobile it now offers a "Take photo" affordance alongside the library/file pick (the library option is never suppressed), via a dedicated capture="environment" accept="image/*" input, plus an isUploading/uploadProgress spinner. Rolled the molecule out to the three evidence surfaces — CPD evidence (via ManualCPDFormView), Passport documents (DocumentForm) and immunisations (ImmunisationsCard), the latter two embedding the shared CameraCaptureInput next to their bespoke library pick with a per-file uploading spinner.#9328, #9327Doctors photograph certificates on their phone, but the evidence file inputs did not offer the camera and gave no per-file upload feedback. One FileUpload molecule offering a Take-photo path alongside (not replacing) the library pick, with per-file progress, gives a consistent mobile evidence-capture experience across CPD, Passport and immunisations. Child of #9320.
2026-06-25Third-wave responsive Table→Card rollout — the remaining wide tables the mobile audit found with NO card fallback are migrated onto the canonical PppDataTable (or, for the MCR rating-scale reference, a bespoke one-card-per-supervision-level mobile branch): Attendance history (cert-download preserved), Additional Medical Registrations, the MCR 6-col rating scale, DailyInputs metrics (4-col), the Approver-portal 8-col time-entries (grand-total kept as a summary line). The Admin Users mobile list, which had dropped the hospital-role toggles and the break-glass reset-link, has those restored. Also fixed a latent PppDataTable crash on the disablePagination path (table.getState().pagination was undefined).#9326A mobile audit (child of #9320, following the #9263/#9282 PppDataTable rollout) found these wide tables still side-scrolled on a phone with no card fallback, and the Admin Users mobile view silently dropped role-management actions that exist on desktop — a feature cut-off. Every table now collapses to cards/stacked rows on a narrow viewport with all columns and row actions reachable, and no table forces a horizontal scroll on a phone (design-system.table.mobile-card-fallback / design-system.table.wide-table-rollout).
2026-06-25Drove the two #9179-surfaced shared-primitive a11y findings to zero. Darkened the interactive brand primary from #117BE5 (4.21:1 on white, failing WCAG AA) to #0F6FD3 (4.96:1, passing AA) in COLORS.ppp.primary (and primaryHover → #0D5EC9, link → #0F6FD3), and mirrored palette.primary.main into the shared @ppp-org/config-mui theme so the published @ppp-org/core-ui Storybook and the PPP app agree. Added accessible names to the @easepick DateRangePicker month-nav arrows (aria-label="Previous month" / "Next month" via the picker view lifecycle hook). Cleared the PRE_EXISTING_PRIMITIVE_A11Y allowlist in primitives.spec.ts — the nightly gate now enforces both rules everywhere.#9293, #9277The #9179 primitive VR/a11y suite surfaced these as pre-existing shared-theme / third-party findings and allowlisted them with #9277 as the tracking issue. This closes #9277 so design-system.brand.primary-consistent (interactive primary meets WCAG AA on white) and design-system.primitive.tested (zero serious/critical axe violations) hold with no allowlist carve-outs.
2026-06-24Standardised the contextual Help button placement — it now always sits in the PageHeader actions slot as the first child (left of any other action), on every screen. Migrated the inline-after-title placements (Billing, Plans & Pricing, CPD Activities, Notifications, Action Items, Hospital admin dashboards, Health Monitoring Settings), the buried meta-row placement (CPD Plan) and the duplicated sub-header placement (Timesheet) onto the standard.#9250, #9213The Help button was placed inconsistently across pages — sometimes inline immediately after the page title, sometimes near a date picker, sometimes far-right with action buttons — so doctors could not predict where to find help. Anchoring it as the first child of the canonical PageHeader actions slot gives it one fixed, learnable position app-wide.
2026-06-24Canonical page-title standard — every screen renders its title through the shared components/PageHeader atom as a single semantic &lt;h1&gt; at 24px (FONT_SIZE.lg) / bold, token-driven. Atom updated from variant="h5" (~18px) to the 24px/bold &lt;h1&gt;; hand-rolled titles on My Profile, Wellness, Action Items, User Guide and the CPD Dashboard greeting migrated onto it; missing titles added to Timesheet and PPP Passport.#9205, #9213A header audit across every left-menu screen found the page title inconsistent in size and level — undersized 18px titles on all PageHeader consumers, 16px h6 titles on Wellness/User Guide, h5 titles on Action Items/Reports, and no title at all on Timesheet/PPP Passport. Standardising on one atom gives a consistent, professional header rhythm and closes the cross-feature heading drift (cf. #8940).
2026-06-24Added a primitive-layer visual-regression + accessibility suite (design-system.primitive.tested). A Storybook-driven Playwright suite (instances/ppp/e2e/storybook-a11y/primitives.spec.ts) discovers every shared primitive from the published Storybook — each @ppp-org/core-ui export plus the local FormLayout / SectionCard / PageLayout kit — render-asserts each story (with a VR screenshot artefact) and runs @axe-core/playwright over each primitive's default render, asserting zero serious/critical violations. Wired as a non-Tier-1 / nightly job in storybook-nightly.yml. Added a missing PageLayout Storybook story and fixed the TextFieldClear clear-button accessible name surfaced by the suite.#9179Atomic-design L3 (epic #9176), audit dim 5 (primitive testing) was 1/3 — 622 test files existed but primitive coverage was incidental (tests.primitive_test_files=0 against the shared layer). The suite gives every shared primitive a render + a11y assertion so dim 5 clears 2/3, without slowing the merge gate. Pre-existing shared-theme/third-party findings (primary-blue contrast 4.2:1; @easepick nav buttons unnamed) are allowlisted and tracked in #9277 rather than masked.
2026-06-23Promote the no-restricted-syntax inline-fontSize lint guard from 'warn' to 'error' (T6 capstone of #8940), completing the migration of every src/modules offender to the token scale. Adds an ICON_SIZE token set for decorative icon sizes plus pixel-exact FONT_SIZE.cardTitle (15px) / FONT_SIZE.sectionTitle (17px) tokens, and per-file PDF_FONT point-size consts for the report/export PDF generators — every substitution preserves the original rendered size.#9139, #9083, #8940Capstone of the #8940 typography-consistency epic. T1–T5 (#9077/#9079/#9080/#9081/#9082) migrated the known inline numeric fontSize clusters; this T6 swept the remaining ~90 production files so zero raw inline numeric fontSize literals remain in src/modules. Decorative MUI icon sizes (previously '2rem'/'3rem'/'4rem'/'5rem'/40px/22px/18px literals) now reference a new ICON_SIZE token set. Review caught that the first pass had silently changed pixels in two places, now fixed pixel-for-pixel: (1) bold card/section headings (15px CPD/logbook card titles + HLSR heading, 17px CPD total-hours header) had been normalised to 14/16 — restored via new FONT_SIZE.cardTitle/sectionTitle tokens (preserving #9082's deliberate 15px pixel-lock); (2) the four report/export PDF generators (MultiFeature, UserActivities, Timesheet, Logbook) had mapped sub-12pt pdfme point sizes (1/7/8/9/10/11pt) to the 12px screen FONT_SIZE.xs floor, inflating PDF output — now each carries a local PDF_FONT const capturing the exact original points (the same pattern the certificate PDFs use). With no offenders left, the guard was promoted to 'error' so any reintroduced literal blocks CI at Tier 1. One intentional 7px decorative list-bullet (no token equivalent) carries a documented eslint-disable-next-line; the @regression BDD scan honours that same disable so the guard and the test agree.
2026-06-20Wire a single rem-based type scale (TYPOGRAPHY_SCALE) into the MUI theme for every variant and wrap the export in responsiveFontSizes(), plus a WARN-level lint guard flagging new raw inline numeric fontSize in src/modules.#8968, #8940New design-system.typography.rem-scale AC. The theme defined FONT_SIZE tokens but never wired them into a typographic scale (h1–h6 set only fontFamily; body/subtitle/caption fell back to MUI defaults; no responsiveFontSizes wrapper), while ~72 module files hard-code inline px fontSize — mixing fixed px with MUI rem defaults caused the cross-feature size/zoom drift Matt reported (#8940). This enabler derives each variant's rem from the px FONT_SIZE tokens (px ÷ 16), keeps nothing below the 12px readable floor, and adds a warn-only lint guard so new code adopts the scale without breaking CI on the 72 existing offenders. The per-feature migration of those offenders is incremental (#8931/#8932/#8937) — the issue stays open for it.
2026-06-10Publish the component Storybook to GitHub Pages at /storybook/ alongside the docs and link it from the Brand → Components / Brand index pages, so the canonical dashboard widget organisms (PPP/Widgets/Dashboard/*) are browsable on-brand without running the app.#8530, #8269New design-system.docs.storybook-published AC. A build-storybook job in pages.yml builds the static bundle and folds it into the existing Pages deploy (same Google-SSO access gate), path-gated to instances/ppp changes and a manual redeploy. The dead-link crawler and VitePress ignoreDeadLinks are taught the /storybook/ prefix since it is not part of the VitePress build.
2026-06-02Enforce the FormLayout standard — new design-system.form-layout.compose-from-kit AC plus a check-form-layout.mjs CI gate that fails when a form hand-rolls a bespoke gridTemplateColumns / display:'grid' root instead of composing from components/FormLayout + FORM_SPACING.#8162, #8137, #8111Capstone of the forms-standardisation epic #8111. With every in-scope form now composing from the kit, the standard needs teeth so new forms (or regressions in clean ones) cannot reintroduce per-form grid/spacing drift. A narrow, issue-tracked (#8161) allowlist covers the residual not-yet-migrated forms; the guard fails on anything outside it and can only shrink toward empty.
2026-05-28Filter bars now consume the shared PillDateRangeFilter; doughnut widgets share the THIN_DOUGHNUT_CONFIG from the canonical ThinDoughnutChart component.DRY refactor — eliminate duplicated chip-preset and chart-radius logic so a single source of truth governs the date-range pill and thin-doughnut look across the app.
2026-05-27Author the design-system spec with a Product-UI button standard, and retrofit the app theme so destructive buttons render in the error colour.Rob asked for a real button spec (the only one was the marketing CTA table) and to retrofit the app for professional consistency. Split brand/components Buttons into "Marketing CTA" vs "Product UI"; added a MuiButton outlined+error variant so color="error" (e.g. CPD Plan Reset) renders red instead of the muted discard grey that was clobbering it.
2026-05-27Add a global layout spacing standard (LAYOUT.sectionScrollMargin) so in-page section headings clear the sticky topbar instead of being crowded or clipped beneath it.#7767Raised by Matt + Rob in the 2026-05-27 demo run-through — section headings sat too close to the top banner and got cut off when scrolling. Applied once at the app-shell level (PppAppContainer) as scroll-margin-top on headings and anchors, sized to the sticky topbar height plus breathing room, rather than a per-page refactor.

Internal documentation — org members only