refactor(theme): share one base theme between backoffice and portal

The two apps had drifted into unrelated themes. The portal's carried a full
type scale, radius scale, shadow ramp and component defaults; the backoffice's
had none of them — 55 lines defining two colour ramps and little else. With
nothing to inherit, its 23 features each invented their own sizing, which is
the real source of the inconsistency the UI reads with.

Promote the portal's structure to `libs/shared` as `baseTheme`, and reduce both
themes to what they should differ on: brand. The backoffice keeps #1e40af and
the portal keeps Coastal Modern — a distinct accent tells an officer which of
the two systems they are in, and the ramps are not interchangeable in contrast.

Both export names are preserved, so no consumer import changes.

Two properties are deliberately held back rather than shared:
- `colors.gray`: the portal's blue-tinted neutrals retint every dimmed label,
  neutral badge and table border. The backoffice adopts them as its own
  reviewed change, not as a side effect of sharing a base.
- `primaryShade.dark`: moves every filled control in dark mode; waits until
  dark mode is verified end to end.

Also fixes a live bug: PageLoader coloured its primary label `navy.9`, which is
defined in neither theme. Mantine drops unresolved colour keys silently, so the
label in a component used by 20 files had been rendering an inherited colour.

Adds a visual-regression harness to make all of this reviewable. It runs
against a static gallery route rather than real pages, so it needs no API,
database or auth — a theme diff cannot be masked by a migration or an expired
token. The portal is the control group: it is pixel-identical across all four
light/dark × desktop/tablet baselines, which is what makes the refactor
provably lossless.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

apps/backoffice/src/app/router/index.tsx

@@ -12,6 +12,7 @@ import {
   RequirePermission,
   LICENSE_PERMISSIONS as P,
 } from '@ema-platform/auth';
+import { ThemeGallery } from '@ema-platform/ui';
 import { AuthLayout } from '../layouts/AuthLayout';
 import { BackofficeLayout } from '../layouts/BackofficeLayout';
 import { ProtectedRoute } from './ProtectedRoute';
@@ -68,6 +69,9 @@ const router = createBrowserRouter([
     ],
   },
   { path: '/um/*', element: <UserManagementPage /> },
+  // Theme visual-regression surface. Unauthenticated by design — it renders
+  // only static primitives, so it needs no API and cannot flake.
+  { path: '/__gallery', element: <ThemeGallery /> },
   { path: '/', element: <LandingRoute /> },
   { path: '/profile-setup', element: <Navigate to="/dashboard" replace /> },
   {

apps/e2e/visual.config.ts

@@ -0,0 +1,65 @@
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Visual-regression suite for theme work.
+ *
+ * Deliberately separate from `playwright.config.ts`. That suite drives real
+ * cross-app workflows and therefore needs the API, a database and migrations;
+ * this one only needs to know what the theme renders. Loading the same
+ * dependencies here would make a screenshot diff fail for reasons that have
+ * nothing to do with the theme — a migration, a seeded row, an expired token.
+ *
+ * So: static routes only, `vite preview` over an already-built bundle, no
+ * backend. Run `vite build` for both apps first.
+ */
+
+const PORTAL_PORT = Number(process.env.VISUAL_PORTAL_PORT ?? 4312);
+const BACKOFFICE_PORT = Number(process.env.VISUAL_BACKOFFICE_PORT ?? 4313);
+
+export const VISUAL = {
+  portalUrl: `http://localhost:${PORTAL_PORT}`,
+  backofficeUrl: `http://localhost:${BACKOFFICE_PORT}`,
+};
+
+export default defineConfig({
+  testDir: './visual',
+  workers: 1,
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  // A visual diff that passes on a retry is a flake, and a flake here would
+  // mask exactly the regressions this suite exists to catch.
+  retries: 0,
+  timeout: 60_000,
+  expect: {
+    // Anti-aliasing differs slightly between runs; a handful of pixels is not
+    // a regression. Anything the theme actually changed is far larger.
+    toHaveScreenshot: { maxDiffPixelRatio: 0.01, animations: 'disabled' },
+  },
+  reporter: [['list'], ['html', { outputFolder: '../../dist/visual-report', open: 'never' }]],
+
+  use: {
+    trace: 'retain-on-failure',
+    actionTimeout: 15_000,
+  },
+
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+
+  webServer: [
+    {
+      name: 'portal',
+      command: `npx vite preview --config apps/portal/vite.config.mts --port ${PORTAL_PORT} --strictPort`,
+      cwd: '../..',
+      url: VISUAL.portalUrl,
+      reuseExistingServer: !process.env.CI,
+      timeout: 120_000,
+    },
+    {
+      name: 'backoffice',
+      command: `npx vite preview --config apps/backoffice/vite.config.mts --port ${BACKOFFICE_PORT} --strictPort`,
+      cwd: '../..',
+      url: VISUAL.backofficeUrl,
+      reuseExistingServer: !process.env.CI,
+      timeout: 120_000,
+    },
+  ],
+});

apps/e2e/visual/theme.spec.ts

@@ -0,0 +1,61 @@
+import { test, expect, type Page } from '@playwright/test';
+import { VISUAL } from '../visual.config';
+
+/**
+ * Theme baselines.
+ *
+ * These exist so a change to the shared theme can be reviewed as a diff rather
+ * than trusted. The gallery route renders every primitive the theme controls,
+ * so one screenshot per app per scheme per width covers the whole surface.
+ *
+ * Update baselines deliberately, never reflexively:
+ *   npx playwright test -c apps/e2e/visual.config.ts --update-snapshots
+ * A diff you did not intend is the entire point of the suite.
+ */
+
+const WIDTHS = [
+  { name: 'desktop', width: 1440, height: 1200 },
+  { name: 'tablet', width: 768, height: 1200 },
+] as const;
+
+const SCHEMES = ['light', 'dark'] as const;
+
+const APPS = [
+  { name: 'backoffice', url: VISUAL.backofficeUrl },
+  { name: 'portal', url: VISUAL.portalUrl },
+] as const;
+
+/**
+ * Set the scheme the way the app itself does — the pre-paint script in
+ * index.html reads this key. Setting it before navigation means the very first
+ * paint is already correct, so no screenshot catches a flash of the wrong one.
+ */
+async function gotoGallery(page: Page, baseUrl: string, scheme: string) {
+  await page.addInitScript((value) => {
+    window.localStorage.setItem('mantine-color-scheme-value', value);
+  }, scheme);
+
+  await page.goto(`${baseUrl}/__gallery`, { waitUntil: 'networkidle' });
+
+  // The gallery is static, but web fonts are not: screenshotting before they
+  // settle bakes a fallback-font baseline that every later run then fails
+  // against.
+  await page.evaluate(() => document.fonts.ready);
+  await expect(page.getByRole('heading', { name: 'Theme Gallery' })).toBeVisible();
+}
+
+for (const app of APPS) {
+  for (const scheme of SCHEMES) {
+    for (const size of WIDTHS) {
+      test(`${app.name} gallery — ${scheme} — ${size.name}`, async ({ page }) => {
+        await page.setViewportSize({ width: size.width, height: size.height });
+        await gotoGallery(page, app.url, scheme);
+
+        await expect(page).toHaveScreenshot(
+          `${app.name}-gallery-${scheme}-${size.name}.png`,
+          { fullPage: true },
+        );
+      });
+    }
+  }
+}

apps/portal/src/app/router.tsx

@@ -1,4 +1,5 @@
 import { createBrowserRouter, Navigate } from "react-router-dom";
+import { ThemeGallery } from "@ema-platform/ui";
 import { PortalLayout } from "./layouts/PortalLayout";
 import { ProtectedRoute } from "./components/ProtectedRoute";
 import { LandingRoute } from "./components/LandingRoute";
@@ -57,6 +58,10 @@ export const router = createBrowserRouter([
   // Public landing page — institutional overview + role-based entry points.
   { path: "/", element: <LandingRoute /> },
 
+  // Theme visual-regression surface. Unauthenticated by design — it renders
+  // only static primitives, so it needs no API and cannot flake.
+  { path: "/__gallery", element: <ThemeGallery /> },
+
   // Public auth pages
   { path: "/login", element: <LoginPage /> },
   { path: "/signup", element: <SignupPage /> },

apps/portal/src/app/theme/portalTheme.ts

@@ -1,116 +1,13 @@
-import {
-  createTheme,
-  rem,
-  type MantineColorsTuple,
-} from '@mantine/core';
-
-// ---- Coastal Modern palette ----------------------------------------------
-// Portal-only theme. Lives here (not in @ema-platform/shared) so the backoffice
-// is unaffected.
-
-const emaPrimary: MantineColorsTuple = [
-  '#eef4ff', '#dce7fb', '#b6cdf4', '#8db0ee', '#6c97e9',
-  '#5887e6', '#4b7fe5', '#3b6ccc', '#3160b7', '#2453a2',
-];
-
-// Teal accent — the "coastal" half of the palette.
-const emaTeal: MantineColorsTuple = [
-  '#e1fbf6', '#cdf3eb', '#9ee6d7', '#6bd9c1', '#46cdaf',
-  '#30c7a5', '#1fc29d', '#0aab89', '#009879', '#008368',
-];
-
-// Cool neutral grays (slightly blue-tinted) for surfaces & text.
-const emaGray: MantineColorsTuple = [
-  '#f6f8fb', '#eceff4', '#dde2eb', '#c8d0dd', '#aab5c7',
-  '#8d9bb3', '#73839e', '#5c6b85', '#46546b', '#333f52',
-];
-
-export const portalTheme = createTheme({
-  primaryColor: 'emaPrimary',
-  primaryShade: { light: 6, dark: 5 },
-  colors: {
-    emaPrimary,
-    emaTeal,
-    gray: emaGray,
-  },
-  fontFamily:
-    'Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
-  headings: {
-    fontFamily: 'Inter, sans-serif',
-    fontWeight: '700',
-    sizes: {
-      h1: { fontSize: rem(32), lineHeight: '1.25' },
-      h2: { fontSize: rem(25), lineHeight: '1.3' },
-      h3: { fontSize: rem(21), lineHeight: '1.35' },
-      h4: { fontSize: rem(17), lineHeight: '1.4' },
-      h5: { fontSize: rem(15), lineHeight: '1.45' },
-    },
-  },
-  defaultRadius: 'md',
-  radius: {
-    xs: rem(6),
-    sm: rem(8),
-    md: rem(12),
-    lg: rem(16),
-    xl: rem(22),
-  },
-  shadows: {
-    xs: '0 1px 2px rgba(15,23,42,0.06)',
-    sm: '0 2px 8px rgba(15,23,42,0.06), 0 1px 2px rgba(15,23,42,0.04)',
-    md: '0 8px 24px rgba(15,23,42,0.08)',
-    lg: '0 16px 40px rgba(15,23,42,0.12)',
-    xl: '0 24px 64px rgba(15,23,42,0.16)',
-  },
-  breakpoints: {
-    xs: '36em',
-    sm: '48em',
-    md: '62em',
-    lg: '75em',
-    xl: '88em',
-  },
-  cursorType: 'pointer',
-  components: {
-    Paper: {
-      defaultProps: { radius: 'lg' },
-    },
-    Card: {
-      defaultProps: { radius: 'lg' },
-    },
-    Button: {
-      defaultProps: { radius: 'md' },
-      styles: { root: { fontWeight: 600 } },
-    },
-    Badge: {
-      defaultProps: { radius: 'sm' },
-    },
-    ThemeIcon: {
-      defaultProps: { radius: 'md' },
-    },
-    NavLink: {
-      styles: { root: { borderRadius: rem(10), fontWeight: 500 } },
-    },
-    TextInput: { defaultProps: { radius: 'md' } },
-    Textarea: { defaultProps: { radius: 'md' } },
-    Select: { defaultProps: { radius: 'md' } },
-    PasswordInput: { defaultProps: { radius: 'md' } },
-    // Mantine's stock scroll wrapper (NativeScrollArea) discards the
-    // max-height it's handed unless scrollAreaComponent is set, so a modal
-    // taller than the viewport just gets clipped with no way to scroll it.
-    // Making the body the scrollport here fixes every Modal/Drawer at once.
-    Modal: {
-      styles: {
-        content: { display: 'flex', flexDirection: 'column', maxHeight: '90dvh' },
-        body: { flex: '1 1 auto', minHeight: 0, overflowY: 'auto' },
-      },
-    },
-    Drawer: {
-      styles: {
-        content: { display: 'flex', flexDirection: 'column' },
-        body: { flex: '1 1 auto', minHeight: 0, overflowY: 'auto' },
-      },
-    },
-  },
-  other: {
-    heroGradient: 'linear-gradient(135deg, #3160b7 0%, #1fc29d 100%)',
-  },
-});
+/**
+ * The portal theme now lives in `@ema-platform/shared`, alongside the
+ * backoffice theme and the base they share.
+ *
+ * It moved because the two themes had diverged into unrelated definitions —
+ * this one carried a full type scale, radius scale and component defaults that
+ * the backoffice simply lacked. Sharing the structure fixes the backoffice
+ * without changing the portal.
+ *
+ * This re-export is kept so the portal's MantineThemeProvider import stays
+ * valid. Prefer importing from `@ema-platform/shared` directly in new code.
+ */
+export { portalTheme } from '@ema-platform/shared';