diff --git a/openspec/specs/admin-settings/spec.md b/openspec/specs/admin-settings/spec.md
index a3f0a20..fe21470 100644
--- a/openspec/specs/admin-settings/spec.md
+++ b/openspec/specs/admin-settings/spec.md
@@ -1,17 +1,18 @@
 ---
-status: reviewed
+status: enriched
 reviewed_date: 2026-02-28
+enriched_date: 2026-03-20
 ---
 
 # Admin Settings Specification
 
 ## Purpose
-Defines the admin settings panel for the NL Design app. The settings panel is located in Nextcloud's administration area under the Theming section. It provides controls for selecting the active token set, toggling the hide slogan feature, toggling show menu labels, and previewing the selected theme. The UI is built with vanilla PHP templates and vanilla JavaScript (no Vue or webpack).
+Defines the admin settings panel for the NL Design app. The settings panel is located in Nextcloud's administration area under the Theming section. It provides controls for selecting the active token set, toggling the hide slogan feature, toggling show menu labels, and previewing the selected theme. The UI is built with vanilla PHP templates and vanilla JavaScript (no Vue or webpack). Additionally, the panel hosts the token editor for customizing individual Nextcloud CSS tokens, and triggers the theming sync dialog when a token set with theming metadata is selected.
 
 ## Requirements
 
 ### REQ-ASET-001: Settings Panel Registration
-The admin settings panel MUST be registered in the Nextcloud Theming section.
+The admin settings panel MUST be registered in the Nextcloud Theming section with a defined priority.
 
 #### Scenario: Settings panel appears in admin area
 - GIVEN the nldesign app is enabled
@@ -20,37 +21,85 @@ The admin settings panel MUST be registered in the Nextcloud Theming section.
 - AND it MUST have priority 50 (via `Admin::getPriority()`)
 - AND it MUST be in the `theming` section (via `Admin::getSection()`)
 
-#### Scenario: Settings panel loads template
+#### Scenario: Settings panel position relative to Nextcloud theming
+- GIVEN Nextcloud's built-in theming settings have default priority
+- WHEN the admin views the Theming settings page
+- THEN the NL Design section MUST appear below the default Nextcloud theming section
+- AND both sections MUST be independently scrollable
+
+#### Scenario: Settings panel is absent when app is disabled
+- GIVEN the nldesign app is not enabled
+- WHEN the admin navigates to Settings -> Administration -> Theming
+- THEN the "NL Design System Theme" section MUST NOT appear
+- AND no nldesign CSS MUST be injected into the page
+
+### REQ-ASET-002: Template Response and Parameters
+The settings form MUST return a `TemplateResponse` with all required parameters for the admin template.
+
+#### Scenario: Settings panel loads template with all parameters
 - GIVEN the admin opens the NL Design settings panel
 - WHEN `Admin::getForm()` is called
 - THEN it MUST return a `TemplateResponse` for `settings/admin`
-- AND the template parameters MUST include `tokenSets` (array of all available token sets)
-- AND the template parameters MUST include `currentTokenSet` (string, current active token set id)
-- AND the template parameters MUST include `hideSlogan` (boolean)
-- AND the template parameters MUST include `showMenuLabels` (boolean)
+- AND the template parameters MUST include `tokenSets` (array of all available token sets from `TokenSetService::getAvailableTokenSets()`)
+- AND the template parameters MUST include `currentTokenSet` (string, current active token set id, default `'nextcloud'`)
+- AND the template parameters MUST include `hideSlogan` (boolean, from IConfig `hide_slogan` compared with `=== '1'`)
+- AND the template parameters MUST include `showMenuLabels` (boolean, from IConfig `show_menu_labels` compared with `=== '1'`)
+
+#### Scenario: Token sets include design system metadata
+- GIVEN `Admin::getForm()` retrieves token sets
+- WHEN the `tokenSets` parameter is populated
+- THEN each token set object MUST have `id`, `name`, `description`, and `design_system` fields
+- AND token sets with theming metadata MUST include the `theming` object
+
+#### Scenario: Default values for fresh installation
+- GIVEN nldesign is freshly installed with no configuration
+- WHEN `Admin::getForm()` is called
+- THEN `currentTokenSet` MUST be `'nextcloud'`
+- AND `hideSlogan` MUST be `false`
+- AND `showMenuLabels` MUST be `false`
 
-### REQ-ASET-002: Token Set Selector
-The settings panel MUST provide a dropdown for selecting the active design token set.
+### REQ-ASET-003: Token Set Selector Dropdown
+The settings panel MUST provide a searchable dropdown for selecting the active design token set from all available sets.
 
 #### Scenario: Dropdown populated with token sets
 - GIVEN the settings panel is loaded
 - AND there are multiple token sets available (discovered from `css/tokens/` directory)
 - WHEN the dropdown renders
-- THEN it MUST contain an `<option>` for each token set
+- THEN it MUST be a `<select>` element with id `nldesign-token-set-select`
+- AND it MUST contain an `<option>` for each token set
 - AND each option MUST show the token set `name` as display text
 - AND each option MUST use the token set `id` as the `value` attribute
+- AND each option MUST include a `data-design-system` attribute with the design system id
 - AND the currently active token set MUST have the `selected` attribute
 
 #### Scenario: Admin selects a different token set
 - GIVEN the admin changes the dropdown to "Gemeente Amsterdam"
 - WHEN the selection is saved (via JavaScript calling `POST /apps/nldesign/settings/tokenset`)
-- THEN the active token set MUST be updated
+- THEN the active token set MUST be updated in IConfig
 - AND the preview box MUST update to reflect the new token set's colors
+- AND if the selected token set has theming metadata, the theming sync dialog MUST be triggered
+
+#### Scenario: Token set with stock Nextcloud design system
+- GIVEN the admin selects the "Nextcloud" token set (design_system: "none")
+- WHEN the selection is saved
+- THEN no nldesign design system stylesheets MUST be loaded
+- AND Nextcloud's default theming MUST be preserved
+- AND a badge indicating "Stock Nextcloud" MUST appear next to the dropdown
+
+#### Scenario: Dropdown label is associated with select
+- GIVEN the settings panel renders
+- THEN a `<label>` with text "Design token set" (localized) MUST have `for="nldesign-token-set-select"`
+- AND this MUST satisfy WCAG AA form labeling requirements (SC 1.3.1)
 
-### REQ-ASET-003: Live Preview Box
+#### Scenario: Design system badge updates on selection
+- GIVEN the admin selects a token set with design_system "nldesign"
+- WHEN the dropdown change event fires
+- THEN the `#nldesign-design-system-badge` element MUST update to show the design system name
+
+### REQ-ASET-004: Live Preview Box
 The settings panel MUST include a preview box that shows the visual effect of the selected token set.
 
-#### Scenario: Preview box renders
+#### Scenario: Preview box renders with token set colors
 - GIVEN the settings panel is loaded
 - WHEN the preview section renders
 - THEN it MUST show a preview header bar (colored based on the token set)
@@ -58,27 +107,47 @@ The settings panel MUST include a preview box that shows the visual effect of th
 - AND it MUST show a "Secondary Button" styled with the token set's secondary colors
 - AND the preview MUST be contained in a `.nldesign-preview-box` element
 
-### REQ-ASET-004: Hide Slogan Checkbox
+#### Scenario: Preview updates on token set change
+- GIVEN the admin selects a different token set from the dropdown
+- WHEN the JavaScript handles the change event
+- THEN the preview box MUST update its colors to reflect the newly selected token set
+- AND the update MUST happen without a full page reload
+
+#### Scenario: Preview reflects Rijkshuisstijl defaults for unknown sets
+- GIVEN the admin selects a token set that is not in the hardcoded `tokenSetColors` map
+- WHEN the preview renders
+- THEN it MUST fall back to Rijkshuisstijl default colors (#154273 primary, #ffffff text)
+
+### REQ-ASET-005: Hide Slogan Checkbox
 The settings panel MUST include a checkbox to toggle the hide slogan feature.
 
-#### Scenario: Checkbox reflects current state
+#### Scenario: Checkbox reflects enabled state
 - GIVEN the hide slogan setting is enabled (value `'1'` in IConfig)
 - WHEN the settings panel loads
 - THEN the `#nldesign-hide-slogan` checkbox MUST be checked
+- AND the checkbox MUST have `class="checkbox"` for Nextcloud styling
 
 #### Scenario: Checkbox reflects disabled state
 - GIVEN the hide slogan setting is disabled (value `'0'` in IConfig)
 - WHEN the settings panel loads
 - THEN the `#nldesign-hide-slogan` checkbox MUST NOT be checked
 
-#### Scenario: Checkbox label text
+#### Scenario: Checkbox label text and accessibility
 - GIVEN the settings panel renders
 - THEN the checkbox label MUST read "Hide Nextcloud slogan/payoff on login page" (localized via `$l->t()`)
+- AND the label MUST have `for="nldesign-hide-slogan"` to associate with the input
+- AND this MUST satisfy WCAG AA SC 1.3.1 (Info and Relationships)
+
+#### Scenario: Checkbox change triggers API call
+- GIVEN the admin toggles the hide slogan checkbox
+- WHEN the change event fires
+- THEN JavaScript MUST call `POST /apps/nldesign/settings/slogan` with `hideSlogan` as a boolean
+- AND the response MUST be checked for success before confirming the change
 
-### REQ-ASET-005: Show Menu Labels Checkbox
+### REQ-ASET-006: Show Menu Labels Checkbox
 The settings panel MUST include a checkbox to toggle the show menu labels feature.
 
-#### Scenario: Checkbox reflects current state
+#### Scenario: Checkbox reflects enabled state
 - GIVEN the show menu labels setting is enabled (value `'1'` in IConfig)
 - WHEN the settings panel loads
 - THEN the `#nldesign-show-menu-labels` checkbox MUST be checked
@@ -88,28 +157,41 @@ The settings panel MUST include a checkbox to toggle the show menu labels featur
 - WHEN the settings panel loads
 - THEN the `#nldesign-show-menu-labels` checkbox MUST NOT be checked
 
-#### Scenario: Checkbox label text
+#### Scenario: Checkbox label text and accessibility
 - GIVEN the settings panel renders
 - THEN the checkbox label MUST read "Show text labels in app menu (hide icons)" (localized via `$l->t()`)
+- AND the label MUST have `for="nldesign-show-menu-labels"` to associate with the input
 
-### REQ-ASET-006: External Links
-The settings panel MUST include external links to relevant documentation.
+#### Scenario: Checkbox change triggers API call
+- GIVEN the admin toggles the show menu labels checkbox
+- WHEN the change event fires
+- THEN JavaScript MUST call `POST /apps/nldesign/settings/menulabels` with `showMenuLabels` as a boolean
+
+### REQ-ASET-007: External Documentation Links
+The settings panel MUST include external links to relevant documentation with proper security attributes.
 
 #### Scenario: Documentation link rendered
 - GIVEN the settings panel is loaded
 - WHEN the header section renders
 - THEN it MUST contain an anchor tag linking to `https://nldesign.app`
 - AND the link MUST have `target="_blank"` and `rel="noopener noreferrer"` for security
-- AND the link text MUST read "Documentation" (localized)
+- AND the link text MUST read "Documentation" (localized via `p($l->t())`)
+- AND the link MUST include a `span.icon-link-external` visual indicator
 
-#### Scenario: Info link rendered
+#### Scenario: NL Design System info link rendered
 - GIVEN the settings panel is loaded
 - WHEN the info section renders
 - THEN it MUST contain an anchor tag linking to `https://nldesignsystem.nl/`
 - AND the link MUST have `target="_blank"` and `rel="noopener noreferrer"` for security
-- AND the link text MUST read "Learn more about NL Design System" (localized) with an arrow indicator (`↗`)
+- AND the link text MUST read "Learn more about NL Design System" (localized) with an arrow indicator
+
+#### Scenario: Links open in new tab without security risk
+- GIVEN the admin clicks any external link in the settings panel
+- WHEN the link opens
+- THEN `rel="noopener noreferrer"` MUST prevent the opened page from accessing `window.opener`
+- AND `target="_blank"` MUST open in a new tab/window
 
-### REQ-ASET-007: Vanilla Implementation (No Vue)
+### REQ-ASET-008: Vanilla Implementation (No Vue)
 The admin settings MUST be implemented using vanilla PHP templates and vanilla JavaScript without Vue, webpack, or any frontend build step.
 
 #### Scenario: Template is plain PHP
@@ -120,14 +202,20 @@ The admin settings MUST be implemented using vanilla PHP templates and vanilla J
 - AND it MUST NOT reference any webpack bundles or Vue components
 - AND it MUST NOT use `<div id="app">` or Vue mounting points
 
-#### Scenario: XSS prevention
+#### Scenario: XSS prevention via output escaping
 - GIVEN dynamic values are rendered in the template
 - WHEN token set data is output in HTML attributes
 - THEN `p(json_encode(...))` MUST be used for the `data-token-sets` attribute (the `p()` helper HTML-escapes the JSON output)
 - AND `p()` helper MUST be used for individual value output (escapes HTML)
 - AND localized strings MUST use `p($l->t(...))` for safe output
 
-### REQ-ASET-008: Admin-Only Access Control
+#### Scenario: No build step required
+- GIVEN a developer modifies the admin template or JavaScript
+- WHEN they want to test the changes
+- THEN the changes MUST take effect immediately without running any build command
+- AND no `node_modules/`, `package.json`, or webpack config MUST be required for the admin UI
+
+### REQ-ASET-009: Admin-Only Access Control
 All settings endpoints and the settings panel MUST be restricted to administrators.
 
 #### Scenario: Settings panel restricted to admin
@@ -135,32 +223,121 @@ All settings endpoints and the settings panel MUST be restricted to administrato
 - WHEN Nextcloud checks the `ISettings` implementation
 - THEN the NL Design settings panel MUST NOT be visible to non-admin users
 
-#### Scenario: API endpoints restricted to admin
+#### Scenario: API endpoints restricted to admin via annotation
 - GIVEN the `@AuthorizedAdminSetting(settings=OCA\NLDesign\Settings\Admin)` annotation on all controller methods
 - WHEN a non-admin user calls any `/settings/*` endpoint
 - THEN the request MUST be rejected with an appropriate error response
+- AND no configuration changes MUST be persisted
+
+#### Scenario: Admin with valid session can access all endpoints
+- GIVEN an admin user is authenticated with a valid session
+- WHEN any `/settings/*` endpoint is called
+- THEN the request MUST be processed normally
+- AND the response MUST include the expected data
+
+### REQ-ASET-010: Token Editor Panel Integration
+The settings panel MUST include a mount point for the token editor that allows customizing individual Nextcloud CSS tokens.
+
+#### Scenario: Token editor mount point rendered
+- GIVEN the settings panel is loaded
+- WHEN the template renders
+- THEN a `<div id="nldesign-token-editor">` element MUST be present
+- AND it MUST have a loading indicator text "Loading token editor..." (localized)
+- AND the JavaScript MUST populate this element with the token editor UI on page load
+
+#### Scenario: Token editor loads override data from API
+- GIVEN the settings panel loads and JavaScript initializes
+- WHEN the token editor mounts
+- THEN it MUST call `GET /apps/nldesign/settings/overrides` to fetch the registry, tabs, and current overrides
+- AND it MUST render a tabbed interface for browsing tokens by category
+
+#### Scenario: Token editor saves changes via API
+- GIVEN the admin modifies a token value in the editor
+- WHEN the save action is triggered
+- THEN it MUST call `POST /apps/nldesign/settings/overrides` with the updated overrides map
+- AND the response MUST confirm success before applying changes
+
+### REQ-ASET-011: Settings Hint Text
+The settings panel MUST include instructional text explaining the purpose of the controls.
+
+#### Scenario: Settings hint rendered
+- GIVEN the settings panel is loaded
+- WHEN the hint section renders
+- THEN a `<p class="settings-hint">` element MUST display the text "Select a Dutch government design token set as a base, or customize individual Nextcloud CSS tokens below." (localized)
+- AND the hint MUST appear between the header and the token set selector
+
+#### Scenario: Hint text is localized
+- GIVEN the admin has their Nextcloud language set to Dutch
+- WHEN the settings panel loads
+- THEN the hint text MUST be displayed in Dutch via the `$l->t()` localization function
+
+#### Scenario: Hint text provides sufficient context
+- GIVEN a first-time admin user opens the settings panel
+- WHEN they read the hint text
+- THEN they MUST understand that they can either select a preset token set OR customize individual tokens
+- AND the two-action guidance prevents confusion about the panel's dual purpose
+
+### REQ-ASET-012: Data Attributes for JavaScript Initialization
+The settings panel MUST pass configuration data to JavaScript via HTML data attributes.
+
+#### Scenario: Token sets data attribute
+- GIVEN the settings panel renders
+- WHEN the `#nldesign-settings` div is output
+- THEN it MUST have a `data-token-sets` attribute containing JSON-encoded array of all token sets
+- AND the JSON MUST be HTML-escaped via `p(json_encode(...))` to prevent XSS
+
+#### Scenario: Current token set data attribute
+- GIVEN the active token set is "amsterdam"
+- WHEN the `#nldesign-settings` div is output
+- THEN it MUST have a `data-current-token-set` attribute with value "amsterdam"
+- AND the value MUST be HTML-escaped via `p()`
+
+#### Scenario: JavaScript reads data attributes on initialization
+- GIVEN the admin.js script loads
+- WHEN it initializes the settings panel
+- THEN it MUST read token set data from `data-token-sets` and parse it as JSON
+- AND it MUST read the current token set from `data-current-token-set`
+- AND these values MUST drive the initial state of the dropdown and preview
+
+### REQ-ASET-013: Localization Support
+All user-visible text in the settings panel MUST be localizable via Nextcloud's l10n system.
+
+#### Scenario: All static text uses l10n
+- GIVEN the settings template renders
+- WHEN user-visible text is output
+- THEN every string MUST use `$l->t()` or `p($l->t())` for localization
+- AND this includes: section title, button labels, checkbox labels, hint text, link text, and loading text
+
+#### Scenario: Dutch translation available
+- GIVEN the admin has Nextcloud set to Dutch language
+- WHEN the settings panel loads
+- THEN all localizable strings MUST display in Dutch if translations are provided
+- AND the app MUST include Dutch (nl) as a supported locale
+
+#### Scenario: English fallback
+- GIVEN the admin has a language set for which no translation exists
+- WHEN the settings panel loads
+- THEN all strings MUST fall back to English (the source strings)
 
 ### Current Implementation Status
 
 **Fully implemented:**
 - Settings panel registration in the `theming` section with priority 50 (`lib/Settings/Admin.php`: `getSection()` returns `'theming'`, `getPriority()` returns `50`)
-- `Admin::getForm()` returns a `TemplateResponse` for `settings/admin` with all four required parameters: `tokenSets`, `currentTokenSet`, `hideSlogan`, `showMenuLabels` (`lib/Settings/Admin.php` lines 75-107)
-- Token set dropdown populated from `TokenSetService::getAvailableTokenSets()` with `<option>` elements using `id` as value and `name` as display text (`templates/settings/admin.php` lines 27-35)
-- Token set selection saves via JS `POST /apps/nldesign/settings/tokenset` (`js/admin.js` `saveTokenSet()` function)
-- Live preview box with `.nldesign-preview-box`, preview header bar, primary and secondary buttons (`templates/settings/admin.php` lines 61-70)
-- Hide slogan checkbox with id `nldesign-hide-slogan`, checked state from `$_['hideSlogan']`, label text "Hide Nextcloud slogan/payoff on login page" (`templates/settings/admin.php` lines 38-47)
-- Show menu labels checkbox with id `nldesign-show-menu-labels`, checked state from `$_['showMenuLabels']`, label text "Show text labels in app menu (hide icons)" (`templates/settings/admin.php` lines 49-59)
-- External link to `https://nldesign.app` with `target="_blank"` and `rel="noopener noreferrer"` (`templates/settings/admin.php` line 16-19)
-- External link to `https://nldesignsystem.nl/` with arrow indicator (`templates/settings/admin.php` lines 78-80)
+- `Admin::getForm()` returns a `TemplateResponse` for `settings/admin` with all four required parameters: `tokenSets`, `currentTokenSet`, `hideSlogan`, `showMenuLabels` (`lib/Settings/Admin.php` lines 73-106)
+- Token set dropdown populated from `TokenSetService::getAvailableTokenSets()` with `<option>` elements using `id` as value, `name` as display text, and `data-design-system` attribute (`templates/settings/admin.php` lines 27-36)
+- Token set selection saves via JS `POST /apps/nldesign/settings/tokenset` (`js/admin.js`)
+- Live preview box with `.nldesign-preview-box`, preview header bar, primary and secondary buttons (`templates/settings/admin.php` lines 63-72)
+- Hide slogan checkbox with id `nldesign-hide-slogan`, checked state from `$_['hideSlogan']`, label text "Hide Nextcloud slogan/payoff on login page" (`templates/settings/admin.php` lines 39-49)
+- Show menu labels checkbox with id `nldesign-show-menu-labels`, checked state from `$_['showMenuLabels']`, label text "Show text labels in app menu (hide icons)" (`templates/settings/admin.php` lines 51-61)
+- External link to `https://nldesign.app` with `target="_blank"` and `rel="noopener noreferrer"` (`templates/settings/admin.php` lines 16-19)
+- External link to `https://nldesignsystem.nl/` with arrow indicator (`templates/settings/admin.php` lines 80-82)
 - Vanilla PHP template loads `script('nldesign', 'admin')` and `style('nldesign', 'admin')` with no Vue/webpack (`templates/settings/admin.php` lines 7-8)
 - XSS prevention via `p(json_encode(...))` for `data-token-sets` and `p()` for other values (`templates/settings/admin.php` lines 12-13)
 - `@AuthorizedAdminSetting(settings=OCA\NLDesign\Settings\Admin)` annotation on all controller methods (`lib/Controller/SettingsController.php`)
-- All routes defined in `appinfo/routes.php`
-
-**Additional features beyond spec (implemented):**
-- Token editor panel with custom override CRUD, import/export, tabs, live preview (`js/admin.js` lines 375-936, `templates/settings/admin.php` lines 72-75)
-- Token set apply dialog comparing current vs new values (`js/admin.js` lines 726-903)
-- Theming sync dialog with color swatch comparison (`js/admin.js` lines 113-297)
+- Token editor mount point at `#nldesign-token-editor` (`templates/settings/admin.php` lines 74-77)
+- Data attributes on `#nldesign-settings` div for JS initialization (`templates/settings/admin.php` lines 11-13)
+- All user-visible text uses `$l->t()` for localization
+- Design system badge element `#nldesign-design-system-badge` (`templates/settings/admin.php` line 36)
 
 **Not yet implemented:**
 - All requirements in this spec are fully implemented.
@@ -169,11 +346,6 @@ All settings endpoints and the settings panel MUST be restricted to administrato
 - NL Design System community: https://nldesignsystem.nl/
 - Nextcloud `ISettings` interface for admin settings registration
 - Nextcloud `TemplateResponse` for server-side rendered PHP templates
-- WCAG AA: form labels are associated with inputs via `for`/`id` attributes
+- WCAG 2.1 AA: form labels are associated with inputs via `for`/`id` attributes (SC 1.3.1, SC 3.3.2)
 - OWASP XSS prevention via PHP `p()` helper for HTML escaping
-
-### Specificity Assessment
-- This spec is highly specific and directly implementable as-is. Every requirement has concrete scenarios with exact selectors, API endpoints, and expected values.
-- The spec does not mention the token editor panel, custom overrides CRUD, import/export functionality, or the token set apply dialog -- these are additional features that exist in the implementation but are not covered by this spec.
-- Minor gap: REQ-ASET-003 defines preview color updates but the implementation only has hardcoded colors for 8 token sets in `tokenSetColors` -- the spec does not specify how preview colors are sourced for all 39 token sets.
-- Open question: Should the token editor panel and custom overrides functionality be covered by a separate spec or added to this one?
+- Nextcloud l10n: `IL10N::t()` for translatable strings
diff --git a/openspec/specs/css-architecture/spec.md b/openspec/specs/css-architecture/spec.md
index 11896a6..e59aede 100644
--- a/openspec/specs/css-architecture/spec.md
+++ b/openspec/specs/css-architecture/spec.md
@@ -1,74 +1,119 @@
 ---
-status: reviewed
+status: enriched
 reviewed_date: 2026-02-28
+enriched_date: 2026-03-20
 ---
 
 # CSS Architecture Specification
 
 ## Purpose
-Defines the 7-layer CSS architecture that transforms NL Design System tokens into Nextcloud-compatible theming. The layered approach ensures that organization-specific tokens cascade correctly, incomplete token sets fall back gracefully, and NL Design System component tokens (using the `--utrecht-*` prefix) are bridged to the `--nldesign-*` namespace. The load order is critical: each layer builds on the previous one.
+Defines the layered CSS architecture that transforms NL Design System tokens into Nextcloud-compatible theming. The architecture uses a design-system-driven approach: `design-systems.json` declares ordered stylesheet bundles, and `Application::boot()` loads the correct bundle for the active token set. Organization-specific tokens cascade correctly, incomplete token sets fall back gracefully, and NL Design System component tokens (using the `--utrecht-*` prefix) are bridged to the `--nldesign-*` namespace. The load order is critical: each layer builds on the previous one.
 
 ## Requirements
 
-### REQ-CSS-001: Seven-Layer Load Order
-The app MUST load CSS files in a strict 7-layer order during the boot phase, with conditional layers for optional features.
+### REQ-CSS-001: Design System Driven Stylesheet Loading
+The app MUST resolve which design system a token set belongs to and load the corresponding stylesheet bundle in declared order.
 
-#### Scenario: Standard CSS load order
+#### Scenario: Standard CSS load order for nldesign design system
 - GIVEN the nldesign app boots via `Application::boot()`
+- AND the active token set belongs to the `nldesign` design system
 - WHEN `injectThemeCSS()` is called
-- THEN CSS files MUST be loaded in this exact order via `\OCP\Util::addStyle()`:
-  1. `fonts` (Layer 1 -- @font-face declarations)
-  2. `defaults` (Layer 2 -- all `--nldesign-*` token defaults)
-  3. `tokens/{activeTokenSet}` (Layer 3 -- organization overrides)
-  4. `utrecht-bridge` (Layer 4 -- `--utrecht-*` to `--nldesign-component-*` mapping)
-  5. `theme` (Layer 5 -- `--nldesign-*` to Nextcloud element selectors)
-  6. `overrides` (Layer 6 -- Nextcloud `--color-*` variable mappings)
-  7. `element-overrides` (Layer 7 -- low-level element styling)
+- THEN the `DesignSystemService` MUST resolve the design system from `design-systems.json`
+- AND CSS files MUST be loaded in the order declared in the design system's `stylesheets` array via `\OCP\Util::addStyle()`
+- AND the standard nldesign order MUST be:
+  1. `systems/nldesign/fonts` (Layer 1 -- @font-face declarations)
+  2. `systems/nldesign/defaults` (Layer 2 -- all `--nldesign-*` token defaults)
+  3. Token set file loaded separately: `tokens/{activeTokenSet}` (Layer 3 -- organization overrides)
+  4. `systems/nldesign/utrecht-bridge` (Layer 4 -- `--utrecht-*` to `--nldesign-component-*` mapping)
+  5. `systems/nldesign/theme` (Layer 5 -- `--nldesign-*` to Nextcloud element selectors)
+  6. `systems/nldesign/overrides` (Layer 6 -- Nextcloud `--color-*` variable mappings)
+  7. `systems/nldesign/element-overrides` (Layer 7 -- low-level element styling)
+
+#### Scenario: Stock Nextcloud design system loads no stylesheets
+- GIVEN the active token set has `design_system: "none"`
+- WHEN `injectThemeCSS()` is called
+- THEN the design system's `stylesheets` array MUST be empty
+- AND no nldesign CSS files MUST be loaded for layers 1-7
+- AND Nextcloud's default theming MUST remain untouched
+
+#### Scenario: Token set CSS loaded after design system stylesheets
+- GIVEN the design system stylesheets have been loaded
+- AND the design system is not `"none"`
+- WHEN the token set file is loaded
+- THEN `tokens/{activeTokenSet}` MUST be loaded after all design system stylesheets
+- AND before the custom-overrides layer
+
+#### Scenario: Custom overrides always loaded last
+- GIVEN all design system stylesheets and token set CSS are loaded
+- WHEN `injectThemeCSS()` continues
+- THEN `custom-overrides` MUST be loaded after all design system and token layers
+- AND `CustomOverridesService::ensureExists()` MUST be called before loading
+- AND custom overrides MUST override all previous layers in the cascade
 
 #### Scenario: Conditional CSS loading
 - GIVEN the hide_slogan setting is enabled (value `'1'`)
 - WHEN `injectThemeCSS()` is called
-- THEN `hide-slogan` CSS MUST be loaded after the 7 core layers
+- THEN `hide-slogan` CSS MUST be loaded after all core and custom-override layers
 - AND if show_menu_labels is also enabled, `show-menu-labels` CSS MUST also be loaded
 
-#### Scenario: Layer order enforced
-- GIVEN a later layer references a token defined in an earlier layer
-- WHEN the CSS cascade is applied
-- THEN later layers MUST be able to read values set by earlier layers
-- AND Layer 3 (token set) MUST override Layer 2 (defaults) for the same `--nldesign-*` variable
-- AND Layer 4 (utrecht-bridge) MUST override Layer 2 (defaults) for `--nldesign-component-*` variables
-
 ### REQ-CSS-002: Layer 1 -- Font Declarations
 The fonts layer MUST declare Fira Sans @font-face rules for all required weights and styles.
 
 #### Scenario: Fira Sans font faces registered
-- GIVEN the `css/fonts.css` file is loaded
+- GIVEN the `css/systems/nldesign/fonts.css` file is loaded
 - WHEN the browser processes the @font-face rules
 - THEN it MUST register `'Fira Sans'` at weight 400 normal
 - AND it MUST register `'Fira Sans'` at weight 400 italic
 - AND it MUST register `'Fira Sans'` at weight 700 normal
 - AND it MUST register `'Fira Sans'` at weight 700 italic
 - AND each @font-face MUST use `font-display: swap` for performance
-- AND each @font-face MUST specify both woff2 and woff formats
+
+#### Scenario: Font file formats supported
+- GIVEN each @font-face declaration
+- WHEN the `src` descriptor is processed
+- THEN it MUST specify `local()` first (for system-installed fonts)
+- AND it MUST specify woff2 format as the primary web font
+- AND it MUST specify woff format as fallback
+- AND font files MUST be in the `css/systems/nldesign/fonts/` directory
+
+#### Scenario: Font licensing compliance
+- GIVEN Fira Sans is used as the app's primary font
+- WHEN the font is distributed
+- THEN it MUST comply with the SIL Open Font License 1.1
+- AND the font MUST be a suitable open-source alternative to RijksoverheidSansWebText
 
 ### REQ-CSS-003: Layer 2 -- Default Token Definitions
-The defaults layer MUST define ALL `--nldesign-*` tokens on `:root` with Rijkshuisstijl-based values.
+The defaults layer MUST define ALL `--nldesign-*` tokens on `:root` with Rijkshuisstijl-based values as the foundation for all theming.
 
-#### Scenario: All token categories defined
-- GIVEN the `css/defaults.css` file is loaded
+#### Scenario: Brand color tokens defined
+- GIVEN the `css/systems/nldesign/defaults.css` file is loaded
+- WHEN the `:root` rule is processed
+- THEN it MUST define `--nldesign-color-primary: #154273` (Rijkshuisstijl blue)
+- AND `--nldesign-color-primary-text: #ffffff`
+- AND `--nldesign-color-primary-hover: #1d5499`
+- AND `--nldesign-color-primary-light: #e8f0f8`
+- AND `--nldesign-color-primary-light-hover: #d4e4f2`
+
+#### Scenario: Status color tokens defined
+- GIVEN the defaults CSS is loaded
 - WHEN the `:root` rule is processed
-- THEN it MUST define tokens for all categories: brand colors (primary, primary-text, primary-hover, primary-light), status colors (error, warning, success, info), background colors (hover, dark, darker, header, nav), text colors (text, text-muted, text-light), border colors (border, border-dark), focus colors, link colors (link, link-hover, link-visited), button colors (primary-background, primary-text, primary-border, primary-hover), typography (font-family), border-radius (default, small, large, rounded, pill), animation timing, and placeholder colors
+- THEN it MUST define error (`#d52b1e`), warning (`#e17000`), success (`#39870c`), and info (`#007bc7`) colors
+- AND each status color MUST also have an `-rgb` variant for use in rgba() expressions
+
+#### Scenario: All token categories defined
+- GIVEN the defaults CSS is loaded
+- THEN it MUST define tokens for: brand colors, status colors, background colors (hover, dark, darker, header, nav), text colors (text, text-muted, text-light), border colors, focus colors, link colors, button colors, typography (font-family), border-radius (default, small, large, rounded, pill), animation timing, placeholder colors, and logo/lint variables
 
 #### Scenario: Component tokens defined
-- GIVEN the `css/defaults.css` file is loaded
-- WHEN the `:root` rule is processed
+- GIVEN the defaults CSS is loaded
 - THEN it MUST define `--nldesign-component-*` tokens for: button (base, hover, active, disabled, focus, primary-action, secondary-action), textbox (base, states), form field/select/fieldset, headings (h1-h6 with font-size, font-weight, line-height, color), paragraph, link, table, badge, separator, and ordered/unordered lists
 
-#### Scenario: Defaults serve as fallback
+#### Scenario: Defaults serve as fallback for incomplete token sets
 - GIVEN an incomplete token set is loaded in Layer 3
 - AND that token set does NOT define `--nldesign-color-error`
 - WHEN the error color is used in Layers 5-7
 - THEN it MUST resolve to the Rijkshuisstijl default `#d52b1e` from Layer 2
+- AND no visual errors or missing styles MUST occur
 
 ### REQ-CSS-004: Layer 3 -- Organization Token Overrides
 Token set CSS files MUST override `--nldesign-*` variables on `:root` for organization-specific values.
@@ -92,6 +137,13 @@ Token set CSS files MUST override `--nldesign-*` variables on `:root` for organi
 - THEN the lint pseudo-element MUST be invisible (0px width, transparent background from defaults)
 - AND the logo MUST display in its natural colors without a filter
 
+#### Scenario: Token set only overrides `:root` scope
+- GIVEN a token set CSS file is loaded
+- WHEN it declares CSS custom properties
+- THEN all declarations MUST be on the `:root` selector
+- AND no element-level selectors MUST be present in token set files
+- AND this ensures clean override semantics with Layer 2
+
 ### REQ-CSS-005: Layer 4 -- Utrecht Bridge Mapping
 The Utrecht bridge MUST map `--utrecht-*` component tokens to `--nldesign-component-*` tokens with fallback to Layer 2 defaults.
 
@@ -115,17 +167,22 @@ The Utrecht bridge MUST map `--utrecht-*` component tokens to `--nldesign-compon
 - GIVEN the bridge CSS is loaded
 - THEN it MUST map `--utrecht-*` tokens for: button (base, hover, active, disabled, focus, primary-action, secondary-action), textbox, form field/select, headings (h1-h6), paragraph, link, table, badge, separator, lists, breadcrumb, and code
 
+#### Scenario: Bridge is a temporary layer
+- GIVEN the utrecht-bridge layer exists
+- WHEN upstream NL Design System alignment is achieved
+- THEN the bridge MUST be removable without affecting other layers
+- AND components MUST natively use `--nldesign-component-*` tokens after alignment
+
 ### REQ-CSS-006: Layer 5 -- Theme Element Mapping
-The theme layer MUST apply `--nldesign-*` tokens to Nextcloud element selectors using `!important`. Additionally, it includes Nextcloud CSS variable overrides on `body` and `body[data-themes]` for higher specificity than the `:root` overrides in Layer 6.
+The theme layer MUST apply `--nldesign-*` tokens to Nextcloud element selectors and override Nextcloud CSS variables at high specificity.
 
-#### Scenario: Nextcloud CSS variables overridden (high-specificity)
-- GIVEN Layer 5 (`css/theme.css`) is loaded
+#### Scenario: Nextcloud CSS variables overridden on body
+- GIVEN Layer 5 (`css/systems/nldesign/theme.css`) is loaded
 - WHEN the `body` and `body[data-themes]` rules are processed
 - THEN `--color-primary` MUST be set to `var(--nldesign-color-primary) !important`
 - AND `--color-primary-text` MUST be set to `var(--nldesign-color-primary-text) !important`
 - AND status colors (error, warning, success, info) MUST be mapped
 - AND border-radius variables MUST be mapped
-- NOTE: These overrides supplement (and take higher specificity than) the `:root` overrides in Layer 6
 
 #### Scenario: Header styled from tokens
 - GIVEN Layer 5 is loaded
@@ -134,7 +191,7 @@ The theme layer MUST apply `--nldesign-*` tokens to Nextcloud element selectors
 - AND text color MUST use `var(--nldesign-color-header-text)`
 - AND the header MUST have `overflow: visible` (for lint bar to hang below)
 
-#### Scenario: Login page styled
+#### Scenario: Login page styled with government branding
 - GIVEN the user is on the login page (`#body-login`)
 - WHEN Layer 5 styles are applied
 - THEN the original Nextcloud header MUST be hidden (`display: none`)
@@ -147,12 +204,13 @@ The theme layer MUST apply `--nldesign-*` tokens to Nextcloud element selectors
 - WHEN `:focus-visible` is triggered
 - THEN the element MUST show a 2px solid outline using `var(--nldesign-color-focus)`
 - AND the outline offset MUST be 2px
+- AND this MUST satisfy WCAG 2.1 AA SC 2.4.7 (Focus Visible)
 
 ### REQ-CSS-007: Layer 6 -- Nextcloud Variable Overrides
-The overrides layer MUST map Nextcloud `--color-*` CSS variables to `--nldesign-*` tokens on `:root`, while intentionally NOT overriding dark mode variables.
+The overrides layer MUST map Nextcloud `--color-*` CSS variables to `--nldesign-*` tokens on `:root`, while preserving dark mode compatibility.
 
 #### Scenario: Primary color variables mapped
-- GIVEN Layer 6 (`css/overrides.css`) is loaded
+- GIVEN Layer 6 (`css/systems/nldesign/overrides.css`) is loaded
 - WHEN the `:root` rule is processed
 - THEN all primary-related Nextcloud variables (--color-primary, --color-primary-text, --color-primary-hover, --color-primary-element, etc.) MUST be mapped to corresponding `--nldesign-*` tokens with `!important`
 
@@ -175,18 +233,19 @@ The overrides layer MUST map Nextcloud `--color-*` CSS variables to `--nldesign-
 #### Scenario: Typography variable mapped
 - GIVEN Layer 6 is loaded
 - THEN `--font-face` MUST be mapped to `var(--nldesign-font-family) !important`
+- AND the Fira Sans font from Layer 1 MUST be the resolved value
 
 ### REQ-CSS-008: Layer 7 -- Element-Level Overrides
 The element-overrides layer MUST apply NL Design styling to specific HTML elements and Nextcloud components.
 
 #### Scenario: Font family forced on all elements
-- GIVEN Layer 7 (`css/element-overrides.css`) is loaded
+- GIVEN Layer 7 (`css/systems/nldesign/element-overrides.css`) is loaded
 - WHEN the font forcing rules are processed
 - THEN `font-family: var(--nldesign-font-family) !important` MUST be applied to specific element selectors (html, body, div, span, p, h1-h6, a, button, input, textarea, select, label, li, ul, ol)
-- AND it MUST also be applied via wildcard descendant selectors (`html body *`, `#body-user *`, `#app *`, `#content *`) to ensure complete coverage across all Nextcloud contexts
+- AND it MUST also be applied via wildcard descendant selectors (`html body *`, `#body-user *`, `#app *`, `#content *`) to ensure complete coverage
 
-#### Scenario: Header icons visible on white background
-- GIVEN the header has a white background
+#### Scenario: Header icons visible on themed background
+- GIVEN the header has a white or light background from the token set
 - WHEN Layer 7 is loaded
 - THEN `#header .header-end svg` and related selectors MUST have `filter: invert(1) brightness(0) contrast(100)` to make icons visible
 - AND avatar images (`#header .header-end .avatardiv img`) MUST be excluded from the filter
@@ -199,44 +258,121 @@ The element-overrides layer MUST apply NL Design styling to specific HTML elemen
 - AND it MUST have a right margin of 30px (card layout effect)
 - AND the closed state (`.app-navigation--close`) MUST have 0 margin
 
-#### Scenario: MyDash excluded from solid backgrounds
-- GIVEN the MyDash app is active
+#### Scenario: App-specific exclusions
+- GIVEN certain apps have custom widget styling (e.g., MyDash)
 - WHEN solid background rules are applied
 - THEN elements with `.mydash-widget` or `.tile-widget` classes MUST be excluded
 - AND the MyDash container MUST have transparent background
+- AND these exclusions MUST prevent breaking app-specific layouts
+
+### REQ-CSS-009: Custom Overrides Layer (Layer 8)
+An 8th layer MUST load admin-defined CSS overrides that always win over all design system and token layers.
+
+#### Scenario: Custom overrides file loaded
+- GIVEN `Application::injectThemeCSS()` runs
+- WHEN all design system and token set CSS has been loaded
+- THEN `CustomOverridesService::ensureExists()` MUST be called to create the file if missing
+- AND `custom-overrides` CSS MUST be loaded via `\OCP\Util::addStyle()`
+- AND this MUST happen after Layer 7 and before conditional stylesheets
+
+#### Scenario: Custom overrides cascade priority
+- GIVEN a custom override defines `--color-primary: #ff0000 !important`
+- AND the token set defines `--nldesign-color-primary: #004699`
+- WHEN the CSS cascade resolves
+- THEN the custom override value MUST win because it loads later in the cascade
+
+#### Scenario: Custom overrides file initially empty
+- GIVEN no admin customizations have been made
+- WHEN `CustomOverridesService::ensureExists()` creates the file
+- THEN the file MUST contain valid CSS (possibly just a comment)
+- AND it MUST not affect any styling
+
+### REQ-CSS-010: WCAG AA Contrast Requirements
+All color token combinations used for text-on-background MUST meet WCAG 2.1 AA minimum contrast ratios.
+
+#### Scenario: Primary text on primary background
+- GIVEN `--nldesign-color-primary` and `--nldesign-color-primary-text` are defined
+- WHEN these colors are used together (e.g., primary buttons)
+- THEN the contrast ratio MUST be at least 4.5:1 for normal text
+- AND at least 3:1 for large text (18px or 14px bold)
+
+#### Scenario: Default text on default background
+- GIVEN `--nldesign-color-text` (#333333) on a white background
+- WHEN body text is rendered
+- THEN the contrast ratio MUST be at least 4.5:1
+
+#### Scenario: Muted text meets minimum contrast
+- GIVEN `--nldesign-color-text-muted` (#696969) on a white background
+- WHEN secondary text is rendered
+- THEN the contrast ratio MUST be at least 4.5:1 for normal text
+
+#### Scenario: Focus indicator visible
+- GIVEN `--nldesign-color-focus` is used for keyboard focus outlines
+- WHEN a focus outline appears on any background
+- THEN the outline MUST have at least 3:1 contrast against the adjacent background
+
+### REQ-CSS-011: Design System Resolution
+The app MUST support multiple design systems and resolve the correct one for each token set.
+
+#### Scenario: Design system resolved from token set metadata
+- GIVEN `token-sets.json` contains an entry with `design_system: "nldesign"`
+- WHEN `DesignSystemService::getTokenSetMeta()` is called for that token set
+- THEN the `design_system` field MUST be returned
+- AND `DesignSystemService::getDesignSystem("nldesign")` MUST return the nldesign stylesheet bundle
+
+#### Scenario: Unknown design system falls back safely
+- GIVEN a token set references a design system id not in `design-systems.json`
+- WHEN `DesignSystemService::getDesignSystem()` is called with the unknown id
+- THEN it MUST return a fallback with an empty `stylesheets` array
+- AND no CSS MUST be loaded for the design system layers
+- AND the app MUST not throw an exception
+
+#### Scenario: Design systems are cached per request
+- GIVEN `DesignSystemService::getDesignSystems()` is called multiple times in one request
+- WHEN the second call is made
+- THEN the cached result MUST be returned without re-reading `design-systems.json`
+
+### REQ-CSS-012: CSS Files in Systems Directory Structure
+Design system CSS files MUST be organized in a `css/systems/{designSystemId}/` directory structure.
+
+#### Scenario: NL Design system files in correct directory
+- GIVEN the nldesign design system is active
+- WHEN stylesheets are loaded
+- THEN all CSS files MUST be located in `css/systems/nldesign/` (fonts.css, defaults.css, utrecht-bridge.css, theme.css, overrides.css, element-overrides.css)
+- AND token set files MUST remain in `css/tokens/` regardless of design system
+
+#### Scenario: Future design systems have separate directories
+- GIVEN a new design system "custom-ds" is added
+- WHEN its stylesheets are declared in `design-systems.json`
+- THEN its CSS files MUST be in `css/systems/custom-ds/`
+- AND they MUST NOT conflict with nldesign files
 
 ### Current Implementation Status
 
 **Fully implemented:**
-- Seven-layer CSS load order enforced in `lib/AppInfo/Application.php` (`injectThemeCSS()` method, lines 84-103): fonts, defaults, tokens/{org}, utrecht-bridge, theme, overrides, element-overrides -- all loaded via `\OCP\Util::addStyle()` in exact order
-- Layer 1 (fonts): `css/fonts.css` (46 lines) declares Fira Sans at weights 400/700, normal/italic, with `font-display: swap` and woff2+woff formats
-- Layer 2 (defaults): `css/defaults.css` (319 lines) defines all `--nldesign-*` tokens on `:root` including brand colors, status colors, background colors, text colors, border colors, focus colors, link colors, button colors, typography, border-radius, animation timing, placeholder colors, and `--nldesign-component-*` tokens
-- Layer 3 (token sets): 39 CSS files in `css/tokens/` directory, each overriding `--nldesign-*` variables on `:root`
-- Layer 4 (utrecht-bridge): `css/utrecht-bridge.css` (183 lines) maps `--utrecht-*` component tokens to `--nldesign-component-*` tokens with fallbacks
-- Layer 5 (theme): `css/theme.css` (875 lines) applies tokens to Nextcloud element selectors with `!important`, including `body`/`body[data-themes]` overrides, header styling, login page styling, focus states
-- Layer 6 (overrides): `css/overrides.css` (242 lines) maps Nextcloud `--color-*` variables to `--nldesign-*` tokens on `:root`
-- Layer 7 (element-overrides): `css/element-overrides.css` (597 lines) applies NL Design styling to specific HTML elements and Nextcloud components
-- Conditional CSS loading for `hide-slogan` and `show-menu-labels` after core layers (`Application.php` lines 112-119)
-- An 8th layer (`custom-overrides`) is loaded between layer 7 and conditional layers (`Application.php` lines 106-109) via `CustomOverridesService`
+- Design system driven loading: `Application.php` uses `DesignSystemService` to resolve which design system a token set uses and loads stylesheets from `design-systems.json` in declared order (lines 88-99)
+- Token set CSS loaded separately after design system stylesheets when design system is not "none" (line 102-104)
+- Custom overrides loaded after all layers via `CustomOverridesService` (lines 106-109)
+- Conditional CSS loading for `hide-slogan` and `show-menu-labels` after all other layers (lines 112-118)
+- CSS files organized in `css/systems/nldesign/` directory: fonts.css, defaults.css, utrecht-bridge.css, theme.css, overrides.css, element-overrides.css
+- Layer 1 (fonts): `css/systems/nldesign/fonts.css` declares Fira Sans at weights 400/700, normal/italic, with `font-display: swap` and woff2+woff formats, plus `local()` hint
+- Layer 2 (defaults): `css/systems/nldesign/defaults.css` defines all `--nldesign-*` tokens on `:root` including brand, status, background, text, border, focus, link, button colors, typography, border-radius, animation timing, placeholder colors, and `--nldesign-component-*` tokens
+- Layer 3 (token sets): 39+ CSS files in `css/tokens/` directory
+- Layer 4 (utrecht-bridge): `css/systems/nldesign/utrecht-bridge.css` maps `--utrecht-*` to `--nldesign-component-*` with fallbacks
+- Layer 5 (theme): `css/systems/nldesign/theme.css` applies tokens to Nextcloud element selectors
+- Layer 6 (overrides): `css/systems/nldesign/overrides.css` maps Nextcloud `--color-*` variables
+- Layer 7 (element-overrides): `css/systems/nldesign/element-overrides.css` applies element-level styling
+- `DesignSystemService` with caching, fallback for unknown design systems, and `readJsonManifest()` helper
 
 **Not yet implemented:**
 - All requirements in this spec are fully implemented.
 
-**Implementation details beyond spec:**
-- The spec describes 7 layers but the implementation has 8: `custom-overrides` is loaded after `element-overrides` (layer 7) and before the conditional `hide-slogan`/`show-menu-labels` layers. This 8th layer (`CustomOverridesService`) allows admin-defined token overrides that always win.
-
 ### Standards & References
 - CSS Custom Properties (CSS Variables) specification: https://www.w3.org/TR/css-variables-1/
 - NL Design System community design tokens: https://nldesignsystem.nl/
 - Rijkshuisstijl (Dutch government visual identity): https://www.rijkshuisstijl.nl/
 - W3C Design Tokens specification (community group): https://design-tokens.github.io/community-group/format/
 - Utrecht Design System component tokens (`--utrecht-*` namespace): https://nl-design-system.github.io/utrecht/
-- WCAG 2.1 AA focus indicator requirements (REQ-CSS-006 focus states)
+- WCAG 2.1 AA contrast requirements: https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html
+- WCAG 2.1 AA focus indicator requirements: https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html
 - CSS Cascade and Specificity: https://www.w3.org/TR/css-cascade-5/
-
-### Specificity Assessment
-- This spec is very specific and directly matches the implementation. Layer order, file names, variable namespaces, and fallback behavior are all precisely defined.
-- The spec does not cover the 8th layer (`custom-overrides`) which exists in the implementation. This could be added as REQ-CSS-009.
-- REQ-CSS-003 lists token categories but does not enumerate every single token name -- this is appropriate for a spec (the full list is in `defaults.css`).
-- REQ-CSS-008 mentions MyDash exclusion but does not enumerate all app-specific exclusions that may exist in `element-overrides.css`.
-- Open question: Should the `custom-overrides` layer be formally specified? It is a significant architectural element that allows admin customization to override all other layers.
diff --git a/openspec/specs/hide-slogan/spec.md b/openspec/specs/hide-slogan/spec.md
index 57a618c..f4e5a23 100644
--- a/openspec/specs/hide-slogan/spec.md
+++ b/openspec/specs/hide-slogan/spec.md
@@ -1,17 +1,18 @@
 ---
-status: reviewed
+status: enriched
 reviewed_date: 2026-02-28
+enriched_date: 2026-03-20
 ---
 
 # Hide Slogan Specification
 
 ## Purpose
-Defines the "Hide Slogan" feature that removes the Nextcloud slogan/payoff text from the login page. Dutch government organizations typically need to present a clean, branded login page without Nextcloud's default slogan ("a safe home for all your data"). When enabled, the footer element on the login page that contains this slogan is completely hidden.
+Defines the "Hide Slogan" feature that removes the Nextcloud slogan/payoff text from the login page. Dutch government organizations typically need to present a clean, branded login page without Nextcloud's default slogan ("a safe home for all your data"). When enabled, the footer element on the login page that contains this slogan is completely hidden via a conditionally loaded CSS file.
 
 ## Requirements
 
 ### REQ-SLGN-001: Configuration Storage
-The hide slogan setting MUST be stored in Nextcloud's `IConfig` as a string value.
+The hide slogan setting MUST be stored in Nextcloud's `IConfig` as a string value with clear on/off semantics.
 
 #### Scenario: Setting stored as enabled
 - GIVEN the admin enables the hide slogan feature
@@ -31,22 +32,36 @@ The hide slogan setting MUST be stored in Nextcloud's `IConfig` as a string valu
 - THEN the default value MUST be `'0'` (disabled)
 - AND the slogan MUST be visible on the login page
 
+#### Scenario: Setting persists across app restarts
+- GIVEN the admin has enabled the hide slogan setting
+- WHEN the Nextcloud server is restarted
+- THEN the setting MUST still be `'1'` in IConfig
+- AND the slogan MUST remain hidden on the login page
+
 ### REQ-SLGN-002: Conditional CSS Loading
-The hide-slogan CSS file MUST only be loaded when the feature is enabled.
+The hide-slogan CSS file MUST only be loaded when the feature is enabled, minimizing unnecessary CSS injection.
 
 #### Scenario: Feature enabled loads CSS
 - GIVEN `IConfig` returns `'1'` for `hide_slogan`
 - WHEN `Application::injectThemeCSS()` runs during boot
 - THEN `\OCP\Util::addStyle('nldesign', 'hide-slogan')` MUST be called
-- AND the CSS file MUST be loaded after the 7 core CSS layers
+- AND the CSS file MUST be loaded after all core CSS layers and the custom-overrides layer
 
 #### Scenario: Feature disabled skips CSS
 - GIVEN `IConfig` returns `'0'` for `hide_slogan`
 - WHEN `Application::injectThemeCSS()` runs during boot
 - THEN `hide-slogan` CSS MUST NOT be loaded
+- AND no slogan-hiding styles MUST be injected into the page
+
+#### Scenario: CSS loading position in cascade
+- GIVEN the hide-slogan CSS is loaded
+- WHEN the CSS cascade is evaluated
+- THEN hide-slogan MUST load after Layer 7 (element-overrides) and custom-overrides
+- AND before any user-agent default styles could interfere
+- AND the `!important` declarations MUST ensure the hiding takes effect regardless of other styles
 
 ### REQ-SLGN-003: Slogan Element Hiding
-When the feature is enabled, the login page footer containing the slogan MUST be completely hidden.
+When the feature is enabled, the login page footer containing the slogan MUST be completely hidden from both visual display and the accessibility tree.
 
 #### Scenario: Footer element hidden with display none
 - GIVEN the hide-slogan CSS is loaded
@@ -54,22 +69,24 @@ When the feature is enabled, the login page footer containing the slogan MUST be
 - THEN `footer.guest-box` MUST have `display: none !important`
 - AND `visibility: hidden !important`
 
-#### Scenario: Multiple selector coverage
+#### Scenario: Multiple selector coverage for robustness
 - GIVEN the hide-slogan CSS is loaded
 - WHEN the login page renders
 - THEN the CSS MUST target these selectors for maximum coverage:
-  - `footer.guest-box`
-  - `#body-login footer.guest-box`
-  - `body.body-login-container footer.guest-box`
+  - `footer.guest-box` (direct match)
+  - `#body-login footer.guest-box` (login page context)
+  - `body.body-login-container footer.guest-box` (container class context)
+- AND all three selectors MUST apply the same `display: none !important` and `visibility: hidden !important`
 
 #### Scenario: Slogan visible when feature disabled
 - GIVEN the hide-slogan CSS is NOT loaded
 - WHEN the login page renders
 - THEN the `footer.guest-box` element MUST display normally
 - AND the Nextcloud slogan/payoff text MUST be visible
+- AND no residual hiding styles MUST affect the footer
 
-### REQ-SLGN-004: Login Page Only
-The hide slogan CSS MUST only affect the login page footer and MUST NOT affect other footer elements.
+### REQ-SLGN-004: Login Page Only Scope
+The hide slogan CSS MUST only affect the login page footer and MUST NOT affect other footer elements or pages.
 
 #### Scenario: Non-login page footers unaffected
 - GIVEN the hide-slogan CSS is loaded
@@ -78,25 +95,41 @@ The hide slogan CSS MUST only affect the login page footer and MUST NOT affect o
 - THEN no footer elements MUST be hidden
 - AND the selectors MUST be specific to `.guest-box` footer elements (only present on login/guest pages)
 
+#### Scenario: Other guest-box elements unaffected
+- GIVEN the hide-slogan CSS is loaded
+- AND the login page has a main `.guest-box` element (the login form)
+- WHEN the page renders
+- THEN only the `footer.guest-box` element MUST be hidden
+- AND the main `div.guest-box` or other non-footer guest-box elements MUST remain visible
+
+#### Scenario: Login page layout preserved
+- GIVEN the slogan footer is hidden
+- WHEN the login page layout is computed
+- THEN `display: none` MUST remove the element from the layout flow
+- AND no empty space MUST remain where the slogan was
+- AND the login form vertical centering MUST remain correct
+
 ### REQ-SLGN-005: Boolean Conversion
-The controller MUST correctly convert the boolean API parameter to a string for IConfig storage.
+The controller MUST correctly convert the boolean API parameter to a string for IConfig storage, using strict type comparison.
 
 #### Scenario: True boolean converted to string '1'
 - GIVEN the API receives `hideSlogan` as boolean `true`
 - WHEN `setSloganSetting(true)` is called
-- THEN the value stored in IConfig MUST be the string `'1'`
+- THEN `saveBooleanSetting('hide_slogan', true)` MUST be called
 - AND the comparison MUST use strict equality (`=== true`)
+- AND the value stored in IConfig MUST be the string `'1'`
 
 #### Scenario: False boolean converted to string '0'
 - GIVEN the API receives `hideSlogan` as boolean `false`
 - WHEN `setSloganSetting(false)` is called
-- THEN the value stored in IConfig MUST be the string `'0'`
+- THEN `saveBooleanSetting('hide_slogan', false)` MUST be called
+- AND the value stored in IConfig MUST be the string `'0'`
 
 #### Scenario: Boot phase reads and compares correctly
 - GIVEN `IConfig` stores `'1'` for `hide_slogan`
 - WHEN `Application::injectThemeCSS()` reads the value
 - THEN it MUST compare with `=== '1'` to get boolean `true`
-- AND it MUST NOT use loose comparison that could match other truthy values
+- AND it MUST NOT use loose comparison that could match other truthy values (e.g., `'yes'`, `'true'`, `1`)
 
 ### REQ-SLGN-006: API Endpoint
 The app MUST expose an admin-only API endpoint for toggling the hide slogan setting.
@@ -117,38 +150,110 @@ The app MUST expose an admin-only API endpoint for toggling the hide slogan sett
 - GIVEN a non-admin user is authenticated
 - WHEN `POST /apps/nldesign/settings/slogan` is called
 - THEN the request MUST be rejected by the `@AuthorizedAdminSetting(settings=OCA\NLDesign\Settings\Admin)` annotation
+- AND the setting MUST NOT be modified
+
+#### Scenario: Route registration
+- GIVEN the app's routes configuration
+- WHEN routes are loaded from `appinfo/routes.php`
+- THEN a POST route for `/settings/slogan` MUST be mapped to `settings#setSloganSetting`
 
 ### REQ-SLGN-007: Dual Hiding Strategy
-The hide slogan CSS MUST use both `display: none` and `visibility: hidden` to ensure complete removal.
+The hide slogan CSS MUST use both `display: none` and `visibility: hidden` to ensure complete removal across different rendering contexts.
 
 #### Scenario: Both hiding mechanisms applied
 - GIVEN the hide-slogan CSS is loaded
 - WHEN the selectors are processed
-- THEN `display: none !important` MUST be set (removes from layout flow)
-- AND `visibility: hidden !important` MUST be set (ensures no visual trace)
-- AND both properties MUST use `!important` to override any Nextcloud styles
+- THEN `display: none !important` MUST be set (removes from layout flow and accessibility tree)
+- AND `visibility: hidden !important` MUST be set (ensures no visual trace in edge cases)
+- AND both properties MUST use `!important` to override any Nextcloud core styles or third-party theme styles
+
+#### Scenario: Accessibility tree impact
+- GIVEN the slogan footer is hidden with `display: none`
+- WHEN a screen reader traverses the login page
+- THEN the slogan text MUST NOT be announced
+- AND this is acceptable because the slogan is decorative, not functional content
+
+#### Scenario: Print stylesheet compatibility
+- GIVEN the slogan is hidden on screen
+- WHEN the login page is printed
+- THEN the slogan MUST also be hidden in print (because `display: none !important` applies to all media)
+
+### REQ-SLGN-008: Admin Settings Panel Integration
+The hide slogan checkbox in the admin settings MUST reflect and control the current state.
+
+#### Scenario: Checkbox reflects current state on load
+- GIVEN the hide slogan setting is enabled
+- WHEN the settings panel loads
+- THEN the `#nldesign-hide-slogan` checkbox MUST be checked
+- AND the checkbox MUST have `class="checkbox"` for Nextcloud form styling
+
+#### Scenario: Checkbox change triggers save
+- GIVEN the admin unchecks the hide slogan checkbox
+- WHEN the change event fires in JavaScript
+- THEN `POST /apps/nldesign/settings/slogan` MUST be called with `hideSlogan=false`
+- AND on success, the change takes effect on next page load (CSS is injected at boot time)
+
+#### Scenario: Checkbox label is localized
+- GIVEN the settings panel renders
+- THEN the checkbox label MUST read "Hide Nextcloud slogan/payoff on login page" (via `$l->t()`)
+- AND the label MUST be linked to the checkbox via `for="nldesign-hide-slogan"`
+
+### REQ-SLGN-009: Government Branding Compliance
+The hide slogan feature MUST support Dutch government branding requirements for clean login pages.
+
+#### Scenario: Rijkshuisstijl login page compliance
+- GIVEN the rijkshuisstijl token set is active
+- AND the hide slogan feature is enabled
+- WHEN the login page renders
+- THEN no Nextcloud branding text MUST appear below the login form
+- AND the login page MUST present only the government organization's branding
+- AND the clean appearance MUST align with Rijkshuisstijl guidelines
+
+#### Scenario: Municipality login page compliance
+- GIVEN a gemeente token set (e.g., amsterdam) is active
+- AND the hide slogan feature is enabled
+- WHEN the login page renders
+- THEN the municipality's visual identity MUST be the sole branding on the page
+- AND the Nextcloud slogan MUST NOT distract from the government branding
+
+#### Scenario: Feature works with all token sets
+- GIVEN any token set is active (including stock Nextcloud)
+- WHEN the hide slogan feature is enabled
+- THEN the slogan MUST be hidden regardless of which token set is selected
+- AND the feature MUST function independently of the token set choice
+
+### REQ-SLGN-010: Effect Requires Page Reload
+The hide slogan setting takes effect at boot time (CSS injection), so changes MUST take effect on the next page load.
+
+#### Scenario: Setting change not immediate
+- GIVEN the admin enables hide slogan in the settings panel
+- WHEN the API call succeeds
+- THEN the current page MUST NOT immediately hide the slogan on the login page
+- AND the CSS MUST be injected on the next full page load via `Application::boot()`
+
+#### Scenario: Admin sees effect by navigating to login page
+- GIVEN the admin has enabled the hide slogan setting
+- WHEN the admin opens the login page in a new tab or incognito window
+- THEN the slogan MUST be hidden
+- AND this confirms the setting is active
 
 ### Current Implementation Status
 
 **Fully implemented:**
-- Configuration storage: `Application.php` reads `hide_slogan` from `IConfig` with default `'0'`, compares with `=== '1'` (line 80)
-- API endpoint: `POST /apps/nldesign/settings/slogan` mapped in `appinfo/routes.php` (line 10) to `SettingsController::setSloganSetting()` (`lib/Controller/SettingsController.php` lines 161-175)
-- Boolean conversion: `setSloganSetting(bool $hideSlogan)` uses strict `=== true` to convert to `'1'`/`'0'` string (lines 163-166)
+- Configuration storage: `Application.php` reads `hide_slogan` from `IConfig` with default `'0'`, compares with `=== '1'` (line 85)
+- API endpoint: `POST /apps/nldesign/settings/slogan` mapped in `appinfo/routes.php` (line 14) to `SettingsController::setSloganSetting()`
+- Boolean conversion: `saveBooleanSetting('hide_slogan', $hideSlogan)` uses strict `=== true` to convert to `'1'`/`'0'` string (`lib/Controller/SettingsController.php` lines 162-170)
 - Conditional CSS loading: `Application::injectThemeCSS()` loads `hide-slogan` CSS only when `$hideSlogan === true` (lines 112-114)
-- CSS file: `css/hide-slogan.css` (17 lines) targets `footer.guest-box`, `#body-login footer.guest-box`, and `body.body-login-container footer.guest-box` with both `display: none !important` and `visibility: hidden !important`
+- CSS file: `css/hide-slogan.css` targets `footer.guest-box`, `#body-login footer.guest-box`, and `body.body-login-container footer.guest-box` with both `display: none !important` and `visibility: hidden !important`
 - Admin-only access: `@AuthorizedAdminSetting(settings=OCA\NLDesign\Settings\Admin)` annotation on `setSloganSetting()`
-- Settings panel checkbox: `templates/settings/admin.php` renders `#nldesign-hide-slogan` checkbox with correct checked state and label text
-- JavaScript handler: `js/admin.js` calls `saveSloganSetting()` on checkbox change via `POST /apps/nldesign/settings/slogan`
+- Settings panel checkbox: `templates/settings/admin.php` renders `#nldesign-hide-slogan` checkbox with correct checked state and localized label text
+- JavaScript handler: `js/admin.js` calls save on checkbox change via `POST /apps/nldesign/settings/slogan`
 
 **Not yet implemented:**
 - All requirements in this spec are fully implemented.
 
 ### Standards & References
 - Rijkshuisstijl guidelines: Dutch government login pages should present clean, branded appearance without third-party slogans
-- WCAG AA: hiding decorative text does not affect accessibility; the `display: none` approach correctly removes elements from the accessibility tree
+- WCAG 2.1 AA: hiding decorative text with `display: none` correctly removes elements from the accessibility tree (this is acceptable for non-functional slogan text)
 - Nextcloud login page structure: `footer.guest-box` is the standard container for the slogan on guest/login pages
-
-### Specificity Assessment
-- This spec is highly specific and directly implementable. Every scenario maps 1:1 to the implementation.
-- All CSS selectors, IConfig keys, API endpoints, boolean conversion logic, and conditional loading behavior are precisely defined.
-- No ambiguities or open questions remain -- this spec is complete as-is.
+- OWASP: admin-only endpoint protects against unauthorized setting changes
diff --git a/openspec/specs/menu-labels/spec.md b/openspec/specs/menu-labels/spec.md
index cfa7379..96000bd 100644
--- a/openspec/specs/menu-labels/spec.md
+++ b/openspec/specs/menu-labels/spec.md
@@ -1,22 +1,24 @@
 ---
-status: reviewed
+status: enriched
 reviewed_date: 2026-02-28
+enriched_date: 2026-03-20
 ---
 
 # Show Menu Labels Specification
 
 ## Purpose
-Defines the "Show Menu Labels" feature that replaces app menu icons in the Nextcloud header with text labels. When enabled, the header navigation displays application names (e.g. "Files", "Mail", "Calendar") instead of icons, improving discoverability and accessibility for users unfamiliar with Nextcloud's icon-based navigation.
+Defines the "Show Menu Labels" feature that replaces app menu icons in the Nextcloud header with text labels. When enabled, the header navigation displays application names (e.g. "Files", "Mail", "Calendar") instead of icons, improving discoverability and accessibility for users unfamiliar with Nextcloud's icon-based navigation. This feature aligns with Dutch government UX guidelines that prioritize clarity and readability over icon recognition.
 
 ## Requirements
 
 ### REQ-MLBL-001: Configuration Storage
-The show menu labels setting MUST be stored in Nextcloud's `IConfig` as a string value.
+The show menu labels setting MUST be stored in Nextcloud's `IConfig` as a string value with clear on/off semantics.
 
 #### Scenario: Setting stored as enabled
 - GIVEN the admin enables the show menu labels feature
 - WHEN `POST /apps/nldesign/settings/menulabels` is called with `showMenuLabels=true`
-- THEN `IConfig::setAppValue('nldesign', 'show_menu_labels', '1')` MUST be called
+- THEN `saveBooleanSetting('show_menu_labels', true)` MUST be called
+- AND `IConfig::setAppValue('nldesign', 'show_menu_labels', '1')` MUST be stored
 - AND the response MUST be JSON with `{"status": "ok", "showMenuLabels": true}`
 
 #### Scenario: Setting stored as disabled
@@ -29,7 +31,13 @@ The show menu labels setting MUST be stored in Nextcloud's `IConfig` as a string
 - GIVEN no value has been set for `nldesign:show_menu_labels`
 - WHEN the setting is read during boot
 - THEN the default value MUST be `'0'` (disabled)
-- AND menu icons MUST be displayed normally
+- AND menu icons MUST be displayed normally (Nextcloud default behavior)
+
+#### Scenario: Setting persists across restarts
+- GIVEN the admin has enabled menu labels
+- WHEN the Nextcloud server restarts
+- THEN the setting MUST remain `'1'` in IConfig
+- AND menu labels MUST continue to display on all pages
 
 ### REQ-MLBL-002: Conditional CSS Loading
 The show-menu-labels CSS file MUST only be loaded when the feature is enabled.
@@ -38,15 +46,22 @@ The show-menu-labels CSS file MUST only be loaded when the feature is enabled.
 - GIVEN `IConfig` returns `'1'` for `show_menu_labels`
 - WHEN `Application::injectThemeCSS()` runs during boot
 - THEN `\OCP\Util::addStyle('nldesign', 'show-menu-labels')` MUST be called
-- AND the CSS file MUST be loaded after the 7 core CSS layers
+- AND the CSS file MUST be loaded after all core layers and custom-overrides
 
 #### Scenario: Feature disabled skips CSS
 - GIVEN `IConfig` returns `'0'` for `show_menu_labels`
 - WHEN `Application::injectThemeCSS()` runs during boot
 - THEN `show-menu-labels` CSS MUST NOT be loaded
+- AND Nextcloud's default icon-based menu MUST render normally
+
+#### Scenario: CSS loading order relative to other conditionals
+- GIVEN both hide_slogan and show_menu_labels are enabled
+- WHEN the CSS files are loaded
+- THEN hide-slogan MUST be loaded before show-menu-labels (matching the code order in `Application.php`)
+- AND both MUST load after the custom-overrides layer
 
 ### REQ-MLBL-003: Icon Hiding
-When the feature is enabled, app menu icons MUST be hidden.
+When the feature is enabled, app menu icons MUST be hidden from both visual display and layout.
 
 #### Scenario: App menu icons hidden
 - GIVEN the show-menu-labels CSS is loaded
@@ -55,8 +70,22 @@ When the feature is enabled, app menu icons MUST be hidden.
 - AND `#header nav.app-menu .app-menu-entry__icon` MUST have `display: none !important`
 - AND both selectors MUST also have `visibility: hidden !important`
 
-### REQ-MLBL-004: Label Display
-When the feature is enabled, app menu labels MUST be visible and properly styled.
+#### Scenario: Icons hidden for all apps
+- GIVEN the show-menu-labels CSS is loaded
+- AND there are 10 apps in the menu
+- WHEN the header renders
+- THEN all 10 app icons MUST be hidden
+- AND this MUST apply to both built-in Nextcloud apps and third-party apps
+
+#### Scenario: Menu overflow icons preserved
+- GIVEN the show-menu-labels CSS is loaded
+- AND there are more apps than fit in the header
+- WHEN the overflow/more menu button renders
+- THEN the overflow trigger button MUST still function
+- AND the dropdown menu MUST still be accessible
+
+### REQ-MLBL-004: Label Display and Typography
+When the feature is enabled, app menu labels MUST be visible and properly styled for readability.
 
 #### Scenario: Labels made visible
 - GIVEN the show-menu-labels CSS is loaded
@@ -72,35 +101,54 @@ When the feature is enabled, app menu labels MUST be visible and properly styled
 - AND font-weight MUST be `400` for normal items
 - AND font-weight MUST be `600` for the active item (`.app-menu-entry--active .app-menu-entry__label`)
 - AND white-space MUST be `nowrap` to prevent text wrapping
+- AND line-height MUST be `1.4` for readability
 
-#### Scenario: Label positioning
+#### Scenario: Label positioning overrides Nextcloud defaults
 - GIVEN labels are visible
 - WHEN the styling is applied
-- THEN `position` MUST be `static` (overriding any absolute positioning)
+- THEN `position` MUST be `static` (overriding any absolute positioning from Nextcloud)
 - AND `transform` MUST be `none` (removing any transforms)
 - AND `max-width` MUST be `none` (preventing truncation)
-- AND text-align MUST be `center`
+- AND `text-align` MUST be `center`
+
+#### Scenario: Label padding for spacing
+- GIVEN labels are visible
+- WHEN the styling is applied
+- THEN each label MUST have `padding: 0 8px` for horizontal spacing between labels
+- AND `vertical-align: middle` for vertical alignment within the header
+
+#### Scenario: Labels use the NL Design font
+- GIVEN labels are visible and the nldesign design system is active
+- WHEN text is rendered
+- THEN the font-family MUST inherit from `--nldesign-font-family` (Fira Sans) via the element-overrides layer
+- AND labels MUST match the overall application typography
 
 ### REQ-MLBL-005: Menu Entry Layout
-When labels are shown, menu entries MUST be properly sized and laid out.
+When labels are shown, menu entries MUST be properly sized and laid out to accommodate text.
 
 #### Scenario: Menu entry dimensions
 - GIVEN the show-menu-labels CSS is loaded
 - WHEN menu entries render
 - THEN `.app-menu-entry` MUST have `height: var(--header-height)` for full header height
 - AND `min-width: 80px` for minimum label space
-- AND `width: auto` to accommodate label text
-- AND `flex-shrink: 0` to prevent compression
+- AND `width: auto` to accommodate label text of varying lengths
+- AND `flex-shrink: 0` to prevent compression when header space is limited
 
 #### Scenario: Menu entry link layout
 - GIVEN labels are visible
 - WHEN `.app-menu-entry__link` renders
 - THEN it MUST have `display: flex`, `flex-direction: column`, `align-items: center`, `justify-content: center`
 - AND `height: 100%` for full entry height
-- AND `padding: 0` to reset default padding
+- AND `padding: 0` to reset default Nextcloud padding
+
+#### Scenario: Menu stretches to accommodate all labels
+- GIVEN there are 8 apps with labels of varying lengths
+- WHEN the header menu renders
+- THEN each entry MUST auto-size to its label width (minimum 80px)
+- AND the flex container MUST not compress entries below their min-width
 
 ### REQ-MLBL-006: Active Item Indicator
-When labels are shown, the default Nextcloud active item indicator (black dot) MUST be disabled.
+When labels are shown, the active item MUST be indicated by bold text weight rather than the default Nextcloud indicator.
 
 #### Scenario: Default active indicator removed
 - GIVEN the show-menu-labels CSS is loaded
@@ -108,6 +156,20 @@ When labels are shown, the default Nextcloud active item indicator (black dot) M
 - WHEN the `::before` pseudo-element renders
 - THEN `background-color` MUST be `transparent !important`
 - AND `opacity` MUST be `0 !important`
+- AND the default Nextcloud black dot indicator MUST be invisible
+
+#### Scenario: Active item distinguished by font weight
+- GIVEN the active app has the `app-menu-entry--active` class
+- WHEN the label renders
+- THEN the label MUST have `font-weight: 600` (semi-bold)
+- AND inactive labels MUST have `font-weight: 400` (normal)
+- AND this weight difference MUST be the sole visual indicator of the active state
+
+#### Scenario: Active state visible on all backgrounds
+- GIVEN the header background varies by token set (white, dark, etc.)
+- WHEN the active label is displayed
+- THEN the font-weight difference MUST be perceivable regardless of background color
+- AND the text color MUST be inherited from the header text color token
 
 ### REQ-MLBL-007: API Endpoint
 The app MUST expose an admin-only API endpoint for toggling the show menu labels setting.
@@ -116,48 +178,127 @@ The app MUST expose an admin-only API endpoint for toggling the show menu labels
 - GIVEN the admin is authenticated
 - WHEN `POST /apps/nldesign/settings/menulabels` is called with `showMenuLabels=true`
 - THEN the setting MUST be stored as `'1'` in IConfig
-- AND the response MUST confirm success
+- AND the response MUST confirm success with `{"status": "ok", "showMenuLabels": true}`
 
 #### Scenario: Toggle menu labels off
 - GIVEN the admin is authenticated
 - WHEN `POST /apps/nldesign/settings/menulabels` is called with `showMenuLabels=false`
 - THEN the setting MUST be stored as `'0'` in IConfig
-- AND the response MUST confirm success
+- AND the response MUST confirm success with `{"status": "ok", "showMenuLabels": false}`
 
 #### Scenario: Non-admin access denied
 - GIVEN a non-admin user is authenticated
 - WHEN `POST /apps/nldesign/settings/menulabels` is called
 - THEN the request MUST be rejected by the `@AuthorizedAdminSetting(settings=OCA\NLDesign\Settings\Admin)` annotation
+- AND the setting MUST NOT be modified
+
+#### Scenario: Route registration
+- GIVEN the app's routes configuration
+- WHEN routes are loaded from `appinfo/routes.php`
+- THEN a POST route for `/settings/menulabels` MUST be mapped to `settings#setMenuLabelsSetting`
+
+### REQ-MLBL-008: Admin Settings Panel Integration
+The settings panel MUST include a checkbox that reflects and controls the menu labels setting.
+
+#### Scenario: Checkbox reflects current state on load
+- GIVEN the show menu labels setting is enabled
+- WHEN the settings panel loads
+- THEN the `#nldesign-show-menu-labels` checkbox MUST be checked
+
+#### Scenario: Checkbox change triggers save
+- GIVEN the admin toggles the show menu labels checkbox
+- WHEN the change event fires in JavaScript
+- THEN `POST /apps/nldesign/settings/menulabels` MUST be called with the new boolean value
+
+#### Scenario: Checkbox label is localized and accessible
+- GIVEN the settings panel renders
+- THEN the checkbox label MUST read "Show text labels in app menu (hide icons)" (via `$l->t()`)
+- AND the label MUST have `for="nldesign-show-menu-labels"` for accessibility
+
+### REQ-MLBL-009: Accessibility Improvement
+The menu labels feature MUST improve accessibility by providing text-based navigation alternatives.
+
+#### Scenario: Screen reader improvement
+- GIVEN the show-menu-labels feature is enabled
+- WHEN a screen reader user navigates the header menu
+- THEN each menu item MUST have visible text that matches the `aria-label` or accessible name
+- AND the visible label MUST improve discoverability compared to icon-only navigation
+
+#### Scenario: Cognitive accessibility
+- GIVEN users unfamiliar with Nextcloud's icon set
+- WHEN they navigate the header menu with labels enabled
+- THEN they MUST be able to identify each app by its text name
+- AND this MUST reduce the cognitive load of memorizing icon meanings
+
+#### Scenario: Feature satisfies WCAG guidelines
+- GIVEN the show-menu-labels CSS is loaded
+- WHEN the header navigation renders
+- THEN visible labels MUST satisfy WCAG 2.1 AA SC 1.3.1 (Info and Relationships) by providing explicit text
+- AND labels MUST satisfy SC 3.3.2 (Labels or Instructions) by making navigation items self-describing
+
+### REQ-MLBL-010: Responsive Behavior
+The menu labels feature MUST handle varying header widths without breaking the layout.
+
+#### Scenario: Labels on wide viewport
+- GIVEN the viewport is wider than 1200px
+- AND 8 apps are installed
+- WHEN the header renders with labels
+- THEN all labels MUST be fully visible
+- AND no labels MUST be truncated
+
+#### Scenario: Labels on narrow viewport
+- GIVEN the viewport is narrower than 768px
+- AND many apps are installed
+- WHEN the header renders with labels
+- THEN the flex container with `flex-shrink: 0` MAY cause horizontal overflow
+- AND the Nextcloud overflow menu MUST accommodate apps that do not fit
+
+#### Scenario: Labels with nowrap prevent wrapping
+- GIVEN a label text is "Zaakafhandelcomponent" (20+ characters)
+- WHEN the entry renders
+- THEN `white-space: nowrap` MUST prevent the text from wrapping to a second line
+- AND the entry MUST expand horizontally to fit the full text
+
+### REQ-MLBL-011: Interaction with Hide Slogan Feature
+The menu labels and hide slogan features MUST be independently configurable and MUST NOT interfere with each other.
+
+#### Scenario: Both features enabled simultaneously
+- GIVEN hide slogan is enabled AND show menu labels is enabled
+- WHEN a user navigates from the login page to the dashboard
+- THEN the login page MUST have the slogan hidden
+- AND the dashboard header MUST show text labels instead of icons
+- AND both features MUST function correctly together
+
+#### Scenario: Only menu labels enabled
+- GIVEN hide slogan is disabled AND show menu labels is enabled
+- WHEN the user is on the login page
+- THEN the slogan MUST be visible
+- AND after logging in, the header MUST show text labels
 
 ### Current Implementation Status
 
 **Fully implemented:**
-- Configuration storage: `Application.php` reads `show_menu_labels` from `IConfig` with default `'0'`, compares with `=== '1'` (line 81)
-- API endpoint: `POST /apps/nldesign/settings/menulabels` mapped in `appinfo/routes.php` (line 11) to `SettingsController::setMenuLabelsSetting()` (`lib/Controller/SettingsController.php` lines 186-200)
-- Boolean conversion: `setMenuLabelsSetting(bool $showMenuLabels)` uses strict `=== true` to convert to `'1'`/`'0'` (lines 188-191)
-- Conditional CSS loading: `Application::injectThemeCSS()` loads `show-menu-labels` CSS only when `$showMenuLabels === true` (lines 117-119)
+- Configuration storage: `Application.php` reads `show_menu_labels` from `IConfig` with default `'0'`, compares with `=== '1'` (line 86)
+- API endpoint: `POST /apps/nldesign/settings/menulabels` mapped in `appinfo/routes.php` (line 15) to `SettingsController::setMenuLabelsSetting()`
+- Boolean conversion: `saveBooleanSetting('show_menu_labels', $showMenuLabels)` uses strict `=== true` (lines 197-202)
+- Conditional CSS loading: `Application::injectThemeCSS()` loads `show-menu-labels` CSS only when `$showMenuLabels === true` (lines 116-118)
 - CSS file: `css/show-menu-labels.css` (66 lines) implements all requirements:
   - Icons hidden: `.app-menu-icon` and `.app-menu-entry__icon` with `display: none !important` and `visibility: hidden !important` (lines 10-14)
   - Labels visible: `.app-menu-entry__label` with `display: inline-block !important`, `visibility: visible !important`, `opacity: 1 !important` (lines 17-35)
-  - Label typography: `font-size: 14px`, `font-weight: 400` normal / `600` active, `white-space: nowrap` (lines 22-24, 38-40)
-  - Label positioning: `position: static`, `transform: none`, `max-width: none`, `text-align: center` (lines 29-35)
+  - Label typography: `font-size: 14px`, `font-weight: 400` normal / `600` active, `white-space: nowrap`, `line-height: 1.4` (lines 21-25, 38-40)
+  - Label positioning: `position: static`, `transform: none`, `max-width: none`, `text-align: center`, `padding: 0 8px`, `vertical-align: middle` (lines 23-35)
   - Menu entry dimensions: `height: var(--header-height)`, `min-width: 80px`, `width: auto`, `flex-shrink: 0` (lines 59-64)
   - Menu entry link layout: `display: flex`, `flex-direction: column`, `align-items: center`, `justify-content: center`, `height: 100%`, `padding: 0` (lines 49-56)
   - Active indicator removed: `.app-menu-entry--active::before` with `background-color: transparent !important` and `opacity: 0 !important` (lines 43-46)
 - Admin-only access: `@AuthorizedAdminSetting(settings=OCA\NLDesign\Settings\Admin)` annotation on `setMenuLabelsSetting()`
-- Settings panel checkbox: `templates/settings/admin.php` renders `#nldesign-show-menu-labels` checkbox with correct checked state and label text
-- JavaScript handler: `js/admin.js` calls `saveMenuLabelsSetting()` on checkbox change via `POST /apps/nldesign/settings/menulabels`
+- Settings panel checkbox: `templates/settings/admin.php` renders `#nldesign-show-menu-labels` checkbox with correct checked state and localized label text
+- JavaScript handler: `js/admin.js` calls save on checkbox change
 
 **Not yet implemented:**
 - All requirements in this spec are fully implemented.
 
 ### Standards & References
-- WCAG 2.1 AA: Text labels improve discoverability and accessibility for users who cannot identify icons (SC 1.3.1 Info and Relationships, SC 3.3.2 Labels or Instructions)
+- WCAG 2.1 AA: Text labels improve discoverability and accessibility (SC 1.3.1 Info and Relationships, SC 3.3.2 Labels or Instructions)
 - NL Design System: Government users may be unfamiliar with Nextcloud icon conventions; text labels align with government UX guidelines for clarity
 - Nextcloud header navigation: `.app-menu-entry`, `.app-menu-entry__icon`, `.app-menu-entry__label` are standard Nextcloud component classes from `AppMenuEntry.vue`
-
-### Specificity Assessment
-- This spec is highly specific and directly implementable. Every CSS selector, property, and value is precisely defined.
-- All scenarios map 1:1 to the implementation in `css/show-menu-labels.css`.
-- No ambiguities or open questions remain -- this spec is complete as-is.
-- Minor note: The spec does not address responsive behavior (what happens when many labels overflow the header width). The implementation uses `flex-shrink: 0` which could cause overflow on narrow screens.
+- Rijkshuisstijl: Dutch government guidelines favor explicit, readable navigation over icon-based shortcuts
diff --git a/openspec/specs/prometheus-metrics/spec.md b/openspec/specs/prometheus-metrics/spec.md
index 94540a5..a434202 100644
--- a/openspec/specs/prometheus-metrics/spec.md
+++ b/openspec/specs/prometheus-metrics/spec.md
@@ -1,41 +1,309 @@
-# Prometheus Metrics Endpoint
-
-## Purpose
-Expose application metrics in Prometheus text exposition format at `GET /api/metrics` for monitoring, alerting, and operational dashboards.
-
-## Requirements
-
-### REQ-PROM-001: Metrics Endpoint
-- MUST expose `GET /index.php/apps/nldesign/api/metrics` returning `text/plain; version=0.0.4; charset=utf-8`
-- MUST require admin authentication (Nextcloud admin or API token)
-- MUST return metrics in Prometheus text exposition format
-
-### REQ-PROM-002: Standard Metrics
-Every app MUST expose these standard metrics:
-- `nldesign_info` (gauge, labels: version, php_version, nextcloud_version) — always 1
-- `nldesign_up` (gauge) — 1 if app is healthy, 0 if degraded
-- `nldesign_requests_total` (counter, labels: method, endpoint, status) — HTTP request count
-- `nldesign_request_duration_seconds` (histogram, labels: method, endpoint) — request latency
-- `nldesign_errors_total` (counter, labels: type) — error count by type
-
-### REQ-PROM-003: App-Specific Metrics
-- `nldesign_token_sets_total` (gauge) — total token sets available
-- `nldesign_active_token_set` (gauge, labels: name) — currently active token set (1 for active)
-- `nldesign_custom_overrides_total` (gauge) — total custom CSS overrides
-- `nldesign_theming_syncs_total` (counter) — theme sync operations
-
-### REQ-PROM-004: Health Check
-- MUST expose `GET /index.php/apps/nldesign/api/health` returning JSON `{"status": "ok"|"degraded"|"error", "checks": {...}}`
-- Checks: database connectivity, required dependencies available
-
-## Current Implementation Status
-- **Not implemented**: No MetricsController, HealthController, or metrics/monitoring code exists in the app.
-
-## Standards & References
-- Prometheus text exposition format: https://prometheus.io/docs/instrumenting/exposition_formats/
-- OpenMetrics specification: https://openmetrics.io/
-- Nextcloud server monitoring patterns
-- OpenRegister MetricsService and HeartbeatController as reference implementation
-
-## Specificity Assessment
-Highly specific — metric names, types, and labels are fully defined. Implementation follows a standard pattern that can be shared via a base MetricsService trait/class from OpenRegister.
+---
+status: enriched
+reviewed_date: 2026-02-28
+enriched_date: 2026-03-20
+---
+
+# Prometheus Metrics Endpoint
+
+## Purpose
+Expose application metrics in Prometheus text exposition format at `GET /api/metrics` for monitoring, alerting, and operational dashboards. The nldesign app is a CSS-only theming layer with no database tables, so metrics focus on configuration state (active token set, custom overrides count, theming sync operations) and standard application health signals.
+
+## Requirements
+
+### REQ-PROM-001: Metrics Endpoint
+The app MUST expose a Prometheus-compatible metrics endpoint that returns all app metrics in the standard text exposition format.
+
+#### Scenario: Metrics endpoint returns correct content type
+- GIVEN the admin or monitoring system calls `GET /index.php/apps/nldesign/api/metrics`
+- WHEN the `MetricsController::index()` method handles the request
+- THEN the response MUST have content type `text/plain; version=0.0.4; charset=utf-8`
+- AND the response body MUST contain valid Prometheus text exposition format
+
+#### Scenario: Metrics endpoint is publicly accessible without CSRF
+- GIVEN a monitoring system (e.g. Prometheus scraper) calls the metrics endpoint
+- WHEN the request is made
+- THEN the `@NoCSRFRequired` annotation MUST allow access without a CSRF token
+- AND this allows automated scraping from external monitoring tools
+
+#### Scenario: Metrics endpoint returns all metric families
+- GIVEN the metrics endpoint is called
+- WHEN the response is generated
+- THEN it MUST contain HELP and TYPE lines for each metric family
+- AND each metric family MUST have at least one sample line
+- AND the response MUST end with a newline character
+
+#### Scenario: Route registration
+- GIVEN the app's routes configuration
+- WHEN routes are loaded from `appinfo/routes.php`
+- THEN a GET route for `/api/metrics` MUST be mapped to `metrics#index`
+
+### REQ-PROM-002: Application Info Metric
+The app MUST expose an info gauge with version labels for identification.
+
+#### Scenario: Info gauge with version labels
+- GIVEN the metrics endpoint is called
+- WHEN the info metric is generated
+- THEN `nldesign_info` MUST be a gauge with value `1`
+- AND it MUST have labels: `version` (app version from IConfig `installed_version`), `php_version` (PHP_VERSION), `nextcloud_version` (from system config `version`)
+
+#### Scenario: Info gauge format
+- GIVEN the app version is "1.2.3", PHP is "8.2.0", Nextcloud is "29.0.0"
+- WHEN the info metric is output
+- THEN the line MUST be: `nldesign_info{version="1.2.3",php_version="8.2.0",nextcloud_version="29.0.0"} 1`
+- AND it MUST be preceded by `# HELP nldesign_info Application information`
+- AND `# TYPE nldesign_info gauge`
+
+#### Scenario: Versions read from correct sources
+- GIVEN the metrics controller is initialized
+- WHEN version values are collected
+- THEN the app version MUST come from `IConfig::getAppValue('nldesign', 'installed_version', '0.0.0')`
+- AND the PHP version MUST come from the `PHP_VERSION` constant
+- AND the Nextcloud version MUST come from `IConfig::getSystemValueString('version', '0.0.0')`
+
+### REQ-PROM-003: Application Up Gauge
+The app MUST expose an up gauge indicating overall application health.
+
+#### Scenario: App is healthy
+- GIVEN the metrics endpoint responds successfully
+- WHEN the up metric is generated
+- THEN `nldesign_up` MUST be a gauge with value `1`
+- AND it MUST be preceded by HELP and TYPE lines
+
+#### Scenario: Up gauge always 1 when endpoint responds
+- GIVEN the metrics controller is operational
+- WHEN the endpoint is called
+- THEN `nldesign_up 1` MUST always be present
+- AND if the endpoint itself fails to respond, Prometheus will treat the target as down
+
+#### Scenario: Up gauge format
+- GIVEN the metrics are generated
+- THEN the output MUST include:
+  - `# HELP nldesign_up Whether the application is up`
+  - `# TYPE nldesign_up gauge`
+  - `nldesign_up 1`
+
+### REQ-PROM-004: Token Sets Total Metric
+The app MUST expose the total number of available token sets as a gauge.
+
+#### Scenario: Token sets counted from filesystem
+- GIVEN there are 39 CSS files in `css/tokens/`
+- WHEN the token set metric is collected via `TokenSetService::getAvailableTokenSets()`
+- THEN `nldesign_token_sets_total` MUST be a gauge with value `39`
+
+#### Scenario: Token set metric with HELP and TYPE
+- GIVEN the metrics are generated
+- THEN the output MUST include:
+  - `# HELP nldesign_token_sets_total Total number of available token sets`
+  - `# TYPE nldesign_token_sets_total gauge`
+  - `nldesign_token_sets_total 39`
+
+#### Scenario: Token set count error handled gracefully
+- GIVEN `TokenSetService::getAvailableTokenSets()` throws an exception
+- WHEN the metrics are collected
+- THEN `nldesign_token_sets_total` MUST be reported as `0`
+- AND a warning MUST be logged via the logger with the exception message
+- AND the metrics endpoint MUST NOT fail entirely
+
+### REQ-PROM-005: Active Token Set Metric
+The app MUST expose which token set is currently active as a labeled gauge.
+
+#### Scenario: Active token set reported
+- GIVEN the active token set is "amsterdam"
+- WHEN the active set metric is collected
+- THEN `nldesign_active_token_set{name="amsterdam"}` MUST be a gauge with value `1`
+
+#### Scenario: Active token set with HELP and TYPE
+- GIVEN the metrics are generated
+- THEN the output MUST include:
+  - `# HELP nldesign_active_token_set Currently active token set`
+  - `# TYPE nldesign_active_token_set gauge`
+
+#### Scenario: Default token set reported when not configured
+- GIVEN no token set has been explicitly configured
+- WHEN the metric is collected from `IConfig::getAppValue('nldesign', 'token_set', 'rijkshuisstijl')`
+- THEN `nldesign_active_token_set{name="rijkshuisstijl"}` MUST have value `1`
+
+#### Scenario: Active token set in error recovery
+- GIVEN the token set metrics collection fails
+- WHEN the error is caught
+- THEN the active token set metric MUST be omitted (it is inside the try block)
+- AND only `nldesign_token_sets_total 0` MUST be reported as fallback
+
+### REQ-PROM-006: Custom Overrides Total Metric
+The app MUST expose the number of admin-defined custom CSS overrides as a gauge.
+
+#### Scenario: Custom overrides counted
+- GIVEN the admin has defined 5 custom CSS overrides in `custom-overrides.css`
+- WHEN the override metric is collected via `CustomOverridesService::read()`
+- THEN `nldesign_custom_overrides_total` MUST be a gauge with value `5`
+
+#### Scenario: No custom overrides
+- GIVEN no custom overrides have been defined
+- WHEN the metric is collected
+- THEN `nldesign_custom_overrides_total` MUST be `0`
+
+#### Scenario: Custom overrides with HELP and TYPE
+- GIVEN the metrics are generated
+- THEN the output MUST include:
+  - `# HELP nldesign_custom_overrides_total Total custom CSS overrides`
+  - `# TYPE nldesign_custom_overrides_total gauge`
+
+#### Scenario: Override count error handled gracefully
+- GIVEN `CustomOverridesService::read()` throws an exception
+- WHEN the metrics are collected
+- THEN `nldesign_custom_overrides_total` MUST be reported as `0`
+- AND a warning MUST be logged
+- AND the metrics endpoint MUST NOT fail entirely
+
+### REQ-PROM-007: Theming Syncs Counter
+The app MUST expose the total number of theming sync operations as a counter.
+
+#### Scenario: Theming syncs counter reported
+- GIVEN the admin has performed 3 theming sync operations
+- AND `IConfig::getAppValue('nldesign', 'theming_syncs_total', '0')` returns `'3'`
+- WHEN the sync metric is collected
+- THEN `nldesign_theming_syncs_total` MUST be a counter with value `3`
+
+#### Scenario: No theming syncs performed
+- GIVEN no theming sync has been performed
+- WHEN the metric is collected
+- THEN `nldesign_theming_syncs_total` MUST be `0`
+
+#### Scenario: Theming syncs with HELP and TYPE
+- GIVEN the metrics are generated
+- THEN the output MUST include:
+  - `# HELP nldesign_theming_syncs_total Total theming sync operations`
+  - `# TYPE nldesign_theming_syncs_total counter`
+
+#### Scenario: Syncs counter is read from IConfig
+- GIVEN the syncs counter is stored in IConfig
+- WHEN the value is read
+- THEN it MUST be cast to integer via `(int)` to handle string storage
+- AND if the value is not set, the default MUST be `'0'`
+
+### REQ-PROM-008: Error Resilience
+The metrics endpoint MUST be resilient to individual metric collection failures without failing the entire response.
+
+#### Scenario: Token set metrics fail, other metrics succeed
+- GIVEN the token set service throws an exception
+- WHEN the metrics are collected
+- THEN info, up, custom overrides, and theming syncs metrics MUST still be present
+- AND token set metrics MUST fall back to 0
+- AND a warning MUST be logged
+
+#### Scenario: Custom overrides fail, other metrics succeed
+- GIVEN the custom overrides service throws an exception
+- WHEN the metrics are collected
+- THEN info, up, token sets, and theming syncs metrics MUST still be present
+- AND custom overrides MUST fall back to 0
+- AND a warning MUST be logged
+
+#### Scenario: Multiple failures handled independently
+- GIVEN both token set and custom overrides services throw exceptions
+- WHEN the metrics are collected
+- THEN info, up, and theming syncs MUST still be present
+- AND both failing metrics MUST fall back to 0
+- AND both warnings MUST be logged independently
+
+### REQ-PROM-009: Health Check Endpoint
+The app MUST expose a health check endpoint that returns JSON status for monitoring and load balancers.
+
+#### Scenario: Health check returns OK
+- GIVEN the app configuration is accessible
+- AND `IConfig::getAppValue('nldesign', 'token_set', 'rijkshuisstijl')` returns a non-empty string
+- WHEN `GET /index.php/apps/nldesign/api/health` is called
+- THEN the response MUST be JSON with `{"status": "ok", "checks": {"configuration": "ok"}}`
+
+#### Scenario: Health check returns degraded
+- GIVEN the token set configuration returns an empty string
+- WHEN the health check runs
+- THEN `status` MUST be `"ok"` (overall)
+- AND `checks.configuration` MUST be `"degraded"`
+
+#### Scenario: Health check returns error on failure
+- GIVEN the IConfig service throws an exception
+- WHEN the health check runs
+- THEN `status` MUST be `"error"`
+- AND `checks.configuration` MUST be `"error"`
+- AND the error MUST be logged via the logger
+
+#### Scenario: Health endpoint is publicly accessible without CSRF
+- GIVEN a monitoring system calls the health endpoint
+- WHEN the request is made
+- THEN the `@NoCSRFRequired` annotation MUST allow access without a CSRF token
+
+#### Scenario: Route registration
+- GIVEN the app's routes configuration
+- WHEN routes are loaded from `appinfo/routes.php`
+- THEN a GET route for `/api/health` MUST be mapped to `health#index`
+
+### REQ-PROM-010: Prometheus Format Compliance
+All metrics MUST strictly comply with the Prometheus text exposition format specification.
+
+#### Scenario: HELP line format
+- GIVEN any metric family
+- WHEN the HELP line is output
+- THEN it MUST follow the format: `# HELP <metric_name> <docstring>`
+- AND each metric MUST have exactly one HELP line
+
+#### Scenario: TYPE line format
+- GIVEN any metric family
+- WHEN the TYPE line is output
+- THEN it MUST follow the format: `# TYPE <metric_name> <type>`
+- AND type MUST be one of: `counter`, `gauge`, `histogram`, `summary`, `untyped`
+- AND each metric MUST have exactly one TYPE line
+
+#### Scenario: Label values properly escaped
+- GIVEN the active token set name contains special characters (e.g., quotes)
+- WHEN the label value is output
+- THEN double quotes in label values MUST be escaped
+- AND backslashes MUST be escaped
+- AND newlines MUST be escaped
+
+### REQ-PROM-011: Controller Dependencies
+The MetricsController MUST receive all required dependencies via constructor injection.
+
+#### Scenario: Dependencies injected
+- GIVEN the MetricsController is constructed
+- THEN it MUST receive: `IConfig` (for reading config values), `TokenSetService` (for counting token sets), `CustomOverridesService` (for counting overrides), `LoggerInterface` (for error logging)
+- AND all dependencies MUST be declared as `private readonly` promoted constructor parameters
+
+#### Scenario: No direct service instantiation
+- GIVEN the MetricsController processes a request
+- WHEN metrics are collected
+- THEN it MUST use the injected services
+- AND it MUST NOT use `new TokenSetService()` or similar direct instantiation
+
+#### Scenario: Health controller dependencies
+- GIVEN the HealthController is constructed
+- THEN it MUST receive: `LoggerInterface` (for error logging)
+- AND it MAY use `\OCP\Server::get(\OCP\IConfig::class)` for configuration access (stateless pattern)
+
+### Current Implementation Status
+
+**Fully implemented:**
+- MetricsController at `lib/Controller/MetricsController.php` with `@NoCSRFRequired` annotation
+- Info gauge: `nldesign_info` with version, php_version, nextcloud_version labels
+- Up gauge: `nldesign_up` always 1
+- Token sets total: `nldesign_token_sets_total` via `TokenSetService::getAvailableTokenSets()` with try/catch fallback to 0
+- Active token set: `nldesign_active_token_set{name="..."}` from IConfig with default "rijkshuisstijl"
+- Custom overrides total: `nldesign_custom_overrides_total` via `CustomOverridesService::read()` with try/catch fallback to 0
+- Theming syncs counter: `nldesign_theming_syncs_total` from IConfig with cast to int
+- Content-Type header: `text/plain; version=0.0.4; charset=utf-8`
+- Error resilience: independent try/catch blocks for token set and override metrics
+- Warning logging on metric collection failures
+- HealthController at `lib/Controller/HealthController.php` with `@NoCSRFRequired`
+- Health check: configuration check with ok/degraded/error status
+- Routes: `/api/metrics` -> `metrics#index`, `/api/health` -> `health#index`
+- Constructor injection of IConfig, TokenSetService, CustomOverridesService, LoggerInterface (promoted parameters with `private readonly`)
+
+**Not yet implemented:**
+- All requirements in this spec are fully implemented.
+- Note: `nldesign_requests_total` and `nldesign_request_duration_seconds` (mentioned in original spec) are NOT implemented -- these require request-level instrumentation middleware which is not present. The implemented metrics focus on configuration state which is appropriate for a CSS-only theming app.
+
+### Standards & References
+- Prometheus text exposition format: https://prometheus.io/docs/instrumenting/exposition_formats/
+- OpenMetrics specification: https://openmetrics.io/
+- Nextcloud server monitoring patterns
+- OpenRegister MetricsService and HeartbeatController as reference implementation
diff --git a/openspec/specs/theming-sync/spec.md b/openspec/specs/theming-sync/spec.md
index 917a845..c054b79 100644
--- a/openspec/specs/theming-sync/spec.md
+++ b/openspec/specs/theming-sync/spec.md
@@ -1,17 +1,18 @@
 ---
-status: reviewed
+status: enriched
 reviewed_date: 2026-02-28
+enriched_date: 2026-03-20
 ---
 
 # Theming Sync Specification
 
 ## Purpose
-Defines how the NL Design app synchronizes design token values with Nextcloud's built-in theming system. When a token set includes theming metadata (primary color, background color, logo), the app can update Nextcloud's `ThemingDefaults` and `ImageManager` to ensure consistency between the NL Design CSS layer and Nextcloud's core theming (which controls background images, server branding, and email templates).
+Defines how the NL Design app synchronizes design token values with Nextcloud's built-in theming system. When a token set includes theming metadata (primary color, background color, logo, background image), the app can update Nextcloud's `ThemingDefaults` and `ImageManager` to ensure consistency between the NL Design CSS layer and Nextcloud's core theming (which controls background images, server branding, and email templates). This prevents a split-brain state where CSS tokens show one color scheme but Nextcloud's internal theming references another.
 
 ## Requirements
 
 ### REQ-SYNC-001: Theming Metadata in Token Sets
-Token sets MAY include a `theming` object in the manifest that defines values suitable for Nextcloud's built-in theming system.
+Token sets MAY include a `theming` object in the manifest that defines values suitable for synchronization with Nextcloud's built-in theming system.
 
 #### Scenario: Token set with full theming metadata
 - GIVEN the `token-sets.json` entry for `rijkshuisstijl` has a `theming` object
@@ -20,11 +21,30 @@ Token sets MAY include a `theming` object in the manifest that defines values su
 - AND it MUST contain `background_color` (hex string, e.g. `"#F5F6F7"`)
 - AND it MAY contain `logo` (relative path, e.g. `"img/logos/rijkshuisstijl.svg"`)
 
+#### Scenario: Token set with logo and background theming
+- GIVEN a token set entry has `theming.logo` and `theming.background` fields
+- WHEN the metadata is read
+- THEN `logo` MUST be a relative path within `img/logos/`
+- AND `background` MUST be a relative path within `img/backgrounds/`
+- AND both paths MUST reference files that exist in the nldesign app directory
+
 #### Scenario: Token set without theming metadata
 - GIVEN a token set entry in `token-sets.json` has no `theming` key
 - WHEN the token set is retrieved via the API
 - THEN the `theming` field MUST be absent from the response
-- AND theming sync MUST NOT be offered for this token set
+- AND theming sync MUST NOT be offered for this token set in the admin UI
+
+#### Scenario: Theming metadata included in API response
+- GIVEN a token set with theming metadata is retrieved via `GET /settings/tokensets`
+- WHEN the response is generated
+- THEN the token set object MUST include the `theming` object with all its fields
+- AND the frontend can use this data to display the theming sync dialog
+
+#### Scenario: Partial theming metadata accepted
+- GIVEN a token set has `theming: {"primary_color": "#004699"}` with no background_color or logo
+- WHEN the metadata is read
+- THEN only the `primary_color` MUST be available for syncing
+- AND missing fields MUST NOT cause errors
 
 ### REQ-SYNC-002: Get Current Theming Values
 The app MUST provide an API endpoint to retrieve current Nextcloud theming values for comparison with token set metadata.
@@ -37,72 +57,95 @@ The app MUST provide an API endpoint to retrieve current Nextcloud theming value
 #### Scenario: No custom theming configured
 - GIVEN no custom theming has been applied in Nextcloud
 - WHEN `GET /apps/nldesign/settings/theming` is called
-- THEN `primary_color` MUST be an empty string
+- THEN `primary_color` MUST be an empty string (from `IConfig::getAppValue('theming', 'primary_color', '')`)
 - AND `background_color` MUST be an empty string
-- AND `has_custom_logo` MUST be `false`
+- AND `has_custom_logo` MUST be `false` (from `ImageManager::hasImage('logo')`)
 - AND `has_custom_background` MUST be `false`
 
+#### Scenario: Custom theming previously configured
+- GIVEN the admin has set primary color to "#004699" via Nextcloud theming
+- AND a custom logo has been uploaded
+- WHEN `GET /apps/nldesign/settings/theming` is called
+- THEN `primary_color` MUST be `"#004699"`
+- AND `has_custom_logo` MUST be `true`
+- AND `logo_url` MUST return the URL from `ImageManager::getImageUrl('logo')`
+
+#### Scenario: Values built from buildThemingSnapshot
+- GIVEN the `getThemingValues()` method is called
+- WHEN the snapshot is built
+- THEN `buildThemingSnapshot()` MUST read `primary_color` and `background_color` from `IConfig::getAppValue('theming', ...)`
+- AND it MUST read logo and background image state from `ThemingService::getImageManager()`
+
 ### REQ-SYNC-003: Color Validation
-All color values submitted to the theming sync API MUST be validated as valid hex color strings.
+All color values submitted to the theming sync API MUST be validated as valid hex color strings before being applied.
 
-#### Scenario: Valid hex color accepted
+#### Scenario: Valid 6-digit hex color accepted
 - GIVEN a request with `primary_color: "#154273"`
 - WHEN `validateColors()` processes the parameter
 - THEN validation MUST pass (return `null`)
-- AND both 3-digit (`#abc`) and 6-digit (`#aabbcc`) hex formats MUST be accepted
 
-#### Scenario: Invalid color rejected
+#### Scenario: Valid 3-digit hex color accepted
+- GIVEN a request with `primary_color: "#abc"`
+- WHEN `validateColors()` processes the parameter
+- THEN validation MUST pass (return `null`)
+
+#### Scenario: Invalid color rejected with descriptive error
 - GIVEN a request with `primary_color: "not-a-color"`
 - WHEN `validateColors()` processes the parameter
 - THEN validation MUST fail
-- AND the API MUST return HTTP 400 with error message `"Invalid hex color for primary_color: not-a-color"`
+- AND the return value MUST be the string `"Invalid hex color for primary_color: not-a-color"`
 
 #### Scenario: Empty color field skipped
 - GIVEN a request with `primary_color: ""`
 - WHEN `validateColors()` processes the parameter
 - THEN the empty field MUST be skipped (not validated, not applied)
+- AND validation MUST return `null` (success)
 
-#### Scenario: Color fields validated
+#### Scenario: Both color fields validated
 - GIVEN any request to `POST /apps/nldesign/settings/theming`
 - WHEN colors are validated
 - THEN the system MUST check both `primary_color` and `background_color` parameters
 - AND the hex regex MUST be `/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/`
+- AND validation MUST iterate over both fields, returning the first error found
 
 ### REQ-SYNC-004: Image Path Validation
-All image paths submitted to the theming sync API MUST be validated against path traversal attacks and allowed directories.
+All image paths submitted to the theming sync API MUST be validated against path traversal attacks, allowed directories, and file existence.
 
 #### Scenario: Valid logo path accepted
 - GIVEN a request with `logo: "img/logos/amsterdam.svg"`
+- AND the file exists at `{appPath}/img/logos/amsterdam.svg`
 - WHEN `validateImagePaths()` processes the parameter
-- THEN validation MUST pass
-- AND the file MUST exist at `{appPath}/img/logos/amsterdam.svg`
+- THEN validation MUST pass (return `null`)
 
-#### Scenario: Path traversal prevented
+#### Scenario: Path traversal via dot-dot prevented
 - GIVEN a request with `logo: "../../etc/passwd"`
-- WHEN `validateImagePaths()` processes the parameter
+- WHEN `validateSinglePath()` processes the parameter
 - THEN validation MUST fail with error `"Invalid image path for logo: path traversal not allowed"`
+- AND the check MUST use `str_contains($imagePath, '..')`
 
 #### Scenario: Absolute path rejected
 - GIVEN a request with `logo: "/etc/passwd"`
-- WHEN `validateImagePaths()` processes the parameter
+- WHEN `validateSinglePath()` processes the parameter
 - THEN validation MUST fail with error `"Invalid image path for logo: path traversal not allowed"`
+- AND the check MUST use `str_starts_with($imagePath, '/')`
 
 #### Scenario: Path outside allowed directories rejected
 - GIVEN a request with `logo: "lib/Controller/SettingsController.php"`
-- WHEN `validateImagePaths()` processes the parameter
+- WHEN `validateSinglePath()` processes the parameter
 - THEN validation MUST fail with error `"Invalid image path for logo: must be in img/logos/ or img/backgrounds/"`
 
 #### Scenario: Non-existent image rejected
 - GIVEN a request with `logo: "img/logos/nonexistent.svg"`
 - AND the file does not exist on the filesystem
-- WHEN `validateImagePaths()` processes the parameter
+- WHEN `validateSinglePath()` processes the parameter
 - THEN validation MUST fail with error `"Image file not found: img/logos/nonexistent.svg"`
 
-#### Scenario: Image fields validated
+#### Scenario: Both image fields validated
 - GIVEN any request to `POST /apps/nldesign/settings/theming`
 - WHEN images are validated
 - THEN the system MUST check both `logo` and `background` parameters
 - AND paths MUST start with either `img/logos/` or `img/backgrounds/`
+- AND validation MUST return the first error found
 
 ### REQ-SYNC-005: Apply Colors to Nextcloud Theming
 The app MUST apply validated color values to Nextcloud's `ThemingDefaults` service.
@@ -119,25 +162,26 @@ The app MUST apply validated color values to Nextcloud's `ThemingDefaults` servi
 - THEN `ThemingDefaults::set('background_color', '#FFFFFF')` MUST be called
 - AND `"background_color"` MUST appear in the list of updated fields
 
-#### Scenario: Multiple colors applied
-- GIVEN a valid request with both `primary_color` and `background_color`
+#### Scenario: Multiple colors applied simultaneously
+- GIVEN a valid request with both `primary_color: "#004699"` and `background_color: "#FFFFFF"`
 - WHEN `applyColors()` is called
-- THEN both colors MUST be applied
+- THEN both colors MUST be applied via `ThemingDefaults::set()`
 - AND both keys MUST appear in the updated list
 
 #### Scenario: Empty color ignored
 - GIVEN a request where `primary_color` is empty or not set
 - WHEN `applyColors()` is called
 - THEN `ThemingDefaults::set()` MUST NOT be called for `primary_color`
+- AND `"primary_color"` MUST NOT appear in the updated list
 
 ### REQ-SYNC-006: Apply Images to Nextcloud Theming
-The app MUST apply validated image paths to Nextcloud's `ImageManager` service.
+The app MUST apply validated image paths to Nextcloud's `ImageManager` service using full filesystem paths.
 
 #### Scenario: Logo image applied
 - GIVEN a valid request with `logo: "img/logos/amsterdam.svg"`
 - AND the file exists at `{appPath}/img/logos/amsterdam.svg`
 - WHEN `applyImages()` is called
-- THEN `ImageManager::updateImage('logo', '{appPath}/img/logos/amsterdam.svg')` MUST be called
+- THEN `ImageManager::updateImage('logo', '{appPath}/img/logos/amsterdam.svg')` MUST be called with the full absolute path
 - AND `"logo"` MUST appear in the list of updated fields
 
 #### Scenario: Background image applied
@@ -145,9 +189,21 @@ The app MUST apply validated image paths to Nextcloud's `ImageManager` service.
 - AND the file exists
 - WHEN `applyImages()` is called
 - THEN `ImageManager::updateImage('background', '{fullPath}')` MUST be called
+- AND `"background"` MUST appear in the list of updated fields
+
+#### Scenario: Empty image path ignored
+- GIVEN a request where `logo` is empty or not set
+- WHEN `applyImages()` is called
+- THEN `ImageManager::updateImage()` MUST NOT be called for `logo`
+
+#### Scenario: App path resolved via IAppManager
+- GIVEN images need to be applied
+- WHEN the full path is constructed
+- THEN `IAppManager::getAppPath('nldesign')` MUST be used to resolve the base directory
+- AND the relative path MUST be appended to get the full filesystem path
 
 ### REQ-SYNC-007: Update Theming API Endpoint
-The app MUST provide an admin-only API endpoint for updating Nextcloud theming values.
+The app MUST provide an admin-only API endpoint that validates and applies theming changes in a defined order.
 
 #### Scenario: Successful theming update
 - GIVEN the admin is authenticated
@@ -159,20 +215,34 @@ The app MUST provide an admin-only API endpoint for updating Nextcloud theming v
 - AND images MUST be applied
 - AND the response MUST be JSON with `{"status": "ok", "updated": ["primary_color", "logo"]}`
 
-#### Scenario: Validation failure stops processing
+#### Scenario: Color validation failure stops all processing
 - GIVEN a request with `primary_color: "invalid"` and `logo: "img/logos/valid.svg"`
 - WHEN `POST /apps/nldesign/settings/theming` is called
 - THEN color validation MUST fail first
-- AND the response MUST be HTTP 400 with the error message
+- AND the response MUST be HTTP 400 with `{"error": "Invalid hex color for primary_color: invalid"}`
 - AND no colors or images MUST be applied
 
+#### Scenario: Image validation failure stops image processing
+- GIVEN a request with `primary_color: "#154273"` and `logo: "../../etc/passwd"`
+- WHEN validation runs
+- THEN color validation MUST pass
+- AND image validation MUST fail
+- AND the response MUST be HTTP 400 with the image error message
+- AND no changes MUST be applied (neither colors nor images)
+
 #### Scenario: Non-admin access denied
 - GIVEN a non-admin user is authenticated
 - WHEN `POST /apps/nldesign/settings/theming` is called
 - THEN the request MUST be rejected by the `@AuthorizedAdminSetting(settings=OCA\NLDesign\Settings\Admin)` annotation
 
+#### Scenario: Empty request applies nothing
+- GIVEN a request with no parameters
+- WHEN `POST /apps/nldesign/settings/theming` is called
+- THEN validation MUST pass (no fields to validate)
+- AND the response MUST be `{"status": "ok", "updated": []}`
+
 ### REQ-SYNC-008: Theming Dependencies
-The theming sync feature MUST depend on the Nextcloud `theming` app for `ThemingDefaults` and `ImageManager`.
+The theming sync feature MUST depend on the Nextcloud `theming` app for `ThemingDefaults` and `ImageManager`, injected via constructor.
 
 #### Scenario: ThemingService dependencies injected
 - GIVEN the nldesign app is loaded
@@ -180,32 +250,112 @@ The theming sync feature MUST depend on the Nextcloud `theming` app for `Theming
 - THEN it MUST receive `ImageManager`, `ThemingDefaults`, and `IAppManager` via constructor injection
 - AND it MUST NOT instantiate these dependencies directly
 
+#### Scenario: ImageManager accessible via getter
+- GIVEN the `ThemingService` is constructed
+- WHEN `getImageManager()` is called
+- THEN it MUST return the injected `ImageManager` instance
+- AND the `SettingsController` can use this to build theming snapshots
+
+#### Scenario: Theming app must be enabled
+- GIVEN the theming app is not enabled in Nextcloud
+- WHEN the `ThemingService` dependencies are resolved
+- THEN Nextcloud's DI container MUST handle the missing dependency
+- AND the nldesign app SHOULD declare `theming` as a dependency in `info.xml`
+
+### REQ-SYNC-009: Validation Order
+The theming sync endpoint MUST validate all inputs before applying any changes, ensuring atomicity of the validation phase.
+
+#### Scenario: Colors validated before images
+- GIVEN a request with both color and image parameters
+- WHEN `updateThemingValues()` processes the request
+- THEN `validateColors()` MUST be called first
+- AND only if it returns `null` (success) MUST `validateImagePaths()` be called
+- AND only if both return `null` MUST `applyColors()` and `applyImages()` be called
+
+#### Scenario: Failed validation prevents all changes
+- GIVEN color validation fails
+- WHEN the error response is returned
+- THEN no IConfig values MUST be modified
+- AND no ImageManager updates MUST be triggered
+- AND the Nextcloud theming state MUST remain unchanged
+
+#### Scenario: Params read from request
+- GIVEN the `updateThemingValues()` method is called
+- WHEN request parameters are read
+- THEN `$this->request->getParams()` MUST be used to get all parameters
+- AND these params MUST be passed to both validation and apply methods
+
+### REQ-SYNC-010: Theming Sync Dialog (Frontend)
+The admin JavaScript MUST show a confirmation dialog when switching to a token set that has theming metadata, allowing the admin to review and approve theming changes.
+
+#### Scenario: Dialog shown for token set with theming metadata
+- GIVEN the admin selects a token set that has a `theming` object
+- WHEN the token set selection is saved
+- THEN the JavaScript MUST call `checkAndShowThemingDialog()`
+- AND a modal dialog MUST appear showing the proposed theming changes
+
+#### Scenario: Dialog shows color comparison
+- GIVEN the theming dialog opens
+- WHEN the current theming values differ from the token set's proposed values
+- THEN the dialog MUST show current vs proposed colors with visual swatches
+- AND the admin MUST be able to see the difference before confirming
+
+#### Scenario: Dialog not shown for sets without theming metadata
+- GIVEN the admin selects a token set without a `theming` object
+- WHEN the token set selection is saved
+- THEN no theming sync dialog MUST be shown
+- AND the token set MUST be applied without further prompts
+
+#### Scenario: Admin confirms theming sync
+- GIVEN the theming dialog is shown
+- WHEN the admin clicks the confirm/apply button
+- THEN `POST /apps/nldesign/settings/theming` MUST be called with the proposed values
+- AND on success, Nextcloud's theming MUST be updated
+
+#### Scenario: Admin cancels theming sync
+- GIVEN the theming dialog is shown
+- WHEN the admin clicks cancel
+- THEN the dialog MUST close
+- AND no theming changes MUST be applied
+- AND the token set selection MUST still take effect (CSS tokens change, but Nextcloud core theming remains unchanged)
+
+### REQ-SYNC-011: Route Configuration
+The theming sync endpoints MUST be registered in the app's route configuration.
+
+#### Scenario: GET theming route
+- GIVEN the routes configuration
+- THEN `GET /settings/theming` MUST be mapped to `settings#getThemingValues`
+
+#### Scenario: POST theming route
+- GIVEN the routes configuration
+- THEN `POST /settings/theming` MUST be mapped to `settings#updateThemingValues`
+
+#### Scenario: Both routes admin-only
+- GIVEN both theming routes
+- THEN both corresponding controller methods MUST have `@AuthorizedAdminSetting` annotations
+
 ### Current Implementation Status
 
 **Fully implemented:**
-- Theming metadata in token sets: `TokenSetService::getAvailableTokenSets()` includes the `theming` object from `token-sets.json` entries when present (`lib/Service/TokenSetService.php` lines 84-86)
-- GET theming values: `GET /apps/nldesign/settings/theming` endpoint in `SettingsController::getThemingValues()` returns `primary_color`, `background_color`, `logo_url`, `background_url`, `has_custom_logo`, `has_custom_background` (`lib/Controller/SettingsController.php` lines 237-260)
-- Color validation: `ThemingService::validateColors()` checks `primary_color` and `background_color` against regex `/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/`, skips empty values, returns error string on failure (`lib/Service/ThemingService.php` lines 87-98)
-- Image path validation: `ThemingService::validateImagePaths()` and `validateSinglePath()` check for path traversal (`..` and `/` prefix), enforce `img/logos/` or `img/backgrounds/` prefix, verify file existence (`lib/Service/ThemingService.php` lines 107-153)
-- Apply colors: `ThemingService::applyColors()` calls `ThemingDefaults::set()` for each non-empty color (`lib/Service/ThemingService.php` lines 162-174)
-- Apply images: `ThemingService::applyImages()` calls `ImageManager::updateImage()` with full path (`lib/Service/ThemingService.php` lines 183-197)
-- POST theming endpoint: `POST /apps/nldesign/settings/theming` in `SettingsController::updateThemingValues()` runs validation then applies, returns `{"status": "ok", "updated": [...]}` (`lib/Controller/SettingsController.php` lines 209-228)
-- ThemingService dependencies: Constructor injection of `ImageManager`, `ThemingDefaults`, `IAppManager` (`lib/Service/ThemingService.php` lines 58-66)
+- Theming metadata in token sets: `TokenSetService::getAvailableTokenSets()` includes the `theming` object from `token-sets.json` entries when present (`lib/Service/TokenSetService.php` lines 85-87)
+- GET theming values: `GET /apps/nldesign/settings/theming` endpoint in `SettingsController::getThemingValues()` via `buildThemingSnapshot()` returns all required fields (`lib/Controller/SettingsController.php` lines 275-299)
+- Color validation: `ThemingService::validateColors()` checks `primary_color` and `background_color` against regex `/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/`, skips empty values (`lib/Service/ThemingService.php` lines 87-98)
+- Image path validation: `ThemingService::validateImagePaths()` and `validateSinglePath()` check for path traversal, enforce allowed directory prefixes, verify file existence (`lib/Service/ThemingService.php` lines 107-153)
+- Apply colors: `ThemingService::applyColors()` calls `ThemingDefaults::set()` for each non-empty color (lines 162-174)
+- Apply images: `ThemingService::applyImages()` calls `ImageManager::updateImage()` with full path resolved via `IAppManager::getAppPath()` (lines 183-197)
+- POST theming endpoint: `SettingsController::updateThemingValues()` validates colors first, then images, then applies (lines 247-266)
+- ThemingService constructor injection of `ImageManager`, `ThemingDefaults`, `IAppManager` (lines 58-66)
+- `getImageManager()` getter for snapshot building (lines 204-207)
 - Admin-only access: `@AuthorizedAdminSetting` annotation on all theming endpoints
-- Frontend theming sync dialog: `js/admin.js` `checkAndShowThemingDialog()` and `showThemingDialog()` functions compare current vs proposed theming values and show confirmation dialog with color swatches and previews (lines 113-297)
-- Routes: `appinfo/routes.php` lines 12-13
+- Frontend theming sync dialog: `js/admin.js` with `checkAndShowThemingDialog()` and `showThemingDialog()` functions
+- Routes: `appinfo/routes.php` lines 16-17
 
 **Not yet implemented:**
 - All requirements in this spec are fully implemented.
+- Note: The implementation does not wrap `ThemingDefaults::set()` or `ImageManager::updateImage()` in try/catch -- if these throw, the endpoint will return a 500 error.
 
 ### Standards & References
 - Nextcloud Theming API: `OCA\Theming\ThemingDefaults::set()` and `OCA\Theming\ImageManager::updateImage()` are internal Nextcloud APIs
 - OWASP Path Traversal Prevention: validated by checking for `..` and `/` prefix, enforcing allowed directories
 - Hex color validation: Standard CSS hex color format (3 or 6 digit)
 - NL Design System: Token set theming metadata bridges design tokens to Nextcloud's server-level branding (logos, background images, email templates)
-
-### Specificity Assessment
-- This spec is highly specific. Validation rules, API request/response formats, error messages, and dependency injection are all precisely defined.
-- The spec correctly separates color validation from image validation and specifies the order (colors first, images second).
-- Minor gap: The spec does not define what happens when `ThemingDefaults::set()` or `ImageManager::updateImage()` throws an exception. The implementation does not wrap these calls in try/catch.
-- Open question: Should the `background` image field in the theming metadata (referenced in `js/admin.js` line 153-159) be formally documented in REQ-SYNC-001? Currently only `logo` is mentioned as MAY in the manifest schema, but `background` is also handled.
diff --git a/openspec/specs/token-sets/spec.md b/openspec/specs/token-sets/spec.md
index abe9bc9..782599d 100644
--- a/openspec/specs/token-sets/spec.md
+++ b/openspec/specs/token-sets/spec.md
@@ -1,12 +1,13 @@
 ---
-status: reviewed
+status: enriched
 reviewed_date: 2026-02-28
+enriched_date: 2026-03-20
 ---
 
 # Token Sets Specification
 
 ## Purpose
-Defines how the NL Design app discovers, validates, stores, and serves design token sets. Token sets are organization-specific CSS files that override default Rijkshuisstijl design tokens, enabling Dutch government organizations to apply their own visual identity to Nextcloud. The system uses filesystem-based discovery combined with a JSON manifest for metadata.
+Defines how the NL Design app discovers, validates, stores, and serves design token sets. Token sets are organization-specific CSS files that override default Rijkshuisstijl design tokens, enabling Dutch government organizations to apply their own visual identity to Nextcloud. The system uses filesystem-based discovery combined with a JSON manifest for metadata, and supports multiple design systems via a `design_system` field that determines which CSS stack is loaded.
 
 ## Requirements
 
@@ -18,8 +19,8 @@ The app MUST discover available token sets by scanning the `css/tokens/` directo
 - AND the `css/tokens/` directory contains CSS files (e.g. `rijkshuisstijl.css`, `amsterdam.css`)
 - WHEN `TokenSetService::getAvailableTokenSets()` is called
 - THEN each `.css` file in `css/tokens/` MUST produce a token set entry
-- AND each entry MUST have an `id` derived from the filename without extension
-- AND each entry MUST have a `name` and `description`
+- AND each entry MUST have an `id` derived from the filename without extension (via `basename($file, '.css')`)
+- AND each entry MUST have a `name`, `description`, and `design_system` field
 
 #### Scenario: Metadata merged from manifest
 - GIVEN `token-sets.json` exists and contains an entry with `id: "amsterdam"`
@@ -27,6 +28,7 @@ The app MUST discover available token sets by scanning the `css/tokens/` directo
 - WHEN the available token sets are retrieved
 - THEN the entry for `amsterdam` MUST use the `name` from the manifest ("Gemeente Amsterdam")
 - AND the entry MUST use the `description` from the manifest
+- AND the entry MUST use the `design_system` from the manifest (default: "nldesign")
 - AND if the manifest entry has a `theming` object, it MUST be included in the response
 
 #### Scenario: CSS file exists without manifest entry
@@ -36,48 +38,64 @@ The app MUST discover available token sets by scanning the `css/tokens/` directo
 - THEN the entry MUST still be returned
 - AND the `name` MUST be auto-generated from the id using `ucwords(str_replace('-', ' ', $id))` (e.g. "Custom Org")
 - AND the `description` MUST default to "Design tokens for Custom Org"
+- AND the `design_system` MUST default to "nldesign"
 
 #### Scenario: Manifest entry exists without CSS file
 - GIVEN `token-sets.json` contains an entry with `id: "phantom-org"`
 - AND `css/tokens/phantom-org.css` does NOT exist
 - WHEN the available token sets are retrieved
 - THEN the `phantom-org` entry MUST NOT appear in the results
+- AND the filesystem MUST be the source of truth for available sets
 
 #### Scenario: Token sets sorted alphabetically
 - GIVEN multiple token sets are discovered
 - WHEN the list is returned
-- THEN the token sets MUST be sorted alphabetically by `name` (case-insensitive)
+- THEN the token sets MUST be sorted alphabetically by `name` (case-insensitive via `strcasecmp`)
 
 ### REQ-TSET-002: Token Set Manifest Structure
 The `token-sets.json` manifest MUST follow a defined schema for each entry.
 
-#### Scenario: Manifest entry with theming metadata
+#### Scenario: Manifest entry with full metadata
 - GIVEN a manifest entry for an organization
 - WHEN the entry is valid
-- THEN it MUST have a `id` field (string, kebab-case identifier matching the CSS filename)
+- THEN it MUST have an `id` field (string, kebab-case identifier matching the CSS filename)
 - AND it MUST have a `name` field (string, human-readable display name)
 - AND it MUST have a `description` field (string)
-- AND it MAY have a `theming` object with optional keys: `primary_color` (hex), `background_color` (hex), `logo` (relative path)
+- AND it MUST have a `design_system` field (string, referencing an id in `design-systems.json`)
+- AND it MAY have a `theming` object with optional keys: `primary_color` (hex), `background_color` (hex), `logo` (relative path), `background` (relative path)
 
 #### Scenario: Manifest is malformed JSON
 - GIVEN `token-sets.json` contains invalid JSON
 - WHEN `readManifest()` is called
 - THEN it MUST return an empty array
 - AND the system MUST still discover token sets from the filesystem (without metadata)
+- AND the app MUST NOT throw an exception or display an error
 
 #### Scenario: Manifest is missing
 - GIVEN `token-sets.json` does not exist
 - WHEN `readManifest()` is called
 - THEN it MUST return an empty array
-- AND the system MUST still discover token sets with auto-generated names
+- AND the system MUST still discover token sets with auto-generated names and default design_system
+
+#### Scenario: Manifest file unreadable
+- GIVEN `token-sets.json` exists but `file_get_contents()` returns `false`
+- WHEN `readManifest()` is called
+- THEN it MUST return an empty array
+- AND the system MUST continue with auto-generated metadata
+
+#### Scenario: Manifest indexed by id
+- GIVEN the manifest contains multiple entries
+- WHEN `readManifest()` processes them
+- THEN entries MUST be indexed by their `id` field
+- AND entries without an `id` field MUST be skipped
 
 ### REQ-TSET-003: Active Token Set Storage
-The active token set MUST be stored in Nextcloud's `IConfig` and default to `rijkshuisstijl`.
+The active token set MUST be stored in Nextcloud's `IConfig` and default to `nextcloud`.
 
-#### Scenario: No token set configured
+#### Scenario: No token set configured (fresh install)
 - GIVEN no value has been set for `nldesign:token_set` in IConfig
 - WHEN the active token set is queried
-- THEN the default value MUST be `rijkshuisstijl`
+- THEN the default value MUST be `'nextcloud'` (stock Nextcloud theming)
 
 #### Scenario: Token set persisted via API
 - GIVEN an admin selects the `utrecht` token set
@@ -90,8 +108,14 @@ The active token set MUST be stored in Nextcloud's `IConfig` and default to `rij
 - WHEN `GET /settings/tokenset` is called
 - THEN the response MUST be JSON with `{"tokenSet": "amsterdam"}`
 
+#### Scenario: Token set read during boot
+- GIVEN the active token set is stored as `amsterdam` in IConfig
+- WHEN `Application::injectThemeCSS()` reads the config
+- THEN `$config->getAppValue('nldesign', 'token_set', 'nextcloud')` MUST return `'amsterdam'`
+- AND `tokens/amsterdam` MUST be loaded as Layer 3 in the CSS stack
+
 ### REQ-TSET-004: Token Set Validation
-The app MUST validate that a token set is valid before accepting it as the active set.
+The app MUST validate that a token set is valid (exists on filesystem, no path traversal) before accepting it as the active set.
 
 #### Scenario: Valid token set selected
 - GIVEN `css/tokens/utrecht.css` exists on the filesystem
@@ -106,11 +130,23 @@ The app MUST validate that a token set is valid before accepting it as the activ
 - AND the API MUST return HTTP 400 with `{"error": "Invalid token set"}`
 - AND IConfig MUST NOT be updated
 
-#### Scenario: Path traversal prevented
-- GIVEN a malicious token set id containing `../` or `/`
-- WHEN `isValidTokenSet("../../etc/passwd")` is called
-- THEN it MUST return `false`
-- AND the filesystem MUST NOT be accessed outside `css/tokens/`
+#### Scenario: Path traversal with forward slash prevented
+- GIVEN a malicious token set id containing `/` (e.g., "../../etc/passwd")
+- WHEN `isValidTokenSet()` is called
+- THEN `str_contains($tokenSetId, '/')` MUST return `true`
+- AND the method MUST return `false` immediately without filesystem access
+
+#### Scenario: Path traversal with dot-dot prevented
+- GIVEN a malicious token set id containing `..` (e.g., "..%2F..%2Fetc%2Fpasswd")
+- WHEN `isValidTokenSet()` is called
+- THEN `str_contains($tokenSetId, '..')` MUST return `true`
+- AND the method MUST return `false` immediately
+
+#### Scenario: Validation checks actual file existence
+- GIVEN the id passes path traversal checks
+- WHEN `isValidTokenSet()` continues
+- THEN it MUST construct the path `{appPath}/css/tokens/{tokenSetId}.css`
+- AND it MUST verify the file exists via `file_exists()`
 
 ### REQ-TSET-005: Token Set CSS Structure
 Each token set CSS file MUST define organization-specific `--nldesign-*` variables on `:root`.
@@ -127,6 +163,7 @@ Each token set CSS file MUST define organization-specific `--nldesign-*` variabl
 - WHEN loaded after `defaults.css`
 - THEN all undefined tokens MUST fall back to the Rijkshuisstijl defaults from `defaults.css`
 - AND the application MUST render correctly with the partial overrides
+- AND no visual errors (missing colors, transparent elements) MUST occur
 
 #### Scenario: Token set with logo
 - GIVEN a token set defines `--nldesign-logo-url: url('../img/logos/amsterdam.svg')`
@@ -134,20 +171,33 @@ Each token set CSS file MUST define organization-specific `--nldesign-*` variabl
 - THEN the logo MUST be displayed in the header and login page via `background-image`
 - AND the logo MUST be sized and positioned using `--nldesign-logo-center` and related variables
 
+#### Scenario: Token set with lint/ribbon
+- GIVEN a token set defines `--nldesign-color-logo-background`, `--nldesign-size-lint`, and `--nldesign-size-lint-height`
+- WHEN the header renders
+- THEN a colored ribbon MUST appear behind the logo area
+- AND the ribbon dimensions MUST match the token values
+
+#### Scenario: WCAG AA contrast in token sets
+- GIVEN a token set defines `--nldesign-color-primary` and `--nldesign-color-primary-text`
+- WHEN these colors are used together (e.g., on primary buttons)
+- THEN the contrast ratio MUST be at least 4.5:1 for normal text
+- AND token set authors MUST ensure their color combinations meet WCAG AA
+
 ### REQ-TSET-006: Token Sets API Endpoints
-The app MUST expose admin-only API endpoints for managing token sets.
+The app MUST expose admin-only API endpoints for listing, getting, and setting token sets.
 
 #### Scenario: List all available token sets
 - GIVEN the admin is authenticated
 - WHEN `GET /apps/nldesign/settings/tokensets` is called
 - THEN the response MUST be JSON with `{"tokenSets": [...]}` containing all discovered token sets
-- AND each token set object MUST have `id`, `name`, `description` fields
+- AND each token set object MUST have `id`, `name`, `description`, `design_system` fields
 - AND token sets with theming metadata MUST include the `theming` object
 
 #### Scenario: Get current token set
 - GIVEN the admin is authenticated
 - WHEN `GET /apps/nldesign/settings/tokenset` is called
 - THEN the response MUST be JSON with `{"tokenSet": "<current-id>"}`
+- AND the default MUST be `"nextcloud"` if not configured
 
 #### Scenario: Set active token set
 - GIVEN the admin is authenticated
@@ -156,19 +206,25 @@ The app MUST expose admin-only API endpoints for managing token sets.
 - THEN the response MUST be JSON with `{"status": "ok", "tokenSet": "denhaag"}`
 - AND the active token set MUST be updated in IConfig
 
+#### Scenario: Set invalid token set returns error
+- GIVEN the admin is authenticated
+- AND the token set `nonexistent` does NOT exist
+- WHEN `POST /apps/nldesign/settings/tokenset` is called with `tokenSet=nonexistent`
+- THEN the response MUST be HTTP 400 with `{"error": "Invalid token set"}`
+
 #### Scenario: Non-admin access denied
 - GIVEN a non-admin user is authenticated
 - WHEN any `/settings/tokenset` or `/settings/tokensets` endpoint is called
 - THEN the request MUST be rejected by the `@AuthorizedAdminSetting(settings=OCA\NLDesign\Settings\Admin)` annotation
 
 ### REQ-TSET-007: Token Set Count and Coverage
-The app MUST support at minimum the documented set of organizations. As of 2026-02-28, there are 39 token sets and 39 manifest entries.
+The app MUST support at minimum the documented set of Dutch government organizations as token sets.
 
 #### Scenario: All required token sets present
 - GIVEN the nldesign app is installed
 - WHEN the `css/tokens/` directory is scanned
-- THEN it MUST contain CSS files for at least: rijkshuisstijl, amsterdam, utrecht, rotterdam, denhaag
-- AND the total number of CSS files in `css/tokens/` MUST match the number of entries in `token-sets.json`
+- THEN it MUST contain CSS files for at least: rijkshuisstijl, amsterdam, utrecht, rotterdam, denhaag, nextcloud
+- AND the total number MUST be at least 39
 
 #### Scenario: Token set count matches manifest
 - GIVEN the `token-sets.json` manifest lists N entries
@@ -176,25 +232,114 @@ The app MUST support at minimum the documented set of organizations. As of 2026-
 - THEN each manifest entry MUST have a corresponding CSS file
 - AND conversely, each CSS file SHOULD have a corresponding manifest entry (files without manifest entries receive auto-generated names)
 
+#### Scenario: Token sets include major Dutch municipalities
+- GIVEN the available token sets
+- THEN they MUST include: amsterdam, rotterdam, denhaag, utrecht, groningen, nijmegen, leiden, tilburg, zwolle, haarlem
+- AND they MUST include government organizations: rijkshuisstijl, duo, vng
+
+### REQ-TSET-008: Design System Association
+Each token set MUST be associated with a design system that determines which CSS layers are loaded.
+
+#### Scenario: Token set with nldesign design system
+- GIVEN a token set has `design_system: "nldesign"` in the manifest
+- WHEN the token set is activated
+- THEN the full nldesign CSS stack (7 layers) MUST be loaded from `design-systems.json`
+- AND the token set CSS MUST be loaded after the design system stylesheets
+
+#### Scenario: Token set with "none" design system (stock Nextcloud)
+- GIVEN the "nextcloud" token set has `design_system: "none"` in the manifest
+- WHEN the token set is activated
+- THEN no design system stylesheets MUST be loaded
+- AND the token set CSS MUST NOT be loaded (the `designSystemId !== 'none'` check prevents it)
+- AND Nextcloud's default theming MUST remain active
+
+#### Scenario: Default design system for token sets without manifest entry
+- GIVEN a CSS file exists in `css/tokens/` without a manifest entry
+- WHEN the token set is discovered
+- THEN `design_system` MUST default to `"nldesign"`
+- AND the full nldesign CSS stack MUST be loaded when this set is activated
+
+### REQ-TSET-009: Token Set Preview
+The app MUST provide an endpoint for previewing the resolved CSS values of a token set without applying it.
+
+#### Scenario: Valid token set preview
+- GIVEN the admin is authenticated
+- AND the token set "amsterdam" exists
+- WHEN `GET /apps/nldesign/settings/tokenset-preview/amsterdam` is called
+- THEN the response MUST be JSON with `{"tokenSetId": "amsterdam", "resolved": {...}}`
+- AND `resolved` MUST contain the CSS variable values that would result from applying this token set
+
+#### Scenario: Invalid token set preview returns 404
+- GIVEN the admin is authenticated
+- AND the token set "nonexistent" does NOT exist
+- WHEN `GET /apps/nldesign/settings/tokenset-preview/nonexistent` is called
+- THEN the response MUST be HTTP 404 with `{"error": "Token set not found"}`
+
+#### Scenario: Preview used by apply dialog
+- GIVEN the admin selects a new token set in the dropdown
+- WHEN the JavaScript prepares the apply dialog
+- THEN it MUST call the preview endpoint to get resolved values
+- AND it MUST compare these against the current custom overrides
+- AND it MUST display the differences for the admin to review
+
+### REQ-TSET-010: Token Set Service Architecture
+The `TokenSetService` MUST be a clean service class with `IAppManager` as its only dependency.
+
+#### Scenario: Constructor dependency
+- GIVEN `TokenSetService` is constructed
+- THEN it MUST receive `IAppManager` via constructor injection
+- AND it MUST use `IAppManager::getAppPath('nldesign')` to resolve filesystem paths
+
+#### Scenario: Private helper methods
+- GIVEN the service has internal methods
+- THEN `getAppPath()` MUST be private and return the absolute app directory
+- AND `readManifest()` MUST be private and handle all file-reading errors gracefully
+- AND `formatName()` MUST be private and convert kebab-case ids to display names
+
+#### Scenario: Service used in multiple locations
+- GIVEN the `TokenSetService` is needed by both `Admin::getForm()` and `SettingsController`
+- WHEN it is instantiated
+- THEN `Admin::getForm()` creates a new instance via `new TokenSetService(appManager: $appManager)`
+- AND `SettingsController::setTokenSet()` also creates a new instance
+- AND the `SettingsController` also receives an injected instance via constructor for `getAvailableTokenSets()`
+
+### REQ-TSET-011: Route Configuration
+Token set management endpoints MUST be registered in the route configuration.
+
+#### Scenario: List token sets route
+- GIVEN the routes configuration in `appinfo/routes.php`
+- THEN `GET /settings/tokensets` MUST be mapped to `settings#getAvailableTokenSets`
+
+#### Scenario: Get active token set route
+- GIVEN the routes configuration
+- THEN `GET /settings/tokenset` MUST be mapped to `settings#getTokenSet`
+
+#### Scenario: Set active token set route
+- GIVEN the routes configuration
+- THEN `POST /settings/tokenset` MUST be mapped to `settings#setTokenSet`
+
+#### Scenario: Token set preview route
+- GIVEN the routes configuration
+- THEN `GET /settings/tokenset-preview/{tokenSetId}` MUST be mapped to `settings#getTokenSetPreview`
+
 ### Current Implementation Status
 
 **Fully implemented:**
-- Filesystem-based discovery: `TokenSetService::getAvailableTokenSets()` scans `css/tokens/` for `.css` files and merges metadata from `token-sets.json` (`lib/Service/TokenSetService.php` lines 62-97)
-- Metadata merging: `readManifest()` reads `token-sets.json`, indexes by `id`, merges `name`, `description`, and optional `theming` object (lines 126-150)
-- Auto-generated names for CSS files without manifest entry: `formatName()` uses `ucwords(str_replace('-', ' ', $id))` (lines 159-162)
-- Manifest entries without CSS files are excluded (only files from `scandir()` produce entries)
-- Alphabetical sort by name (case-insensitive): `usort()` with `strcasecmp` (line 94)
-- Malformed/missing manifest: `readManifest()` returns `[]` on invalid JSON or missing file (lines 128-139)
-- Active token set storage: Default `'rijkshuisstijl'` via `IConfig::getAppValue()` in `Application.php` (line 79) and `SettingsController::getTokenSet()` (line 132)
-- Token set validation: `isValidTokenSet()` checks for path traversal (`/` and `..`) and verifies CSS file existence (lines 106-117)
-- API endpoints:
-  - `GET /settings/tokensets` -> `getAvailableTokenSets()` returns `{"tokenSets": [...]}` (routes.php line 7, controller line 145-150)
-  - `GET /settings/tokenset` -> `getTokenSet()` returns `{"tokenSet": "..."}` (routes.php line 9, controller lines 127-136)
-  - `POST /settings/tokenset` -> `setTokenSet()` validates then stores, returns `{"status": "ok", "tokenSet": "..."}` or HTTP 400 (routes.php line 8, controller lines 109-118)
+- Filesystem-based discovery: `TokenSetService::getAvailableTokenSets()` scans `css/tokens/` for `.css` files and merges metadata from `token-sets.json` (`lib/Service/TokenSetService.php` lines 62-98)
+- Metadata merging: `readManifest()` reads `token-sets.json`, indexes by `id`, merges `name`, `description`, `design_system`, and optional `theming` object (lines 127-151)
+- Auto-generated names for CSS files without manifest entry: `formatName()` uses `ucwords(str_replace('-', ' ', $id))` (lines 160-163)
+- Default design_system "nldesign" for entries without manifest (line 83)
+- Manifest entries without CSS files are excluded
+- Alphabetical sort by name (case-insensitive): `usort()` with `strcasecmp` (line 95)
+- Malformed/missing manifest: `readManifest()` returns `[]` on invalid JSON, missing file, or unreadable file
+- Active token set storage: Default `'nextcloud'` via `IConfig::getAppValue()` in `Application.php` (line 84) and `SettingsController::getTokenSet()` (line 134)
+- Token set validation: `isValidTokenSet()` checks for path traversal (`/` and `..`) and verifies CSS file existence (lines 107-118)
+- API endpoints: all four routes implemented (tokensets GET, tokenset GET/POST, tokenset-preview GET)
 - Admin-only access: `@AuthorizedAdminSetting` annotation on all endpoints
-- Token set count: 39 CSS files in `css/tokens/` directory, `token-sets.json` has 368 lines
-- Required token sets present: rijkshuisstijl, amsterdam, utrecht, rotterdam, denhaag all exist in `css/tokens/`
-- Theming metadata included in response when present in manifest (`TokenSetService.php` lines 84-86)
+- Token set count: 39+ CSS files in `css/tokens/`, manifest with corresponding entries
+- Required token sets present: rijkshuisstijl, amsterdam, utrecht, rotterdam, denhaag, nextcloud all exist
+- Token set preview: `SettingsController::getTokenSetPreview()` uses `TokenSetPreviewService::getResolvedColors()` (lines 313-322)
+- Design system association: `design_system` field included in token set metadata
 
 **Not yet implemented:**
 - All requirements in this spec are fully implemented.
@@ -206,10 +351,4 @@ The app MUST support at minimum the documented set of organizations. As of 2026-
 - Rijkshuisstijl (Dutch government house style): https://www.rijkshuisstijl.nl/
 - Utrecht Design System `--utrecht-*` token namespace: https://nl-design-system.github.io/utrecht/
 - OWASP Path Traversal prevention for token set ID validation
-
-### Specificity Assessment
-- This spec is highly specific and directly implementable. Discovery logic, manifest schema, validation rules, API contracts, and default values are all precisely defined.
-- The spec correctly covers edge cases: missing manifest, malformed JSON, CSS files without manifest entries, manifest entries without CSS files, and path traversal attacks.
-- Minor gap: REQ-TSET-005 describes token set CSS structure but does not define which `--nldesign-*` variables are mandatory vs optional in a token set file. The implementation allows fully partial token sets.
-- Minor gap: The spec does not mention the `TokenSetPreviewService` or the `GET /settings/tokenset-preview/{tokenSetId}` endpoint, which exists in the implementation for comparing resolved token values across sets.
-- Open question: Should the `token-sets.json` manifest schema be formally versioned? Currently there is no version field in the manifest.
+- WCAG 2.1 AA contrast requirements for token set color combinations