Edwin van den Houdt
e82309786d
One-time prettier --write so the new format:check CI gate starts green. .prettierignore excludes generated (api-client.ts, documentation.json), vendored (public/cibg-huisstijl), and backend (dotnet format owns it). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
51 lines
3.5 KiB
Markdown
51 lines
3.5 KiB
Markdown
# 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.
|