# ADR-0003 — Adopt the CIBG Huisstijl (Bootstrap 5.2) as the design system

Status: Accepted · Date: 2026-07-02

## Context

The portal must adhere visually to the **CIBG design system** (designsystem.cibg.nl) — CIBG runs
the real BIG-register. Until now the app was themed with **Rijkshuisstijl-Community / Utrecht**
(`@rijkshuisstijl-community/components-css` + `design-tokens`), emitting `utrecht-*`/`rhc-*` classes
and consuming a `--rhc-*` CSS-custom-property token set.

CIBG Huisstijl (`@cibg/huisstijl`, v3.22.0) is **a customized build of Bootstrap 5.2.0**: standard
Bootstrap CSS classes (`btn`, `form-control`, `card`, `table`, `breadcrumb`) themed via SCSS variable
overrides, with a full `--bs-*` runtime variable surface. For SPA frameworks it is **CSS-only — no
Bootstrap JS** (the framework drives interactivity). The two systems share neither class names nor
tokens, so adopting CIBG is a re-skin of the shared component layer plus a replacement of the token
layer — not a palette swap.

## Decision

1. **Vendor the package** under `public/cibg-huisstijl/` (not an npm dep — it was delivered as files),
   loaded via a `<link>` in `src/index.html` so the CSS's relative `url(../fonts|icons|images)`
   references resolve at runtime. Storybook serves the same via `staticDirs`.
2. **Token bridge over token rewrite.** `src/styles.scss` redefines the app's ~54 `--rhc-*` tokens
   onto CIBG values (`--bs-*` where one exists, CIBG palette hex otherwise). The `--rhc-*` names are
   now an internal alias set; the *values* are CIBG. This avoided rewriting 300+ token references and
   keeps the "components reference tokens" convention intact. (`styles.scss` is exempt from
   `check:tokens`, so palette hex lives in that one file only.)
3. **Re-skin atoms, keep their `input()` APIs.** Each `shared/ui` atom now emits Bootstrap/CIBG classes
   (`app-button` → `btn btn-primary`, `text-input` → `form-control`, radio/checkbox → `form-check-*`);
   domain pages compose the same atoms and barely changed.
4. **Hand-roll what CIBG's build drops.** CIBG omits Bootstrap's `.alert` and `.navbar`, so `app-alert`
   is a small token-styled surface and the header/side-nav use `.nav` + a local blue bar. Local class
   names that collide with Bootstrap components were renamed (`.card` → `.app-card`, badge → `.status-badge`).
5. **System-font stack; no licensed fonts.** `--bs-font-sans-serif` is overridden to `system-ui`; the
   licensed RO/Rijks **text** woffs are removed from the vendored copy (CIBG icon font kept). Logo stays
   a text wordmark. Interactivity stays Angular-driven (no Bootstrap JS).

## Consequences

- Wiring the design system touches `styles.scss` (token bridge), `index.html`, `angular.json`
  (`public/` already copied), and `.storybook/` — plus the class strings in ~40 `shared/ui` +
  `shared/layout` + a few domain components. The `@rijkshuisstijl-community/*` deps are dropped.
- `check:tokens` still guards raw hex in components; the token bridge + hand-rolled surfaces comply.
- Known benign build warning: *"Unable to locate stylesheet: /cibg-huisstijl/css/huisstijl.min.css"* —
  Angular's index optimizer doesn't process a `public/` stylesheet at build time. The asset is copied
  and the link is preserved (verified: served 200, `.btn-primary` present); the build exits green. The
  alternative (adding the CSS to `angular.json` `styles`) would force-bundle the licensed fonts we
  intentionally dropped, so we accept the warning.
- Renaming the internal token names from `--rhc-*` to `--app-*` is possible later but out of scope.