Merge pull request #185 from ConductionNL/chore/archive-lasuite-token-completeness

docs(openspec): archive lasuite-token-completeness

Author: rubenvdlinde

openspec/changes/app-token-set-selection/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-25

openspec/changes/app-token-set-selection/design.md

@@ -0,0 +1,165 @@
+---
+kind: code
+---
+
+## Why
+
+nldesign already owns the entire NL Design token-set surface: discovery
+(`TokenSetService::getAvailableTokenSets()`, ~lib/Service/TokenSetService.php:135-189), the shipped
+catalogue (`token-sets.json`, `design-systems.json`, `css/tokens/<id>.css` — 43 sets + dark
+variants), admin custom-set upload including W3C DTCG JSON
+(`CustomTokenSetService::store()`, ~lib/Service/CustomTokenSetService.php:175-236), and WCAG
+contrast math (`ContrastService` — relative luminance, fixed pairs primary/text @4.5:1 and
+primary/background @3:1 — invoked from `CustomTokenSetService::store()` at ~:196;
+`ShippedTokenSetAuditService`; `Capabilities::computeWcagLevel()`,
+~lib/Capabilities.php:219-281). Every existing consumption path — the admin dropdown
+(`/settings/tokensets`), the public capabilities document (`Capabilities`, `IPublicCapability`),
+and the whole-instance CSS injector (`CssInjectionService` + `ThemeInjectionListener`) — is either
+**admin-only** or **instance-wide**. None of it lets a **leaf app's own picker** (a builder tool
+inside another Conduction app, e.g. OpenBuild) enumerate the catalogue for its own users, and none
+of it gives leaf apps a shared place to evaluate WCAG contrast instead of re-implementing the math.
+
+### The gap is not hypothetical — OpenBuild already hit it and built around it
+
+OpenBuild's `nldesign-theme-selection` feature (archived 2026-06-15,
+`../../../openbuild/openspec/specs/nldesign-theme-selection/spec.md`) lets a builder pick an
+nldesign token set for a virtual app. Its own spec (REQ-NTS-002, REQ-NTS-006) documents, verbatim,
+the exact gap this change closes:
+
+> "(a) `GET /apps/nldesign/settings/tokensets` when the session is admin — the route is
+> `AuthorizedAdminSetting` today ... (b) the flagged non-admin nldesign list endpoint **once it
+> exists** ... (c) a validated free-text fallback." / "A Codeberg issue against `Conduction/nldesign`
+> MUST be filed ... requesting (a) a `#[NoAdminRequired]` read-only token-set list endpoint and (b)
+> documentation of `css/tokens/*.css` as a consumable contract."
+
+`SettingsController::getAvailableTokenSets()` (~lib/Controller/SettingsController.php:261) and
+every other `settings#*` GET are `#[AuthorizedAdminSetting(Admin::class)]` — confirmed by reading
+the controller, not just OpenBuild's note. `openbuild/src/dialogs/ThemePickerDialog.vue` (lines
+1-19) ships a **feature-probe stub** for leg (b) today: it always falls through to the free-text
+`css/tokens/<id>.css` fallback because the non-admin endpoint does not exist.
+
+OpenBuild also independently built a **second, unrelated** feature, `app-theming` (archived
+2026-07-24, `../../../openbuild/openspec/specs/app-theming/spec.md`), that **duplicates nldesign's
+WCAG math** in `openbuild/src/services/checkThemeContrast.js` — the same relative-luminance
+formula, re-typed in JS, checked against a **hardcoded `#FFFFFF` background** rather than the real
+active background — and enforces it as a **hard, non-bypassable save-blocking gate** (`"There SHALL
+be no override or bypass of this check"`), unlike nldesign's own upload-time policy, which is
+**warn-only** (`custom-token-sets` spec, "WCAG AA Contrast Warnings on Upload": *"Failures MUST be
+returned as non-blocking warnings"*).
+
+Finally, `app-theming`'s own spec already documents an ad hoc scoped-CSS **rewriter** contract
+(REQ-NTS-003, reused verbatim by `app-theming`'s Requirement "Theme applies via the existing scoped
+CSS-variable mechanism"): fetch `css/tokens/<id>.css`, rewrite every `:root` selector to
+`[data-openbuild-theme-scope="<appSlug>"]`, inject as one managed `<style>` element, and — critically
+— **bail out and inject nothing** if the CSS contains a construct the rewriter does not positively
+recognise (nested at-rules etc.). This is homegrown, OpenBuild-owned (`data-openbuild-*`), and would
+have to be reinvented by every other leaf app that wants the same trick. Verified empirically
+(`grep` over all 43 `css/tokens/*.css`): every shipped set is already exactly one flat `:root { }`
+block with no at-rules or other selectors — the invariant OpenBuild's rewriter silently depends on
+already holds, it has just never been published as an nldesign contract. The dark variants
+(`css/tokens/dark/<id>.css`, generated by `DarkPaletteService`) are the opposite shape —
+`@media (prefers-color-scheme: dark) { body:not(...) { ... } }` — confirming the rewriter's bail-out
+rule is load-bearing and that dark-mode scoped application is a distinct, unsolved problem (out of
+scope here, see design.md).
+
+### What this change is (and is not)
+
+This is **nldesign's side of the contract only**. A companion `nextcloud-vue` change will add the
+generic, shared, scoped client-side applier (replacing OpenBuild's homegrown
+`data-openbuild-theme-scope` rewriter with a design-system-owned one). A companion OpenBuild change
+will reduce `ThemePickerDialog`'s three-tier fallback to a direct call against the new endpoint, and
+will evaluate whether `checkThemeContrast.js` can be deleted in favour of the new shared contrast
+endpoint. Neither of those changes is proposed, designed, or implemented here — this change adds
+**no Vue, no scoped applier, no OpenBuild edits** — it only defines and documents nldesign's PHP
+contract surface: a read-only catalogue endpoint, a shared contrast-evaluation entry point, the
+scoped-application contract nc-vue implements against, and the blocking-policy resolution between
+nldesign's existing warn-only model and OpenBuild's existing hard-block model.
+
+### Evidence
+
+- `lib/Service/TokenSetService.php:135-189` — `getAvailableTokenSets()`, the single discovery path
+  this change reuses without duplication.
+- `lib/Service/CustomTokenSetService.php:175-236` — `store()`, the existing warn-only contrast
+  policy for admin uploads.
+- `lib/Service/ContrastService.php` — the existing fixed-pair WCAG relative-luminance math
+  (`PAIRS` const: primary/text @4.5:1, primary/background @3:1).
+- `lib/Service/ShippedTokenSetAuditService.php`, `lib/Capabilities.php:219-281` — the existing
+  per-set audit + cached `wcagLevel` computation (`ICache` prefix `nldesign_wcag_level`, TTL 3600s)
+  this change's catalogue endpoint reuses rather than re-implements.
+- `lib/Controller/SettingsController.php:242,261,439` — confirms every `settings#*` GET is
+  `#[AuthorizedAdminSetting(Admin::class)]` today (no non-admin read path exists).
+- `appinfo/routes.php` — confirms the `/settings/*` URL prefix is this app's own convention for
+  admin-gated routes, while `/api/*` (metrics, health) is the existing non-`/settings/*` prefix for
+  focused, non-admin-config endpoints.
+- `token-sets.json` — confirms the `theming.{primary_color,background_color,logo}` shape already
+  exists verbatim on every shipped entry (e.g. `rijkshuisstijl`), unchanged since 2026-02.
+- `../../../openbuild/openspec/specs/nldesign-theme-selection/spec.md` (REQ-NTS-002, REQ-NTS-003,
+  REQ-NTS-006) and `../../../openbuild/src/dialogs/ThemePickerDialog.vue:1-19` — the live,
+  already-shipped consumer whose feature-probe stub and filed-issue request this change answers.
+- `../../../openbuild/openspec/specs/app-theming/spec.md` (Requirements "WCAG contrast guardrail
+  blocks saving a non-compliant theme", "Theme applies via the existing scoped CSS-variable
+  mechanism") and `../../../openbuild/src/services/checkThemeContrast.js` — the duplicated WCAG math
+  and hard-block policy this change's contrast entry point and blocking-policy decision resolve.
+- `docs/GOVERNMENT-FEATURES.md` F-03 ("Token set selectie per organisatie"), F-04 ("Aangepaste
+  token sets uploaden"), F-13 ("Theming voor alle Conduction-apps") — the existing government
+  features this change extends to a new class of consumer (a leaf app's own builder-facing picker)
+  without adding a new feature row itself.
+
+## What Changes
+
+- **NEW non-admin, read-only token-set catalogue endpoint** — `GET /api/token-sets`
+  (`#[NoAdminRequired]`, authenticated non-admin user; not `#[PublicPage]`). Reuses
+  `TokenSetService::getAvailableTokenSets()` for discovery (zero duplication) and projects each
+  entry to a closed 5-field contract: `id`, `name`, `design_system`, `theming` (`primary_color`,
+  `background_color`, `logo`), `wcagLevel`. `wcagLevel` is computed and cached exactly as
+  `Capabilities::computeWcagLevel()` already does for the active set, extended to every catalogue
+  entry and sharing the same `ICache` prefix. Deliberately narrower than the admin
+  `getAvailableTokenSets()` response (no `description`, `custom`, `warnings`,
+  `upstreamVersion`/`upstreamRef`) — a minimal, independently-versionable public contract.
+- **NEW shared contrast-evaluation endpoint** — `POST /api/contrast/evaluate`
+  (`#[NoAdminRequired]`). Generalises `ContrastService` beyond its current two fixed pairs: accepts
+  an arbitrary list of candidate colors each tagged `text` (4.5:1) or `ui` (3:1), evaluated against
+  a background (explicit or defaulted), and returns ratio/threshold/level/pass — diagnostic data
+  only, **never** a block/allow verdict. This is the shape a caller like OpenBuild's
+  `checkThemeContrast.js` needs (arbitrary `primaryColor`/`secondaryColor`/`accentColor`, not just
+  nldesign's own fixed primary/text and primary/background pairs) so that JS file can be deleted in
+  the companion OpenBuild change in favour of one shared, server-verified implementation.
+- **NEW published scoped-application contract** — documents (does not implement) the contract a
+  shared client-side applier (the companion `nextcloud-vue` change) implements against: token
+  namespace `--nldesign-*` (existing, reaffirmed), a design-system-owned scope attribute
+  `data-nldesign-theme-scope="<scopeId>"` (superseding leaf-app-owned attributes like OpenBuild's
+  `data-openbuild-theme-scope`), the `:root` → `[data-nldesign-theme-scope="<scopeId>"]`
+  selector-rewrite rule, and the defensive rules already proven necessary by OpenBuild's own
+  rewriter (flat-`:root`-only, bail-and-degrade on any other construct, applies to the base/light
+  `css/tokens/<id>.css` only — the dark variant is explicitly out of scope). Backed by a **new
+  structural-invariant regression test** guaranteeing every shipped token CSS file stays in this
+  shape (custom uploads are already guaranteed by `CustomTokenSetValidator`).
+- **NEW documented blocking-policy resolution** — states explicitly that this endpoint's contrast
+  data is always non-blocking, and that a leaf app **selecting** one of nldesign's curated/shipped
+  or already-uploaded custom sets from the new catalogue MUST treat a contrast result as a warning,
+  never a hard block — consistent with nldesign's own upload-time policy. A leaf app's own
+  **free-hand custom-color authoring** (a distinct concern, e.g. OpenBuild's `appTheme` raw color
+  picker) remains free to apply its own local blocking policy on top of the same shared data; this
+  change resolves the *selection* path only.
+- **No Vue, no OpenBuild changes, no new database/appconfig storage** — read-only projections and
+  computations over existing state.
+
+## Impact
+
+- `lib/Service/TokenSetService.php` — new projection method for the catalogue's closed 5-field
+  shape (reuses `getAvailableTokenSets()`; no change to its existing return shape/consumers).
+- `lib/Service/ContrastService.php` — new `evaluate()`-style method generalising `check()` to
+  arbitrary candidate/role pairs against a background; `check()` (fixed-pair, upload-time) is
+  unchanged.
+- `lib/Capabilities.php` — no change; `computeWcagLevel()`'s per-set audit path is reused, not
+  modified, by the new catalogue projection.
+- New controller(s) (proposed: `CatalogController`, `ContrastController` — small, single-purpose,
+  mirroring the existing `MetricsController`/`HealthController` pattern of focused non-`/settings/*`
+  controllers) and two new `appinfo/routes.php` entries outside the `/settings/*` prefix.
+- `openspec/specs/token-sets/spec.md`, `openspec/specs/theming-capability/spec.md`,
+  `openspec/specs/custom-token-sets/spec.md` — referenced, not modified (this is a NEW capability
+  spec; no existing requirement changes).
+- New PHPUnit structural-invariant test over `css/tokens/*.css` (excluding `dark/`).
+- Docs: a new consumable-contract reference page (scope attribute, rewrite rule, defensive rules,
+  endpoint shapes) for leaf-app authors — the same role `openbuild`'s own spec plays for its
+  consumers today, but published from nldesign's side.