# VBMS Frontend — UI/UX Defect Register (Static Code Audit)

**Scope:** `D:\main\VBMS\frontend\src` (React 18 + plain CSS design tokens)
**Method:** Static analysis only — grep pattern counts + targeted file reads. Every finding cites `file:line`.
**Date:** 2026-10-18

---

## 1. Summary Counts (Evidence Basis)

| Category | Metric | Count | Basis |
|---|---|---|---|
| Typography | `font-size` declarations (css + jsx) | **1,112** | Select-String across `src/**/*.css`, `src/**/*.jsx` |
| Typography | Hardcoded numeric `font-size` (e.g. `0.625rem`, `13px`) | **500** (423 css + 77 jsx) | `font-size:\s*[0-9]` |
| Typography | px-unit `font-size` (never scales with `--font-scale`) | **93** | `font-size:\s*[0-9.]+px` |
| Typography | Sub-0.625rem (< 10px) sizes in CSS | **66** | `font-size:0.(0–5)…rem` |
| Typography | Hardcoded `font-family` bypassing `--font-sans` | 2 components | `CustomerFeedbackTab.jsx:428`, `Login.jsx:323` |
| Typography | Utility classes with non-token sizes (`fs-tiny`, `fs-sm`) | 2 | `index.css:644-645` |
| Long-text | `word-break` usages | 15 | css+jsx grep |
| Long-text | `text-overflow` usages | 38 | css+jsx grep |
| Long-text | Shared clip utility `.dt-cell-clip` applied in | 1 component (`DataTable.jsx:571`) | jsx grep |
| Header | Competing page-header patterns | 4 (`sp-top-row`:38, `db-header`:35, `vbms-m-top`:12, `PageHeader` imports:34) | jsx grep |
| Header | Manual `<ol className="breadcrumb">` vs `Breadcrumb` component | duplicated across pages (e.g. `Settings.jsx:253`, `VbmsReviewPage.jsx:355`) | grep |
| Interaction | `Loading`/`loading` state handling | strong in DataTable (`DataTable.jsx:516`), weak/duplicated in legacy pages (`MasterSetup.jsx:380`) | grep |
| Interaction | `EmptyState` component vs local re-implementations | shared component exists; local duplicate at `MasterSetup.jsx:360` | file reads |
| Responsive | `@media` queries (pages/layout/ui/preference css) | 74 (57+7+10+…; pages.css alone 57) | grep |
| Responsive | Distinct breakpoint values in use | 12+ (380/400/480/560/600/640/768/860/900/1024/1100/1200) | pages.css/layout.css grep |
| Consistency | Toast implementations active simultaneously | **2** (`Toast.jsx` provider + `SweetToast.jsx`, both mounted `main.jsx:15-16,20,24`) | file read |
| Consistency | Confirm-dialog implementations | **3** (`ConfirmDialog`, `ConfirmationDialog`, `DeleteConfirm`; 8+ importers) | grep |
| Consistency | Button systems | **2** (`sp-btn`: 467 usages vs `.btn` Button component: 63) | grep |
| Consistency | Status badge systems | **2** (`<Badge>`: 245 usages vs `.status-chip`: 47 usages, css `StatesPage.css:643`) | grep |
| Consistency | Dead duplicate page tree `src/pages/pages/**` | 23 jsx files, 0 external imports | import grep |
| Accessibility | `aria-label` usages | 116 (jsx) | grep |
| Accessibility | `role="dialog"` implementations | 2 of 3 modal systems (`Modal.jsx:84`; `ConfirmationDialog.jsx` missing) | grep |
| Accessibility | Focus trap in shared `Modal` | **0** (no focus management code) | `Modal.jsx` full read |
| Theming | Hardcoded hex colors in jsx (inline styles / styled snippets) | ~984 matches | `#[0-9a-fA-F]{3,8}` grep |

---

## 2. Defect Register

Severity scale: **Critical** (user-facing breakage / a11y blocker), **High** (systemic quality defect), **Medium** (localized but recurring), **Low** (polish).

| ID | Category | Severity | Affected screens/components | Evidence | Business impact | Proposed fix direction |
|---|---|---|---|---|---|---|
| DEF-UI-001 | Typography | Critical | Whole app; all list pages, dashboards | 500 hardcoded numeric `font-size` declarations vs 4-token scale (`index.css:206-209`); e.g. `pages.css:3275` (0.5625rem), `StatesPage.css:3573`, `CustomerFeedbackTab.jsx:432-468` (px) | User font-size preference (`--font-scale`, `PreferenceContext.jsx:252-254`) silently fails across ~45% of the UI; text stays tiny for low-vision users; accessibility/compliance risk | Codemod pass: replace numeric font-size with `--fs-caption/body/heading/display`; ban px font-size via lint rule |
| DEF-UI-002 | Consistency | Critical | App-wide notifications | Two toast systems both mounted: `ToastProvider` (`main.jsx:15,20`) + `<SweetToast />` (`main.jsx:16,24`); Settings/Preference use `useToast` (`settings/Settings.jsx:4`) while ~40 pages use `SweetToast` (`pages/master/StatesPage.jsx:9` etc.) | Two visually different notification styles; double-mounted providers cost bundle and confuse maintenance; risk of toasts stacking from both systems | Deprecate one system (keep `SweetToast` as the single API), re-export `useToast` adapter, delete the other after migration |
| DEF-UI-003 | Consistency | Critical | All delete/confirm flows | Three confirm dialogs: `ConfirmDialog.jsx:1`, `ConfirmationDialog.jsx:1`, `DeleteConfirm.jsx:1`; imports e.g. `StatesPage.jsx:10` (DeleteConfirm), `CustomerFeedbackTab.jsx:12` | Inconsistent confirm UX (centered card vs headered modal vs gradient-header modal); duplicated i18n wiring; slower feature dev | Standardize on `ConfirmDialog` (already built on shared `Modal`); mark others deprecated and migrate imports |
| DEF-UI-004 | Consistency | High | Everywhere | `sp-btn` family defined in `StatesPage.css:43-74` used 467× (e.g. `StatesPage.jsx:609`, `AllJobsPage.jsx:578`) vs `Button` component `.btn` used 63× (`Button.jsx:36`) | Two button languages (radius, padding, hover) across pages vs components; visual inconsistency between page actions and modal/form actions | Merge `sp-btn` variants into the `Button` token set (`.btn-*`) or wrap `sp-btn` CSS as the canonical set and re-implement `Button` on top of it |
| DEF-UI-005 | Consistency | High | Master, MIS, Jobs, Locations tables | `<Badge>` used 245× (e.g. `StatesPage.jsx:6`) vs hand-rolled `.status-chip--{status}` (`StatesPage.css:643-712`) used 47× (e.g. `LocationsPage.jsx:216`, `CustomersPage.jsx:383`) | Same "Active/Inactive" status renders differently between table rows, cards, and forms → users distrust status display | Create single `StatusBadge` (variant = semantic status) backed by `--status-*` tokens; migrate both call sites |
| DEF-UI-006 | Header design | High | All list/dashboard/settings pages | 4 patterns: `sp-top-row`+`sp-heading` (`VbmsReviewPage.jsx:361-377`, `Settings.jsx:265`), `db-header` (`JobDashboard.jsx:502`), `vbms-m-top` (`MailFormatsPage.jsx:722`), shared `PageHeader` (`settings/Preference.jsx:81`, 34 imports) | Breadcrumb + title + actions alignment, spacing, and typography differ per page family; new pages copy the wrong neighbor | Make `PageHeader` the only supported header; give dashboard/master variants as props (`tone`, `actions`, `breadcrumbs`), deprecate the three ad-hoc class sets |
| DEF-UI-007 | Accessibility | High | Every `Modal`-based screen (forms, view shells, confirms) | `Modal.jsx:41-50` handles Escape + body-scroll lock only — no focus trap, no initial focus, no focus restore on close | Keyboard and screen-reader users tab into the page behind the modal; WCAG 2.4.3 / 2.1.2 failure; critical data-entry modals | Add focus-first-on-open, Tab-cycle trap, restore-to-trigger on close (or integrate a small focus-trap util) |
| DEF-UI-008 | Accessibility | High | Flows using `ConfirmationDialog` (custom modal) | `ConfirmationDialog.jsx:1-30` builds its own overlay/modal with no `role="dialog"`/`aria-modal` (grep: only `Modal.jsx:84` and `Login.jsx:669` carry the role) | Screen readers announce these dialogs as plain content; users may not realize a modal is open | Rebuild `ConfirmationDialog` on shared `Modal` (which already sets `role="dialog"`/`aria-modal`, `Modal.jsx:84-86`) |
| DEF-UI-009 | Typography | High | Dashboard widgets, badges, legend rows | Sub-10px text: `pages.css:3275` (`.db-donut-legend-item` 0.5625rem), `pages.css:3288` (`.db-alert-desc` 0.5625rem), `layout.css:574` (0.5rem); 66 CSS decls below 0.625rem | Key metrics/legends unreadable for many users; violates WCAG 1.4.4 (resize) expectations even at default scale | Raise floor to `--fs-caption` (0.75rem); remove `fs-tiny`/`fs-sm` utilities (`index.css:644-645`) |
| DEF-UI-010 | Long-text | High | Jobs/MIS/Reviews right-aside insight lists | `.aside-insight-title` has no truncation/wrap control (`StatesPage.css:455-460`); rendered with raw customer/member names (`AllJobsPage.jsx:534`, `AllJobsPage.jsx:554`, `VbmsReviewPage.jsx:348`) | Long codes like `VBMS-M-RAIL` push layout, wrap mid-word, or push counts out of the aside card | Add `truncate` (or clamp-2) to `.aside-insight-title`; parent already has `min-width:0` (`StatesPage.css:453`) |
| DEF-UI-011 | Long-text | High | Grid/card views of all master entities + MIS | `.et-card-title` lacks overflow handling (`StatesPage.css:3558-3562`) while sibling `.et-card-sub` has full ellipsis (`StatesPage.css:3564-3569`); used by `EntityViewsPanel` via `titleOf` (`StatesPage.jsx:546`) | Long entity names overflow card headers in grid/card views — the views users switch to for scanning | Apply the same nowrap+ellipsis (+`title` attr) to `.et-card-title` |
| DEF-UI-012 | Long-text | Medium | All DataTable "Created By" columns | `.creator-cell` flex row without `min-width:0` or truncation on the name span (`StatesPage.css:622-626`); used `CustomersPage.jsx:384`, `LocationsPage.jsx:217` | Long staff names stretch the cell; table grows and horizontal scroll appears prematurely | Truncate name span with `min-width:0` + `text-overflow:ellipsis`, keep `title` tooltip |
| DEF-UI-013 | Typography | Medium | Public feedback page, Login | `CustomerFeedbackTab.jsx:428` hardcodes `font-family:Inter,…`; `Login.jsx:323` hardcodes Inter stack; both ignore `--font-sans` set by preference (`PreferenceContext.jsx:245-250`) | Users choosing Poppins/Manrope etc. see mixed fonts mid-journey (login → app → feedback), undermining the paid personalization feature | Replace hardcoded families with `var(--font-sans)`; convert the px font-sizes in the same styled block |
| DEF-UI-014 | Long-text | Medium | All `Modal` titles | `.modal-title` is nowrap+ellipsis with no `title`/tooltip (`ui.css:911-919`); pages pass dynamic titles incl. IDs (`AllJobsPage.jsx:571` passes `job_no`) | Long job numbers ("View Job: VBMS-J-…-2026-00482") silently clip; user can't verify which record is open | Add `title={title}` on the h3 in `Modal.jsx:92` or allow 2-line wrap |
| DEF-UI-015 | Consistency | Medium | Settings, reviews, holidays, jobs pages | Manual `<ol className="breadcrumb">` blocks duplicated (`Settings.jsx:253-263`, `VbmsReviewPage.jsx:355-359`, `CalendarsPage.jsx:338-341`, `OverridesPage.jsx:329-332`) vs `Breadcrumb` component (`ui/Breadcrumb.jsx`, exported `index.js:16`) | Breadcrumb collapse/truncation logic exists only in the component; hand-rolled copies bypass it and drift | Replace manual lists with `<Breadcrumb items={…} />`; have `PageHeader` render it |
| DEF-UI-016 | Header design | Medium | Modal/detail headers | Three modal header treatments: flat surface (`.modal-header`, `ui.css:881-889`), gradient brand wash (`.ms-m-header`, `pages.css:5767-5771`), border-only (`.sv-modal-header`, `pages.css:9139-9141`) | Same class of overlay feels like three different products; weakens perceived polish in demos/customer walkthroughs | Define one `--modal-header-bg` token + single header anatomy in `Modal`; expose `tone="brand|plain"` |
| DEF-UI-017 | Consistency | Medium | Build health / future edits | Dead duplicate tree `frontend/src/pages/pages/**` (23 jsx files; 0 imports from `App.jsx` or elsewhere; e.g. `pages/pages/settings/Settings.jsx:3` still imports old `ui/Toast`) | Dead code confuses audits, bloats bundles if accidentally imported, and will be edited by mistake | Delete the `pages/pages` tree (verify CI/routes first) |
| DEF-UI-018 | Interaction states | Medium | Master setup legacy page | Local `EmptyState` function (`MasterSetup.jsx:360`) and inline spin-loader divs (`MasterSetup.jsx:380,426,473,524,570`) duplicate shared `EmptyState` (`ui/EmptyState.jsx:3`) and `Skeleton` (`ui/index.js:14`) | Empty/loading states differ between MasterSetup sub-panels and every other page; extra code to maintain | Migrate `MasterSetup` panels to shared `EmptyState` + `TableSkeleton` |
| DEF-UI-019 | Accessibility | Medium | All custom `Select` dropdowns | Trigger sets `role="combobox"`, `aria-expanded` (`Select.jsx:186-195`) but options have no `id`, and no `aria-activedescendant`/`aria-controls` link (`Select.jsx:238-243`) | Screen-reader users can't hear which option is keyboard-highlighted (arrow keys work at `Select.jsx:107-115`) | Add option ids + `aria-activedescendant` on the trigger/search input |
| DEF-UI-020 | Typography | Medium | All text | Dual token families: preferred `--fs-*` (`index.css:206-209`) plus legacy `--text-*` aliases (`index.css:213-223`) still referenced (e.g. `.dt-table` uses `--text-sm`, `pages.css:541`; `.vm-title` uses `--text-lg`, `index.css:854`) | `--text-sm` maps to caption and `--text-lg` to heading — aliases with confusing names invite wrong token choice; scale migration stalls | Freeze aliases (comment-only), migrate active usages to `--fs-*`, document mapping in one table |
| DEF-UI-021 | Typography | Medium | Global CSS enforcement layer | Giant catch-all selector list forcing `font-size:var(--fs-body)` (`index.css:612-631`) and category lists (`index.css:569-609`) | Whack-a-mole architecture: new components silently inherit wrong size unless added to global lists; hard to predict | Move sizes into component CSS with tokens; shrink global lists to form controls + a few primitives only |
| DEF-UI-022 | Responsive | Medium | App-wide | 74 media queries across 4 stylesheets; 12+ distinct breakpoints including near-duplicates 860/900 (`pages.css:9302`, `pages.css:5233`), 1100/1200 (`pages.css:7647`, `pages.css:208`), 380/400 (`pages.css:7078`, `layout.css:1152`) | Layout jumps at arbitrary widths; regression testing cost multiplies; mobile behavior hard to predict | Collapse to 4 tokens: `--bp-sm:640`, `--bp-md:768`, `--bp-lg:1024`, `--bp-xl:1280`; audit pass to merge |
| DEF-UI-023 | Consistency | Medium | Theming/dark mode | ~984 hardcoded hex colors in jsx inline styles (e.g. `StatesPage.jsx:86` fallbacks OK, but `CustomerFeedbackTab.jsx:432-468` fully hardcoded, `VbmsReviewPage.jsx:343-346` dot colors `#f59e0b` etc.) | Dark mode / theme presets (`PreferenceContext.jsx:7-43`) break in those spots — e.g. feedback tab is permanently light | Replace inline hex with CSS variables; move colored markup into themed classes |
| DEF-UI-024 | Long-text | Medium | DataTable users on mobile | `.dt-cell-clip` (the only generic truncation) is fixed `max-width:340px` (`pages.css:545-551`) and not applied outside `DataTable.jsx:571`; on ≤640px the table instead shrinks to caption size (`pages.css:7066`) | Long codes either force horizontal scroll on phones or become 12px-tiny; field staff on mobile struggle to read ticket IDs | Tokenize `--cell-clip-max`; prefer horizontal scroll + sticky first column over shrinking text |
| DEF-UI-025 | Interaction states | Medium | Pages with initial fetches | Loading handled ad hoc: DataTable skeleton good (`DataTable.jsx:516-519`), but pages render `--` placeholders (`MailFormatsPage.jsx:365-367`) or a "Loading live data..." subtitle (`Dashboard.jsx:745`); no shared error-boundary UI per page (only global `ErrorBoundary.jsx`) | Users can't distinguish "empty", "still loading", and "failed" consistently → support tickets ("system not working") | Define `LoadingState`/`ErrorState`/`EmptyState` triad on `PageHeader` content area; standardize via DataTable props + page-level `ErrorState` |
| DEF-UI-026 | Accessibility | Medium | Icon-only action buttons in tables | Icon-only row actions rely on `title=` attributes (480 usages, e.g. `VbmsReviewPage.jsx:308-311`) instead of visible labels or the `Tooltip` component (`ui/Tooltip.jsx`) | `title` tooltips are invisible to touch users and inconsistent for SR users; discoverability of approve/rework actions suffers | Use `aria-label` + shared `Tooltip` on `row-action-btn`; keep `title` as progressive enhancement only |
| DEF-UI-027 | Consistency | Low | Dashboard KPI strips | Decorative fake sparklines in Settings KPIs (`Settings.jsx:284` `data={[3,5,2,6,4,5,3]}`) and hardcoded review KPI spark data (`VbmsReviewPage.jsx:322-325`) | Fake trend lines imply analytics that don't exist — erodes trust in real KPIs nearby | Remove sparkline from non-metric KPIs or feed from real series data |
| DEF-UI-028 | Responsive | Low | Login | Fixed `width:800px;height:400px` decorative layer (`Login.jsx:360`) | On narrow/landscape tablets the decorative art can force overflow (body has `overflow-x:hidden`, `index.css:494`, masking but not fixing layout) | Convert to percentage/`max-width` + hide below 640px |
| DEF-UI-029 | Typography | Low | Consumers of font utilities | `fs-tiny` (0.625rem) and `fs-sm` (0.6875rem) utilities outside the documented 4-category scale (`index.css:644-645`) | Encourages inventing intermediate sizes, re-proliferating the token drift seen in DEF-UI-001 | Remove utilities; map use-cases to caption/body |
| DEF-UI-030 | Typography | Low | `index.css` reset | `body` sets both legacy `--text-base` (`index.css:490`) and `--fs-body` (`index.css:521`) | Redundant declarations; one will rot | Keep `--fs-body` only |

---

## 3. Design System Foundation Recommendations

Token naming follows the existing `index.css` conventions: category prefix (`--fs-`, `--space-`, `--status-`), kebab-case, light/dark override blocks (`[data-theme="dark"]`, `index.css:337`). All rem-based so `html { font-size: calc(16px * var(--font-scale)) }` (`index.css:524`) and preference `--font-family` → `--font-sans` (`PreferenceContext.jsx:245-250`) keep working. **No external fonts.**

### 3.1 Token additions (proposed, `:root` block)

```css
/* --- Typography (extend existing scale, don't replace) --- */
--fs-micro: 0.6875rem;   /* 11px — deprecated: migrate to --fs-caption (DEF-UI-029) */
--line-height-clip: 1.25;              /* single-line clamp rows */
--max-chars-cell: 42ch;                /* replaces fixed 340px clip (DEF-UI-024) */
--max-chars-title: 60ch;               /* modal/page titles */

/* --- Layout / structure --- */
--page-padding-inline: var(--space-5); /* app-content already uses space-4/space-5 (layout.css:816) */
--page-padding-block: var(--space-4);
--page-header-gap: var(--space-4);
--page-header-margin-bottom: var(--space-5);
--modal-header-bg: var(--bg-surface);          /* default flat (DEF-UI-016) */
--modal-header-bg-brand: linear-gradient(180deg, color-mix(in srgb, var(--brand) 6%, var(--bg-surface)) 0%, var(--bg-surface) 100%);

/* --- Components (fill gaps; names mirror existing --topbar-*/--sidebar-* style) --- */
--header-title-size: var(--fs-display);        /* page titles (align index.css:602-609 intent) */
--header-subtitle-size: var(--fs-body);
--badge-padding-y: 3px;  --badge-padding-x: 10px;   /* from status-chip (StatesPage.css:647) */
--badge-gap: 5px;
--status-dot-size: 6px;
--toolbar-gap: var(--space-2);
--toolbar-margin-bottom: var(--space-3);

/* --- Breakpoints as documented constants (comment block; CSS can't tokenize media yet) --- */
/* --bp-sm: 640px; --bp-md: 768px; --bp-lg: 1024px; --bp-xl: 1280px  (DEF-UI-022) */
```

### 3.2 Shared component gaps to fill (in `components/ui`, all token-driven)

1. **`PageHeader` (promote existing)** — already exported (`ui/index.js:17`); add `breadcrumbs` prop (wrap `Breadcrumb`), `tone` variants reusing `--page-header-*` tokens; migrate `sp-top-row`/`db-header`/`vbms-m-top` pages (DEF-UI-006, DEF-UI-015).
2. **`ListToolbar`** — consolidate search + filters + view-switcher + export/Add currently re-built per page (`StatesPage.jsx:432-468` filter card, `DataTable.jsx` toolbar) using `--toolbar-*` tokens.
3. **`StatusBadge`** — single component over `--status-*` tokens (`index.css:76-84`), absorbing `Badge` variants and `.status-chip` (DEF-UI-005). Include optional dot using `--status-dot-size`.
4. **`EmptyState` standardization** — promote `ui/EmptyState.jsx`; add `loading` and `error` variants (icon + title + retry action) so pages stop hand-rolling (`MasterSetup.jsx:360,380`) (DEF-UI-018, DEF-UI-025).
5. **Long-text utility classes** in `index.css` next to existing `.truncate` (`index.css:773-777`):
   - `.truncate-1` / `.truncate-2` (line-clamp), `.cell-truncate { max-width: var(--max-chars-cell); }` — then delete bespoke rules (`StatesPage.css:455`, `3558`, `622`) (DEF-UI-010/011/012/024).
6. **Focus management for `Modal`** — trap/restore (DEF-UI-007); rebuild `ConfirmationDialog` on `Modal` (DEF-UI-008); add `aria-activedescendant` wiring in `Select` (DEF-UI-019).
7. **Single toast + single confirm** — retire `Toast.jsx` or `SweetToast.jsx` (keep SweetToast; it is the de-facto standard with 40+ call sites) and collapse 3 confirm dialogs to `ConfirmDialog` (DEF-UI-002, DEF-UI-003).

### 3.3 Guardrails

- ESLint/stylelint rules: no raw `font-size: <number>`, no hex colors in jsx, no `@media` outside the 4 breakpoint values, no new `sp-btn`/`status-chip`/`ms-m-header` usages (ratchet-down counts).
- Keep `--font-scale` rem strategy: never reintroduce px font sizes (93 today, DEF-UI-001/013).
- Preference contract: all text via `var(--font-sans)` / `var(--font-mono)` only (`index.css:195-196`); `FONT_OPTIONS` remain system-font stacks (`PreferenceContext.jsx:45-57`) — no network fonts.
