feat(theme): add ThemeProvider, useTheme, migration docs

rschlaefli · rschlaefli · commit 9f7d92ca388f · 2026-06-13T17:30:43.000+02:00
diff --git a/README.md b/README.md
@@ -2,6 +2,25 @@
 
 This design system is created and maintained by the IT dev-ops team at the Teaching Center of the Department of Finance at the University of Zurich. It simplifies the shared use of commonly used components in our web-development projects with corporate colors already included.
 
+## Theming (v5)
+
+As of v5 the components support two themes, selected via a `data-theme` attribute:
+
+- **`neutral`** (default) — de-branded, shadcn-like. Active on `:root` with no setup.
+- **`uzh`** — the UZH corporate-design theme (UZH blue/red, Source Sans 3).
+
+Switching is a pure CSS-variable cascade (no JS engine). UZH apps opt in with
+`<html data-theme="uzh">` or by wrapping a subtree in `ThemeProvider`:
+
+```tsx
+import { ThemeProvider } from "@uzh-bf/design-system";
+<ThemeProvider theme="uzh">{children}</ThemeProvider>;
+```
+
+**v4 → v5 is a breaking change for UZH apps** (the default is now `neutral`, not
+UZH-branded). See [`packages/design-system/MIGRATION.md`](packages/design-system/MIGRATION.md)
+for the full upgrade guide, including new exports, props, and variants.
+
 ## Prerequisites
 
 - Node.js version 22 (as specified in the project configuration)
diff --git a/packages/design-system/.ladle/components.tsx b/packages/design-system/.ladle/components.tsx
@@ -1,22 +1,22 @@
 // organize-imports-ignore
 import type { GlobalProvider } from '@ladle/react'
 import React from 'react'
+import { ThemeProvider, type Theme } from 'src/ThemeProvider'
 import 'src/tailwind.css'
 
-type Theme = 'neutral' | 'uzh'
-
 /**
  * Ladle global provider with a design-system theme switcher.
  *
- * Wraps every story in a `data-theme` (neutral | uzh) container and an optional
- * `.dark` class, so the v5 dual-theme system can be previewed live in the demo.
+ * Wraps every story in the design-system `ThemeProvider` (neutral | uzh) and an
+ * optional `.dark` class, so the v5 dual-theme system can be previewed live in
+ * the demo.
  */
 export const Provider: GlobalProvider = ({ children }) => {
   const [theme, setTheme] = React.useState<Theme>('neutral')
   const [dark, setDark] = React.useState(false)
 
   return (
-    <div data-theme={theme} className={dark ? 'dark' : undefined}>
+    <ThemeProvider theme={theme} className={dark ? 'dark' : undefined}>
       <div
         style={{
           position: 'fixed',
@@ -56,6 +56,6 @@ export const Provider: GlobalProvider = ({ children }) => {
         </label>
       </div>
       {children}
-    </div>
+    </ThemeProvider>
   )
 }
diff --git a/packages/design-system/MIGRATION.md b/packages/design-system/MIGRATION.md
@@ -0,0 +1,83 @@
+# Migration: v4 → v5 (dual theme)
+
+v5 introduces a **dual-theme** system. The same components now render under two
+themes, selected by a `data-theme` attribute:
+
+- **`neutral`** (default) — de-branded, shadcn-like. Applied on `:root`, so it is
+  what you get with no extra setup.
+- **`uzh`** — the UZH corporate-design theme (UZH blue/red palette, Source Sans 3).
+
+Both themes share one set of components; only the CSS custom properties differ.
+There is no JS theme engine — switching is a pure CSS-variable cascade.
+
+## Breaking change: UZH apps must opt in
+
+In v4 the design system was UZH-branded by default. In v5 the default is
+`neutral`. **The three UZH apps must explicitly select the `uzh` theme**, or they
+will render de-branded.
+
+Pick one of:
+
+```html
+<!-- Simplest: set it once on the document root -->
+<html data-theme="uzh"></html>
+```
+
+```tsx
+// Or wrap the app subtree with the design-system provider
+import { ThemeProvider } from '@uzh-bf/design-system'
+
+export function App({ children }) {
+  return <ThemeProvider theme="uzh">{children}</ThemeProvider>
+}
+```
+
+Anything inside a `data-theme="uzh"` container (set directly or via
+`ThemeProvider`) resolves its tokens against the UZH theme. Nesting is allowed:
+a `uzh` subtree inside a `neutral` page works, and vice versa.
+
+## New exports
+
+| Export          | Purpose                                                       |
+| --------------- | ------------------------------------------------------------- |
+| `ThemeProvider` | Renders a `data-theme` container; controlled or uncontrolled. |
+| `useTheme`      | Reads `{ theme, setTheme }` from the nearest `ThemeProvider`. |
+| `Theme`         | `'neutral' \| 'uzh'` type.                                    |
+
+`ThemeProvider` is optional — a plain `data-theme="uzh"` attribute is enough.
+Use the provider when you want an in-app theme toggle via `useTheme`.
+
+## Fonts
+
+The design system now `@import`s its webfonts (Source Sans 3 for `uzh`, JetBrains
+Mono for monospace) from Google Fonts inside `tailwind.css`. No per-app font setup
+is required. `neutral` uses the system font stack.
+
+## New component props & variants
+
+These are **additive** — existing usage keeps working.
+
+- **`Alert`** — new `variant`s: `neutral`, `info`, `success`, `warning`, `error`
+  (tinted background + coloured left border + status icon). `default` and
+  `destructive` are unchanged.
+- **`Badge`** — new `variant`s: `success`, `warning`, `info`, `error` (solid).
+- **`Input` / `Textarea`** — new `invalid?: boolean` prop → native `aria-invalid`
+  (destructive border + ring). The Formik field wrappers wire this automatically
+  from `error && touched`.
+- **`Avatar`** — new `size?: 'sm' | 'md' | 'lg'` (28 / 40 / 56 px). Omit for the
+  legacy 32 px default.
+- **shadcn `TableRow`** (from the `Table`/`TableHeader`/`TableBody`/… family in
+  `ui/table`, not the legacy `Table` component) — new `hoverable?: boolean`
+  (default `true`) to opt out of row hover.
+- **`Tabs`** — restyled to an underline pattern (active tab gets a primary
+  bottom-border instead of a filled pill). API unchanged.
+
+## Visual changes to verify
+
+- **`AvatarFallback`** background changed from `bg-muted` to `bg-primary-20
+text-primary-100` (theme-tinted initials). Override via `className` if you
+  relied on the grey fallback.
+- **`Tabs`** look different (underline, not pill). Layout/markup is unchanged.
+
+Everything else is theme-token routing: components that hardcoded UZH colours now
+read semantic tokens, so they follow whichever `data-theme` is active.
diff --git a/packages/design-system/src/ThemeProvider.tsx b/packages/design-system/src/ThemeProvider.tsx
@@ -0,0 +1,79 @@
+'use client'
+
+import * as React from 'react'
+import { twMerge } from 'tailwind-merge'
+
+export type Theme = 'neutral' | 'uzh'
+
+interface ThemeContextValue {
+  theme: Theme
+  setTheme: (theme: Theme) => void
+}
+
+const ThemeContext = React.createContext<ThemeContextValue | null>(null)
+
+const noop = () => {}
+
+/**
+ * Wraps an application (or subtree) in a design-system theme.
+ *
+ * Renders a `data-theme` container so all design-system components below it
+ * resolve their tokens against the chosen theme. The default theme is
+ * `neutral` (de-branded shadcn); UZH apps pass `theme="uzh"`.
+ *
+ * Works controlled (`theme` prop) or uncontrolled (`defaultTheme` + `useTheme`).
+ *
+ * @param theme - Controlled theme. When set, the provider is fully controlled.
+ * @param defaultTheme - Initial theme for uncontrolled usage (default `neutral`).
+ * @param className - Optional classes for the wrapping container. The container
+ *   uses `display: contents`, so only inherited classes (e.g. `dark`) take
+ *   effect; box-model classes (padding, sizing, background) are a no-op.
+ * @param children - The subtree that should consume the theme.
+ */
+export function ThemeProvider({
+  theme: controlledTheme,
+  defaultTheme = 'neutral',
+  className,
+  children,
+}: {
+  theme?: Theme
+  defaultTheme?: Theme
+  className?: string
+  children: React.ReactNode
+}) {
+  const [uncontrolledTheme, setUncontrolledTheme] =
+    React.useState<Theme>(defaultTheme)
+  const isControlled = controlledTheme !== undefined
+  const theme = controlledTheme ?? uncontrolledTheme
+
+  // In controlled mode the parent owns `theme`, so `setTheme` is a no-op rather
+  // than writing to internal state that is never rendered (which would desync if
+  // the consumer later dropped the `theme` prop).
+  const value: ThemeContextValue = {
+    theme,
+    setTheme: isControlled ? noop : setUncontrolledTheme,
+  }
+
+  return (
+    <ThemeContext.Provider value={value}>
+      <div data-theme={theme} className={twMerge('contents', className)}>
+        {children}
+      </div>
+    </ThemeContext.Provider>
+  )
+}
+
+/**
+ * Reads the current design-system theme from the nearest `ThemeProvider`.
+ *
+ * @returns The active `theme` and a `setTheme` setter (no-op target when the
+ *   provider is controlled via its `theme` prop).
+ * @throws If used outside a `ThemeProvider`.
+ */
+export function useTheme(): ThemeContextValue {
+  const context = React.useContext(ThemeContext)
+  if (!context) {
+    throw new Error('useTheme must be used within a ThemeProvider')
+  }
+  return context
+}
diff --git a/packages/design-system/src/index.ts b/packages/design-system/src/index.ts
@@ -73,6 +73,7 @@ export * from './Switch'
 export * from './Table'
 export * from './Tabs'
 export * from './Tag'
+export * from './ThemeProvider'
 export * from './Toast'
 export * from './Toggle'
 export * from './ToggleGroup'
diff --git a/project/2026-06-13-v5-dual-theme-uzh-neutral-plan.md b/project/2026-06-13-v5-dual-theme-uzh-neutral-plan.md
@@ -142,9 +142,11 @@ Reference this plan path. Work one slice at a time. Update `Progress` each slice
 - [x] S3 Input + Textarea invalid. Added `invalid?: boolean` to base Input + Textarea → native `aria-invalid` (`invalid ?? ariaInvalid`, no `{...props}` clobber). Existing shadcn classes already give destructive border/ring on aria-invalid + UZH-blue `focus-visible:ring-ring` — no class churn. Wired `invalid={!!error && isTouched}` from forms/TextField (2 branches) + forms/TextareaField (2 branches). Review fix: added missing `isTouched` guard to TextareaField error tooltip (consistency w/ TextField + aria gating). Existing Error stories demo it. Verified tsc/build/format.
 - [x] S4 Refinement batch (scoped to additive/low-regression). Avatar: `size` prop sm/md/lg (28/40/56px, no default → legacy 32px kept); fallback `bg-primary-20 text-primary-100` (theme-tinted, ~7:1 contrast both themes). Table (shadcn): `hoverable?: boolean` opt-out. Avatar story Sizes example. Verified tsc/build/format; CSS has size-7/10/14. DELIBERATELY NOT forced (regression-averse, components already theme-switch + close to spec): uppercase shadcn table headers, 13px/600 labels, shimmer skeleton (kept animate-pulse), Progress (already h-2 + themed primary). MIGRATION note: AvatarFallback bg changed muted→primary-20 (override via className if undesired).
 - [x] S5 Tabs underline + Card + headings. ui/tabs.tsx: TabsList → bottom-border baseline (`border-b border-border gap-4`); TabsTrigger → underline active (`-mb-px border-b-2 border-b-transparent data-[state=active]:border-b-primary-100 data-[state=active]:text-foreground`, hover text, `ring-[3px]` focus). src/Tabs.tsx wrapper: dropped `data-[state=active]:font-bold` (stale pill style), kept full-width grid layout. Card: NO change (already `rounded-xl border shadow-sm`). Headings H1/H2/H3 already correct; added `--text-md` (17px) + `--text-md--line-height: 1.35` token for H4. Review fixes: removed dead `focus-visible:outline-ring` (color w/o width = invisible; `ring-[3px]` is real indicator); added text-md line-height. Verified: tsc clean; ladle build ok; prettier clean.
-- [ ] S6 ThemeProvider + docs + dev-lint + security
-- Current slice: S6 next.
-- Next action: ThemeProvider + useTheme exports, README/MIGRATION docs (`data-theme="uzh"` for UZH apps), dev-lint, final security review.
+- [x] S6 ThemeProvider + docs. Added `src/ThemeProvider.tsx` (`ThemeProvider`, `useTheme`, `Theme` type) — renders `<div data-theme className='contents'>` (layout-transparent; custom-prop inheritance + `.dark` descendant matching both survive `display:contents`), controlled OR uncontrolled (`setTheme` honest no-op when controlled, no stale-state desync). Exported from `index.ts`. Dogfooded: Ladle global provider now wraps stories in `<ThemeProvider>` (dropped local `Theme` type). Docs: root README `## Theming (v5)` section + new `packages/design-system/MIGRATION.md` (v4→v5: neutral default, UZH opt-in `data-theme="uzh"`, new exports/props/variants table, AvatarFallback + Tabs visual notes). Review+simplify (2 subagents): made controlled-mode `setTheme` a real no-op, dropped pointless `useMemo`, documented `contents` className caveat, clarified Table→ShadcnTableRow in migration. Verified: tsc clean; ladle build ok; prettier clean.
+  - **DEV-LINT DEFERRED (A2, evidence-backed)**: reference `_adherence.oxlintrc.json` was generated for the reference's inline-style/synthesized-API code, not our Tailwind+cva library. Against our `src/`: raw-hex rule = 8 hits ALL legit (ColorPicker swatch palette, Cycle default color props, recharts `#ccc`/`#fff` internal selectors); raw-px rule = 75 hits ALL legit Tailwind arbitrary values (`w-[280px]`, `border-[3px]`); JSX prop rules describe a different component API (e.g. Button variants primary|outline|destructive|ghost ≠ ours). Wiring it in = ~83 false positives + new dep, 0 real catches. Mismatched tool; A2 was optional. Deferred to a follow-up (author a Tailwind-aware token-regression guard if wanted). Per-slice grep already verifies zero `uzh-*` leaks.
+- [ ] Finish: final security review (whole branch) + MR + demo deploy.
+- Current slice: S6 done; Finish next.
+- Next action: final security review subagent (whole branch), then `$df-mr-description-writer` MR vs `main` + both-theme screenshots; confirm gh-pages demo deploy carries theme toggle.
 
 ### Verification approach note
 Per-slice: `tsc` + `ladle build` + targeted compiled-CSS/grep assertions. Live visual both-theme screenshots consolidated at finish for MR evidence (browser set up once across all components) rather than per slice.
