atomic-design-poc/docs/architecture/0003-cibg-huisstijl.md

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.
• Hand-rolled components (point 4) are tracked in the CIBG gap register (src/docs/cibg-gaps.mdx, Storybook "Foundations/CIBG Gap Register"): every deviation from the design system carries a // CIBG-GAP EXTENSION: marker so it's auditable rather than silently drifting.