Component Library Audit — Visual Refresh Tracker
Part of #3167 — UI Design Direction: "Medical Professional"
Generated 2026-03-24 | fixes #3686
Executive Summary
Audit of 95 shared component entries in instances/ppp/src/components/ and 43 module directories in instances/ppp/src/modules/. The MUI theme (src/themes/index.tsx) already covers Card, Button, Chip, Dialog, OutlinedInput, InputLabel, FormLabel, and AppBar overrides using the "Medical Professional" design tokens (src/themes/colors.ts). However, many components still use hardcoded hex values and inline sx styles instead of theme tokens, and a significant number of shared components lack Storybook coverage.
Key Metrics
| Metric | Count |
|---|---|
| Shared component entries (files + directories) | 95 |
| Module directories | 43 |
| Components with Storybook stories | ~30 of 95 shared |
| Components with hardcoded hex colours | 37 files in components/, 40+ files in modules/ |
Components with heavy inline sx usage | 40 files in components/ |
Priority Tier Definitions
| Tier | Description | Criteria |
|---|---|---|
| P0 | Visible on every page | Navigation, layout shells, page headers, cards, global banners |
| P1 | Core feature pages | Dashboard, CPD, Logbook, Wellness, Profile, Reviews |
| P2 | Secondary feature pages | Timesheets, WBA, MSF, Billing, Support |
| P3 | Admin / settings | Hospital Admin, Super Admin, Settings, Signup flows |
P0 — Global Components (visible on every page)
| Component | Path | Design Tokens? | Matches Direction? | Storybook? | Status | Notes |
|---|---|---|---|---|---|---|
| PppAppContainer | components/PppAppContainer/ | Partial | Needs work | No | NEEDS REFRESH | 10 hardcoded hex colours; main app shell |
| PageLayout | components/PageLayout/ | Yes | Aligned | No | Aligned | Uses theme spacing; test exists |
| PageHeader | components/PageHeader/ | Yes | Aligned | Yes | Aligned | Stories exist |
| PppBrandHeader | components/PppBrandHeader.tsx | Partial | Needs work | Yes | NEEDS REFRESH | Inline colour overrides in stories |
| BaseDialog | components/BaseDialog.tsx | Yes | Aligned | No | Aligned | Uses MuiDialog theme overrides |
| DialogTitle | components/DialogTitle.tsx | No | Needs work | No | NEEDS REFRESH | 3 hardcoded hex colours |
| DialogTitleV2 | components/DialogTitleV2.tsx | Likely yes | Review | No | Review needed | V2 replacement for DialogTitle |
| ConfirmDialog | components/ConfirmDialog/ | Yes | Aligned | No | Aligned | Has overview doc but no .stories.tsx |
| RoleSwitcher | components/RoleSwitcher/ | No | Needs work | No | NEEDS REFRESH | 5 hardcoded colours in sx props |
| RouteTitle | components/RouteTitle.tsx | Yes | Aligned | No | Aligned | Simple wrapper |
| AppErrorBoundary | components/AppErrorBoundary/ | Partial | Needs work | No | NEEDS REFRESH | PaymentErrorFallback has inline styles |
| ScrollToTop | components/ScrollToTop.tsx | N/A | N/A | No | Aligned | Utility, no visual |
P0 — Dashboard Widgets
| Component | Path | Design Tokens? | Matches Direction? | Storybook? | Status | Notes |
|---|---|---|---|---|---|---|
| BaseWidget | components/widgets/BaseWidget.tsx | No | Needs work | No | NEEDS REFRESH | 20 hardcoded hex colours; foundation for all widgets |
| WidgetSection | components/widgets/WidgetSection.tsx | No | Needs work | No | NEEDS REFRESH | 13 inline sx colour values |
| CPDWidget | components/widgets/CPDWidget.tsx | No | Needs work | Yes | NEEDS REFRESH | 7+ hardcoded colours |
| OverallCPDWidget | components/widgets/components/OverallCPDWidget.tsx | No | Needs work | Yes | NEEDS REFRESH | 40+ hardcoded hex colours; heavy charting |
| CategoryWidget | components/widgets/components/CategoryWidget.tsx | No | Needs work | No | NEEDS REFRESH | 21+ inline colour values |
| StyledComponents | components/widgets/components/StyledComponents.tsx | No | Needs work | No | NEEDS REFRESH | Shared styled utils with hardcoded colours |
| DashboardWidgets | components/widgets/DashboardWidgets.tsx | Partial | Review | No | Review needed | Orchestrator component |
| MobileDashboardWidgets | components/widgets/MobileDashboardWidgets.tsx | No | Needs work | No | NEEDS REFRESH | 26 inline colour values |
| MobileDashboardCard | components/widgets/MobileDashboardCard.tsx | No | Needs work | No | NEEDS REFRESH | Hardcoded background colour |
| RetrospectiveWidget | components/widgets/RetrospectiveWidget.tsx | Partial | Needs work | Yes | NEEDS REFRESH | 5 hardcoded colours |
| SurgicalCasesWidget | components/widgets/SurgicalLogbookWidgets/ | Partial | Review | Yes | Review needed | Stories exist |
| CompetencyTargetWidget | components/widgets/SurgicalLogbookWidgets/ | No | Needs work | Yes | NEEDS REFRESH | Hardcoded colour |
| CumulativeProgressWidget | components/widgets/SurgicalLogbookWidgets/ | Partial | Review | Yes | Review needed | — |
| JCSTCompetencyWidget | components/widgets/SurgicalLogbookWidgets/ | Partial | Review | Yes | Review needed | — |
| TargetGaugeWidget | components/widgets/SurgicalLogbookWidgets/ | Partial | Review | Yes | Review needed | — |
| AppraisalsSummaryWidget | components/widgets/AppraisalsWidgets/ | No | Needs work | Yes | NEEDS REFRESH | 5 hardcoded colours |
| WBASummaryWidget | components/widgets/WBAWidgets/ | Partial | Review | Yes | Review needed | — |
| WBAWidgets | components/widgets/WBAWidgets/ | Partial | Review | Yes | Review needed | — |
| AppraisalsReceivedWidget | components/widgets/WBAWidgets/ | Partial | Review | Yes | Review needed | — |
| TimesheetWidgets | components/widgets/TimesheetWidgets/ | Partial | Review | Yes | Review needed | MonthSelector + TimeAtWork stories |
| TimezoneSelect | components/widgets/components/TimezoneSelect.tsx | No | Needs work | No | NEEDS REFRESH | 3 hardcoded colours |
P1 — Core Feature Page Components
| Component | Path | Design Tokens? | Matches Direction? | Storybook? | Status | Notes |
|---|---|---|---|---|---|---|
| DataGrid (DefaultStyledDataGrid) | components/DataGrid/DefaultStyledDataGrid.tsx | No | Needs work | No | NEEDS REFRESH | 2 hardcoded colours; used across all list views |
| CustomHeaderTable | components/DataGrid/CustomHeaderTable.tsx | No | Needs work | No | NEEDS REFRESH | 4 hardcoded colours |
| UserEntityCell | components/DataGrid/UserEntityCell.tsx | Likely yes | Aligned | Yes | Aligned | — |
| HoverActionsCell | components/DataGrid/HoverActionsCell.tsx | Review | Review | No | Review needed | — |
| VisibilityAction | components/DataGrid/VisibilityAction.tsx | Review | Review | No | Review needed | — |
| HospitalCell | components/DataGrid/HospitalCell.tsx | Review | Review | No | Review needed | — |
| ProcedureCell | components/DataGrid/ProcedureCell.tsx | Review | Review | No | Review needed | — |
| RelatedCategoryCell | components/DataGrid/RelatedCategoryCell.tsx | Review | Review | No | Review needed | — |
| FeedbackCard | components/FeedbackCard.tsx | No | Needs work | Yes | NEEDS REFRESH | 4 hardcoded colours |
| ListView | components/ListView.tsx | No | Needs work | No | NEEDS REFRESH | 5 sx colour values |
| MobileList | components/MobileList.tsx | No | Needs work | No | NEEDS REFRESH | 10 inline sx values, 4 hardcoded colours |
| GenericFilterBar | components/filters/GenericFilterBar.tsx | Partial | Needs work | Yes | NEEDS REFRESH | Hardcoded colour in stories |
| ExportButton | components/export/ExportButton.tsx | Review | Aligned | Yes | Aligned | — |
| CadenceTracker | components/CadenceTracker.tsx | Review | Review | Yes | Review needed | — |
| CategoryColorIndicator | components/CategoryColorIndicator.tsx | Review | Review | Yes | Review needed | — |
| CategorySelector | components/CategorySelector.tsx | Review | Review | No | Review needed | — |
| ChartNavigationBanner | components/ChartNavigationBanner.tsx | No | Needs work | No | NEEDS REFRESH | 2 hardcoded colours |
| FormFieldContainer | components/FormFieldContainer.tsx | Partial | Needs work | No | NEEDS REFRESH | Inline styles |
| FormLayout | components/FormLayout/ | Yes | Aligned | Yes | Aligned | — |
| FieldGroupContainer | components/FieldGroupContainer.tsx | Review | Review | No | Review needed | — |
| ProfilePictureField | components/ProfilePictureField.tsx | Partial | Review | Yes | Review needed | — |
| ProfileCompletionStatus | components/ProfileCompletionStatus.tsx | Review | Review | No | Review needed | — |
| ProfileCompletionGuard | components/ProfileCompletionGuard/ | Review | Review | Yes | Review needed | — |
| LogbookImageUploader | components/LogbookImageUploader.tsx | No | Needs work | Yes | NEEDS REFRESH | 4+ hardcoded colours, 2 hardcoded in component |
| RatingRadioGroup | components/RatingRadioGroup.tsx | Review | Review | No | Review needed | — |
| RatingScale | components/RatingScale.tsx | No | Needs work | No | NEEDS REFRESH | 2 hardcoded colours |
| UnsavedChangesDialog | components/UnsavedChangesDialog.tsx | Yes | Aligned | Yes | Aligned | — |
| GuidanceModal | components/GuidanceModal.tsx | Review | Review | No | Review needed | — |
P1 — Key Module Pages
| Module | Path | Design Tokens? | Matches Direction? | Storybook? | Status | Notes |
|---|---|---|---|---|---|---|
| PPPDashboard | modules/PPPDashboard/ | No | Needs work | Yes (index) | NEEDS REFRESH | DashboardScoreCards (2 hex), DashboardActivitiesTable (3 hex), DashboardDonutChart (1 hex); 16 hardcoded colours in stories |
| CPDActivitiesList | modules/CPDActivitiesList/ | No | Needs work | No | NEEDS REFRESH | 9 hardcoded hex colours |
| CPDActivities | modules/CPDActivities/ | No | Needs work | No | NEEDS REFRESH | ApproveCPD (9 hex), columnDefinition (3 hex) |
| CPDPlans | modules/CPDPlans/ | Partial | Needs work | Yes (partial) | NEEDS REFRESH | CPDPlanStatusBadge has 4 hardcoded colours |
| LogbookCase | modules/LogbookCase/ | Partial | Needs work | Yes | Review needed | Stories exist for list, card, filter bar |
| WellnessScore | modules/WellnessScore/ | Yes | Aligned | Yes | Aligned | Uses wellness design tokens properly |
| MyProfile | modules/MyProfile/ | Partial | Needs work | Yes (UpdateCV) | NEEDS REFRESH | MCRSummary has 4 hardcoded colours |
| Reviews (Feedback) | modules/Reviews/ | No | Needs work | No | NEEDS REFRESH | 2 hardcoded colours in column config |
| EndOfYearReflection | modules/EndOfYearReflection/ | Review | Review | No | Review needed | — |
P2 — Secondary Feature Modules
| Module / Component | Path | Design Tokens? | Matches Direction? | Storybook? | Status | Notes |
|---|---|---|---|---|---|---|
| Timesheet | modules/Timesheet/ | Partial | Review | Yes | Review needed | TimesheetModal + BatchReview stories exist |
| WBA | modules/WBA/ | Partial | Needs work | Yes | NEEDS REFRESH | helper.tsx has 3 hardcoded colours |
| MSF | modules/MSF/ | No | Needs work | No | NEEDS REFRESH | helper.tsx has 3 hardcoded colours |
| MSFReport | modules/MSFReport/ | Review | Review | No | Review needed | — |
| MultiConsultantReport | modules/MultiConsultantReport/ | Review | Review | No | Review needed | — |
| PPP360Reviews | modules/PPP360Reviews/ | Review | Review | No | Review needed | — |
| Notifications | modules/Notifications/ | Review | Review | No | Review needed | — |
| Billing / PlansAndPricing | modules/Billing/, modules/PlansAndPricing/ | Review | Review | No | Review needed | — |
| Support | modules/Support/ | Partial | Review | Yes (CPDResourceLibrary) | Review needed | — |
| UniversalSearch | modules/UniversalSearch/ | Review | Review | No | Review needed | — |
| HrPassport | modules/HrPassport/ | Review | Review | No | Review needed | — |
| MedicalPassport | modules/MedicalPassport/ | Review | Review | No | Review needed | — |
| Reports | modules/Reports/ | Review | Review | No | Review needed | — |
| MakeCpdPlan | modules/MakeCpdPlan/ | No | Needs work | Yes (partial) | NEEDS REFRESH | ActivitiesSelectorModal (4 hex), ProgressInPoints (1 hex); stories have 14+ hardcoded colours |
| Development (Dev Tools) | modules/Development/ | No | Needs work | Yes | NEEDS REFRESH | constants.ts has 3 hardcoded colours; column config has 2 |
| Roadmap components | components/roadmap/ | Review | Review | Yes (RoadmapTimeline) | Review needed | — |
| SelectMealBreak | components/SelectMealBreak/ | Review | Review | Yes | Review needed | — |
| PaymentSection | components/PaymentSection/ | Review | Review | No | Review needed | — |
| PaymentStatusBanner | components/PaymentStatusBanner/ | Review | Review | Yes | Review needed | — |
| PaymentStatusGuard | components/PaymentStatusGuard/ | Review | Review | No | Review needed | — |
| SignatureCanvas | components/SignatureCanvas/ | No | Needs work | Yes | NEEDS REFRESH | 2 inline colours |
| SignatureModal | components/SignatureModal/ | No | Needs work | Yes | NEEDS REFRESH | 6 inline colours |
| HospitalSelector | components/HospitalSelector/ | Review | Review | No | Review needed | — |
| HospitalApproverTable | components/HospitalApproverTable/ | No | Needs work | Yes (Row) | NEEDS REFRESH | HospitalApproverRow (19 sx values), HospitalApproverTable (10 sx values) |
P3 — Admin & Settings
| Module / Component | Path | Design Tokens? | Matches Direction? | Storybook? | Status | Notes |
|---|---|---|---|---|---|---|
| Admin (Hospitals) | modules/Admin/Hospitals/ | No | Needs work | No | NEEDS REFRESH | 4 hex in index, 3 in HospitalDetail |
| HospitalAdmin | modules/HospitalAdmin/ | No | Needs work | No | NEEDS REFRESH | Dashboard (7 hex), CpdComplianceCard (8 hex), WellnessTrendsCard (5 hex), Settings (3 hex) |
| HospitalExecutiveAdmin | modules/HospitalExecutiveAdmin/ | No | Needs work | No | NEEDS REFRESH | Dashboard (11 hardcoded colours) |
| HospitalSuperAdmin | modules/HospitalSuperAdmin/ | No | Needs work | No | NEEDS REFRESH | Dashboard (3 hex), CpdComplianceOverview (8 hex), WorkHoursSummary (1 hex), WellnessTrendsChart (5 hex), FeatureToggles (2 hex) |
| HospitalStaff | modules/HospitalStaff/ | Review | Review | No | Review needed | — |
| Settings | modules/Settings/ | Review | Review | No | Review needed | — |
| Users | modules/Users/ | Review | Review | No | Review needed | — |
| WorkQueue | modules/WorkQueue/ | Review | Review | Yes (hook) | Review needed | — |
| AdminPageLayout | components/AdminPageLayout/ | Yes | Aligned | Yes | Aligned | Stories exist |
| AdminCard | components/admin/AdminCard.tsx | Partial | Needs work | Yes | NEEDS REFRESH | 1 hardcoded colour |
| StatusChip | components/admin/StatusChip.tsx | No | Needs work | Yes | NEEDS REFRESH | 10 hardcoded hex colours |
| InlineTip | components/admin/InlineTip.tsx | Yes | Aligned | Yes | Aligned | — |
| StatsBar | components/admin/StatsBar.tsx | Review | Review | Yes | Review needed | — |
| AdminRoute | components/AdminRoute/ | N/A | N/A | No | Aligned | Auth guard, no visual |
| Signup | modules/Signup/ | Review | Review | Yes | Review needed | — |
P1 — Form Components
| Component | Path | Design Tokens? | Matches Direction? | Storybook? | Status | Notes |
|---|---|---|---|---|---|---|
| LoginForm | components/LoginForm.tsx | Review | Review | No | Review needed | — |
| ForgotPasswordForm | components/ForgotPasswordForm.tsx | No | Needs work | No | NEEDS REFRESH | 10 inline sx colour values |
| ChangePasswordForm | components/ChangePasswordForm.tsx | Review | Review | No | Review needed | — |
| SsoButtons | components/SsoButtons.tsx | No | Needs work | No | NEEDS REFRESH | 5 sx values, 3 hardcoded colours |
| FormCheckbox | components/FormCheckbox.tsx | Review | Review | No | Review needed | — |
| HighLevelRequirementsSelector | components/HighLevelRequirementsSelector.tsx | Review | Review | No | Review needed | — |
| CPDActivityProviderAutocomplete | components/CPDActivityProviderAutocomplete.tsx | Review | Review | No | Review needed | — |
| CriticalConditionField | components/CriticalConditionField.tsx | Review | Review | No | Review needed | — |
| EditableField | components/EditableField.tsx | Review | Review | No | Review needed | — |
| NormalFormTree | components/NormalFormTree/ | No | Needs work | No | NEEDS REFRESH | TreeNode.tsx has 13 hardcoded colours |
| UrnSearchField | components/UrnSearchField/ | No | Needs work | No | NEEDS REFRESH | 11 inline sx colour values |
| ExternalSurgeryLookup | components/ExternalSurgeryLookup/ | Review | Review | No | Review needed | — |
| ConceptDetails | components/ConceptDetails/ | Review | Review | No | Review needed | — |
| ActivityMasterListModal | components/ActivityMasterListModal.tsx | No | Needs work | No | NEEDS REFRESH | 2 inline sx colours |
| AppraisalTypeSelectionModal | components/AppraisalTypeSelectionModal.tsx | Review | Review | No | Review needed | — |
| AuditEventCard | components/AuditEventCard.tsx | Review | Review | No | Review needed | — |
| AuditEventsBadge | components/AuditEventsBadge/ | Review | Review | Yes | Review needed | — |
Utility / Non-Visual Components (No refresh needed)
| Component | Path | Notes |
|---|---|---|
| ScrollToTop | components/ScrollToTop.tsx | Scroll utility |
| AdminRoute | components/AdminRoute/ | Auth guard |
| DrawerContent | components/DrawerContent.tsx | Layout utility |
| EmptyRows | components/EmptyRows.tsx | DataGrid spacer |
| HelpButton | components/HelpButton/ | Minimal visual, 1 hardcoded colour |
| icons/ (22 custom icons) | components/icons/ | SVG icons — review for colour consistency |
| shared/SurgerySection | components/shared/SurgerySection.tsx | Form section wrapper |
| ProcedureInformation | components/ProcedureInformation/ | Display component |
Missing Storybook Stories — Complete List
The following shared components in instances/ppp/src/components/ have no .stories.tsx file:
P0 (must add first)
PppAppContainer— main app shellBaseDialog— modal foundationDialogTitle/DialogTitleV2— dialog headersConfirmDialog— confirmation modal (has overview doc only)RoleSwitcher— role selector in navAppErrorBoundary(+ CameraErrorFallback, ModalFormErrorFallback, PaymentErrorFallback)
P1
DataGrid/DefaultStyledDataGrid— base data grid (has overview doc only)DataGrid/CustomHeaderTable— custom header grid (has overview doc only)DataGrid/HoverActionsCellDataGrid/VisibilityActionDataGrid/HospitalCell(has overview doc only)DataGrid/ProcedureCell(has overview doc only)DataGrid/RelatedCategoryCell(has overview doc only)ListViewMobileListForgotPasswordFormLoginFormChangePasswordFormSsoButtonsFormFieldContainerFormCheckboxNormalFormTreeUrnSearchFieldExternalSurgeryLookupConceptDetailsCategorySelectorChartNavigationBannerFieldGroupContainerEditableFieldGuidanceModalRatingRadioGroupRatingScaleProfileCompletionStatusActivityMasterListModalAppraisalTypeSelectionModalAuditEventCardHighLevelRequirementsSelectorCPDActivityProviderAutocompleteCriticalConditionField
P2
HospitalSelectorHospitalApproverTable(Row has stories, Table does not)PaymentSection(GenericPaymentForm, ApplePayButton, WalletPaymentButton)PaymentStatusGuard
Module-level pages with no stories
modules/CPDActivities/modules/CPDActivitiesList/modules/Reviews/modules/MSF/modules/MSFReport/modules/MultiConsultantReport/modules/PPP360Reviews/modules/Notifications/modules/Billing/modules/PlansAndPricing/modules/Reports/modules/UniversalSearch/modules/HrPassport/modules/MedicalPassport/modules/Settings/modules/Users/modules/Admin/modules/HospitalAdmin/modules/HospitalExecutiveAdmin/modules/HospitalSuperAdmin/modules/HospitalStaff/modules/EndOfYearReflection/modules/MyProfile/(only UpdateCV has stories)modules/AcceptInvite/modules/AwaitingActivation/modules/CompletePayment/modules/Guide/modules/PPPDashboard/(index only)modules/Dashboard/
Summary of Findings
Refresh Status Distribution
| Status | Count |
|---|---|
| NEEDS REFRESH (confirmed hardcoded colours / inline styles) | ~40 components/modules |
| Review needed (may need refresh, needs manual visual inspection) | ~35 components/modules |
| Aligned (uses theme tokens correctly) | ~15 components |
| N/A (utility / non-visual) | ~8 components |
Top Issues
Hardcoded hex colours are pervasive — 37 component files and 40+ module files contain
color: '#...'orbackgroundColor: '#...'outside the theme. The worst offenders are the dashboard widgets (BaseWidget,OverallCPDWidget,CategoryWidget,MobileDashboardWidgets), Hospital Admin dashboards, and theNormalFormTree.Storybook coverage gap — Only ~30 of 95 shared component entries have stories. Zero module-level pages (Dashboard, CPD list, Logbook list, etc.) have meaningful page-level stories. 72 items are missing stories entirely.
Widget system is the largest debt — The
components/widgets/directory contains the most hardcoded colours (100+ across all widget files) and needs a systematic token migration before individual widget refreshes.Admin dashboards are entirely un-tokenised —
HospitalAdmin,HospitalExecutiveAdmin, andHospitalSuperAdmindashboards collectively contain 40+ hardcoded hex values with no Storybook stories.Wellness module is well-aligned — The
WellnessScoremodule correctly uses the dedicated wellness palette tokens and has good Storybook coverage. This should be the reference implementation.
Recommended Next Steps
- Create per-component refresh issues for all items marked "NEEDS REFRESH", starting with P0 tier
- Migrate widget colour constants to
src/themes/colors.tsas a batch (widget tokens PR) - Add Storybook stories for all P0 components before visual refresh work begins
- Use WellnessScore module as the gold standard for how modules should adopt design tokens
- Admin dashboards can be refreshed as a single batch since they share the same chart/card patterns