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-uipackage 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, thebuttons/kit, and thefilters/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 fromCOLORS.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 inlinefontFamilyoverride that names Urbanist, and theFONT_FAMILYbody/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-faceand names'Nunito'infont-family, and no logo SVG references Urbanist. The initial P of each word isfont-weight: 700, the remainder400, 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 appliesLAYOUT.sectionScrollMarginasscroll-margin-topto 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 singleFORM_SPACINGstandard frominstances/ppp/src/themes/tokens.tsforfieldGap/groupGap/sectionGap/dialogPaddingX/dialogPaddingY; forms never inline per-formSPACING.basemagic numbers for between-field gaps or modal padding. The WBA create modal and the sharedFieldGroupContainerboth consumeFORM_SPACING. † ‡ (#7829, 28 May) - ✅
design-system.form-layout.compose-from-kit— every PPP form composes from the sharedcomponents/FormLayoutkit (FormLayout.Section/Row/Field/Actions) +FORM_SPACINGtokens + shared field objects (FormFieldContainer/FieldGroupContainer); no form underinstances/ppp/src/formshand-rolls a bespokegridTemplateColumnsordisplay: 'grid'form root, and no form inlines per-form spacing literals. Enforced by thecheck-form-layout.mjsCI 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 sharedFormLayout.Actions stickyprimitive pins the row (position: sticky; bottom: 0) and reservesenv(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 withscroll="paper"— making MUIDialogContentthe bounded scroll container — instead ofscroll="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) passstickyon their primaryFormLayout.Actionsrow; the sharedFormActionsSectiondefaultssticky=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 singlePILL_TOGGLE/PILL_TOGGLE_SXtoken block ininstances/ppp/src/themes/tokens.ts; no surface inlines a hex/px for these styles. The sharedPillDateRangeFilterprimitive and PulseScoreHistoryChartboth spreadPILL_TOGGLE_SXinto 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 sharedcomponents/widgets/BaseWidgetprimitive resolves its minimum height from aWIDGET_HEIGHTtoken set ininstances/ppp/src/themes/tokens.ts(auto/sm/md/lg/xl) exposed through asizeprop that defaults toauto(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,BaseWidgetdefaultedheight = 400(applied asminHeight) and each Timesheet/Surgical/WBA widget passed its own raw px (380/400/580/300) while wrapping its chart in aBoxlocked to a literalheight: '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 namedsizetoken (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 aBaseWidgetheight. Found during the demo rehearsal. † ‡ (#9191)
Typography
- ✅
design-system.typography.rem-scale— the MUI theme wires a single rem-based type scale (TYPOGRAPHY_SCALEininstances/ppp/src/themes/tokens.ts) into every typography variant —h1–h6,subtitle1/2,body1/2,button,caption,overline— with eachfontSizederived from the existing pxFONT_SIZEtokens (px ÷ 16 = rem) plus an explicitlineHeight/fontWeight, and no variant falls below theMIN_READABLE_FONT_SIZE12px (0.75rem) floor. The theme export is wrapped in MUIresponsiveFontSizes()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 numericfontSizeinsrc/modulesso 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 numericfontSizeliterals insrc/modules; decorative icon sizes use theICON_SIZEtoken set and PDF point sizes useSEMANTIC_COLORS.pdf.fontSize. With the migration complete, theno-restricted-syntaxguard was promoted from'warn'to'error'(#9083) so any reintroduced literal blocks CI at Tier 1. † ‡ (#8940, #9083)
Page header
✅
design-system.page-header.canonical-title— every screen renders its page title through the sharedcomponents/PageHeaderatom 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-h1level. The atom previously rendered the title at MUIvariant="h5"(~18px), so consumer pages were undersized while the dashboard hand-rolled a 24px title — the same cross-feature heading drift asdesign-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 optionaldescriptionand right-alignedactionsslot (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 thePageHeaderatom, not hand-placed per page: a page passeshelpGuideSectionandPageHeaderrenders<HelpButton>itself, immediately beside the heading text (one gap unit, inside the titleBox) — structurally separate from the right-alignedactionsStack, and never hand-rolled by a page after the titleTypography. Superseded the original #9213 placement (#9887): Help was first standardised as "the first child the page threads intoactions=", 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 ofactionsentirely — 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 ofactions" 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-uiexports plus the localFormLayout/SectionCard/PageLayout/buttons/filterskit; 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 literalcomponents/atoms/+components/molecules/dirs (which held only the three login-form fields) are retired and relocated to a feature-honestcomponents/auth/. The reproducible inventory atdocs/site/architecture/raw-literal-inventory.md(regenerated byscripts/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) insidesrc/modulesproduction files are build-failing at CI Tier 1. Theno-restricted-syntaxguard added ininstances/ppp/eslint.config.mjs(scoped tosrc/modules/**/*.{ts,tsx}, tests/stories excluded) targets identifier-key and string-literal-key property forms; it errors when the value starts with#. PDF-localPDF_COLORconsts 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 toSEMANTIC_COLORStokens fromthemes/tokens.tsin migration chunks #9297–#9307; three new accent tokens (dangerStrong#d32f2f,warningStrong#ed6c02,teal#00897b) were added toSEMANTIC_COLORS.accentto cover MUI palette shades that had no existing entry. A standalone CI script (.github/scripts/check-raw-literals.mjs, wired intoci.ymlafter the primitive-layering guard) proves the rule via negative + positive fixtures before scanning the real module tree — identical to thecheck-primitive-layering.mjs(#9181) pattern. Any reintroduced raw hex in a CSS colour property now blocks the lint job. Mirrorsdesign-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 sharedcomponents/DisabledHintprimitive wraps a disabled control and renders its reason as a hover Tooltip on desktop and as visible caption text directly below the control onxs, 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 siblingcomponents/DisabledHint/InfoHintdoes 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 byDisabledHint/InfoHintis programmatically associated with its control viaaria-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 stableuseId()-generatedid; the sibling control wrapper references it witharia-describedby. The visible caption is kept — noaria-labelis 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 sharedcomponents/MobileSafeAutocomplete/useMobileAutocompletePropshook returns the props that make adisablePortalMUI<Autocomplete>mobile-safe: onxsit dropsdisablePortalso the listbox portals to<body>and floats above the dialog/keyboard instead of being clipped inside the short dialog DOM, caps the popup papermax-heightso a long list scrolls within a bounded area, and gives every option row aminHeightof the 44px touch target (COMPONENT.touchTarget.minSize); on desktop it preserves the original in-dialogdisablePortal: truebehaviour 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 iscomponents/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 thedown('sm')breakpoint — one component, two renders. Authors attach mobile metadata through the standard TanStackmetaslot (mobileLabel,align,hideOnMobile). Consumers that page server-side or render a short fixed list passdisablePagination; 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 samedown('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 primitivecomponents/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-scrollbarthat 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 compactEMPTY_DATAGRID_TABLE_HEIGHT(200px) instead of holding the fixedBASE_DATAGRID_TABLE_HEIGHT(700px) or an explicitheight, killing the ~500px dead band under a short/empty table; a content-sizedheight="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 withcollapseWhenEmpty={false}where a layout deliberately reserves a fixed table slot; (3) an additive responsive column-priority model — a column may declarehideBelow?: 'sm' | 'md' | 'lg'and DSDG filters it out viauseMediaQuerywhen 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 withouthideBelowbehaves exactly as today. This is the primitive-level fix; per-table adoption ofhideBelowin 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 theMuiButtontheme block (radius, padding, font weight,textTransform, mobile sizing). Call sites set onlyvariant/color/size/fullWidth; colour, radius, padding andtextTransformare never hardcoded on a button (mirrorsno-hardcoded-brand-values). † (27 May) - ✅
design-system.button.no-all-caps— buttons never render ALL CAPS;textTransform: noneis enforced by the theme forcontained,outlinedandtextvariants. † (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 usecolor="error"and render in the error palette colour (COLORS.ppp.error, red), not the muted discard grey. The theme declares anoutlined+errorvariant after the genericoutlinedvariant so the error colour wins. Destructive buttons must also be gated by a confirmation dialog. Proven by the CPD Plan Reset button (seecpd.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 reusableSubmitButtonform-primitive (instances/ppp/src/components/SubmitButton/) wraps MUIButtonwith{ isPending, disabled, loadingLabel }— whileisPendingit disables the button (a disabled button cannot fireonClick) 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 sharedFileUploadmolecule (components/FileUploadButton) owns the behaviour: it renders the existing library button plus aCameraCaptureInputaffordance (a dedicated hiddeninput type=filewithcapture="environment"accept="image/*") that appears whenuseCameraSupport().isMobileis true, and a determinate/indeterminate spinner driven by anisUploading/uploadProgressprop pair. The molecule is rolled out to the three evidence surfaces — CPD evidence (FileUploadButtonviaManualCPDFormView), Passport documents (DocumentForm) and immunisations (ImmunisationsCard), the latter two embedding the sameCameraCaptureInputnext 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 thesmbreakpoint), 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(exportingPppDatePicker+PppDateTimePicker), renders the MUIMobileDatePicker/MobileDateTimePickervariant belowsmand the desktop variant atsmand up, preserving every caller prop (disableFuture,format,ampm,value/onChange, andslotPropserror/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-pickerspicker. † ‡ (#9325) - ✅
design-system.form-field.label-readable-on-mobile— the sharedcomponents/FormFieldContainerfield label and helper text render at ≥16px on a mobile viewport (below thesmbreakpoint) and step down to the compact desktop sizes only atsmand 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 helperTypographynow render mobile-first atFONT_SIZE.md(16px) and drop toFONT_SIZE.sm(13px) /FONT_SIZE.xs(12px) respectively inside atheme.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-semanticonClickfails the build. Two layers. (1) A PR-blocking jsx-a11y gate (scripts/check-jsx-a11y.mjs, wired as thePPP Mobile a11y GateCI job and surfaced through the blocking CI Summary) runs the stricteslint-plugin-jsx-a11ypreset tree-wide over all ofinstances/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) becauseinstances/ppplints with its own.eslintrc-ide-base.json(notpackages/config-eslint) so the strict preset was never enforced here and turning it on tree-wide surfaced ~40 pre-existing violations (mostlyjsx-a11y/no-autofocuson long-standing dialog first-fields); #9423 burned that debt down — fixing the genuine violations andeslint-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 axetarget-size+ 44px-floor suite (instances/ppp/e2e/storybook-a11y/form-target-size.spec.ts) runs@axe-core/playwright'starget-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 inscripts/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-a11ystructural rules (validaccessibilityRole/state/value, no nested touchables) are enforced at error inmobile/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-uiexport plus the localFormLayout/SectionCard/PageLayoutkit — renders each one in a headless browser (render assertion + VR screenshot artefact) and runs@axe-core/playwrightover 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_filesis now non-zero against the shared layer. Pre-existing shared-theme/third-party findings the suite surfaced (primary-blue#117be5contrast 4.2:1;@easepickmonth-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 thePRE_EXISTING_PRIMITIVE_A11Yallowlist is now empty. The clear-button accessible-name gap on theTextFieldClearprimitive 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
| Date | Change | PR/Issue | Reason |
|---|---|---|---|
| 2026-10-04 | Added 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, #12698 | No 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-12 | Re-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, #11530 | The 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-07 | New 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, #10151 | The 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-06 | Raw-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, #9178 | The #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 < 2.0 AC is honestly already met. Corrects the cited baseline; the epic stays open for consolidated review. |
| 2026-07-05 | Wave-2 DSDG responsive column adoption (slice 1 of ~20 flagged tables) — WBA, Feedback, Reflection, and Timesheet tables. | #10059, #9893 | Four 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-04 | Hardened 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, #9893 | A 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-27 | Burned 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 <th> 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, #9423 | The #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-26 | Enforce 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 <div onClick> 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, #9332 | Lock-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-25 | Made 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, #9324 | The 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-25 | Added 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, #9323 | Child 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-25 | Added 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, #9325 | Every 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-25 | Visible-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, #9320 | MUI 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-25 | Added 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, #9327 | Doctors 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-25 | Third-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). | #9326 | A 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-25 | Drove 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, #9277 | The #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-24 | Standardised 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, #9213 | The 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-24 | Canonical page-title standard — every screen renders its title through the shared components/PageHeader atom as a single semantic <h1> at 24px (FONT_SIZE.lg) / bold, token-driven. Atom updated from variant="h5" (~18px) to the 24px/bold <h1>; 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, #9213 | A 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-24 | Added 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. | #9179 | Atomic-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-23 | Promote 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, #8940 | Capstone 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-20 | Wire 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, #8940 | New 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-10 | Publish 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, #8269 | New 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-02 | Enforce 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, #8111 | Capstone 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-28 | Filter 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-27 | Author 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-27 | Add a global layout spacing standard (LAYOUT.sectionScrollMargin) so in-page section headings clear the sticky topbar instead of being crowded or clipped beneath it. | #7767 | Raised 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. |