Validation Matrix

This document defines the engineering controls and evidence model for UI quality. It is for engineers and reviewers shipping UI: it tells you what proof each class of component needs before it merges, and which components carry extra scrutiny. It builds on the Contribution Guide and Component Taxonomy.

The intent is GxP-ready (GxP is the umbrella for the "Good Practice" quality guidelines used in regulated industries such as pharma; here it means risk-based, traceable, reproducible) - not a blanket certification claim.

Evidence categories

Component class risk matrix

🔴 High risk - explicit validation checklist required

These component classes handle critical user actions. Each must have a manual validation checklist in the PR that ships or modifies them.

🟡 Medium risk - story + a11y check required

🟢 Standard - story coverage sufficient

Minimum test expectations per component

Approved primitive or overlay:
  ✅ Jest: renders without crashing
  ✅ Jest: key variants render correctly
  ✅ Jest: disabled/error state renders correctly
  ✅ Jest: callbacks fire on interaction
  ✅ Storybook: story for each variant and state
  ✅ Storybook: a11y addon passes with no violations
  ✅ Storybook: interaction story for keyboard usage (if interactive)

High-risk overlay (modal, upload, confirm):
  All of the above, plus:
  ✅ Jest: focus moves into dialog on open
  ✅ Jest: Escape key closes the dialog
  ✅ Jest: focus returns to trigger on close
  ✅ Manual checklist reviewed in PR

Storybook interaction test expectations

Interactive components (Accordion, Modal, Dropdown, Search) must have interaction stories using @storybook/test:

play: async ({ canvasElement }) => {
  const canvas = within(canvasElement);
  await userEvent.click(canvas.getByRole('button', { name: /toggle/i }));
  expect(canvas.getByRole('region')).toBeVisible();
};

Current interaction stories: ModalBase (focus trap, escape key, blocked close).

Planned: Accordion expand/collapse, Dropdown open/close, Search input/clear.

CI gates (planned)

Bootstrap removal progress

The following react-bootstrap consumers block full Bootstrap CSS removal from layout.tsx. Each must be replaced before the global import is safe to remove.