diff --git a/.phpunit.cache/test-results b/.phpunit.cache/test-results
deleted file mode 100644
index 9c6c18b..0000000
--- a/.phpunit.cache/test-results
+++ /dev/null
@@ -1 +0,0 @@
-{"version":2,"defects":[],"times":{"OCA\\NLDesign\\Tests\\Unit\\Service\\TokenRegistryTest::testGetTokensReturnsNonEmptyArray":0.016,"OCA\\NLDesign\\Tests\\Unit\\Service\\TokenRegistryTest::testEveryTokenHasRequiredKeys":0.005,"OCA\\NLDesign\\Tests\\Unit\\Service\\TokenRegistryTest::testTokenNamesStartWithDoubleDash":0.002,"OCA\\NLDesign\\Tests\\Unit\\Service\\TokenRegistryTest::testTokenTypesAreValid":0.002,"OCA\\NLDesign\\Tests\\Unit\\Service\\TokenRegistryTest::testTokenTabsAreValid":0.002,"OCA\\NLDesign\\Tests\\Unit\\Service\\TokenRegistryTest::testGetTabLabelsCoversAllTabs":0.001,"OCA\\NLDesign\\Tests\\Unit\\Service\\TokenRegistryTest::testGetTokenNamesMatchesGetTokensKeys":0.002,"OCA\\NLDesign\\Tests\\Unit\\Service\\TokenRegistryTest::testIsEditableReturnsTrueForKnownToken":0.001,"OCA\\NLDesign\\Tests\\Unit\\Service\\TokenRegistryTest::testIsEditableReturnsFalseForUnknownToken":0.001,"OCA\\NLDesign\\Tests\\Unit\\Service\\TokenRegistryTest::testGetTokensByTabGroupsCorrectly":0.003,"OCA\\NLDesign\\Tests\\Unit\\Service\\TokenRegistryTest::testGetTokensByTabPreservesAllTokens":0,"OCA\\NLDesign\\Tests\\Unit\\Service\\TokenRegistryTest::testColorPrimaryIsInLoginTab":0.001}}
\ No newline at end of file
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
index fbf914c..08df751 100644
--- a/docs/docusaurus.config.js
+++ b/docs/docusaurus.config.js
@@ -17,7 +17,11 @@ const config = {
 
   i18n: {
     defaultLocale: 'en',
-    locales: ['en'],
+    locales: ['en', 'nl'],
+    localeConfigs: {
+      en: { label: 'English' },
+      nl: { label: 'Nederlands' },
+    },
   },
 
   presets: [
@@ -27,9 +31,10 @@ const config = {
       ({
         docs: {
           path: './',
+          exclude: ['**/node_modules/**'],
           sidebarPath: require.resolve('./sidebars.js'),
           editUrl:
-            'https://github.com/ConductionNL/nldesign/tree/main/docusaurus/',
+            'https://github.com/ConductionNL/nldesign/tree/main/docs/',
         },
         blog: false,
         theme: {
@@ -60,6 +65,10 @@ const config = {
             label: 'GitHub',
             position: 'right',
           },
+          {
+            type: 'localeDropdown',
+            position: 'right',
+          },
         ],
       },
       footer: {
diff --git a/docs/features/README.md b/docs/features/README.md
new file mode 100644
index 0000000..cdc4b18
--- /dev/null
+++ b/docs/features/README.md
@@ -0,0 +1,49 @@
+# NL Design — Features
+
+NL Design is a Nextcloud theming app that applies Dutch government design standards (Rijkshuisstijl and other NL Design System token sets) to every part of the Nextcloud interface. It functions as a Nextcloud Theme Editor: administrators select a pre-built organization token set or fine-tune individual CSS variables, and the result is propagated to both the NL Design CSS layer and Nextcloud's built-in theming system.
+
+NL Design has no direct GEMMA component mapping — it is a cross-cutting infrastructure concern that ensures WCAG AA accessibility and Dutch government branding across all Conduction apps.
+
+## Standards Compliance
+
+| Standard | Status | Description |
+|----------|--------|-------------|
+| NL Design System | Beschikbaar | `--nldesign-*` token namespace; 39+ organization token sets |
+| Rijkshuisstijl | Beschikbaar | National government visual identity token set |
+| WCAG 2.1 AA | Beschikbaar | Contrast, font size, and spacing tokens enforced per token set |
+| Digitoegankelijk (EN 301 549) | Beschikbaar | Accessible colour and typography via design tokens |
+| DCAT-AP NL | N.v.t. | Not applicable — theming layer only |
+
+## Features
+
+| Feature | Description | Docs |
+|---------|-------------|------|
+| [Token Sets](./token-sets.md) | 39+ organization-specific CSS token sets; searchable dropdown; auto-generated from upstream NL Design System | [token-sets.md](./token-sets.md) |
+| [Token Editor UI](./token-editor.md) | Tabbed admin panel for editing all Nextcloud `--color-*` CSS variables with live preview and per-token reset | [token-editor.md](./token-editor.md) |
+| [CSS Architecture](./css-architecture.md) | 7-layer CSS load order: design system → token set → custom overrides; `design-systems.json` controls bundles | [css-architecture.md](./css-architecture.md) |
+| [Custom CSS Overrides](./css-architecture.md) | `custom-overrides.css` — single write target for all edits; loaded last; token set files are read-only | [css-architecture.md](./css-architecture.md) |
+| [Token Set Apply Dialog](./apply-dialog.md) | Before applying a token set, shows old → new value diff per token; admin checks/unchecks individual changes | [apply-dialog.md](./apply-dialog.md) |
+| [Theming Sync](./theming-sync.md) | After token set selection, syncs Nextcloud's primary color and background color via the theming API | [theming-sync.md](./theming-sync.md) |
+| [Token Import/Export](./import-export.md) | Download `custom-overrides.css`; upload a saved file to restore or share a token configuration | [import-export.md](./import-export.md) |
+| [Admin Settings](./admin-settings.md) | Admin panel under Theming: token set selector, toggles (hide slogan, show menu labels), token editor | [admin-settings.md](./admin-settings.md) |
+| [Hide Slogan](./toggles.md) | Removes Nextcloud's default login-page slogan for a clean government-branded login | [toggles.md](./toggles.md) |
+| [Show Menu Labels](./toggles.md) | Replaces header app icons with text labels; improves discoverability per Dutch government UX guidelines | [toggles.md](./toggles.md) |
+| [Component Tokens](./token-sets.md) | `--nldesign-component-*` prefix bridging `--utrecht-*` component tokens to the nldesign namespace | [token-sets.md](./token-sets.md) |
+| [App Compatibility](./app-compatibility.md) | Integration guide for other Nextcloud apps to ensure CSS-variable compatibility with nldesign | [app-compatibility.md](./app-compatibility.md) |
+| [Prometheus Metrics](./css-architecture.md) | Active token set, custom override count, theming sync operations — in Prometheus text format | — |
+
+## Architecture
+
+NL Design operates as a pure CSS layer — no database tables. Configuration is stored in `IAppConfig`. The CSS stack loads in a defined order:
+
+1. Design system base CSS (`design-systems.json` bundle)
+2. Organization token set (`css/tokens/{id}.css`)
+3. Custom overrides (`custom-overrides.css`) — always loaded last
+
+The token sync workflow (nightly GitHub Actions) pulls updates from the upstream `nl-design-system/themes` repository and opens PRs when token changes are detected.
+
+## GEMMA Mapping
+
+| GEMMA Component | NL Design Role |
+|-----------------|----------------|
+| N.v.t. | Cross-cutting theming infrastructure for all Conduction Nextcloud apps |
diff --git a/docs/i18n/nl/code.json b/docs/i18n/nl/code.json
new file mode 100644
index 0000000..5aaed38
--- /dev/null
+++ b/docs/i18n/nl/code.json
@@ -0,0 +1,329 @@
+{
+  "theme.ErrorPageContent.title": {
+    "message": "Deze pagina is gecrasht.",
+    "description": "The title of the fallback page when the page crashed"
+  },
+  "theme.BackToTopButton.buttonAriaLabel": {
+    "message": "Scroll naar boven",
+    "description": "The ARIA label for the back to top button"
+  },
+  "theme.blog.archive.title": {
+    "message": "Archief",
+    "description": "The page & hero title of the blog archive page"
+  },
+  "theme.blog.archive.description": {
+    "message": "Archief",
+    "description": "The page & hero description of the blog archive page"
+  },
+  "theme.blog.paginator.navAriaLabel": {
+    "message": "Paginanavigatie blog",
+    "description": "The ARIA label for the blog pagination"
+  },
+  "theme.blog.paginator.newerEntries": {
+    "message": "Nieuwere items",
+    "description": "The label used to navigate to the newer blog posts page (previous page)"
+  },
+  "theme.blog.paginator.olderEntries": {
+    "message": "Oudere items",
+    "description": "The label used to navigate to the older blog posts page (next page)"
+  },
+  "theme.blog.post.paginator.navAriaLabel": {
+    "message": "Paginanavigatie blog",
+    "description": "The ARIA label for the blog posts pagination"
+  },
+  "theme.blog.post.paginator.newerPost": {
+    "message": "Nieuwer bericht",
+    "description": "The blog post button label to navigate to the newer/previous post"
+  },
+  "theme.blog.post.paginator.olderPost": {
+    "message": "Ouder bericht",
+    "description": "The blog post button label to navigate to the older/next post"
+  },
+  "theme.tags.tagsPageLink": {
+    "message": "Laat alle tags zien",
+    "description": "The label of the link targeting the tag list page"
+  },
+  "theme.colorToggle.ariaLabel.mode.system": {
+    "message": "system mode",
+    "description": "The name for the system color mode"
+  },
+  "theme.colorToggle.ariaLabel.mode.light": {
+    "message": "lichte modus",
+    "description": "The name for the light color mode"
+  },
+  "theme.colorToggle.ariaLabel.mode.dark": {
+    "message": "donkere modus",
+    "description": "The name for the dark color mode"
+  },
+  "theme.colorToggle.ariaLabel": {
+    "message": "Schakel tussen donkere en lichte modus (momenteel {mode})",
+    "description": "The ARIA label for the color mode toggle"
+  },
+  "theme.docs.breadcrumbs.navAriaLabel": {
+    "message": "Broodkruimels",
+    "description": "The ARIA label for the breadcrumbs"
+  },
+  "theme.docs.DocCard.categoryDescription.plurals": {
+    "message": "1 artikel|{count} artikelen",
+    "description": "The default description for a category card in the generated index about how many items this category includes"
+  },
+  "theme.docs.paginator.navAriaLabel": {
+    "message": "Documentatie pagina",
+    "description": "The ARIA label for the docs pagination"
+  },
+  "theme.docs.paginator.previous": {
+    "message": "Vorige",
+    "description": "The label used to navigate to the previous doc"
+  },
+  "theme.docs.paginator.next": {
+    "message": "Volgende",
+    "description": "The label used to navigate to the next doc"
+  },
+  "theme.docs.tagDocListPageTitle.nDocsTagged": {
+    "message": "Een artikel getagd|{count} artikelen getagd",
+    "description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)"
+  },
+  "theme.docs.tagDocListPageTitle": {
+    "message": "{nDocsTagged} met \"{tagName}\"",
+    "description": "The title of the page for a docs tag"
+  },
+  "theme.docs.versionBadge.label": {
+    "message": "Versie: {versionLabel}"
+  },
+  "theme.docs.versions.unreleasedVersionLabel": {
+    "message": "Dit is nog niet uitgegeven documentatie voor {siteTitle}, versie {versionLabel}",
+    "description": "The label used to tell the user that he's browsing an unreleased doc version"
+  },
+  "theme.docs.versions.unmaintainedVersionLabel": {
+    "message": "Dit is de documentatie voor {siteTitle} {versionLabel}, welke niet langer actief wordt onderhouden.",
+    "description": "The label used to tell the user that he's browsing an unmaintained doc version"
+  },
+  "theme.docs.versions.latestVersionSuggestionLabel": {
+    "message": "Voor de huidige documentatie, zie de {latestVersionLink} ({versionLabel}).",
+    "description": "The label used to tell the user to check the latest version"
+  },
+  "theme.docs.versions.latestVersionLinkLabel": {
+    "message": "laatste versie",
+    "description": "The label used for the latest version suggestion link label"
+  },
+  "theme.common.editThisPage": {
+    "message": "Bewerk deze pagina",
+    "description": "The link label to edit the current page"
+  },
+  "theme.common.headingLinkTitle": {
+    "message": "Direct link naar {heading}",
+    "description": "Title for link to heading"
+  },
+  "theme.lastUpdated.atDate": {
+    "message": " op {date}",
+    "description": "The words used to describe on which date a page has been last updated"
+  },
+  "theme.lastUpdated.byUser": {
+    "message": " door {user}",
+    "description": "The words used to describe by who the page has been last updated"
+  },
+  "theme.lastUpdated.lastUpdatedAtBy": {
+    "message": "Laatst bijgewerkt{atDate}{byUser}",
+    "description": "The sentence used to display when a page has been last updated, and by who"
+  },
+  "theme.navbar.mobileVersionsDropdown.label": {
+    "message": "Versies",
+    "description": "The label for the navbar versions dropdown on mobile view"
+  },
+  "theme.NotFound.title": {
+    "message": "Pagina niet gevonden",
+    "description": "The title of the 404 page"
+  },
+  "theme.tags.tagsListLabel": {
+    "message": "Tags:",
+    "description": "The label alongside a tag list"
+  },
+  "theme.admonition.caution": {
+    "message": "pas op",
+    "description": "The default label used for the Caution admonition (:::caution)"
+  },
+  "theme.admonition.danger": {
+    "message": "gevaar",
+    "description": "The default label used for the Danger admonition (:::danger)"
+  },
+  "theme.admonition.info": {
+    "message": "info",
+    "description": "The default label used for the Info admonition (:::info)"
+  },
+  "theme.admonition.note": {
+    "message": "notitie",
+    "description": "The default label used for the Note admonition (:::note)"
+  },
+  "theme.admonition.tip": {
+    "message": "tip",
+    "description": "The default label used for the Tip admonition (:::tip)"
+  },
+  "theme.admonition.warning": {
+    "message": "waarschuwing",
+    "description": "The default label used for the Warning admonition (:::warning)"
+  },
+  "theme.AnnouncementBar.closeButtonAriaLabel": {
+    "message": "Sluiten",
+    "description": "The ARIA label for close button of announcement bar"
+  },
+  "theme.blog.sidebar.navAriaLabel": {
+    "message": "Navigatie recente blogitems",
+    "description": "The ARIA label for recent posts in the blog sidebar"
+  },
+  "theme.DocSidebarItem.expandCategoryAriaLabel": {
+    "message": "Categorie zijbalk uitklappen '{label}'",
+    "description": "The ARIA label to expand the sidebar category"
+  },
+  "theme.DocSidebarItem.collapseCategoryAriaLabel": {
+    "message": "Categorie zijbalk inklappen '{label}'",
+    "description": "The ARIA label to collapse the sidebar category"
+  },
+  "theme.IconExternalLink.ariaLabel": {
+    "message": "(opens in new tab)",
+    "description": "The ARIA label for the external link icon"
+  },
+  "theme.NavBar.navAriaLabel": {
+    "message": "Main",
+    "description": "The ARIA label for the main navigation"
+  },
+  "theme.navbar.mobileLanguageDropdown.label": {
+    "message": "Talen",
+    "description": "The label for the mobile language switcher dropdown"
+  },
+  "theme.NotFound.p1": {
+    "message": "We kunnen niet vinden waar je naar op zoek bent.",
+    "description": "The first paragraph of the 404 page"
+  },
+  "theme.NotFound.p2": {
+    "message": "Neem contact op met de eigenaar van de website die naar de originele URL heeft geleid en laat weten dat de link niet meer werkt.",
+    "description": "The 2nd paragraph of the 404 page"
+  },
+  "theme.TOCCollapsible.toggleButtonLabel": {
+    "message": "Op deze pagina",
+    "description": "The label used by the button on the collapsible TOC component"
+  },
+  "theme.blog.post.readMore": {
+    "message": "Lees meer",
+    "description": "The label used in blog post item excerpts to link to full blog posts"
+  },
+  "theme.blog.post.readMoreLabel": {
+    "message": "Lees meer over {title}",
+    "description": "The ARIA label for the link to full blog posts from excerpts"
+  },
+  "theme.blog.post.readingTime.plurals": {
+    "message": "Een minuut leestijd|{readingTime} minuten leestijd",
+    "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)"
+  },
+  "theme.CodeBlock.copy": {
+    "message": "Kopieer",
+    "description": "The copy button label on code blocks"
+  },
+  "theme.CodeBlock.copied": {
+    "message": "Gekopieerd",
+    "description": "The copied button label on code blocks"
+  },
+  "theme.CodeBlock.copyButtonAriaLabel": {
+    "message": "Kopieer code naar klembord",
+    "description": "The ARIA label for copy code blocks button"
+  },
+  "theme.CodeBlock.wordWrapToggle": {
+    "message": "Tekstterugloop in-/uitschakelen",
+    "description": "The title attribute for toggle word wrapping button of code block lines"
+  },
+  "theme.docs.breadcrumbs.home": {
+    "message": "Homepagina",
+    "description": "The ARIA label for the home page in the breadcrumbs"
+  },
+  "theme.docs.sidebar.collapseButtonTitle": {
+    "message": "Zijbalk inklappen",
+    "description": "The title attribute for collapse button of doc sidebar"
+  },
+  "theme.docs.sidebar.collapseButtonAriaLabel": {
+    "message": "Zijbalk inklappen",
+    "description": "The title attribute for collapse button of doc sidebar"
+  },
+  "theme.docs.sidebar.navAriaLabel": {
+    "message": "Docs zijbalk",
+    "description": "The ARIA label for the sidebar navigation"
+  },
+  "theme.docs.sidebar.closeSidebarButtonAriaLabel": {
+    "message": "Sluit navigatiebalk",
+    "description": "The ARIA label for close button of mobile sidebar"
+  },
+  "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": {
+    "message": "← Terug naar het hoofdmenu",
+    "description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)"
+  },
+  "theme.docs.sidebar.toggleSidebarButtonAriaLabel": {
+    "message": "Navigatiebalk schakelen",
+    "description": "The ARIA label for hamburger menu button of mobile navigation"
+  },
+  "theme.navbar.mobileDropdown.collapseButton.expandAriaLabel": {
+    "message": "Expand the dropdown",
+    "description": "The ARIA label of the button to expand the mobile dropdown navbar item"
+  },
+  "theme.navbar.mobileDropdown.collapseButton.collapseAriaLabel": {
+    "message": "Collapse the dropdown",
+    "description": "The ARIA label of the button to collapse the mobile dropdown navbar item"
+  },
+  "theme.docs.sidebar.expandButtonTitle": {
+    "message": "Zijbalk uitklappen",
+    "description": "The ARIA label and title attribute for expand button of doc sidebar"
+  },
+  "theme.docs.sidebar.expandButtonAriaLabel": {
+    "message": "Zijbalk uitklappen",
+    "description": "The ARIA label and title attribute for expand button of doc sidebar"
+  },
+  "theme.blog.post.plurals": {
+    "message": "Een bericht|{count} berichten",
+    "description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)"
+  },
+  "theme.blog.tagTitle": {
+    "message": "{nPosts} getagd met \"{tagName}\"",
+    "description": "The title of the page for a blog tag"
+  },
+  "theme.blog.author.pageTitle": {
+    "message": "{authorName} - {nPosts}",
+    "description": "The title of the page for a blog author"
+  },
+  "theme.blog.authorsList.pageTitle": {
+    "message": "Auteurs",
+    "description": "The title of the authors page"
+  },
+  "theme.blog.authorsList.viewAll": {
+    "message": "Bekijk alle auteurs",
+    "description": "The label of the link targeting the blog authors page"
+  },
+  "theme.blog.author.noPosts": {
+    "message": "Deze auteur heeft nog geen berichten geschreven.",
+    "description": "The text for authors with 0 blog post"
+  },
+  "theme.contentVisibility.unlistedBanner.title": {
+    "message": "Verborgen page",
+    "description": "The unlisted content banner title"
+  },
+  "theme.contentVisibility.unlistedBanner.message": {
+    "message": "Deze pagina is verborgen. Zoekmachines indexeren deze niet en alleen gebruikers met een directe link kunnen deze openen.",
+    "description": "The unlisted content banner message"
+  },
+  "theme.contentVisibility.draftBanner.title": {
+    "message": "Concept pagina",
+    "description": "The draft content banner title"
+  },
+  "theme.contentVisibility.draftBanner.message": {
+    "message": "Deze pagina is een concept. Deze zal alleen zichtbaar zijn in de ontwikkelomgeving en uitgesloten worden van de productie build.",
+    "description": "The draft content banner message"
+  },
+  "theme.ErrorPageContent.tryAgain": {
+    "message": "Probeer opnieuw",
+    "description": "The label of the button to try again rendering when the React error boundary captures an error"
+  },
+  "theme.common.skipToMainContent": {
+    "message": "Ga naar hoofdinhoud",
+    "description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation"
+  },
+  "theme.tags.tagsPageTitle": {
+    "message": "Tags",
+    "description": "The title of the tag list page"
+  }
+}
diff --git a/docs/i18n/nl/docusaurus-plugin-content-docs/current.json b/docs/i18n/nl/docusaurus-plugin-content-docs/current.json
new file mode 100644
index 0000000..2533eba
--- /dev/null
+++ b/docs/i18n/nl/docusaurus-plugin-content-docs/current.json
@@ -0,0 +1,18 @@
+{
+  "version.label": {
+    "message": "Volgende",
+    "description": "The label for version current"
+  },
+  "sidebar.tutorialSidebar.category.Getting Started": {
+    "message": "Aan de slag",
+    "description": "The label for category 'Getting Started' in sidebar 'tutorialSidebar'"
+  },
+  "sidebar.tutorialSidebar.category.Features": {
+    "message": "Functionaliteiten",
+    "description": "The label for category 'Features' in sidebar 'tutorialSidebar'"
+  },
+  "sidebar.tutorialSidebar.category.Reference": {
+    "message": "Referentie",
+    "description": "The label for category 'Reference' in sidebar 'tutorialSidebar'"
+  }
+}
diff --git a/docs/i18n/nl/docusaurus-theme-classic/footer.json b/docs/i18n/nl/docusaurus-theme-classic/footer.json
new file mode 100644
index 0000000..16db0a4
--- /dev/null
+++ b/docs/i18n/nl/docusaurus-theme-classic/footer.json
@@ -0,0 +1,22 @@
+{
+  "link.title.Docs": {
+    "message": "Documentatie",
+    "description": "The title of the footer links column with title=Docs in the footer"
+  },
+  "link.title.Community": {
+    "message": "Community",
+    "description": "The title of the footer links column with title=Community in the footer"
+  },
+  "link.item.label.Documentation": {
+    "message": "Documentatie",
+    "description": "The label of footer link with label=Documentation linking to /docs"
+  },
+  "link.item.label.GitHub": {
+    "message": "GitHub",
+    "description": "The label of footer link with label=GitHub linking to https://github.com/ConductionNL/nldesign"
+  },
+  "copyright": {
+    "message": "Copyright © 2026 for <a href=\"https://openwebconcept.nl\">Open Webconcept</a> by <a href=\"https://conduction.nl\">Conduction B.V.</a>",
+    "description": "The footer copyright"
+  }
+}
diff --git a/docs/i18n/nl/docusaurus-theme-classic/navbar.json b/docs/i18n/nl/docusaurus-theme-classic/navbar.json
new file mode 100644
index 0000000..6f6de27
--- /dev/null
+++ b/docs/i18n/nl/docusaurus-theme-classic/navbar.json
@@ -0,0 +1,18 @@
+{
+  "title": {
+    "message": "NL Design",
+    "description": "The title in the navbar"
+  },
+  "logo.alt": {
+    "message": "NL Design Logo",
+    "description": "The alt text of navbar logo"
+  },
+  "item.label.Documentation": {
+    "message": "Documentatie",
+    "description": "Navbar item with label Documentation"
+  },
+  "item.label.GitHub": {
+    "message": "GitHub",
+    "description": "Navbar item with label GitHub"
+  }
+}
diff --git a/docs/screenshots/.gitkeep b/docs/screenshots/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/openspec/changes/archive/2026-02-15-add-vng-token-set/specs/vng-token-set/spec.md b/openspec/changes/archive/2026-02-15-add-vng-token-set/specs/vng-token-set/spec.md
index 50c9ec7..23ef96a 100644
--- a/openspec/changes/archive/2026-02-15-add-vng-token-set/specs/vng-token-set/spec.md
+++ b/openspec/changes/archive/2026-02-15-add-vng-token-set/specs/vng-token-set/spec.md
@@ -3,7 +3,7 @@
 ## Purpose
 Define requirements for adding VNG (Vereniging Nederlandse Gemeenten) as a selectable design token set in the nldesign Nextcloud app. VNG tokens are manually converted from the tilburg-woo-ui project since they are not available in the upstream nl-design-system/themes repository.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: VNG Token CSS File
 The system MUST provide a `css/tokens/vng.css` file containing VNG design tokens in `:root` scope with `--nldesign-*` semantic tokens and `--vng-*` organization palette tokens.
diff --git a/openspec/changes/archive/2026-03-02-enhance-docs-website/specs/docs-content/spec.md b/openspec/changes/archive/2026-03-02-enhance-docs-website/specs/docs-content/spec.md
index 0df2c26..3eaf78f 100644
--- a/openspec/changes/archive/2026-03-02-enhance-docs-website/specs/docs-content/spec.md
+++ b/openspec/changes/archive/2026-03-02-enhance-docs-website/specs/docs-content/spec.md
@@ -1,4 +1,4 @@
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Documentation landing page
 The documentation site SHALL have an `intro.md` file at `docs/intro.md` that serves as the entry point for all documentation. It SHALL provide a high-level overview of what nldesign is, link to key sections (getting started, features, reference), and use the Docusaurus `slug: /` frontmatter to become the docs root.
diff --git a/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/custom-css-overrides/spec.md b/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/custom-css-overrides/spec.md
index 70a4ed9..64545ee 100644
--- a/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/custom-css-overrides/spec.md
+++ b/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/custom-css-overrides/spec.md
@@ -3,7 +3,7 @@
 ## Purpose
 Defines the CSS file persistence layer for user-defined token customizations. `custom-overrides.css` is the single write target for all theme editor output. It is loaded last in the CSS stack so user intent always wins. NL Design token set CSS files are read-only presets and are never modified.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Custom Overrides File
 The system MUST maintain a `custom-overrides.css` file in the nldesign app's CSS directory. This file MUST be written exclusively by the theme editor backend — no other write path exists.
diff --git a/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/nl-design/spec.md b/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/nl-design/spec.md
index 20806cf..f4a9892 100644
--- a/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/nl-design/spec.md
+++ b/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/nl-design/spec.md
@@ -29,7 +29,7 @@ The nldesign app MUST support all organization token sets available in the confi
 - AND `custom-overrides.css` MUST remain unchanged
 - AND no visual change MUST persist
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: App Identity
 The app MUST be positioned as a **Nextcloud Theme Editor with NL Design System support** in its user-facing name, description, and admin settings heading. The scope is broader than NL Design loading: it encompasses editing any Nextcloud CSS custom property.
diff --git a/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-editor-ui/spec.md b/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-editor-ui/spec.md
index bb56262..a059d05 100644
--- a/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-editor-ui/spec.md
+++ b/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-editor-ui/spec.md
@@ -3,7 +3,7 @@
 ## Purpose
 Provides a tabbed admin settings panel for browsing and editing all editable Nextcloud CSS custom properties (`--color-*`) with live preview and per-token reset controls. Changes are previewed in the browser before being committed to `custom-overrides.css`.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Token Editor Panel
 The admin settings page MUST include a token editor panel below the existing NL Design token-set selector. The panel MUST be rendered as a Vue component within the existing nldesign admin settings template.
diff --git a/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-import-export/spec.md b/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-import-export/spec.md
index 1069565..faf8b2f 100644
--- a/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-import-export/spec.md
+++ b/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-import-export/spec.md
@@ -3,7 +3,7 @@
 ## Purpose
 Allows admins to download the current `custom-overrides.css` as a portable file and upload a previously saved file to restore or share a token configuration. Only known, editable Nextcloud `--color-*` tokens are accepted on import — unknown variables are silently rejected and their count is reported.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Export Current Overrides
 The admin settings panel MUST provide a **Download** button that exports the current `custom-overrides.css` as a file download.
diff --git a/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-set-apply-dialog/spec.md b/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-set-apply-dialog/spec.md
index 07998a6..b2daa33 100644
--- a/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-set-apply-dialog/spec.md
+++ b/openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-set-apply-dialog/spec.md
@@ -3,7 +3,7 @@
 ## Purpose
 Defines the modal dialog shown when an admin selects a new NL Design token set. The dialog shows which Nextcloud CSS variable values would change (resolved current value vs the value from the new token set), lets the admin check or uncheck individual changes, and writes only the checked values to `custom-overrides.css`. The NL Design token set CSS file itself is never applied directly.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Dialog Trigger
 Selecting a different NL Design token set from the selector MUST open the apply dialog instead of immediately switching themes.
diff --git a/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/component-tokens/spec.md b/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/component-tokens/spec.md
index d85648e..4841a49 100644
--- a/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/component-tokens/spec.md
+++ b/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/component-tokens/spec.md
@@ -3,7 +3,7 @@
 ## Purpose
 Introduces component-level NL Design System tokens using the `--nldesign-component-*` prefix, with a temporary bridge file that maps the current `--utrecht-*` component tokens to the nldesign namespace.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: NLDesign Component Token Prefix
 All component-level tokens MUST use the `--nldesign-component-*` prefix for consistency with the rest of the nldesign token system.
diff --git a/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/extended-token-sets/spec.md b/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/extended-token-sets/spec.md
index 724fe6f..a5f0606 100644
--- a/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/extended-token-sets/spec.md
+++ b/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/extended-token-sets/spec.md
@@ -3,7 +3,7 @@
 ## Purpose
 Expands the nldesign app from 5 manually maintained token sets to all available NL Design System organization token sets (48+), using auto-generation from official upstream JSON token files.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Support All Available Token Sets
 The system MUST support all organization token sets available in the `nl-design-system/themes` repository.
diff --git a/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/nextcloud-variable-mapping/spec.md b/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/nextcloud-variable-mapping/spec.md
index 1e5c71c..0d7506b 100644
--- a/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/nextcloud-variable-mapping/spec.md
+++ b/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/nextcloud-variable-mapping/spec.md
@@ -3,7 +3,7 @@
 ## Purpose
 Provides a complete, audited mapping between all Nextcloud CSS custom properties and `--nldesign-*` design tokens, with comprehensive documentation and a defaults layer that ensures all tokens always have a value.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Complete Nextcloud Variable Audit
 The system MUST include a mapping for every CSS custom property defined by Nextcloud's theming system (DefaultTheme.php, CommonThemeTrait.php, and core SCSS files).
diff --git a/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/token-sync-workflow/spec.md b/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/token-sync-workflow/spec.md
index ef90804..59c81d4 100644
--- a/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/token-sync-workflow/spec.md
+++ b/openspec/changes/archive/2026-03-06-full-nextcloud-token-support-from-nldesign/specs/token-sync-workflow/spec.md
@@ -3,7 +3,7 @@
 ## Purpose
 Automates the synchronization of NL Design System token sets from the upstream `nl-design-system/themes` repository via a nightly GitHub Actions workflow that generates CSS token files and opens PRs when changes are detected.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Nightly Schedule
 The sync workflow MUST run automatically every night to check for upstream token changes.
diff --git a/openspec/changes/archive/2026-03-06-sync-theming-on-token-change/specs/theming-sync-dialog/spec.md b/openspec/changes/archive/2026-03-06-sync-theming-on-token-change/specs/theming-sync-dialog/spec.md
index f6e5eb6..dfd165a 100644
--- a/openspec/changes/archive/2026-03-06-sync-theming-on-token-change/specs/theming-sync-dialog/spec.md
+++ b/openspec/changes/archive/2026-03-06-sync-theming-on-token-change/specs/theming-sync-dialog/spec.md
@@ -3,7 +3,7 @@
 ## Purpose
 After an admin selects a different token set in nldesign, offer to automatically update Nextcloud's built-in theming values (primary color, background color, logo, background image) to match the selected token set, preventing a split-brain theming state where CSS tokens and Nextcloud theming are out of sync.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Theming Metadata in Token Sets
 Each token set entry in `token-sets.json` MAY include a `theming` object with optional fields: `primary_color`, `background_color`, `logo`, and `background`.
diff --git a/openspec/changes/archive/2026-03-06-sync-theming-on-token-change/specs/token-set-dropdown/spec.md b/openspec/changes/archive/2026-03-06-sync-theming-on-token-change/specs/token-set-dropdown/spec.md
index 1c06634..b36cd99 100644
--- a/openspec/changes/archive/2026-03-06-sync-theming-on-token-change/specs/token-set-dropdown/spec.md
+++ b/openspec/changes/archive/2026-03-06-sync-theming-on-token-change/specs/token-set-dropdown/spec.md
@@ -3,7 +3,7 @@
 ## Purpose
 Replace the radio button list for token set selection with a searchable dropdown (`<select>`) that scales to 400+ entries, improving usability as the number of available token sets grows.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Dropdown Token Set Selector
 The admin settings page MUST use a `<select>` dropdown instead of radio buttons for token set selection.
diff --git a/openspec/changes/archive/2026-03-21-admin-settings/.openspec.yaml b/openspec/changes/archive/2026-03-21-admin-settings/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-settings/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-admin-settings/design.md b/openspec/changes/archive/2026-03-21-admin-settings/design.md
new file mode 100644
index 0000000..5896e69
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-settings/design.md
@@ -0,0 +1,20 @@
+# Design: admin-settings
+
+## Context
+Admin settings panel in Nextcloud's Theming section. Vanilla PHP template + vanilla JS (no Vue/webpack). Provides token set dropdown, hide slogan toggle, menu labels toggle, live preview, token editor mount point, and theming sync trigger.
+
+## Goals / Non-Goals
+**Goals:** Settings panel registration, template with all parameters, token set dropdown, feature toggles, live preview, XSS prevention
+**Non-Goals:** Vue-based UI, per-user settings, real-time multi-admin sync
+
+## Decisions
+1. Vanilla PHP template with script/style injection via Nextcloud helpers
+2. All endpoints gated with `@AuthorizedAdminSetting`
+3. Data attributes on root div for JS initialization
+4. `p(json_encode(...))` for XSS prevention
+
+## File Changes
+- `lib/Settings/Admin.php` — Panel registration and template response
+- `templates/settings/admin.php` — PHP template with all controls
+- `js/admin.js` — Vanilla JS event handlers
+- `css/admin.css` — Admin panel styling
diff --git a/openspec/changes/archive/2026-03-21-admin-settings/proposal.md b/openspec/changes/archive/2026-03-21-admin-settings/proposal.md
new file mode 100644
index 0000000..3b1f66c
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-settings/proposal.md
@@ -0,0 +1,18 @@
+# Admin Settings Specification
+
+## Problem
+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.
+
+## Proposed Solution
+Implement Admin Settings Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the admin-settings specification.
+
+## Success Criteria
+- Settings panel appears in admin area
+- Settings panel position relative to Nextcloud theming
+- Settings panel is absent when app is disabled
+- Settings panel loads template with all parameters
+- Token sets include design system metadata
diff --git a/openspec/specs/admin-settings/design.md b/openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/design.md
similarity index 100%
rename from openspec/specs/admin-settings/design.md
rename to openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/design.md
diff --git a/openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/spec.md b/openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/spec.md
new file mode 100644
index 0000000..a722233
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/spec.md
@@ -0,0 +1,351 @@
+---
+status: implemented
+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). 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 with a defined priority.
+
+#### Scenario: Settings panel appears in admin area
+- GIVEN the nldesign app is enabled
+- WHEN the admin navigates to Settings -> Administration -> Theming
+- THEN an "NL Design System Theme" section MUST appear
+- AND it MUST have priority 50 (via `Admin::getPriority()`)
+- AND it MUST be in the `theming` section (via `Admin::getSection()`)
+
+#### 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 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-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 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 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)
+
+#### 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 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)
+- AND it MUST show a "Primary Button" styled with the token set's primary colors
+- 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
+
+#### 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 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 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-006: Show Menu Labels Checkbox
+The settings panel MUST include a checkbox to toggle the show menu labels feature.
+
+#### 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
+
+#### Scenario: Checkbox reflects disabled state
+- GIVEN the show menu labels setting is disabled (value `'0'` in IConfig)
+- WHEN the settings panel loads
+- THEN the `#nldesign-show-menu-labels` checkbox MUST NOT be checked
+
+#### 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
+
+#### 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 via `p($l->t())`)
+- AND the link MUST include a `span.icon-link-external` visual indicator
+
+#### 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
+
+#### 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-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
+- GIVEN the settings template at `templates/settings/admin.php`
+- WHEN the template is loaded
+- THEN it MUST use `script('nldesign', 'admin')` to load vanilla JS
+- AND it MUST use `style('nldesign', 'admin')` to load admin-specific CSS
+- 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 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
+
+#### 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
+- GIVEN a non-admin user navigates to the admin settings area
+- 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 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 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`)
+- 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.
+
+### Standards & References
+- NL Design System community: https://nldesignsystem.nl/
+- Nextcloud `ISettings` interface for admin settings registration
+- Nextcloud `TemplateResponse` for server-side rendered PHP templates
+- 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
+- Nextcloud l10n: `IL10N::t()` for translatable strings
diff --git a/openspec/specs/admin-settings/tasks.md b/openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/tasks.md
similarity index 100%
rename from openspec/specs/admin-settings/tasks.md
rename to openspec/changes/archive/2026-03-21-admin-settings/specs/admin-settings/tasks.md
diff --git a/openspec/changes/archive/2026-03-21-admin-settings/tasks.md b/openspec/changes/archive/2026-03-21-admin-settings/tasks.md
new file mode 100644
index 0000000..3040e9a
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-admin-settings/tasks.md
@@ -0,0 +1,24 @@
+# Tasks: admin-settings
+
+## 1. Panel Registration
+- [x] 1.1 Register in theming section with priority 50
+- [x] 1.2 Return TemplateResponse with tokenSets, currentTokenSet, hideSlogan, showMenuLabels
+
+## 2. Template
+- [x] 2.1 Token set dropdown with data-design-system attribute
+- [x] 2.2 Hide slogan checkbox with localized label
+- [x] 2.3 Show menu labels checkbox with localized label
+- [x] 2.4 Live preview box
+- [x] 2.5 Token editor mount point
+- [x] 2.6 External links to nldesign.app and nldesignsystem.nl
+- [x] 2.7 XSS prevention via p(json_encode())
+
+## 3. Unit Tests (ADR-009)
+- [x] 3.1 Test Admin::getSection() returns 'theming'
+- [x] 3.2 Test Admin::getPriority() returns 50
+
+## 4. Documentation (ADR-010)
+- [x] 4.1 Feature documentation at docs/features/admin-settings.md (exists)
+
+## 5. Internationalization (ADR-005)
+- [x] 5.1 All user-visible text uses $l->t() for localization
diff --git a/openspec/changes/archive/2026-03-21-component-tokens/.openspec.yaml b/openspec/changes/archive/2026-03-21-component-tokens/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-component-tokens/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-component-tokens/design.md b/openspec/changes/archive/2026-03-21-component-tokens/design.md
new file mode 100644
index 0000000..03d7e7a
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-component-tokens/design.md
@@ -0,0 +1,9 @@
+# Design: component-tokens
+
+## Context
+Introduces component-level NL Design System tokens using `--nldesign-component-*` prefix, with a temporary bridge file mapping `--utrecht-*` component tokens to the nldesign namespace.
+
+## Decisions
+1. Component tokens use `--nldesign-component-*` prefix
+2. Utrecht bridge is a temporary file clearly marked as such
+3. Bridge falls back to defaults when utrecht tokens are not defined
diff --git a/openspec/changes/archive/2026-03-21-component-tokens/proposal.md b/openspec/changes/archive/2026-03-21-component-tokens/proposal.md
new file mode 100644
index 0000000..3d25af0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-component-tokens/proposal.md
@@ -0,0 +1,21 @@
+# Component Tokens Specification
+
+## Problem
+Introduces component-level NL Design System tokens using the `--nldesign-component-*` prefix, with a temporary bridge file that maps the current `--utrecht-*` component tokens to the nldesign namespace.
+
+## Proposed Solution
+Implement Component Tokens Specification following the detailed specification. Key requirements include:
+- Requirement: NLDesign Component Token Prefix
+- Requirement: Utrecht Bridge File
+- Requirement: Component Token Categories
+- Requirement: Component Token Defaults
+
+## Scope
+This change covers all requirements defined in the component-tokens specification.
+
+## Success Criteria
+- Button component token
+- Heading component token
+- Bridge maps Utrecht tokens to nldesign
+- Bridge falls back to defaults
+- Bridge file is clearly marked as temporary
diff --git a/openspec/changes/archive/2026-03-21-component-tokens/specs/component-tokens/spec.md b/openspec/changes/archive/2026-03-21-component-tokens/specs/component-tokens/spec.md
new file mode 100644
index 0000000..fd2326b
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-component-tokens/specs/component-tokens/spec.md
@@ -0,0 +1,81 @@
+---
+status: implemented
+---
+
+# Component Tokens Specification
+
+## Purpose
+Introduces component-level NL Design System tokens using the `--nldesign-component-*` prefix, with a temporary bridge file that maps the current `--utrecht-*` component tokens to the nldesign namespace.
+
+## Requirements
+
+### Requirement: NLDesign Component Token Prefix
+All component-level tokens MUST use the `--nldesign-component-*` prefix for consistency with the rest of the nldesign token system.
+
+#### Scenario: Button component token
+- GIVEN the NL Design System defines `--utrecht-button-primary-action-background-color`
+- WHEN it is used in the nldesign system
+- THEN it MUST be available as `--nldesign-component-button-primary-action-background-color`
+
+#### Scenario: Heading component token
+- GIVEN the NL Design System defines `--utrecht-heading-1-font-size`
+- WHEN it is used in the nldesign system
+- THEN it MUST be available as `--nldesign-component-heading-1-font-size`
+
+### Requirement: Utrecht Bridge File
+The system MUST include a `utrecht-bridge.css` file that maps `--utrecht-*` component tokens to `--nldesign-component-*` tokens.
+
+#### Scenario: Bridge maps Utrecht tokens to nldesign
+- GIVEN an organization token set defines `--utrecht-button-border-radius: 4px`
+- WHEN the CSS is loaded with the bridge file
+- THEN `--nldesign-component-button-border-radius` MUST resolve to `4px`
+
+#### Scenario: Bridge falls back to defaults
+- GIVEN an organization token set does NOT define `--utrecht-button-border-radius`
+- WHEN the CSS is loaded with the bridge file
+- THEN `--nldesign-component-button-border-radius` MUST fall back to the value from `defaults.css`
+
+#### Scenario: Bridge file is clearly marked as temporary
+- GIVEN a developer opens `utrecht-bridge.css`
+- WHEN they read the file header
+- THEN the header MUST contain a comment explaining that this file is temporary
+- AND it MUST state that the file can be removed when the NL Design System adopts a vendor-neutral prefix
+- AND it MUST reference the NL Design System themes repository
+
+### Requirement: Component Token Categories
+The system MUST support component tokens for the following NL Design System component types.
+
+#### Scenario: Button tokens
+- GIVEN the NL Design System defines button component tokens
+- WHEN the nldesign app processes them
+- THEN it MUST support tokens for: background-color, color, border-radius, border-width, border-color, font-family, font-size, padding, and state variants (hover, active, disabled, focus, primary-action, secondary-action)
+
+#### Scenario: Form input tokens
+- GIVEN the NL Design System defines form input component tokens
+- WHEN the nldesign app processes them
+- THEN it MUST support tokens for: textbox, form-field, form-select, and form-fieldset components
+- AND each MUST support state variants (focus, hover, disabled, invalid)
+
+#### Scenario: Typography tokens
+- GIVEN the NL Design System defines heading and paragraph component tokens
+- WHEN the nldesign app processes them
+- THEN it MUST support tokens for heading levels 1-6 (font-size, font-weight, line-height, color)
+- AND it MUST support paragraph tokens (font-size, line-height, color)
+
+#### Scenario: Additional component tokens
+- GIVEN the NL Design System defines tokens for link, table, badge, separator, ordered-list, and unordered-list
+- WHEN the nldesign app processes them
+- THEN these MUST be available as `--nldesign-component-{component}-*` tokens
+
+### Requirement: Component Token Defaults
+All component tokens MUST have sensible default values in `defaults.css`.
+
+#### Scenario: Component token defaults reference brand tokens
+- GIVEN `defaults.css` defines `--nldesign-component-button-primary-background-color`
+- WHEN no organization token overrides it
+- THEN it MUST default to `var(--nldesign-color-primary)` (referencing the brand token)
+
+#### Scenario: Component token defaults are self-consistent
+- GIVEN `defaults.css` defines all component token defaults
+- WHEN loaded without any organization token file
+- THEN all components MUST render with visually consistent styling using the default brand tokens
diff --git a/openspec/changes/archive/2026-03-21-component-tokens/tasks.md b/openspec/changes/archive/2026-03-21-component-tokens/tasks.md
new file mode 100644
index 0000000..87c8716
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-component-tokens/tasks.md
@@ -0,0 +1,7 @@
+# Tasks: component-tokens
+- [x] 1.1 Define --nldesign-component-* tokens in defaults.css
+- [x] 1.2 Create utrecht-bridge.css mapping --utrecht-* to --nldesign-component-*
+- [x] 1.3 Mark bridge file as temporary with clear comment
+- [x] 2.1 Unit tests — N/A (CSS-only)
+- [x] 3.1 Documentation — covered in css-architecture docs
+- [x] 4.1 i18n — N/A (CSS tokens, no user-facing strings)
diff --git a/openspec/changes/archive/2026-03-21-css-architecture/.openspec.yaml b/openspec/changes/archive/2026-03-21-css-architecture/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-css-architecture/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-css-architecture/design.md b/openspec/changes/archive/2026-03-21-css-architecture/design.md
new file mode 100644
index 0000000..63adf00
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-css-architecture/design.md
@@ -0,0 +1,10 @@
+# Design: css-architecture
+
+## Context
+Layered CSS architecture: design-systems.json declares ordered stylesheet bundles, Application::boot() loads the correct bundle. 7 layers: fonts, defaults, utrecht-bridge, theme, overrides, element-overrides, custom-overrides. Plus conditional CSS (hide-slogan, show-menu-labels).
+
+## Decisions
+1. design-systems.json is the single source of truth for stylesheet bundles
+2. "none" design system loads no stylesheets (stock Nextcloud)
+3. Custom overrides always loaded last
+4. Conditional CSS loaded after custom overrides
diff --git a/openspec/changes/archive/2026-03-21-css-architecture/proposal.md b/openspec/changes/archive/2026-03-21-css-architecture/proposal.md
new file mode 100644
index 0000000..be60d5e
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-css-architecture/proposal.md
@@ -0,0 +1,18 @@
+# CSS Architecture Specification
+
+## Problem
+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.
+
+## Proposed Solution
+Implement CSS Architecture Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the css-architecture specification.
+
+## Success Criteria
+- Standard CSS load order for nldesign design system
+- Stock Nextcloud design system loads no stylesheets
+- Token set CSS loaded after design system stylesheets
+- Custom overrides always loaded last
+- Conditional CSS loading
diff --git a/openspec/specs/css-architecture/design.md b/openspec/changes/archive/2026-03-21-css-architecture/specs/css-architecture/design.md
similarity index 100%
rename from openspec/specs/css-architecture/design.md
rename to openspec/changes/archive/2026-03-21-css-architecture/specs/css-architecture/design.md
diff --git a/openspec/changes/archive/2026-03-21-css-architecture/specs/css-architecture/spec.md b/openspec/changes/archive/2026-03-21-css-architecture/specs/css-architecture/spec.md
new file mode 100644
index 0000000..1816dfe
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-css-architecture/specs/css-architecture/spec.md
@@ -0,0 +1,378 @@
+---
+status: implemented
+reviewed_date: 2026-02-28
+enriched_date: 2026-03-20
+---
+
+# CSS Architecture Specification
+
+## Purpose
+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: 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 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 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 all core and custom-override layers
+- AND if show_menu_labels is also enabled, `show-menu-labels` CSS MUST also be loaded
+
+### 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/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
+
+#### 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 as the foundation for all theming.
+
+#### 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 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 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 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.
+
+#### Scenario: Organization colors applied
+- GIVEN the active token set is `amsterdam`
+- AND `css/tokens/amsterdam.css` defines `--nldesign-color-primary: #004699`
+- WHEN the CSS cascade resolves `--nldesign-color-primary`
+- THEN the resolved value MUST be `#004699` (Amsterdam blue)
+- AND all variables in Layers 4-7 referencing `--nldesign-color-primary` MUST use this value
+
+#### Scenario: Rijkshuisstijl lint tokens
+- GIVEN the active token set is `rijkshuisstijl`
+- AND it defines `--nldesign-color-logo-background: #154273`, `--nldesign-size-lint: 48px`, `--nldesign-size-lint-height: 96px`
+- WHEN the header renders
+- THEN a colored lint/ribbon MUST appear behind the logo
+
+#### Scenario: Non-lint theme (no logo background)
+- GIVEN the active token set does NOT define `--nldesign-color-logo-background`
+- WHEN the header renders
+- 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.
+
+#### Scenario: Utrecht token present in token set
+- GIVEN a token set defines `--utrecht-button-primary-action-background-color: #123456`
+- WHEN Layer 4 processes the bridge mapping
+- THEN `--nldesign-component-button-primary-action-background-color` MUST resolve to `#123456`
+
+#### Scenario: Utrecht token absent (fallback to defaults)
+- GIVEN a token set does NOT define any `--utrecht-*` button tokens
+- WHEN Layer 4 processes the bridge mapping
+- THEN `--nldesign-component-button-primary-action-background-color` MUST fall back to `var(--nldesign-color-primary)` from Layer 2 defaults
+
+#### Scenario: No circular references
+- GIVEN the bridge CSS uses `var()` with fallback values
+- WHEN fallback values are specified
+- THEN fallback values MUST NOT self-reference (e.g. `var(--nldesign-foo, var(--nldesign-foo))` is forbidden)
+- AND fallback values MUST reference either a concrete value or a variable defined in Layer 2
+
+#### Scenario: Component categories bridged
+- 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 and override Nextcloud CSS variables at high specificity.
+
+#### 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
+
+#### Scenario: Header styled from tokens
+- GIVEN Layer 5 is loaded
+- WHEN the `#header` element renders
+- THEN background MUST use `var(--nldesign-color-header-background)`
+- 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 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`)
+- AND the guest-box MUST have a white background with no shadows
+- AND the lint/ribbon pseudo-elements MUST render on the login box
+- AND primary buttons MUST use `--nldesign-component-button-primary-action-*` tokens
+
+#### Scenario: Focus states for accessibility
+- GIVEN any interactive element receives keyboard focus
+- 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 preserving dark mode compatibility.
+
+#### Scenario: Primary color variables mapped
+- 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`
+
+#### Scenario: Main background intentionally NOT overridden
+- GIVEN Layer 6 is loaded
+- WHEN the `:root` rule is processed
+- THEN `--color-main-background` MUST NOT be overridden
+- AND `--color-main-background-rgb` MUST NOT be overridden
+- AND `--color-main-background-translucent` MUST NOT be overridden
+- AND `--color-background-plain` MUST NOT be overridden
+- AND each intentionally-unset variable MUST have a comment explaining why
+
+#### Scenario: Dark mode compatibility preserved
+- GIVEN a user has Nextcloud dark mode enabled
+- WHEN the nldesign overrides are applied
+- THEN `--background-invert-if-dark` MUST NOT be overridden
+- AND `--background-invert-if-bright` MUST NOT be overridden
+- AND the dark mode auto-calculated variables MUST continue to function
+
+#### 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/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
+
+#### 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
+- AND user-status icons MUST be excluded from the filter
+
+#### Scenario: App navigation styled as card
+- GIVEN the app navigation sidebar renders
+- WHEN Layer 7 styles are applied
+- THEN `#app-navigation` MUST use `var(--color-main-background)` as background
+- AND it MUST have a right margin of 30px (card layout effect)
+- AND the closed state (`.app-navigation--close`) MUST have 0 margin
+
+#### 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:**
+- 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.
+
+### 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 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/
diff --git a/openspec/specs/css-architecture/tasks.md b/openspec/changes/archive/2026-03-21-css-architecture/specs/css-architecture/tasks.md
similarity index 100%
rename from openspec/specs/css-architecture/tasks.md
rename to openspec/changes/archive/2026-03-21-css-architecture/specs/css-architecture/tasks.md
diff --git a/openspec/changes/archive/2026-03-21-css-architecture/tasks.md b/openspec/changes/archive/2026-03-21-css-architecture/tasks.md
new file mode 100644
index 0000000..a3c395f
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-css-architecture/tasks.md
@@ -0,0 +1,9 @@
+# Tasks: css-architecture
+- [x] 1.1 DesignSystemService reads design-systems.json with caching
+- [x] 1.2 Application::boot() loads stylesheets in declared order
+- [x] 1.3 Token set CSS loaded after design system stylesheets
+- [x] 1.4 Custom overrides loaded last via CustomOverridesService
+- [x] 1.5 Conditional CSS (hide-slogan, show-menu-labels) loaded after overrides
+- [x] 2.1 Unit tests — N/A (boot-time CSS injection)
+- [x] 3.1 Documentation at docs/features/css-architecture.md (exists)
+- [x] 4.1 i18n — N/A (CSS architecture, no user-facing strings)
diff --git a/openspec/changes/archive/2026-03-21-custom-css-overrides/.openspec.yaml b/openspec/changes/archive/2026-03-21-custom-css-overrides/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-custom-css-overrides/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-custom-css-overrides/design.md b/openspec/changes/archive/2026-03-21-custom-css-overrides/design.md
new file mode 100644
index 0000000..f973eb1
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-custom-css-overrides/design.md
@@ -0,0 +1,10 @@
+# Design: custom-css-overrides
+
+## Context
+CSS file persistence layer for user-defined token customizations. custom-overrides.css is the single write target loaded last in the CSS stack.
+
+## Decisions
+1. Single :root {} block format, one declaration per line
+2. Atomic write via temp file + rename
+3. TokenRegistry validation — only editable tokens accepted
+4. No database storage — filesystem only
diff --git a/openspec/changes/archive/2026-03-21-custom-css-overrides/proposal.md b/openspec/changes/archive/2026-03-21-custom-css-overrides/proposal.md
new file mode 100644
index 0000000..468006f
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-custom-css-overrides/proposal.md
@@ -0,0 +1,23 @@
+# Custom CSS Overrides Specification
+
+## Problem
+Defines the CSS file persistence layer for user-defined token customizations. `custom-overrides.css` is the single write target for all theme editor output. It is loaded last in the CSS stack so user intent always wins. NL Design token set CSS files are read-only presets and are never modified.
+
+
+## Proposed Solution
+Implement Custom CSS Overrides Specification
 following the detailed specification. Key requirements include:
+- Requirement: Custom Overrides File
+- Requirement: CSS Stack Load Order
+- Requirement: File Format
+- Requirement: Read/Write PHP Endpoint
+- Requirement: No Database Storage
+
+## Scope
+This change covers all requirements defined in the custom-css-overrides specification.
+
+## Success Criteria
+- File does not exist on fresh install
+- File exists with custom tokens
+- Custom override wins over NL Design token set
+- Missing file does not break stack
+- File is written by the save endpoint
diff --git a/openspec/changes/archive/2026-03-21-custom-css-overrides/specs/custom-css-overrides/spec.md b/openspec/changes/archive/2026-03-21-custom-css-overrides/specs/custom-css-overrides/spec.md
new file mode 100644
index 0000000..a06b119
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-custom-css-overrides/specs/custom-css-overrides/spec.md
@@ -0,0 +1,108 @@
+---
+status: implemented
+---
+
+# Custom CSS Overrides Specification
+
+## Purpose
+Defines the CSS file persistence layer for user-defined token customizations. `custom-overrides.css` is the single write target for all theme editor output. It is loaded last in the CSS stack so user intent always wins. NL Design token set CSS files are read-only presets and are never modified.
+
+## Requirements
+
+### Requirement: Custom Overrides File
+The system MUST maintain a `custom-overrides.css` file in the nldesign app's CSS directory. This file MUST be written exclusively by the theme editor backend — no other write path exists.
+
+#### Scenario: File does not exist on fresh install
+- GIVEN the nldesign app is freshly installed
+- WHEN Nextcloud loads the theming CSS
+- THEN `custom-overrides.css` MUST NOT be required to exist
+- AND the CSS stack MUST function correctly with the file absent
+
+#### Scenario: File exists with custom tokens
+- GIVEN `custom-overrides.css` contains one or more `--color-*` overrides
+- WHEN the browser loads the CSS stack
+- THEN the overrides MUST apply on top of all other CSS layers
+- AND they MUST take effect without a page reload (only on next load)
+
+### Requirement: CSS Stack Load Order
+`custom-overrides.css` MUST be registered as the final CSS file in the nldesign app's CSS load order, after `element-overrides.css`.
+
+Load order (final):
+```
+fonts.css → defaults.css → tokens/{org}.css → utrecht-bridge.css
+  → theme.css → overrides.css → element-overrides.css → custom-overrides.css
+```
+
+#### Scenario: Custom override wins over NL Design token set
+- GIVEN `tokens/utrecht.css` sets `--nldesign-color-primary: #CC0000`
+- AND `overrides.css` maps `--color-primary: var(--nldesign-color-primary)`
+- AND `custom-overrides.css` sets `--color-primary: #0000FF`
+- WHEN the browser resolves `--color-primary`
+- THEN the resolved value MUST be `#0000FF` (custom override wins)
+
+#### Scenario: Missing file does not break stack
+- GIVEN `custom-overrides.css` does not exist on disk
+- WHEN Nextcloud loads the CSS stack
+- THEN the remaining CSS layers MUST apply normally
+- AND no PHP error or missing-file warning MUST appear in logs
+
+### Requirement: File Format
+`custom-overrides.css` MUST contain only a single `:root` block with `--color-*` custom property declarations. The file MUST NOT contain selectors other than `:root`, media queries, or `!important` declarations — the load-order position ensures precedence without `!important`.
+
+#### Scenario: File is written by the save endpoint
+- GIVEN the admin saves token overrides via the editor
+- WHEN the backend writes `custom-overrides.css`
+- THEN the file MUST match the format:
+  ```css
+  /* NL Design — custom token overrides. Generated by theme editor. Do not edit manually. */
+  :root {
+    --color-primary: #c00000;
+    --color-error: #b30000;
+  }
+  ```
+- AND the file MUST contain only tokens that differ from the resolved default
+- AND each token MUST appear on its own line with a trailing semicolon
+
+#### Scenario: No custom tokens results in empty overrides block
+- GIVEN the admin saves with all tokens reset to default
+- WHEN the backend writes `custom-overrides.css`
+- THEN the file MUST contain only the header comment and an empty `:root {}` block
+- AND the file MUST NOT be deleted (absence vs empty file has different semantics)
+
+### Requirement: Read/Write PHP Endpoint
+The backend MUST expose a PHP service that reads the current `custom-overrides.css` and writes a new version atomically. Direct file manipulation from Vue components MUST NOT be used.
+
+#### Scenario: Read current overrides
+- GIVEN `custom-overrides.css` exists with some overrides
+- WHEN the admin settings panel loads
+- THEN a GET request to `/api/overrides` MUST return the list of currently overridden token names and values as JSON
+- AND the response MUST include only tokens present in `custom-overrides.css` (not defaults or resolved values)
+
+#### Scenario: Write new overrides
+- GIVEN the admin clicks Save with a new set of token values
+- WHEN a POST request is made to `/api/overrides` with the token map
+- THEN the backend MUST validate each token name against the editable token registry
+- AND it MUST write the validated tokens to `custom-overrides.css` atomically (write to temp file, rename)
+- AND it MUST return HTTP 200 with the final set of written tokens
+
+#### Scenario: Write fails due to filesystem permissions
+- GIVEN the CSS directory is not writable by the web server process
+- WHEN the save endpoint is called
+- THEN the server MUST return HTTP 500
+- AND the error response MUST include a message indicating the file could not be written
+- AND the existing `custom-overrides.css` MUST remain unchanged
+
+### Requirement: No Database Storage
+Token overrides MUST NOT be stored in Nextcloud's `appconfig` table or any database table. The CSS file is the sole persistence mechanism.
+
+#### Scenario: Token overrides survive app reinstall if CSS directory is preserved
+- GIVEN `custom-overrides.css` exists in the app's CSS directory
+- WHEN the nldesign app is disabled and re-enabled
+- THEN `custom-overrides.css` MUST still apply after re-enable
+- AND no database query MUST be required to restore custom tokens
+
+#### Scenario: Resetting to defaults requires only file deletion
+- GIVEN an admin wants to remove all custom overrides
+- WHEN they delete `custom-overrides.css` (or use a "Reset all" action that empties it)
+- THEN the CSS stack MUST revert entirely to the NL Design token set and Nextcloud defaults
+- AND no database record needs to be cleared
diff --git a/openspec/changes/archive/2026-03-21-custom-css-overrides/tasks.md b/openspec/changes/archive/2026-03-21-custom-css-overrides/tasks.md
new file mode 100644
index 0000000..ea212cb
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-custom-css-overrides/tasks.md
@@ -0,0 +1,8 @@
+# Tasks: custom-css-overrides
+- [x] 1.1 CustomOverridesService with read/write/ensureExists methods
+- [x] 1.2 Atomic write via temp file + rename
+- [x] 1.3 TokenRegistry validation on write
+- [x] 1.4 Parse :root {} declarations on read
+- [x] 2.1 Unit tests — N/A (service tested via integration)
+- [x] 3.1 Documentation at docs/features/import-export.md (exists)
+- [x] 4.1 i18n — N/A (CSS file operations)
diff --git a/openspec/changes/archive/2026-03-21-docs-content/.openspec.yaml b/openspec/changes/archive/2026-03-21-docs-content/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-docs-content/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-docs-content/design.md b/openspec/changes/archive/2026-03-21-docs-content/design.md
new file mode 100644
index 0000000..c0e1765
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-docs-content/design.md
@@ -0,0 +1,9 @@
+# Design: docs-content
+
+## Context
+Documentation website using Docusaurus, providing getting started guide, features overview, reference section, and integration guide for app developers.
+
+## Decisions
+1. Docusaurus static site generator
+2. Sidebar navigation with category files
+3. i18n support for Dutch and English
diff --git a/openspec/changes/archive/2026-03-21-docs-content/proposal.md b/openspec/changes/archive/2026-03-21-docs-content/proposal.md
new file mode 100644
index 0000000..7e7bb09
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-docs-content/proposal.md
@@ -0,0 +1,22 @@
+# docs-content
+
+## Problem
+Implement docs-content functionality as specified.
+
+## Proposed Solution
+Implement docs-content following the detailed specification. Key requirements include:
+- Requirement: Documentation landing page
+- Requirement: Getting started guide
+- Requirement: Features overview section
+- Requirement: Reference section with existing docs
+- Requirement: Integration guide for app developers
+
+## Scope
+This change covers all requirements defined in the docs-content specification.
+
+## Success Criteria
+- Visitor opens documentation
+- New administrator follows getting started guide
+- Getting started sidebar ordering
+- Visitor browses features
+- Token sets showcase page
diff --git a/openspec/changes/archive/2026-03-21-docs-content/specs/docs-content/spec.md b/openspec/changes/archive/2026-03-21-docs-content/specs/docs-content/spec.md
new file mode 100644
index 0000000..7132aeb
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-docs-content/specs/docs-content/spec.md
@@ -0,0 +1,108 @@
+---
+status: implemented
+---
+
+## Requirements
+
+### Requirement: Documentation landing page
+The documentation site SHALL have an `intro.md` file at `docs/intro.md` that serves as the entry point for all documentation. It SHALL provide a high-level overview of what nldesign is, link to key sections (getting started, features, reference), and use the Docusaurus `slug: /` frontmatter to become the docs root.
+
+#### Scenario: Visitor opens documentation
+- **WHEN** a visitor navigates to `/docs/` on the documentation site
+- **THEN** they see the intro page with a description of nldesign, its purpose, and navigation links to getting started, features, and reference sections
+
+### Requirement: Getting started guide
+The documentation SHALL include a `docs/getting-started/` directory containing an installation and configuration guide. The guide SHALL cover: installing the app from the Nextcloud App Store, selecting a token set via admin settings, and verifying the theme is applied.
+
+#### Scenario: New administrator follows getting started guide
+- **WHEN** an administrator reads the getting started guide
+- **THEN** they find step-by-step instructions for installing nldesign, navigating to admin settings, selecting a token set, and confirming the theme is active
+
+#### Scenario: Getting started sidebar ordering
+- **WHEN** the documentation site sidebar renders
+- **THEN** the "Getting Started" section appears as the first section after the intro page (sidebar_position: 1)
+
+### Requirement: Features overview section
+The documentation SHALL include a `docs/features/` directory with pages covering: token sets overview, 7-layer CSS architecture, theming sync, admin settings panel, optional toggles (hide slogan, menu labels), and icon library.
+
+#### Scenario: Visitor browses features
+- **WHEN** a visitor expands the "Features" section in the sidebar
+- **THEN** they see individual pages for token sets, CSS architecture, theming sync, admin settings, toggles, and icons
+
+#### Scenario: Token sets showcase page
+- **WHEN** a visitor opens the token sets feature page
+- **THEN** they see a listing of all 39 available token sets with organization name, primary color, and description
+
+### Requirement: Reference section with existing docs
+The documentation SHALL include a `docs/reference/` directory containing the existing technical documentation: tokens.md, mappings.md, compliance.md, token-audit.md, assets.md, and brand-identity.md. Each file SHALL retain its existing content and have `sidebar_position` frontmatter for ordering.
+
+#### Scenario: Existing doc content preserved
+- **WHEN** a visitor navigates to a reference page (e.g., token mappings)
+- **THEN** they see the same content that was previously at the root of the docs folder
+
+#### Scenario: Reference sidebar ordering
+- **WHEN** the documentation site sidebar renders
+- **THEN** the "Reference" section appears after "Features" (sidebar_position: 3)
+
+### Requirement: Integration guide for app developers
+The documentation SHALL include a page explaining how Nextcloud app developers can ensure their apps are compatible with nldesign. It SHALL cover: using standard Nextcloud CSS variables, avoiding hardcoded colors, testing with nldesign enabled, and using the `--nldesign-*` token namespace.
+
+#### Scenario: App developer reads integration guide
+- **WHEN** a Nextcloud app developer reads the integration guide
+- **THEN** they find concrete guidance on CSS variable usage, color avoidance patterns, and testing procedures to ensure nldesign compatibility
+
+### Requirement: Enhanced homepage feature cards
+The homepage SHALL display feature cards that describe nldesign's key capabilities: token sets, CSS architecture, government compliance, easy configuration, app compatibility, and open source nature. Each card SHALL have a title and a brief description.
+
+#### Scenario: Visitor lands on homepage
+- **WHEN** a visitor opens the documentation site root URL
+- **THEN** they see a hero section with the app name and tagline, plus 6 feature cards summarizing nldesign's capabilities
+
+#### Scenario: Homepage documentation link
+- **WHEN** a visitor clicks the "Documentation" button on the homepage
+- **THEN** they are navigated to the docs intro page (`/docs/intro`), not to the tokens reference page
+
+### Requirement: Documentation builds without errors
+The Docusaurus build SHALL complete without errors after all documentation changes. All internal links between pages SHALL resolve correctly. The auto-generated sidebar SHALL reflect the new directory structure.
+
+#### Scenario: Clean build after reorganization
+- **WHEN** `npm run build` is executed in the `docusaurus/` directory
+- **THEN** the build completes successfully with no broken link errors
+
+#### Scenario: Sidebar reflects directory structure
+- **WHEN** the built site is served
+- **THEN** the sidebar shows sections for Getting Started, Features, and Reference as collapsible groups
+
+### Current Implementation Status
+
+**Fully implemented:**
+- `docs/intro.md` exists as the documentation entry point
+- `docs/getting-started/` directory exists with `installation.md` and `configuration.md`
+- `docs/features/` directory exists with pages: `token-sets.md`, `css-architecture.md`, `theming-sync.md`, `admin-settings.md`, `toggles.md`, `app-compatibility.md`
+- `docs/reference/` directory exists with: `tokens.md`, `mappings.md`, `compliance.md`, `token-audit.md`, `assets.md`, `brand-identity.md`, `development.md`, `icons.md`
+- Docusaurus infrastructure at `docusaurus/` with `docusaurus.config.js`, `sidebars.js`, `package.json`
+- Homepage with feature cards in `docusaurus/src/pages/index.js` and `docusaurus/src/components/HomepageFeatures/`
+- Docusaurus `build/` directory exists (site has been built at least once)
+
+**Additional content beyond spec (implemented):**
+- `docs/GOVERNMENT-FEATURES.md` -- additional document not mentioned in spec
+- `docs/reference/development.md` and `docs/reference/icons.md` -- additional reference pages
+- `docs/features/app-compatibility.md` -- app compatibility page
+
+**Not yet implemented:**
+- All core requirements appear to be implemented. The integration guide for app developers may be partially covered by `docs/features/app-compatibility.md`.
+
+**Note:** The `docs/` directory lives at `nldesign/docs/` (not inside `docusaurus/`). Docusaurus is configured to read from the parent `docs/` folder.
+
+### Standards & References
+- Docusaurus documentation framework: https://docusaurus.io/
+- NL Design System community: https://nldesignsystem.nl/
+- Rijkshuisstijl brand guidelines: https://www.rijkshuisstijl.nl/
+- WCAG AA accessibility compliance for documentation sites
+
+### Specificity Assessment
+- This spec is reasonably specific for documentation content requirements. It defines directory structure, page topics, sidebar ordering, and build requirements.
+- The spec does not prescribe exact `sidebar_position` values for each page -- it references them conceptually.
+- The spec mentions "39 available token sets" on the token sets showcase page -- this should stay in sync with the actual count (currently 39 CSS files in `css/tokens/`).
+- The integration guide requirement is vague: "concrete guidance on CSS variable usage, color avoidance patterns, and testing procedures" -- could be more specific.
+- Open question: Should `docs/GOVERNMENT-FEATURES.md` be incorporated into the structured docs hierarchy or removed?
diff --git a/openspec/changes/archive/2026-03-21-docs-content/tasks.md b/openspec/changes/archive/2026-03-21-docs-content/tasks.md
new file mode 100644
index 0000000..ecb2485
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-docs-content/tasks.md
@@ -0,0 +1,8 @@
+# Tasks: docs-content
+- [x] 1.1 Documentation landing page (docs/index.md)
+- [x] 1.2 Getting started guide (docs/getting-started/)
+- [x] 1.3 Features overview section (docs/features/)
+- [x] 1.4 Reference section (docs/reference/)
+- [x] 2.1 Unit tests — N/A (documentation)
+- [x] 3.1 All docs content created
+- [x] 4.1 i18n — docs/i18n/ with nl translations
diff --git a/openspec/changes/archive/2026-03-21-extended-token-sets/.openspec.yaml b/openspec/changes/archive/2026-03-21-extended-token-sets/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-extended-token-sets/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-extended-token-sets/design.md b/openspec/changes/archive/2026-03-21-extended-token-sets/design.md
new file mode 100644
index 0000000..f418c3f
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-extended-token-sets/design.md
@@ -0,0 +1,9 @@
+# Design: extended-token-sets
+
+## Context
+Expands from 5 manually maintained token sets to 40+ auto-generated from upstream NL Design System JSON token files.
+
+## Decisions
+1. CSS files auto-generated from upstream JSON
+2. token-sets.json manifest for metadata
+3. Dynamic discovery via filesystem scan
diff --git a/openspec/changes/archive/2026-03-21-extended-token-sets/proposal.md b/openspec/changes/archive/2026-03-21-extended-token-sets/proposal.md
new file mode 100644
index 0000000..aa2d5d7
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-extended-token-sets/proposal.md
@@ -0,0 +1,22 @@
+# Extended Token Sets Specification
+
+## Problem
+Expands the nldesign app from 5 manually maintained token sets to all available NL Design System organization token sets (48+), using auto-generation from official upstream JSON token files.
+
+## Proposed Solution
+Implement Extended Token Sets Specification following the detailed specification. Key requirements include:
+- Requirement: Support All Available Token Sets
+- Requirement: Auto-Generated Token CSS Files
+- Requirement: Token Set Manifest
+- Requirement: Dynamic Token Set Discovery
+- Requirement: Admin Settings Dynamic Dropdown
+
+## Scope
+This change covers all requirements defined in the extended-token-sets specification.
+
+## Success Criteria
+- Organization with complete token set
+- Organization with incomplete token set
+- New organization added upstream
+- Token generation from JSON
+- Token naming conversion
diff --git a/openspec/changes/archive/2026-03-21-extended-token-sets/specs/extended-token-sets/spec.md b/openspec/changes/archive/2026-03-21-extended-token-sets/specs/extended-token-sets/spec.md
new file mode 100644
index 0000000..08b066c
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-extended-token-sets/specs/extended-token-sets/spec.md
@@ -0,0 +1,87 @@
+---
+status: implemented
+---
+
+# Extended Token Sets Specification
+
+## Purpose
+Expands the nldesign app from 5 manually maintained token sets to all available NL Design System organization token sets (48+), using auto-generation from official upstream JSON token files.
+
+## Requirements
+
+### Requirement: Support All Available Token Sets
+The system MUST support all organization token sets available in the `nl-design-system/themes` repository.
+
+#### Scenario: Organization with complete token set
+- GIVEN an organization (e.g., Groningen) has a complete token set in the themes repository
+- WHEN an admin selects "Groningen" in the nldesign settings
+- THEN the Nextcloud instance MUST render with Groningen's brand colors, typography, and border radius
+
+#### Scenario: Organization with incomplete token set
+- GIVEN an organization (e.g., Epe) has a partial token set that only defines primary colors
+- WHEN an admin selects "Epe" in the nldesign settings
+- THEN the defined tokens (primary colors) MUST use Epe's values
+- AND undefined tokens MUST fall back to the defaults from `defaults.css`
+
+#### Scenario: New organization added upstream
+- GIVEN a new municipality adds their token set to the `nl-design-system/themes` repository
+- WHEN the nightly sync workflow runs
+- THEN a new CSS token file MUST be generated for that organization
+- AND the `token-sets.json` manifest MUST be updated to include the new organization
+
+### Requirement: Auto-Generated Token CSS Files
+Token CSS files MUST be auto-generated from the official JSON token files in the `nl-design-system/themes` repository, not manually curated.
+
+#### Scenario: Token generation from JSON
+- GIVEN the themes repository contains `proprietary/groningen-design-tokens/src/*.tokens.json`
+- WHEN the generation script runs
+- THEN it MUST produce `css/tokens/groningen.css`
+- AND the CSS file MUST contain `:root` declarations with `--nldesign-*` prefixed variables
+
+#### Scenario: Token naming conversion
+- GIVEN a JSON token like `{ "groningen": { "color": { "primary": { "value": "#2e7d32" } } } }`
+- WHEN the generation script converts it to CSS
+- THEN the output MUST be `--nldesign-color-primary: #2e7d32;`
+
+#### Scenario: Organization-specific palette preservation
+- GIVEN an organization defines additional palette colors (e.g., `groningen.color.green.50`)
+- WHEN the generation script runs
+- THEN organization-specific palette values MUST be preserved as `--{org}-color-green-50`
+- AND standard mappable tokens MUST be converted to `--nldesign-*` prefix
+
+### Requirement: Token Set Manifest
+The system MUST maintain a `token-sets.json` manifest file that maps token set IDs to display names and descriptions.
+
+#### Scenario: Admin views token set dropdown
+- GIVEN the admin opens the nldesign settings page
+- WHEN the token set dropdown is rendered
+- THEN each option MUST show the organization's display name and description from `token-sets.json`
+
+#### Scenario: Manifest is auto-updated
+- GIVEN the generation script discovers a new organization
+- WHEN it generates the CSS token file
+- THEN it MUST also add an entry to `token-sets.json` with the organization name and description
+
+### Requirement: Dynamic Token Set Discovery
+The system MUST dynamically discover available token sets from the filesystem instead of using a hardcoded list.
+
+#### Scenario: Token set validation
+- GIVEN an admin submits a `setTokenSet` API request with `tokenSet=groningen`
+- WHEN the controller validates the request
+- THEN it MUST check that `css/tokens/groningen.css` exists on disk
+- AND it MUST NOT use a hardcoded array of valid set names
+
+#### Scenario: Available token sets API
+- GIVEN a client requests the list of available token sets
+- WHEN `GET /apps/nldesign/settings/available-tokensets` is called
+- THEN the response MUST include all token sets that have a CSS file in `css/tokens/`
+- AND each entry MUST include `id`, `name`, and `description` from the manifest
+
+### Requirement: Admin Settings Dynamic Dropdown
+The admin settings page MUST display all available token sets dynamically, not a hardcoded list.
+
+#### Scenario: Settings page shows all token sets
+- GIVEN 48 token set CSS files exist in `css/tokens/`
+- WHEN the admin opens the nldesign settings
+- THEN the dropdown MUST list all 48 organizations with their display names
+- AND the currently selected token set MUST be highlighted
diff --git a/openspec/changes/archive/2026-03-21-extended-token-sets/tasks.md b/openspec/changes/archive/2026-03-21-extended-token-sets/tasks.md
new file mode 100644
index 0000000..cd693bf
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-extended-token-sets/tasks.md
@@ -0,0 +1,8 @@
+# Tasks: extended-token-sets
+- [x] 1.1 Support 40+ token sets via CSS files in css/tokens/
+- [x] 1.2 Token set manifest in token-sets.json
+- [x] 1.3 Dynamic discovery in TokenSetService
+- [x] 1.4 Admin dropdown dynamically populated
+- [x] 2.1 Unit tests — N/A (filesystem discovery)
+- [x] 3.1 Documentation — covered in token-sets docs
+- [x] 4.1 i18n — token set names from manifest
diff --git a/openspec/changes/archive/2026-03-21-hide-slogan/.openspec.yaml b/openspec/changes/archive/2026-03-21-hide-slogan/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-hide-slogan/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-hide-slogan/design.md b/openspec/changes/archive/2026-03-21-hide-slogan/design.md
new file mode 100644
index 0000000..a076a26
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-hide-slogan/design.md
@@ -0,0 +1,9 @@
+# Design: hide-slogan
+
+## Context
+Removes Nextcloud slogan from login page via conditionally loaded CSS. Dutch government organizations need clean branded login pages.
+
+## Decisions
+1. Boolean app config key 'hide_slogan' stored as '0'/'1'
+2. CSS uses display:none + visibility:hidden on footer.guest-box
+3. Loaded only when setting is enabled
diff --git a/openspec/changes/archive/2026-03-21-hide-slogan/proposal.md b/openspec/changes/archive/2026-03-21-hide-slogan/proposal.md
new file mode 100644
index 0000000..a20e53e
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-hide-slogan/proposal.md
@@ -0,0 +1,18 @@
+# Hide Slogan Specification
+
+## Problem
+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.
+
+## Proposed Solution
+Implement Hide Slogan Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the hide-slogan specification.
+
+## Success Criteria
+- Setting stored as enabled
+- Setting stored as disabled
+- Default value when not configured
+- Setting persists across app restarts
+- Feature enabled loads CSS
diff --git a/openspec/specs/hide-slogan/design.md b/openspec/changes/archive/2026-03-21-hide-slogan/specs/hide-slogan/design.md
similarity index 100%
rename from openspec/specs/hide-slogan/design.md
rename to openspec/changes/archive/2026-03-21-hide-slogan/specs/hide-slogan/design.md
diff --git a/openspec/changes/archive/2026-03-21-hide-slogan/specs/hide-slogan/spec.md b/openspec/changes/archive/2026-03-21-hide-slogan/specs/hide-slogan/spec.md
new file mode 100644
index 0000000..623625a
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-hide-slogan/specs/hide-slogan/spec.md
@@ -0,0 +1,259 @@
+---
+status: implemented
+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 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 with clear on/off semantics.
+
+#### Scenario: Setting stored as enabled
+- GIVEN the admin enables the hide slogan feature
+- WHEN `POST /apps/nldesign/settings/slogan` is called with `hideSlogan=true`
+- THEN `IConfig::setAppValue('nldesign', 'hide_slogan', '1')` MUST be called
+- AND the response MUST be JSON with `{"status": "ok", "hideSlogan": true}`
+
+#### Scenario: Setting stored as disabled
+- GIVEN the admin disables the hide slogan feature
+- WHEN `POST /apps/nldesign/settings/slogan` is called with `hideSlogan=false`
+- THEN `IConfig::setAppValue('nldesign', 'hide_slogan', '0')` MUST be called
+- AND the response MUST be JSON with `{"status": "ok", "hideSlogan": false}`
+
+#### Scenario: Default value when not configured
+- GIVEN no value has been set for `nldesign:hide_slogan`
+- WHEN the setting is read during boot
+- 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, 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 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 from both visual display and the accessibility tree.
+
+#### Scenario: Footer element hidden with display none
+- GIVEN the hide-slogan CSS is loaded
+- WHEN the login page renders
+- THEN `footer.guest-box` MUST have `display: none !important`
+- AND `visibility: hidden !important`
+
+#### 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` (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 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
+- AND the user is on a non-login page (e.g. Files app)
+- WHEN the page renders
+- 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, 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 `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 `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 (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.
+
+#### Scenario: Toggle slogan hiding on
+- GIVEN the admin is authenticated
+- WHEN `POST /apps/nldesign/settings/slogan` is called with `hideSlogan=true`
+- THEN the setting MUST be stored as `'1'` in IConfig
+- AND the response MUST confirm success with `{"status": "ok", "hideSlogan": true}`
+
+#### Scenario: Toggle slogan hiding off
+- GIVEN the admin is authenticated
+- WHEN `POST /apps/nldesign/settings/slogan` is called with `hideSlogan=false`
+- THEN the setting MUST be stored as `'0'` in IConfig
+- AND the response MUST confirm success with `{"status": "ok", "hideSlogan": false}`
+
+#### Scenario: Non-admin access denied
+- 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 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 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 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` 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 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 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
+- OWASP: admin-only endpoint protects against unauthorized setting changes
diff --git a/openspec/specs/hide-slogan/tasks.md b/openspec/changes/archive/2026-03-21-hide-slogan/specs/hide-slogan/tasks.md
similarity index 100%
rename from openspec/specs/hide-slogan/tasks.md
rename to openspec/changes/archive/2026-03-21-hide-slogan/specs/hide-slogan/tasks.md
diff --git a/openspec/changes/archive/2026-03-21-hide-slogan/tasks.md b/openspec/changes/archive/2026-03-21-hide-slogan/tasks.md
new file mode 100644
index 0000000..1ece988
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-hide-slogan/tasks.md
@@ -0,0 +1,9 @@
+# Tasks: hide-slogan
+- [x] 1.1 Config storage with '0' default
+- [x] 1.2 API endpoint POST /settings/slogan
+- [x] 1.3 Conditional CSS loading in Application::boot()
+- [x] 1.4 CSS file targeting footer.guest-box
+- [x] 1.5 Admin checkbox in settings template
+- [x] 2.1 Unit tests — N/A (config + CSS toggle)
+- [x] 3.1 Documentation at docs/features/toggles.md (exists)
+- [x] 4.1 i18n — checkbox label uses $l->t()
diff --git a/openspec/changes/archive/2026-03-21-menu-labels/.openspec.yaml b/openspec/changes/archive/2026-03-21-menu-labels/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-menu-labels/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-menu-labels/design.md b/openspec/changes/archive/2026-03-21-menu-labels/design.md
new file mode 100644
index 0000000..3977235
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-menu-labels/design.md
@@ -0,0 +1,9 @@
+# Design: menu-labels
+
+## Context
+Replaces app menu icons with text labels for improved accessibility and discoverability per Dutch government UX guidelines.
+
+## Decisions
+1. Boolean app config key 'show_menu_labels' stored as '0'/'1'
+2. CSS hides icons and shows labels with proper typography
+3. Active indicator removed to prevent visual conflicts
diff --git a/openspec/changes/archive/2026-03-21-menu-labels/proposal.md b/openspec/changes/archive/2026-03-21-menu-labels/proposal.md
new file mode 100644
index 0000000..cda2e10
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-menu-labels/proposal.md
@@ -0,0 +1,18 @@
+# Show Menu Labels Specification
+
+## Problem
+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.
+
+## Proposed Solution
+Implement Show Menu Labels Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the menu-labels specification.
+
+## Success Criteria
+- Setting stored as enabled
+- Setting stored as disabled
+- Default value when not configured
+- Setting persists across restarts
+- Feature enabled loads CSS
diff --git a/openspec/specs/menu-labels/design.md b/openspec/changes/archive/2026-03-21-menu-labels/specs/menu-labels/design.md
similarity index 100%
rename from openspec/specs/menu-labels/design.md
rename to openspec/changes/archive/2026-03-21-menu-labels/specs/menu-labels/design.md
diff --git a/openspec/changes/archive/2026-03-21-menu-labels/specs/menu-labels/spec.md b/openspec/changes/archive/2026-03-21-menu-labels/specs/menu-labels/spec.md
new file mode 100644
index 0000000..f5704ff
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-menu-labels/specs/menu-labels/spec.md
@@ -0,0 +1,304 @@
+---
+status: implemented
+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. 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 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 `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
+- GIVEN the admin disables the show menu labels feature
+- WHEN `POST /apps/nldesign/settings/menulabels` is called with `showMenuLabels=false`
+- THEN `IConfig::setAppValue('nldesign', 'show_menu_labels', '0')` MUST be called
+- AND the response MUST be JSON with `{"status": "ok", "showMenuLabels": false}`
+
+#### Scenario: Default value when not configured
+- 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 (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.
+
+#### Scenario: Feature enabled loads CSS
+- 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 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 from both visual display and layout.
+
+#### Scenario: App menu icons hidden
+- GIVEN the show-menu-labels CSS is loaded
+- WHEN the header navigation renders
+- THEN `#header nav.app-menu .app-menu-icon` MUST have `display: none !important`
+- AND `#header nav.app-menu .app-menu-entry__icon` MUST have `display: none !important`
+- AND both selectors MUST also have `visibility: hidden !important`
+
+#### 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
+- WHEN the header navigation renders
+- THEN `#header nav.app-menu .app-menu-entry__label` MUST have `display: inline-block !important`
+- AND `visibility: visible !important`
+- AND `opacity: 1 !important`
+
+#### Scenario: Label typography
+- GIVEN labels are visible
+- WHEN the styling is applied
+- THEN font-size MUST be `14px`
+- 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 overrides Nextcloud defaults
+- GIVEN labels are visible
+- WHEN the styling is applied
+- 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`
+
+#### 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 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 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 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 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
+- AND an app menu entry has the `app-menu-entry--active` class
+- 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.
+
+#### Scenario: Toggle menu labels on
+- 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 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 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 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`, `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 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 (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`
+- Rijkshuisstijl: Dutch government guidelines favor explicit, readable navigation over icon-based shortcuts
diff --git a/openspec/specs/menu-labels/tasks.md b/openspec/changes/archive/2026-03-21-menu-labels/specs/menu-labels/tasks.md
similarity index 100%
rename from openspec/specs/menu-labels/tasks.md
rename to openspec/changes/archive/2026-03-21-menu-labels/specs/menu-labels/tasks.md
diff --git a/openspec/changes/archive/2026-03-21-menu-labels/tasks.md b/openspec/changes/archive/2026-03-21-menu-labels/tasks.md
new file mode 100644
index 0000000..ce2dbf6
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-menu-labels/tasks.md
@@ -0,0 +1,9 @@
+# Tasks: menu-labels
+- [x] 1.1 Config storage with '0' default
+- [x] 1.2 API endpoint POST /settings/menulabels
+- [x] 1.3 Conditional CSS loading in Application::boot()
+- [x] 1.4 CSS file with icon hiding + label styling
+- [x] 1.5 Admin checkbox in settings template
+- [x] 2.1 Unit tests — N/A (config + CSS toggle)
+- [x] 3.1 Documentation at docs/features/toggles.md (exists)
+- [x] 4.1 i18n — checkbox label uses $l->t()
diff --git a/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/.openspec.yaml b/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/design.md b/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/design.md
new file mode 100644
index 0000000..f50648b
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/design.md
@@ -0,0 +1,9 @@
+# Design: nextcloud-variable-mapping
+
+## Context
+Complete mapping between Nextcloud CSS custom properties and --nldesign-* design tokens with defaults layer.
+
+## Decisions
+1. Overrides CSS maps --color-* to --nldesign-* tokens
+2. Defaults layer ensures all tokens have values
+3. Intentionally unoverridden tokens documented
diff --git a/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/proposal.md b/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/proposal.md
new file mode 100644
index 0000000..2bcdf0c
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/proposal.md
@@ -0,0 +1,22 @@
+# Nextcloud Variable Mapping Specification
+
+## Problem
+Provides a complete, audited mapping between all Nextcloud CSS custom properties and `--nldesign-*` design tokens, with comprehensive documentation and a defaults layer that ensures all tokens always have a value.
+
+## Proposed Solution
+Implement Nextcloud Variable Mapping Specification following the detailed specification. Key requirements include:
+- Requirement: Complete Nextcloud Variable Audit
+- Requirement: Overrides CSS Structure
+- Requirement: Defaults CSS Layer
+- Requirement: Mappings Documentation
+- Requirement: CSS Load Order
+
+## Scope
+This change covers all requirements defined in the nextcloud-variable-mapping specification.
+
+## Success Criteria
+- All Nextcloud variables are accounted for
+- New Nextcloud variable is added upstream
+- Mapped variable
+- Unmapped variable
+- Intentionally unoverridden variable
diff --git a/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/specs/nextcloud-variable-mapping/spec.md b/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/specs/nextcloud-variable-mapping/spec.md
new file mode 100644
index 0000000..265abb2
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/specs/nextcloud-variable-mapping/spec.md
@@ -0,0 +1,87 @@
+---
+status: implemented
+---
+
+# Nextcloud Variable Mapping Specification
+
+## Purpose
+Provides a complete, audited mapping between all Nextcloud CSS custom properties and `--nldesign-*` design tokens, with comprehensive documentation and a defaults layer that ensures all tokens always have a value.
+
+## Requirements
+
+### Requirement: Complete Nextcloud Variable Audit
+The system MUST include a mapping for every CSS custom property defined by Nextcloud's theming system (DefaultTheme.php, CommonThemeTrait.php, and core SCSS files).
+
+#### Scenario: All Nextcloud variables are accounted for
+- GIVEN the Nextcloud server defines CSS custom properties in its theming system
+- WHEN the nldesign app is installed
+- THEN the `overrides.css` file MUST contain an entry for every Nextcloud CSS variable
+- AND each entry MUST either map to a `--nldesign-*` token or be commented out with a reason
+
+#### Scenario: New Nextcloud variable is added upstream
+- GIVEN Nextcloud adds a new CSS custom property in a future release
+- WHEN the nldesign maintainers review the change
+- THEN the `mappings.md` documentation MUST be updated to include the new variable
+- AND the `overrides.css` MUST be updated with a mapping or commented entry
+
+### Requirement: Overrides CSS Structure
+The `overrides.css` file MUST contain ALL Nextcloud CSS variables organized by category, with each variable either mapped to a `--nldesign-*` token or commented out with an explanation.
+
+#### Scenario: Mapped variable
+- GIVEN a Nextcloud CSS variable that has an appropriate NL Design equivalent
+- WHEN the `overrides.css` is loaded
+- THEN the variable MUST be overridden using `var(--nldesign-*)` syntax with `!important`
+
+#### Scenario: Unmapped variable
+- GIVEN a Nextcloud CSS variable that has no appropriate NL Design equivalent
+- WHEN the `overrides.css` is loaded
+- THEN the variable MUST be present as a CSS comment
+- AND the comment MUST explain why no mapping exists
+
+#### Scenario: Intentionally unoverridden variable
+- GIVEN a Nextcloud CSS variable that is intentionally left to Nextcloud's control (e.g., `--color-main-background`)
+- WHEN the `overrides.css` is loaded
+- THEN the variable MUST be present as a CSS comment
+- AND the comment MUST state "intentionally not overridden" with the reason
+
+### Requirement: Defaults CSS Layer
+The system MUST include a `defaults.css` file that defines sensible default values for ALL `--nldesign-*` tokens.
+
+#### Scenario: Token has no organization-specific override
+- GIVEN an organization token set that does not define `--nldesign-color-favorite`
+- WHEN the CSS is loaded in order (defaults → tokens → theme → overrides)
+- THEN `--nldesign-color-favorite` MUST have the default value from `defaults.css`
+
+#### Scenario: Token is overridden by organization
+- GIVEN an organization token set that defines `--nldesign-color-primary: #ec0000`
+- WHEN the CSS is loaded in order
+- THEN `--nldesign-color-primary` MUST have the value `#ec0000` (from the token set, overriding the default)
+
+#### Scenario: New nldesign token is added
+- GIVEN a developer adds a new `--nldesign-*` token
+- WHEN they update the system
+- THEN the new token MUST be added to `defaults.css` with a default value
+- AND existing organization token sets MUST continue to work without modification
+
+### Requirement: Mappings Documentation
+The system MUST include a `mappings.md` file documenting the complete relationship between Nextcloud variables and NL Design tokens.
+
+#### Scenario: Developer looks up a Nextcloud variable
+- GIVEN a developer wants to know which NL Design token maps to `--color-primary-element`
+- WHEN they open `mappings.md`
+- THEN they MUST find a table row with the Nextcloud variable name, its `--nldesign-*` mapping, the category, and any notes
+
+#### Scenario: Unmapped variable in documentation
+- GIVEN a Nextcloud variable has no NL Design mapping
+- WHEN the developer looks it up in `mappings.md`
+- THEN the table row MUST show "unmapped" in the mapping column
+- AND the notes column MUST explain why
+
+### Requirement: CSS Load Order
+The nldesign app MUST load CSS files in the following order to ensure correct cascading.
+
+#### Scenario: CSS files load in correct order
+- GIVEN the nldesign app is enabled
+- WHEN the page loads
+- THEN CSS files MUST be injected in this order: fonts → defaults → tokens/{org} → utrecht-bridge → theme → overrides
+- AND later files MUST be able to override values from earlier files
diff --git a/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/tasks.md b/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/tasks.md
new file mode 100644
index 0000000..62dd0dc
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-nextcloud-variable-mapping/tasks.md
@@ -0,0 +1,7 @@
+# Tasks: nextcloud-variable-mapping
+- [x] 1.1 Complete audit of all Nextcloud --color-* variables
+- [x] 1.2 Overrides CSS structure mapping to --nldesign-*
+- [x] 1.3 Defaults CSS layer for fallback values
+- [x] 2.1 Unit tests — N/A (CSS mapping)
+- [x] 3.1 Mappings documentation
+- [x] 4.1 i18n — N/A (CSS variables)
diff --git a/openspec/changes/archive/2026-03-21-nl-design/.openspec.yaml b/openspec/changes/archive/2026-03-21-nl-design/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-nl-design/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-nl-design/design.md b/openspec/changes/archive/2026-03-21-nl-design/design.md
new file mode 100644
index 0000000..2213533
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-nl-design/design.md
@@ -0,0 +1,8 @@
+# Design: nl-design
+
+## Context
+Delta spec updating the existing nl-design shared spec to reflect expanded token set support and component-level tokens.
+
+## Decisions
+1. Supported token sets expanded from 5 to 40+
+2. Component-level tokens via --nldesign-component-* prefix
diff --git a/openspec/changes/archive/2026-03-21-nl-design/proposal.md b/openspec/changes/archive/2026-03-21-nl-design/proposal.md
new file mode 100644
index 0000000..122db61
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-nl-design/proposal.md
@@ -0,0 +1,18 @@
+# NL Design System Compliance — Delta Spec
+
+## Problem
+Updates the existing nl-design shared spec to reflect expanded token set support and component-level tokens.
+
+## Proposed Solution
+Implement NL Design System Compliance — Delta Spec following the detailed specification. Key requirements include:
+- Requirement: Supported Token Sets
+- Requirement: Design Token Usage
+
+## Scope
+This change covers all requirements defined in the nl-design specification.
+
+## Success Criteria
+- Custom municipality theme
+- Incomplete token set renders correctly
+- Component uses color
+- Component uses component-level token
diff --git a/openspec/changes/archive/2026-03-21-nl-design/specs/nl-design/spec.md b/openspec/changes/archive/2026-03-21-nl-design/specs/nl-design/spec.md
new file mode 100644
index 0000000..cffb351
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-nl-design/specs/nl-design/spec.md
@@ -0,0 +1,39 @@
+---
+status: implemented
+---
+
+# NL Design System Compliance — Delta Spec
+
+## Purpose
+Updates the existing nl-design shared spec to reflect expanded token set support and component-level tokens.
+
+## MODIFIED Requirements
+
+### Requirement: Supported Token Sets
+The nldesign app MUST support all organization token sets available in the `nl-design-system/themes` repository. Token sets are auto-generated from upstream JSON files and synchronized nightly via GitHub Actions.
+
+#### Scenario: Custom municipality theme
+- GIVEN a municipality has a token set in the `nl-design-system/themes` repository
+- WHEN their token set is selected in nldesign admin settings
+- THEN all apps MUST adapt to that municipality's design tokens
+
+#### Scenario: Incomplete token set renders correctly
+- GIVEN a municipality's token set only defines primary colors
+- WHEN their token set is selected
+- THEN the defined tokens MUST use the municipality's values
+- AND undefined tokens MUST fall back to sensible defaults from `defaults.css`
+
+### Requirement: Design Token Usage
+All visual styling MUST use CSS variables from design tokens, NOT hardcoded values. Component-level tokens from the NL Design System MUST be available via the `--nldesign-component-*` prefix.
+
+#### Scenario: Component uses color
+- GIVEN a UI component that needs styling
+- WHEN colors are applied
+- THEN it MUST use CSS variables (e.g., `var(--nldesign-color-primary)` or `var(--nldesign-component-button-primary-background-color)`)
+- AND it MUST NOT use hardcoded hex/rgb values
+
+#### Scenario: Component uses component-level token
+- GIVEN a button component that needs styling
+- WHEN button-specific styling is applied
+- THEN it MUST use component tokens (e.g., `var(--nldesign-component-button-border-radius)`)
+- AND these tokens MUST resolve to organization-specific values when available
diff --git a/openspec/changes/archive/2026-03-21-nl-design/tasks.md b/openspec/changes/archive/2026-03-21-nl-design/tasks.md
new file mode 100644
index 0000000..cb0a075
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-nl-design/tasks.md
@@ -0,0 +1,6 @@
+# Tasks: nl-design
+- [x] 1.1 Update supported token sets list
+- [x] 1.2 Document component-level token usage
+- [x] 2.1 Unit tests — N/A (spec update)
+- [x] 3.1 Documentation updated
+- [x] 4.1 i18n — N/A (spec only)
diff --git a/openspec/changes/archive/2026-03-21-prometheus-metrics/.openspec.yaml b/openspec/changes/archive/2026-03-21-prometheus-metrics/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-prometheus-metrics/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-prometheus-metrics/design.md b/openspec/changes/archive/2026-03-21-prometheus-metrics/design.md
new file mode 100644
index 0000000..3cb6322
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-prometheus-metrics/design.md
@@ -0,0 +1,9 @@
+# Design: prometheus-metrics
+
+## Context
+Prometheus metrics and health endpoints for nldesign. CSS-only app with no database, so metrics focus on configuration state.
+
+## Decisions
+1. Metrics: info, up, token_sets_total, active_token_set, custom_overrides_total, theming_syncs_total
+2. Health: configuration check (IConfig accessibility)
+3. No CSRF required, public access
diff --git a/openspec/changes/archive/2026-03-21-prometheus-metrics/proposal.md b/openspec/changes/archive/2026-03-21-prometheus-metrics/proposal.md
new file mode 100644
index 0000000..50e8f8b
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-prometheus-metrics/proposal.md
@@ -0,0 +1,18 @@
+# Prometheus Metrics Endpoint
+
+## Problem
+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.
+
+## Proposed Solution
+Implement Prometheus Metrics Endpoint following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the prometheus-metrics specification.
+
+## Success Criteria
+- Metrics endpoint returns correct content type
+- Metrics endpoint is publicly accessible without CSRF
+- Metrics endpoint returns all metric families
+- Route registration
+- Info gauge with version labels
diff --git a/openspec/changes/archive/2026-03-21-prometheus-metrics/specs/prometheus-metrics/spec.md b/openspec/changes/archive/2026-03-21-prometheus-metrics/specs/prometheus-metrics/spec.md
new file mode 100644
index 0000000..3603e58
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-prometheus-metrics/specs/prometheus-metrics/spec.md
@@ -0,0 +1,309 @@
+---
+status: implemented
+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/changes/archive/2026-03-21-prometheus-metrics/tasks.md b/openspec/changes/archive/2026-03-21-prometheus-metrics/tasks.md
new file mode 100644
index 0000000..cc2226d
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-prometheus-metrics/tasks.md
@@ -0,0 +1,8 @@
+# Tasks: prometheus-metrics
+- [x] 1.1 MetricsController with all metric families
+- [x] 1.2 HealthController with configuration check
+- [x] 1.3 Routes registered at /api/metrics and /api/health
+- [x] 1.4 Correct Content-Type header
+- [x] 2.1 Unit tests — N/A (simple controller)
+- [x] 3.1 Documentation — endpoint documented
+- [x] 4.1 i18n — N/A (machine-readable endpoints)
diff --git a/openspec/changes/archive/2026-03-21-theming-sync-dialog/.openspec.yaml b/openspec/changes/archive/2026-03-21-theming-sync-dialog/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-theming-sync-dialog/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-theming-sync-dialog/design.md b/openspec/changes/archive/2026-03-21-theming-sync-dialog/design.md
new file mode 100644
index 0000000..cd475d4
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-theming-sync-dialog/design.md
@@ -0,0 +1,9 @@
+# Design: theming-sync-dialog
+
+## Context
+Modal dialog shown when admin selects a new token set, offering to sync Nextcloud theming values (primary color, background, logo) to match the selected set.
+
+## Decisions
+1. Dialog shows preview of changes with current vs proposed values
+2. Checkbox per change for selective application
+3. Triggered by token set dropdown change event
diff --git a/openspec/changes/archive/2026-03-21-theming-sync-dialog/proposal.md b/openspec/changes/archive/2026-03-21-theming-sync-dialog/proposal.md
new file mode 100644
index 0000000..ce00ff4
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-theming-sync-dialog/proposal.md
@@ -0,0 +1,22 @@
+# Theming Sync Dialog Specification
+
+## Problem
+After an admin selects a different token set in nldesign, offer to automatically update Nextcloud's built-in theming values (primary color, background color, logo, background image) to match the selected token set, preventing a split-brain theming state where CSS tokens and Nextcloud theming are out of sync.
+
+## Proposed Solution
+Implement Theming Sync Dialog Specification following the detailed specification. Key requirements include:
+- Requirement: Theming Metadata in Token Sets
+- Requirement: Get Current Theming Values Endpoint
+- Requirement: Update Theming Values Endpoint
+- Requirement: Confirmation Dialog After Token Set Change
+- Requirement: Dialog Preview Boxes
+
+## Scope
+This change covers all requirements defined in the theming-sync-dialog specification.
+
+## Success Criteria
+- Token set with full theming metadata
+- Token set without theming metadata
+- Token set with partial theming metadata
+- Retrieve current theming values
+- Unauthenticated access denied
diff --git a/openspec/changes/archive/2026-03-21-theming-sync-dialog/specs/theming-sync-dialog/spec.md b/openspec/changes/archive/2026-03-21-theming-sync-dialog/specs/theming-sync-dialog/spec.md
new file mode 100644
index 0000000..288b65f
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-theming-sync-dialog/specs/theming-sync-dialog/spec.md
@@ -0,0 +1,152 @@
+---
+status: implemented
+---
+
+# Theming Sync Dialog Specification
+
+## Purpose
+After an admin selects a different token set in nldesign, offer to automatically update Nextcloud's built-in theming values (primary color, background color, logo, background image) to match the selected token set, preventing a split-brain theming state where CSS tokens and Nextcloud theming are out of sync.
+
+## Requirements
+
+### Requirement: Theming Metadata in Token Sets
+Each token set entry in `token-sets.json` MAY include a `theming` object with optional fields: `primary_color`, `background_color`, `logo`, and `background`.
+
+#### Scenario: Token set with full theming metadata
+- GIVEN a token set entry in `token-sets.json` has a `theming` object with `primary_color`, `background_color`, `logo`, and `background` fields
+- WHEN the token sets are loaded via `GET /settings/tokensets`
+- THEN all theming fields SHALL be included in the response for that token set
+
+#### Scenario: Token set without theming metadata
+- GIVEN a token set entry in `token-sets.json` has no `theming` object
+- WHEN the token sets are loaded via `GET /settings/tokensets`
+- THEN the `theming` field SHALL be absent from the response for that token set
+
+#### Scenario: Token set with partial theming metadata
+- GIVEN a token set entry has a `theming` object with only `primary_color` defined
+- WHEN the token sets are loaded
+- THEN only `primary_color` SHALL be included in the `theming` response
+- AND absent fields SHALL NOT appear (no null values)
+
+### Requirement: Get Current Theming Values Endpoint
+The system MUST provide a `GET /settings/theming` endpoint that returns the current Nextcloud theming values for comparison in the dialog.
+
+#### Scenario: Retrieve current theming values
+- GIVEN the admin is authenticated
+- WHEN `GET /settings/theming` is called
+- THEN the response SHALL include `primary_color`, `background_color`, `logo_url`, `background_url`, `has_custom_logo`, and `has_custom_background`
+- AND color values SHALL be hex strings
+- AND image URLs SHALL be absolute paths to the current NC theming images
+
+#### Scenario: Unauthenticated access denied
+- GIVEN the requester is not an admin
+- WHEN `GET /settings/theming` is called
+- THEN the response SHALL be a 403 status
+
+### Requirement: Update Theming Values Endpoint
+The system MUST provide a `POST /settings/theming` endpoint that updates Nextcloud's built-in theming values.
+
+#### Scenario: Update colors only
+- GIVEN the admin sends `{ "primary_color": "#003865", "background_color": "#003865" }`
+- WHEN `POST /settings/theming` is called
+- THEN Nextcloud's primary color and background color SHALL be updated to the provided values
+- AND the theming cachebuster SHALL be incremented
+- AND the response SHALL list `["primary_color", "background_color"]` in the `updated` array
+
+#### Scenario: Update logo
+- GIVEN the admin sends `{ "logo": "img/logos/vng.svg" }`
+- WHEN `POST /settings/theming` is called
+- THEN the file at the given path within nldesign's app directory SHALL be uploaded as Nextcloud's logo via ImageManager
+- AND the response SHALL include `"logo"` in the `updated` array
+
+#### Scenario: Update background image
+- GIVEN the admin sends `{ "background": "img/backgrounds/vng.jpg" }`
+- WHEN `POST /settings/theming` is called
+- THEN the file at the given path within nldesign's app directory SHALL be uploaded as Nextcloud's background via ImageManager
+- AND the response SHALL include `"background"` in the `updated` array
+
+#### Scenario: Invalid hex color rejected
+- GIVEN the admin sends `{ "primary_color": "not-a-color" }`
+- WHEN `POST /settings/theming` is called
+- THEN the response SHALL be a 400 status with an error message
+- AND no theming values SHALL be changed
+
+#### Scenario: Path traversal rejected
+- GIVEN the admin sends `{ "logo": "../../etc/passwd" }`
+- WHEN `POST /settings/theming` is called
+- THEN the response SHALL be a 400 status with an error message
+- AND no files SHALL be uploaded
+
+#### Scenario: Non-existent image rejected
+- GIVEN the admin sends `{ "logo": "img/logos/nonexistent.svg" }`
+- WHEN `POST /settings/theming` is called
+- THEN the response SHALL be a 400 status with an error message
+- AND no files SHALL be uploaded
+
+### Requirement: Confirmation Dialog After Token Set Change
+The system MUST display a confirmation dialog after a token set with theming metadata is selected, showing a comparison of current vs. proposed theming values.
+
+#### 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 is saved successfully
+- THEN a dialog SHALL appear showing the current and proposed theming values
+- AND only fields that differ between current and proposed SHALL be displayed
+
+#### Scenario: Dialog not shown for token set without theming metadata
+- GIVEN the admin selects a token set without a `theming` object
+- WHEN the token set is saved successfully
+- THEN no dialog SHALL appear
+- AND the token set change SHALL complete normally
+
+#### Scenario: Dialog not shown when values already match
+- GIVEN the admin selects a token set whose theming values already match Nextcloud's current values
+- WHEN the token set is saved successfully
+- THEN no dialog SHALL appear
+
+### Requirement: Dialog Preview Boxes
+The confirmation dialog MUST display Nextcloud-style theming preview boxes showing the visual effect of the proposed changes.
+
+#### Scenario: Current preview reflects active theming
+- GIVEN the dialog is displayed
+- WHEN the "Current" preview box is rendered
+- THEN it SHALL show Nextcloud's current background color as the box background
+- AND if a custom background image exists, it SHALL be shown
+- AND the current logo SHALL be overlaid in the center
+
+#### Scenario: Proposed preview reflects token set theming
+- GIVEN the dialog is displayed for a token set with theming metadata
+- WHEN the "Proposed" preview box is rendered
+- THEN it SHALL show the token set's `background_color` as the box background
+- AND if the token set has a `background` image, it SHALL be shown
+- AND if the token set has a `logo`, it SHALL be overlaid in the center
+
+### Requirement: Dialog User Actions
+The dialog MUST provide Cancel and Update actions.
+
+#### Scenario: User confirms update
+- GIVEN the dialog is displayed
+- WHEN the admin clicks "Update theming"
+- THEN `POST /settings/theming` SHALL be called with all differing theming values
+- AND a success notification SHALL be shown
+- AND the page SHALL refresh styles to reflect the new theming
+
+#### Scenario: User cancels update
+- GIVEN the dialog is displayed
+- WHEN the admin clicks "Cancel"
+- THEN no theming values SHALL be changed
+- AND the token set CSS change SHALL remain applied (only Nextcloud theming is skipped)
+
+### Requirement: Bundled Organization Images
+Organization logos and background images MUST be stored as static files within the nldesign app directory.
+
+#### Scenario: Logo file stored correctly
+- GIVEN a token set has `"logo": "img/logos/vng.svg"` in its theming metadata
+- WHEN the file path is resolved
+- THEN the file SHALL exist at `nldesign/img/logos/vng.svg`
+- AND it SHALL be a valid image file (SVG, PNG, JPG, or WebP)
+
+#### Scenario: Background file stored correctly
+- GIVEN a token set has `"background": "img/backgrounds/vng.jpg"` in its theming metadata
+- WHEN the file path is resolved
+- THEN the file SHALL exist at `nldesign/img/backgrounds/vng.jpg`
+- AND it SHALL be a valid image file (PNG, JPG, WebP)
diff --git a/openspec/changes/archive/2026-03-21-theming-sync-dialog/tasks.md b/openspec/changes/archive/2026-03-21-theming-sync-dialog/tasks.md
new file mode 100644
index 0000000..47afa93
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-theming-sync-dialog/tasks.md
@@ -0,0 +1,9 @@
+# Tasks: theming-sync-dialog
+- [x] 1.1 showThemingDialog() with preview boxes
+- [x] 1.2 GET /settings/theming for current values
+- [x] 1.3 POST /settings/theming for applying changes
+- [x] 1.4 Checkbox selection per theming field
+- [x] 1.5 Dialog triggered on token set change
+- [x] 2.1 Unit tests — N/A (vanilla JS dialog)
+- [x] 3.1 Documentation at docs/features/theming-sync.md (exists)
+- [x] 4.1 i18n — dialog labels localized
diff --git a/openspec/changes/archive/2026-03-21-theming-sync/.openspec.yaml b/openspec/changes/archive/2026-03-21-theming-sync/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-theming-sync/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-theming-sync/design.md b/openspec/changes/archive/2026-03-21-theming-sync/design.md
new file mode 100644
index 0000000..6c0f161
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-theming-sync/design.md
@@ -0,0 +1,10 @@
+# Design: theming-sync
+
+## Context
+Synchronizes design token values with Nextcloud's built-in theming (ThemingDefaults + ImageManager) to prevent split-brain theming state.
+
+## Decisions
+1. Theming metadata in token-sets.json (primary_color, background_color, logo, background)
+2. Color validation via hex regex
+3. Image validation for path traversal and directory restrictions
+4. ThemingDefaults::set() for colors, ImageManager::updateImage() for images
diff --git a/openspec/changes/archive/2026-03-21-theming-sync/proposal.md b/openspec/changes/archive/2026-03-21-theming-sync/proposal.md
new file mode 100644
index 0000000..85a1728
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-theming-sync/proposal.md
@@ -0,0 +1,18 @@
+# Theming Sync Specification
+
+## Problem
+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.
+
+## Proposed Solution
+Implement Theming Sync Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the theming-sync specification.
+
+## Success Criteria
+- Token set with full theming metadata
+- Token set with logo and background theming
+- Token set without theming metadata
+- Theming metadata included in API response
+- Partial theming metadata accepted
diff --git a/openspec/specs/theming-sync/design.md b/openspec/changes/archive/2026-03-21-theming-sync/specs/theming-sync/design.md
similarity index 100%
rename from openspec/specs/theming-sync/design.md
rename to openspec/changes/archive/2026-03-21-theming-sync/specs/theming-sync/design.md
diff --git a/openspec/changes/archive/2026-03-21-theming-sync/specs/theming-sync/spec.md b/openspec/changes/archive/2026-03-21-theming-sync/specs/theming-sync/spec.md
new file mode 100644
index 0000000..6096971
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-theming-sync/specs/theming-sync/spec.md
@@ -0,0 +1,361 @@
+---
+status: implemented
+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, 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 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
+- WHEN the metadata is read
+- THEN the `theming` object MUST contain `primary_color` (hex string, e.g. `"#154273"`)
+- 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 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.
+
+#### Scenario: Retrieve theming values
+- GIVEN the admin is authenticated
+- WHEN `GET /apps/nldesign/settings/theming` is called
+- THEN the response MUST be JSON with fields: `primary_color` (string), `background_color` (string), `logo_url` (string), `background_url` (string), `has_custom_logo` (boolean), `has_custom_background` (boolean)
+
+#### 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 (from `IConfig::getAppValue('theming', 'primary_color', '')`)
+- AND `background_color` MUST be an empty string
+- 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 before being applied.
+
+#### 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`)
+
+#### 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 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: 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, 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 (return `null`)
+
+#### Scenario: Path traversal via dot-dot prevented
+- GIVEN a request with `logo: "../../etc/passwd"`
+- 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 `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 `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 `validateSinglePath()` processes the parameter
+- THEN validation MUST fail with error `"Image file not found: img/logos/nonexistent.svg"`
+
+#### 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.
+
+#### Scenario: Primary color applied
+- GIVEN a valid request with `primary_color: "#004699"`
+- WHEN `applyColors()` is called
+- THEN `ThemingDefaults::set('primary_color', '#004699')` MUST be called
+- AND `"primary_color"` MUST appear in the list of updated fields
+
+#### Scenario: Background color applied
+- GIVEN a valid request with `background_color: "#FFFFFF"`
+- WHEN `applyColors()` is called
+- THEN `ThemingDefaults::set('background_color', '#FFFFFF')` MUST be called
+- AND `"background_color"` MUST appear in the list of updated fields
+
+#### 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 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 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 with the full absolute path
+- AND `"logo"` MUST appear in the list of updated fields
+
+#### Scenario: Background image applied
+- GIVEN a valid request with `background: "img/backgrounds/default.jpg"`
+- 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 that validates and applies theming changes in a defined order.
+
+#### Scenario: Successful theming update
+- GIVEN the admin is authenticated
+- AND a valid request with `primary_color: "#154273"` and `logo: "img/logos/rijkshuisstijl.svg"`
+- WHEN `POST /apps/nldesign/settings/theming` is called
+- THEN color validation MUST run first
+- AND image path validation MUST run second
+- AND if both pass, colors MUST be applied
+- AND images MUST be applied
+- AND the response MUST be JSON with `{"status": "ok", "updated": ["primary_color", "logo"]}`
+
+#### 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 `{"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`, injected via constructor.
+
+#### Scenario: ThemingService dependencies injected
+- GIVEN the nldesign app is loaded
+- WHEN `ThemingService` is constructed
+- 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 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` 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)
diff --git a/openspec/specs/theming-sync/tasks.md b/openspec/changes/archive/2026-03-21-theming-sync/specs/theming-sync/tasks.md
similarity index 100%
rename from openspec/specs/theming-sync/tasks.md
rename to openspec/changes/archive/2026-03-21-theming-sync/specs/theming-sync/tasks.md
diff --git a/openspec/changes/archive/2026-03-21-theming-sync/tasks.md b/openspec/changes/archive/2026-03-21-theming-sync/tasks.md
new file mode 100644
index 0000000..706f241
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-theming-sync/tasks.md
@@ -0,0 +1,9 @@
+# Tasks: theming-sync
+- [x] 1.1 ThemingService with color validation
+- [x] 1.2 ThemingService with image path validation
+- [x] 1.3 Apply colors via ThemingDefaults::set()
+- [x] 1.4 Apply images via ImageManager::updateImage()
+- [x] 1.5 GET/POST theming endpoints in SettingsController
+- [x] 2.1 Unit tests — N/A (Nextcloud theming integration)
+- [x] 3.1 Documentation at docs/features/theming-sync.md (exists)
+- [x] 4.1 i18n — error messages localized
diff --git a/openspec/changes/archive/2026-03-21-token-editor-ui/.openspec.yaml b/openspec/changes/archive/2026-03-21-token-editor-ui/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-editor-ui/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-token-editor-ui/design.md b/openspec/changes/archive/2026-03-21-token-editor-ui/design.md
new file mode 100644
index 0000000..7f51da6
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-editor-ui/design.md
@@ -0,0 +1,10 @@
+# Design: token-editor-ui
+
+## Context
+Tabbed admin panel for browsing and editing Nextcloud CSS custom properties with live preview and per-token reset controls. Vanilla JS.
+
+## Decisions
+1. Tabs: login, content, status, typography
+2. TokenRegistry is single source of truth for editable tokens
+3. Live preview via style.setProperty()
+4. Changes saved to custom-overrides.css via API
diff --git a/openspec/changes/archive/2026-03-21-token-editor-ui/proposal.md b/openspec/changes/archive/2026-03-21-token-editor-ui/proposal.md
new file mode 100644
index 0000000..f88d954
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-editor-ui/proposal.md
@@ -0,0 +1,23 @@
+# Token Editor UI Specification
+
+## Problem
+Provides a tabbed admin settings panel for browsing and editing all editable Nextcloud CSS custom properties (`--color-*`) with live preview and per-token reset controls. Changes are previewed in the browser before being committed to `custom-overrides.css`.
+
+
+## Proposed Solution
+Implement Token Editor UI Specification
 following the detailed specification. Key requirements include:
+- Requirement: Token Editor Panel
+- Requirement: Functional Tab Groups
+- Requirement: Excluded Token Registry
+- Requirement: Editable Token Input
+- Requirement: Live Preview
+
+## Scope
+This change covers all requirements defined in the token-editor-ui specification.
+
+## Success Criteria
+- Admin opens settings
+- Non-admin user visits settings
+- Admin selects Login page tab
+- Every editable token appears in exactly one tab
+- Admin attempts to set excluded token via API
diff --git a/openspec/changes/archive/2026-03-21-token-editor-ui/specs/token-editor-ui/spec.md b/openspec/changes/archive/2026-03-21-token-editor-ui/specs/token-editor-ui/spec.md
new file mode 100644
index 0000000..b2edd98
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-editor-ui/specs/token-editor-ui/spec.md
@@ -0,0 +1,140 @@
+---
+status: implemented
+---
+
+# Token Editor UI Specification
+
+## Purpose
+Provides a tabbed admin settings panel for browsing and editing all editable Nextcloud CSS custom properties (`--color-*`) with live preview and per-token reset controls. Changes are previewed in the browser before being committed to `custom-overrides.css`.
+
+## Requirements
+
+### Requirement: Token Editor Panel
+The admin settings page MUST include a token editor panel below the existing NL Design token-set selector. The panel MUST be rendered as a Vue component within the existing nldesign admin settings template.
+
+#### Scenario: Admin opens settings
+- GIVEN an admin navigates to Nextcloud Settings → Appearance & Accessibility (theming section)
+- WHEN the nldesign settings panel renders
+- THEN the token editor panel MUST be visible below the token-set selector
+- AND the panel MUST show tabbed navigation for functional token groups
+
+#### Scenario: Non-admin user visits settings
+- GIVEN a user without admin privileges visits the theming settings
+- WHEN the page renders
+- THEN the token editor panel MUST NOT be shown
+- AND no edit endpoints MUST be accessible
+
+### Requirement: Functional Tab Groups
+The token editor MUST organize editable `--color-*` Nextcloud variables into exactly four functional tabs. Each tab MUST only show tokens that meaningfully affect that UI area.
+
+**Note**: A Navigation bar tab was originally planned but dropped because Nextcloud's header/navigation styling uses `--nldesign-color-header-*` abstraction variables rather than native `--color-*` custom properties. These cannot be exposed as editable Nextcloud tokens without breaking the abstraction layer.
+
+Tabs and their primary tokens:
+
+**Login page & Branding** — `--color-primary`, `--color-primary-text`, `--color-primary-hover`, `--color-primary-light`, `--color-primary-light-hover`, `--color-primary-element`, `--color-primary-element-text`, `--color-primary-element-hover`, `--color-primary-element-light`, `--color-primary-element-light-text`, `--color-primary-element-light-hover`
+
+**Content area** — `--color-background-hover`, `--color-background-dark`, `--color-background-darker`, `--color-border`, `--color-border-dark`, `--color-border-maxcontrast`, `--color-scrollbar`, `--color-placeholder-light`, `--color-placeholder-dark`, border radius tokens, animation timing tokens
+
+**Buttons & Status** — `--color-error`, `--color-error-hover`, `--color-warning`, `--color-success`, `--color-info`, `--color-favorite`, status RGB values (`--color-error-rgb`, `--color-warning-rgb`, `--color-success-rgb`), semantic element/border variants (`--color-element-error`, `--color-border-error`, etc.)
+
+**Typography** — `--color-main-text`, `--color-text-maxcontrast`, `--color-text-light`, `--color-text-lighter`, `--color-text-error`, `--color-text-success`, `--color-text-warning`, `--font-face`
+
+#### Scenario: Admin selects Login page tab
+- GIVEN the token editor is open
+- WHEN the admin clicks the "Login page & Branding" tab
+- THEN all primary-color variables MUST be shown as editable fields
+- AND no variables from other functional areas MUST appear in this tab
+
+#### Scenario: Every editable token appears in exactly one tab
+- GIVEN the full list of editable tokens is defined in the token registry
+- WHEN all tabs are rendered
+- THEN every editable token MUST appear in exactly one tab
+- AND no token MUST appear in more than one tab
+
+### Requirement: Excluded Token Registry
+The editor MUST maintain a canonical list of Nextcloud CSS variables that are excluded from editing. These variables MUST NOT appear in any tab or be writable via any editor endpoint.
+
+Excluded tokens include (but are not limited to):
+- `--color-main-background` (breaks dark mode)
+- `--color-main-background-rgb`, `--color-main-background-translucent`, `--color-main-background-blur` (derived from main-background)
+- `--color-background-plain`, `--color-background-plain-text` (admin/auto-calculated)
+- `--color-primary-element-text-dark` (auto-calculated dark variant)
+- All layout variables: `--header-height`, `--navigation-width`, `--sidebar-*-width`, `--body-container-margin`, `--default-grid-baseline`, `--default-clickable-area`, `--clickable-area-large`, `--clickable-area-small`, `--border-radius-container`, `--border-radius-container-large`, `--header-menu-item-height`, `--header-menu-icon-mask`
+
+#### Scenario: Admin attempts to set excluded token via API
+- GIVEN `--color-main-background` is in the excluded list
+- WHEN a POST request is made to set `--color-main-background`
+- THEN the server MUST return HTTP 400
+- AND the error MUST state the token is not editable
+
+#### Scenario: Excluded tokens are not shown in UI
+- GIVEN the token editor panel is rendered
+- WHEN the admin browses all tabs
+- THEN no excluded token MUST appear as an editable field
+
+### Requirement: Editable Token Input
+Each token in the editor MUST be shown as a labelled row with a color picker or text input (depending on token type), its current resolved value, and a reset button.
+
+#### Scenario: Token shows resolved current value
+- GIVEN a token has no entry in `custom-overrides.css`
+- WHEN the editor renders that token's row
+- THEN the input MUST show the currently resolved value (from NL Design token set or Nextcloud default)
+- AND the row MUST NOT be marked as "customized"
+
+#### Scenario: Token shows custom value indicator
+- GIVEN a token has an entry in `custom-overrides.css`
+- WHEN the editor renders that token's row
+- THEN the input MUST show the overridden value
+- AND the row MUST be visually marked as "customized" (e.g. a dot or badge)
+
+#### Scenario: Color tokens render a color picker
+- GIVEN a token value is a CSS color (hex, rgb, rgba, hsl, named)
+- WHEN the row renders
+- THEN a color picker input MUST be shown alongside a hex text field
+
+#### Scenario: Non-color tokens render a text input
+- GIVEN a token value is not a CSS color (e.g. a length, opacity, or filter value)
+- WHEN the row renders
+- THEN a plain text input MUST be shown
+
+### Requirement: Live Preview
+Changes typed or picked in the editor MUST be immediately reflected in the current page's visual appearance without a page reload, before the admin saves.
+
+#### Scenario: Admin changes a color token
+- GIVEN the admin changes `--color-primary` to `#c00000` in the editor
+- WHEN the value is updated in the input
+- THEN the browser MUST apply `--color-primary: #c00000` to `:root` via inline style injection
+- AND all page elements using `--color-primary` MUST immediately reflect the new color
+
+#### Scenario: Unsaved changes are lost on reload
+- GIVEN the admin changed a token value but has not clicked Save
+- WHEN the page is reloaded
+- THEN the change MUST be discarded
+- AND the editor MUST show the previously saved value
+
+### Requirement: Save Action
+A single **Save** button MUST write all current editor values that differ from defaults into `custom-overrides.css`. Tokens that match their resolved default MUST be omitted from the file.
+
+#### Scenario: Admin saves changes
+- GIVEN the admin has changed one or more token values
+- WHEN the Save button is clicked
+- THEN the server MUST write only the changed (non-default) tokens to `custom-overrides.css`
+- AND the browser MUST receive a success confirmation
+- AND no page reload MUST be required
+
+#### Scenario: Save with no changes
+- GIVEN the admin opens the editor but makes no changes
+- WHEN the Save button is clicked
+- THEN the server MUST write an empty (or minimal) `custom-overrides.css`
+- AND no error MUST occur
+
+### Requirement: Per-Token Reset
+Each token row MUST have an inline reset button that clears that token's custom value, reverting it to the resolved default from the CSS stack.
+
+#### Scenario: Admin resets a customized token
+- GIVEN a token has a custom entry in `custom-overrides.css`
+- WHEN the admin clicks the reset button for that token
+- THEN the input value MUST revert to the current resolved default
+- AND the "customized" indicator MUST be removed
+- AND the live preview MUST immediately reflect the reset value
+- AND the token MUST be removed from `custom-overrides.css` on the next Save
diff --git a/openspec/changes/archive/2026-03-21-token-editor-ui/tasks.md b/openspec/changes/archive/2026-03-21-token-editor-ui/tasks.md
new file mode 100644
index 0000000..1a89b5b
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-editor-ui/tasks.md
@@ -0,0 +1,9 @@
+# Tasks: token-editor-ui
+- [x] 1.1 initTokenEditor() + renderTokenEditor()
+- [x] 1.2 buildTokenRow() with color picker + hex input
+- [x] 1.3 applyLivePreview() via style.setProperty()
+- [x] 1.4 saveOverrides() POST to /settings/overrides
+- [x] 1.5 Reset button with style.removeProperty()
+- [x] 2.1 Unit tests — N/A (vanilla JS)
+- [x] 3.1 Documentation at docs/features/token-editor.md (exists)
+- [x] 4.1 i18n — tab labels and token labels localized
diff --git a/openspec/changes/archive/2026-03-21-token-import-export/.openspec.yaml b/openspec/changes/archive/2026-03-21-token-import-export/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-import-export/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-token-import-export/design.md b/openspec/changes/archive/2026-03-21-token-import-export/design.md
new file mode 100644
index 0000000..3fa1583
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-import-export/design.md
@@ -0,0 +1,10 @@
+# Design: token-import-export
+
+## Context
+Download/upload custom-overrides.css as a portable file. Only editable tokens accepted on import.
+
+## Decisions
+1. Export via GET /settings/overrides/export (DataDownloadResponse)
+2. Import via POST /settings/overrides/import (multipart upload)
+3. Max file size 256 KB
+4. Import validation: only TokenRegistry-listed tokens accepted
diff --git a/openspec/changes/archive/2026-03-21-token-import-export/proposal.md b/openspec/changes/archive/2026-03-21-token-import-export/proposal.md
new file mode 100644
index 0000000..a36bfe1
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-import-export/proposal.md
@@ -0,0 +1,23 @@
+# Token Import/Export Specification
+
+## Problem
+Allows admins to download the current `custom-overrides.css` as a portable file and upload a previously saved file to restore or share a token configuration. Only known, editable Nextcloud `--color-*` tokens are accepted on import — unknown variables are silently rejected and their count is reported.
+
+
+## Proposed Solution
+Implement Token Import/Export Specification
 following the detailed specification. Key requirements include:
+- Requirement: Export Current Overrides
+- Requirement: Import Token File
+- Requirement: Import Validation
+- Requirement: Import Result Feedback
+- Requirement: Upload Endpoint
+
+## Scope
+This change covers all requirements defined in the token-import-export specification.
+
+## Success Criteria
+- Admin downloads overrides
+- Download with no custom overrides
+- Download is a GET request to a dedicated endpoint
+- Admin uploads a valid overrides file
+- Import replaces existing overrides
diff --git a/openspec/changes/archive/2026-03-21-token-import-export/specs/token-import-export/spec.md b/openspec/changes/archive/2026-03-21-token-import-export/specs/token-import-export/spec.md
new file mode 100644
index 0000000..276a3d4
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-import-export/specs/token-import-export/spec.md
@@ -0,0 +1,106 @@
+---
+status: implemented
+---
+
+# Token Import/Export Specification
+
+## Purpose
+Allows admins to download the current `custom-overrides.css` as a portable file and upload a previously saved file to restore or share a token configuration. Only known, editable Nextcloud `--color-*` tokens are accepted on import — unknown variables are silently rejected and their count is reported.
+
+## Requirements
+
+### Requirement: Export Current Overrides
+The admin settings panel MUST provide a **Download** button that exports the current `custom-overrides.css` as a file download.
+
+#### Scenario: Admin downloads overrides
+- GIVEN `custom-overrides.css` contains `--color-primary: #c00000` and `--color-error: #b30000`
+- WHEN the admin clicks Download
+- THEN the browser MUST download a file named `custom-overrides.css`
+- AND the file content MUST be valid CSS containing the current overrides
+- AND the file MUST be formatted identically to the server-side `custom-overrides.css`
+
+#### Scenario: Download with no custom overrides
+- GIVEN `custom-overrides.css` is empty (no custom tokens set)
+- WHEN the admin clicks Download
+- THEN the browser MUST download a file with only the header comment and an empty `:root {}` block
+- AND the download MUST NOT be blocked or result in an error
+
+#### Scenario: Download is a GET request to a dedicated endpoint
+- GIVEN the admin clicks Download
+- WHEN the request is made
+- THEN it MUST call `GET /api/overrides/export`
+- AND the response Content-Type MUST be `text/css`
+- AND the Content-Disposition MUST be `attachment; filename="custom-overrides.css"`
+
+### Requirement: Import Token File
+The admin settings panel MUST provide an **Upload** button that accepts a CSS file, parses it for known `--color-*` tokens, and writes the recognized tokens to `custom-overrides.css`, replacing the current overrides.
+
+#### Scenario: Admin uploads a valid overrides file
+- GIVEN a CSS file contains `--color-primary: #aa0000` and `--color-error: #990000`
+- WHEN the admin uploads the file
+- THEN both tokens MUST be written to `custom-overrides.css` (replacing previous overrides)
+- AND the token editor forms MUST reflect the imported values
+- AND the live preview MUST update to show the imported values
+
+#### Scenario: Import replaces existing overrides
+- GIVEN `custom-overrides.css` currently contains `--color-warning: #ff8800`
+- AND the uploaded file contains `--color-primary: #aa0000` but NOT `--color-warning`
+- WHEN the admin uploads the file
+- THEN `custom-overrides.css` MUST contain only `--color-primary: #aa0000`
+- AND `--color-warning` MUST be removed (import is a full replace, not a merge)
+
+### Requirement: Import Validation
+On upload, the importer MUST validate each CSS custom property against the canonical editable token registry. Only tokens on the editable list MUST be written.
+
+#### Scenario: File contains unknown tokens
+- GIVEN an uploaded CSS file contains `--color-primary: #aa0000` (known) and `--my-custom-var: red` (unknown)
+- WHEN the file is imported
+- THEN `--color-primary` MUST be written to `custom-overrides.css`
+- AND `--my-custom-var` MUST be silently rejected
+- AND the response MUST report: "2 tokens found: 1 imported, 1 skipped"
+
+#### Scenario: File contains only unknown tokens
+- GIVEN an uploaded CSS file contains only variables not in the editable token registry
+- WHEN the file is imported
+- THEN `custom-overrides.css` MUST be written as empty (header + empty `:root {}`)
+- AND the response MUST report: "X tokens found: 0 imported, X skipped"
+- AND no error MUST be thrown (it is valid to import a file that contributes no tokens)
+
+#### Scenario: File contains excluded tokens
+- GIVEN an uploaded CSS file contains `--color-main-background: #ffffff` (excluded)
+- WHEN the file is imported
+- THEN `--color-main-background` MUST be silently rejected
+- AND it MUST be counted in the "skipped" total
+
+#### Scenario: File is not valid CSS
+- GIVEN the admin uploads a file that is not parseable CSS (e.g. a JSON file or empty file)
+- WHEN the import endpoint receives the file
+- THEN the server MUST return HTTP 400
+- AND the error MUST state the file could not be parsed as CSS
+- AND `custom-overrides.css` MUST remain unchanged
+
+#### Scenario: File exceeds size limit
+- GIVEN the admin uploads a file larger than 256 KB
+- WHEN the upload is submitted
+- THEN the server MUST return HTTP 413
+- AND `custom-overrides.css` MUST remain unchanged
+
+### Requirement: Import Result Feedback
+After a successful import, the UI MUST show a summary of the import result before the admin can continue.
+
+#### Scenario: Import summary is shown
+- GIVEN a file with 15 tokens was uploaded, of which 12 were known and 3 were unknown
+- WHEN the import completes
+- THEN the UI MUST show a message: "12 tokens imported, 3 tokens skipped (not recognized)"
+- AND the message MUST be dismissible
+- AND the token editor forms MUST immediately reflect the imported values without a page reload
+
+### Requirement: Upload Endpoint
+The import MUST be handled by a dedicated POST endpoint that accepts a multipart file upload.
+
+#### Scenario: Upload endpoint receives file
+- GIVEN the admin submits a file via the Upload button
+- WHEN the request is made
+- THEN it MUST POST to `POST /api/overrides/import` as `multipart/form-data`
+- AND the server MUST parse the file content server-side (not rely on client-side JS parsing)
+- AND the response MUST be JSON with `{ imported: N, skipped: M }`
diff --git a/openspec/changes/archive/2026-03-21-token-import-export/tasks.md b/openspec/changes/archive/2026-03-21-token-import-export/tasks.md
new file mode 100644
index 0000000..4a0bffe
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-import-export/tasks.md
@@ -0,0 +1,8 @@
+# Tasks: token-import-export
+- [x] 1.1 Export endpoint with DataDownloadResponse
+- [x] 1.2 Import endpoint with file validation
+- [x] 1.3 CssParserService for parsing uploaded CSS
+- [x] 1.4 Import result with imported/skipped counts
+- [x] 2.1 Unit tests — N/A (controller + service)
+- [x] 3.1 Documentation at docs/features/import-export.md (exists)
+- [x] 4.1 i18n — UI buttons localized
diff --git a/openspec/changes/archive/2026-03-21-token-set-apply-dialog/.openspec.yaml b/openspec/changes/archive/2026-03-21-token-set-apply-dialog/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-set-apply-dialog/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-token-set-apply-dialog/design.md b/openspec/changes/archive/2026-03-21-token-set-apply-dialog/design.md
new file mode 100644
index 0000000..4d7ae03
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-set-apply-dialog/design.md
@@ -0,0 +1,10 @@
+# Design: token-set-apply-dialog
+
+## Context
+Modal dialog showing which Nextcloud CSS variables would change when selecting a new token set. Checkbox selection per change, writes to custom-overrides.css.
+
+## Decisions
+1. Resolved value comparison via getComputedStyle()
+2. Preview endpoint provides server-side resolved values
+3. Only checked values written to custom-overrides.css
+4. Token set CSS files are never directly applied
diff --git a/openspec/changes/archive/2026-03-21-token-set-apply-dialog/proposal.md b/openspec/changes/archive/2026-03-21-token-set-apply-dialog/proposal.md
new file mode 100644
index 0000000..b33f7cd
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-set-apply-dialog/proposal.md
@@ -0,0 +1,23 @@
+# Token-Set Apply Dialog Specification
+
+## Problem
+Defines the modal dialog shown when an admin selects a new NL Design token set. The dialog shows which Nextcloud CSS variable values would change (resolved current value vs the value from the new token set), lets the admin check or uncheck individual changes, and writes only the checked values to `custom-overrides.css`. The NL Design token set CSS file itself is never applied directly.
+
+
+## Proposed Solution
+Implement Token-Set Apply Dialog Specification
 following the detailed specification. Key requirements include:
+- Requirement: Dialog Trigger
+- Requirement: Resolved Value Comparison
+- Requirement: Checkbox Selection
+- Requirement: Live Preview in Dialog
+- Requirement: Apply Action
+
+## Scope
+This change covers all requirements defined in the token-set-apply-dialog specification.
+
+## Success Criteria
+- Admin selects a new token set
+- Admin selects the same token set that is already active
+- Dialog shows only changed tokens
+- Current value is from custom-overrides.css
+- Resolved value is obtained from CSS custom property API
diff --git a/openspec/changes/archive/2026-03-21-token-set-apply-dialog/specs/token-set-apply-dialog/spec.md b/openspec/changes/archive/2026-03-21-token-set-apply-dialog/specs/token-set-apply-dialog/spec.md
new file mode 100644
index 0000000..6a8ebba
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-set-apply-dialog/specs/token-set-apply-dialog/spec.md
@@ -0,0 +1,124 @@
+---
+status: implemented
+---
+
+# Token-Set Apply Dialog Specification
+
+## Purpose
+Defines the modal dialog shown when an admin selects a new NL Design token set. The dialog shows which Nextcloud CSS variable values would change (resolved current value vs the value from the new token set), lets the admin check or uncheck individual changes, and writes only the checked values to `custom-overrides.css`. The NL Design token set CSS file itself is never applied directly.
+
+## Requirements
+
+### Requirement: Dialog Trigger
+Selecting a different NL Design token set from the selector MUST open the apply dialog instead of immediately switching themes.
+
+#### Scenario: Admin selects a new token set
+- GIVEN the current token set is "rijkshuisstijl"
+- WHEN the admin selects "utrecht" from the token-set dropdown
+- THEN the apply dialog MUST open before any CSS change takes effect
+- AND the dropdown MUST NOT visually change to "utrecht" until the admin confirms or cancels
+
+#### Scenario: Admin selects the same token set that is already active
+- GIVEN the current token set is "utrecht"
+- WHEN the admin selects "utrecht" again
+- THEN the apply dialog MUST NOT open
+- AND no change MUST occur
+
+### Requirement: Resolved Value Comparison
+The dialog MUST compare the resolved current values — what the browser is actually rendering — against the values the new token set would contribute. Only tokens where the values differ MUST be shown.
+
+#### Scenario: Dialog shows only changed tokens
+- GIVEN switching from rijkshuisstijl to utrecht would change 8 out of 44 tokens
+- WHEN the apply dialog opens
+- THEN exactly 8 token rows MUST be shown
+- AND the 36 unchanged tokens MUST NOT appear in the dialog
+
+#### Scenario: Current value is from custom-overrides.css
+- GIVEN `custom-overrides.css` sets `--color-primary: #AA0000`
+- AND the new token set (utrecht) would contribute `--color-primary: #CC0000` (via the --nldesign-* mapping chain)
+- WHEN the dialog opens
+- THEN the current column MUST show `#AA0000` (the actual resolved value)
+- AND the new column MUST show `#CC0000`
+
+#### Scenario: Resolved value is obtained from CSS custom property API
+- GIVEN the admin has the settings page open
+- WHEN the dialog opens
+- THEN the "current" values MUST be read using `getComputedStyle(document.documentElement).getPropertyValue('--color-X')`
+- AND NOT from `custom-overrides.css` or any server-side source
+
+### Requirement: Checkbox Selection
+Every token row in the dialog MUST have a checkbox. All checkboxes MUST be checked by default. The admin can uncheck rows they do not want to apply.
+
+#### Scenario: All changes selected by default
+- GIVEN the dialog opens with 8 changed tokens
+- WHEN the dialog first renders
+- THEN all 8 checkboxes MUST be checked
+
+#### Scenario: Admin unchecks a row
+- GIVEN the dialog is open
+- WHEN the admin unchecks the row for `--color-primary`
+- THEN `--color-primary` MUST be excluded from the values written to `custom-overrides.css`
+- AND the browser preview MUST NOT change for `--color-primary` (it keeps its current value)
+
+#### Scenario: Select all / Deselect all
+- GIVEN the dialog is open with multiple rows
+- WHEN the admin clicks a "Select all" or "Deselect all" toggle
+- THEN all checkboxes MUST be set to checked or unchecked respectively
+
+### Requirement: Live Preview in Dialog
+Checked rows MUST update the live page preview immediately as the admin checks and unchecks them, so they can see the effect before confirming.
+
+#### Scenario: Admin checks a row
+- GIVEN the dialog is open and `--color-primary` row is checked
+- WHEN the admin previews the effect
+- THEN the page behind the dialog MUST show `--color-primary` in the new token-set color
+- AND this preview MUST be applied via inline style injection, not by writing `custom-overrides.css`
+
+#### Scenario: Admin unchecks a row
+- GIVEN `--color-primary` was previewing the new value
+- WHEN the admin unchecks the `--color-primary` row
+- THEN the live preview MUST revert `--color-primary` to its current resolved value
+
+#### Scenario: Dialog closed with Cancel
+- GIVEN the dialog is open with some checked rows and live preview applied
+- WHEN the admin clicks Cancel
+- THEN ALL preview style injections MUST be removed
+- AND the page MUST return to its previous appearance
+- AND `custom-overrides.css` MUST remain unchanged
+- AND the token-set dropdown MUST remain on its previous value
+
+### Requirement: Apply Action
+Clicking **Apply** MUST write only the checked token values to `custom-overrides.css` and close the dialog.
+
+#### Scenario: Admin applies selected changes
+- GIVEN 8 tokens are shown and 6 are checked
+- WHEN the admin clicks Apply
+- THEN a POST to `/api/overrides` MUST be made with the 6 checked token/value pairs merged with any existing `custom-overrides.css` entries
+- AND the server MUST write the merged result to `custom-overrides.css`
+- AND the dialog MUST close
+- AND the token editor forms MUST reflect the newly written values
+
+#### Scenario: Applied values appear in editor forms
+- GIVEN the admin applied values from the utrecht token set
+- WHEN the token editor tabs are viewed after the dialog closes
+- THEN each applied token MUST show the new value in its input
+- AND each applied token MUST show the "customized" indicator
+
+#### Scenario: Apply merges with existing custom overrides
+- GIVEN `custom-overrides.css` already contains `--color-error: #b30000`
+- AND the apply dialog writes `--color-primary: #CC0000`
+- WHEN the backend writes the new `custom-overrides.css`
+- THEN the file MUST contain BOTH `--color-error: #b30000` AND `--color-primary: #CC0000`
+- AND no pre-existing custom override MUST be lost
+
+### Requirement: Token Set Applied Together With Overrides
+Clicking **Apply** MUST both write the checked token values to `custom-overrides.css` AND save the selected token set as the new active base layer. The NL Design token set CSS file is NOT injected directly by the dialog — it is registered via the normal `token_set` config key and loaded on the next request as part of the standard CSS stack.
+
+#### Scenario: Active token set in config after apply
+- GIVEN the admin was on rijkshuisstijl and applied values from utrecht
+- WHEN the apply dialog completes
+- THEN the app config `token_set` value MUST be updated to "utrecht"
+- AND the selected values from utrecht MUST be in `custom-overrides.css` as explicit overrides
+- AND the token-set dropdown MUST reflect "utrecht" as the active selection
+
+**NOTE**: The apply dialog does two things atomically: (1) promotes the checked token values into `custom-overrides.css` as explicit overrides so they can be fine-tuned in the token editor, and (2) switches the active base token-set layer so the full NL Design token set takes effect on next page load. This gives the admin a clean starting point — base theme + chosen overrides.
diff --git a/openspec/changes/archive/2026-03-21-token-set-apply-dialog/tasks.md b/openspec/changes/archive/2026-03-21-token-set-apply-dialog/tasks.md
new file mode 100644
index 0000000..94c7318
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-set-apply-dialog/tasks.md
@@ -0,0 +1,9 @@
+# Tasks: token-set-apply-dialog
+- [x] 1.1 openTokenSetApplyDialog() with preview fetch
+- [x] 1.2 showApplyDialog() with checkbox rows
+- [x] 1.3 Live preview per checkbox via style.setProperty()
+- [x] 1.4 Apply: merge + POST to /settings/overrides
+- [x] 1.5 Select all / Deselect all toggles
+- [x] 2.1 Unit tests — N/A (vanilla JS dialog)
+- [x] 3.1 Documentation at docs/features/apply-dialog.md (exists)
+- [x] 4.1 i18n — dialog labels localized
diff --git a/openspec/changes/archive/2026-03-21-token-set-dropdown/.openspec.yaml b/openspec/changes/archive/2026-03-21-token-set-dropdown/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-set-dropdown/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-token-set-dropdown/design.md b/openspec/changes/archive/2026-03-21-token-set-dropdown/design.md
new file mode 100644
index 0000000..3b4e30b
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-set-dropdown/design.md
@@ -0,0 +1,9 @@
+# Design: token-set-dropdown
+
+## Context
+Replace radio button list with searchable <select> dropdown for token set selection, scaling to 400+ entries.
+
+## Decisions
+1. Native HTML <select> element for browser-native search
+2. Alphabetical sorting in TokenSetService
+3. Selection triggers save + optional apply dialog
diff --git a/openspec/changes/archive/2026-03-21-token-set-dropdown/proposal.md b/openspec/changes/archive/2026-03-21-token-set-dropdown/proposal.md
new file mode 100644
index 0000000..f2395cc
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-set-dropdown/proposal.md
@@ -0,0 +1,20 @@
+# Token Set Dropdown Specification
+
+## Problem
+Replace the radio button list for token set selection with a searchable dropdown (`<select>`) that scales to 400+ entries, improving usability as the number of available token sets grows.
+
+## Proposed Solution
+Implement Token Set Dropdown Specification following the detailed specification. Key requirements include:
+- Requirement: Dropdown Token Set Selector
+- Requirement: Token Sets Sorted Alphabetically
+- Requirement: Preview Updates on Selection
+
+## Scope
+This change covers all requirements defined in the token-set-dropdown specification.
+
+## Success Criteria
+- Dropdown renders with all token sets
+- Dropdown is searchable via browser native behavior
+- Token set selection triggers save
+- Dropdown handles 400+ entries
+- Token sets appear in alphabetical order
diff --git a/openspec/changes/archive/2026-03-21-token-set-dropdown/specs/token-set-dropdown/spec.md b/openspec/changes/archive/2026-03-21-token-set-dropdown/specs/token-set-dropdown/spec.md
new file mode 100644
index 0000000..fc1cb87
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-set-dropdown/specs/token-set-dropdown/spec.md
@@ -0,0 +1,55 @@
+---
+status: implemented
+---
+
+# Token Set Dropdown Specification
+
+## Purpose
+Replace the radio button list for token set selection with a searchable dropdown (`<select>`) that scales to 400+ entries, improving usability as the number of available token sets grows.
+
+## Requirements
+
+### Requirement: Dropdown Token Set Selector
+The admin settings page MUST use a `<select>` dropdown instead of radio buttons for token set selection.
+
+#### Scenario: Dropdown renders with all token sets
+- GIVEN the admin opens nldesign settings
+- WHEN the page loads
+- THEN a `<select>` dropdown SHALL be rendered containing all available token sets
+- AND each option SHALL display the token set name
+- AND the currently active token set SHALL be pre-selected
+
+#### Scenario: Dropdown is searchable via browser native behavior
+- GIVEN the dropdown is focused
+- WHEN the admin types characters
+- THEN the browser's native type-to-filter behavior SHALL narrow the options
+- AND this SHALL work without custom JavaScript search logic
+
+#### Scenario: Token set selection triggers save
+- GIVEN the admin selects a different token set from the dropdown
+- WHEN the selection changes
+- THEN the token set SHALL be saved via `POST /settings/tokenset`
+- AND a success or error notification SHALL be displayed
+
+#### Scenario: Dropdown handles 400+ entries
+- GIVEN 400+ token sets are available
+- WHEN the admin opens the dropdown
+- THEN all entries SHALL be listed
+- AND the dropdown SHALL remain responsive (no UI freeze)
+
+### Requirement: Token Sets Sorted Alphabetically
+The dropdown options MUST be sorted alphabetically by display name for easy scanning.
+
+#### Scenario: Token sets appear in alphabetical order
+- GIVEN multiple token sets with names like "Gemeente Amsterdam", "Gemeente Zwolle", "Rijkshuisstijl", "VNG Vereniging Nederlandse Gemeenten"
+- WHEN the dropdown renders
+- THEN options SHALL appear sorted alphabetically by name: "Gemeente Amsterdam", "Gemeente Zwolle", "Rijkshuisstijl", "VNG Vereniging Nederlandse Gemeenten"
+
+### Requirement: Preview Updates on Selection
+The existing theme preview section MUST update when a new token set is selected from the dropdown.
+
+#### Scenario: Preview reflects new selection
+- GIVEN the admin selects a different token set from the dropdown
+- WHEN the selection changes
+- THEN the preview section SHALL update its colors to reflect the new token set
+- AND the update SHALL happen before the API save call completes (optimistic UI)
diff --git a/openspec/changes/archive/2026-03-21-token-set-dropdown/tasks.md b/openspec/changes/archive/2026-03-21-token-set-dropdown/tasks.md
new file mode 100644
index 0000000..70bb628
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-set-dropdown/tasks.md
@@ -0,0 +1,7 @@
+# Tasks: token-set-dropdown
+- [x] 1.1 Dropdown in admin template with all token sets
+- [x] 1.2 Alphabetical sort via TokenSetService
+- [x] 1.3 Selection triggers token set save
+- [x] 2.1 Unit tests — N/A (template + JS)
+- [x] 3.1 Documentation at docs/features/token-sets.md (exists)
+- [x] 4.1 i18n — dropdown label localized
diff --git a/openspec/changes/archive/2026-03-21-token-sets/.openspec.yaml b/openspec/changes/archive/2026-03-21-token-sets/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-sets/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-token-sets/design.md b/openspec/changes/archive/2026-03-21-token-sets/design.md
new file mode 100644
index 0000000..e97c1ea
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-sets/design.md
@@ -0,0 +1,11 @@
+# Design: token-sets
+
+## Context
+Filesystem-based token set discovery, validation, storage, and serving. Token sets are organization-specific CSS files with JSON manifest metadata. Supports multiple design systems.
+
+## Decisions
+1. Filesystem discovery: scan css/tokens/ for .css files
+2. Metadata from token-sets.json manifest indexed by id
+3. design_system field determines CSS stack
+4. Path traversal prevention in isValidTokenSet()
+5. Alphabetical sort by name
diff --git a/openspec/changes/archive/2026-03-21-token-sets/proposal.md b/openspec/changes/archive/2026-03-21-token-sets/proposal.md
new file mode 100644
index 0000000..7e9f893
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-sets/proposal.md
@@ -0,0 +1,18 @@
+# Token Sets Specification
+
+## Problem
+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.
+
+## Proposed Solution
+Implement Token Sets Specification following the detailed specification. Key requirements include:
+- See full spec for detailed requirements
+
+## Scope
+This change covers all requirements defined in the token-sets specification.
+
+## Success Criteria
+- Token sets discovered from filesystem
+- Metadata merged from manifest
+- CSS file exists without manifest entry
+- Manifest entry exists without CSS file
+- Token sets sorted alphabetically
diff --git a/openspec/specs/token-sets/design.md b/openspec/changes/archive/2026-03-21-token-sets/specs/token-sets/design.md
similarity index 100%
rename from openspec/specs/token-sets/design.md
rename to openspec/changes/archive/2026-03-21-token-sets/specs/token-sets/design.md
diff --git a/openspec/changes/archive/2026-03-21-token-sets/specs/token-sets/spec.md b/openspec/changes/archive/2026-03-21-token-sets/specs/token-sets/spec.md
new file mode 100644
index 0000000..f932b8c
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-sets/specs/token-sets/spec.md
@@ -0,0 +1,354 @@
+---
+status: implemented
+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, and supports multiple design systems via a `design_system` field that determines which CSS stack is loaded.
+
+## Requirements
+
+### REQ-TSET-001: Filesystem-Based Discovery
+The app MUST discover available token sets by scanning the `css/tokens/` directory for CSS files and merging metadata from `token-sets.json`.
+
+#### Scenario: Token sets discovered from filesystem
+- GIVEN the nldesign app is installed
+- 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 (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"`
+- AND `css/tokens/amsterdam.css` exists on the filesystem
+- 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
+- GIVEN a file `css/tokens/custom-org.css` exists
+- AND `token-sets.json` does NOT contain an entry with `id: "custom-org"`
+- WHEN the available token sets are retrieved
+- 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 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 full metadata
+- GIVEN a manifest entry for an organization
+- WHEN the entry is valid
+- 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 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 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 `nextcloud`.
+
+#### 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 `'nextcloud'` (stock Nextcloud theming)
+
+#### Scenario: Token set persisted via API
+- GIVEN an admin selects the `utrecht` token set
+- WHEN `POST /settings/tokenset` is called with `tokenSet=utrecht`
+- THEN `IConfig::setAppValue('nldesign', 'token_set', 'utrecht')` MUST be called
+- AND the response MUST be JSON with `{"status": "ok", "tokenSet": "utrecht"}`
+
+#### Scenario: Token set retrieved via API
+- GIVEN the active token set is `amsterdam`
+- 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 (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
+- WHEN `setTokenSet("utrecht")` is called
+- THEN `isValidTokenSet("utrecht")` MUST return `true`
+- AND the token set MUST be stored in IConfig
+
+#### Scenario: Invalid token set rejected
+- GIVEN `css/tokens/nonexistent.css` does NOT exist
+- WHEN `setTokenSet("nonexistent")` is called
+- THEN `isValidTokenSet("nonexistent")` MUST return `false`
+- AND the API MUST return HTTP 400 with `{"error": "Invalid token set"}`
+- AND IConfig MUST NOT be updated
+
+#### 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`.
+
+#### Scenario: Complete token set
+- GIVEN a token set like `rijkshuisstijl.css`
+- WHEN loaded after `defaults.css`
+- THEN it MUST override `--nldesign-color-primary` with the organization's primary color
+- AND it MUST override `--nldesign-color-primary-text` for accessible text on the primary color
+- AND it MAY override any other `--nldesign-*` variable defined in `defaults.css`
+
+#### Scenario: Incomplete token set (partial overrides)
+- GIVEN a token set that only defines `--nldesign-color-primary` and `--nldesign-color-primary-text`
+- 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')`
+- WHEN the theme is rendered
+- 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 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`, `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
+- AND the token set `denhaag` exists
+- WHEN `POST /apps/nldesign/settings/tokenset` is called with `tokenSet=denhaag`
+- 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 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, 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
+- WHEN the `css/tokens/` directory is scanned
+- 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-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/`, 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.
+
+### Standards & References
+- NL Design System community design tokens: https://nldesignsystem.nl/
+- W3C Design Tokens community group specification: https://design-tokens.github.io/community-group/format/
+- CSS Custom Properties specification: https://www.w3.org/TR/css-variables-1/
+- 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
+- WCAG 2.1 AA contrast requirements for token set color combinations
diff --git a/openspec/specs/token-sets/tasks.md b/openspec/changes/archive/2026-03-21-token-sets/specs/token-sets/tasks.md
similarity index 100%
rename from openspec/specs/token-sets/tasks.md
rename to openspec/changes/archive/2026-03-21-token-sets/specs/token-sets/tasks.md
diff --git a/openspec/changes/archive/2026-03-21-token-sets/tasks.md b/openspec/changes/archive/2026-03-21-token-sets/tasks.md
new file mode 100644
index 0000000..0563cd0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-sets/tasks.md
@@ -0,0 +1,10 @@
+# Tasks: token-sets
+- [x] 1.1 TokenSetService with filesystem discovery
+- [x] 1.2 Manifest reading and metadata merging
+- [x] 1.3 Auto-generated names for missing manifest entries
+- [x] 1.4 Path traversal prevention
+- [x] 1.5 Alphabetical sort
+- [x] 1.6 design_system field support
+- [x] 2.1 Unit tests — N/A (filesystem service)
+- [x] 3.1 Documentation at docs/features/token-sets.md (exists)
+- [x] 4.1 i18n — token set names from manifest
diff --git a/openspec/changes/archive/2026-03-21-token-sync-workflow/.openspec.yaml b/openspec/changes/archive/2026-03-21-token-sync-workflow/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-sync-workflow/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-token-sync-workflow/design.md b/openspec/changes/archive/2026-03-21-token-sync-workflow/design.md
new file mode 100644
index 0000000..b699891
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-sync-workflow/design.md
@@ -0,0 +1,10 @@
+# Design: token-sync-workflow
+
+## Context
+GitHub Actions workflow for nightly sync of NL Design System token sets from upstream nl-design-system/themes repository.
+
+## Decisions
+1. Nightly schedule with manual trigger
+2. Change detection via hash comparison
+3. PR-based updates with auto-generated CSS
+4. README sources section for attribution
diff --git a/openspec/changes/archive/2026-03-21-token-sync-workflow/proposal.md b/openspec/changes/archive/2026-03-21-token-sync-workflow/proposal.md
new file mode 100644
index 0000000..5587dc0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-sync-workflow/proposal.md
@@ -0,0 +1,22 @@
+# Token Sync Workflow Specification
+
+## Problem
+Automates the synchronization of NL Design System token sets from the upstream `nl-design-system/themes` repository via a nightly GitHub Actions workflow that generates CSS token files and opens PRs when changes are detected.
+
+## Proposed Solution
+Implement Token Sync Workflow Specification following the detailed specification. Key requirements include:
+- Requirement: Nightly Schedule
+- Requirement: Change Detection
+- Requirement: PR-Based Updates
+- Requirement: Token Generation Script
+- Requirement: README Sources Section
+
+## Scope
+This change covers all requirements defined in the token-sync-workflow specification.
+
+## Success Criteria
+- Scheduled execution
+- Manual trigger
+- No upstream changes
+- Upstream changes detected
+- New organization added upstream
diff --git a/openspec/changes/archive/2026-03-21-token-sync-workflow/specs/token-sync-workflow/spec.md b/openspec/changes/archive/2026-03-21-token-sync-workflow/specs/token-sync-workflow/spec.md
new file mode 100644
index 0000000..1b5980f
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-sync-workflow/specs/token-sync-workflow/spec.md
@@ -0,0 +1,93 @@
+---
+status: implemented
+---
+
+# Token Sync Workflow Specification
+
+## Purpose
+Automates the synchronization of NL Design System token sets from the upstream `nl-design-system/themes` repository via a nightly GitHub Actions workflow that generates CSS token files and opens PRs when changes are detected.
+
+## Requirements
+
+### Requirement: Nightly Schedule
+The sync workflow MUST run automatically every night to check for upstream token changes.
+
+#### Scenario: Scheduled execution
+- GIVEN the GitHub Actions workflow `sync-tokens.yml` is configured
+- WHEN the cron schedule triggers (daily at 3 AM UTC)
+- THEN the workflow MUST clone the `nl-design-system/themes` repository
+- AND it MUST run the token generation script
+
+#### Scenario: Manual trigger
+- GIVEN a maintainer wants to sync tokens immediately
+- WHEN they trigger the workflow manually via `workflow_dispatch`
+- THEN the workflow MUST execute the same steps as the nightly run
+
+### Requirement: Change Detection
+The workflow MUST detect whether upstream token changes result in different CSS output before creating a PR.
+
+#### Scenario: No upstream changes
+- GIVEN the upstream token files have not changed since the last sync
+- WHEN the generation script runs and produces identical CSS output
+- THEN the workflow MUST NOT create a PR
+- AND it MUST exit successfully
+
+#### Scenario: Upstream changes detected
+- GIVEN the upstream token files have changed
+- WHEN the generation script produces different CSS output
+- THEN the workflow MUST create a PR with the updated token files
+
+#### Scenario: New organization added upstream
+- GIVEN a new organization directory appears in the themes repository
+- WHEN the generation script runs
+- THEN a new CSS token file MUST be generated
+- AND `token-sets.json` MUST be updated with the new organization
+- AND the PR MUST include both the new CSS file and the updated manifest
+
+### Requirement: PR-Based Updates
+Token updates MUST be delivered as pull requests, not direct commits, to allow review before merging.
+
+#### Scenario: PR creation
+- GIVEN the generation script produced changed CSS output
+- WHEN the workflow creates a PR
+- THEN the PR title MUST be `chore: sync NL Design System tokens`
+- AND the PR body MUST describe which token sets were added or changed
+- AND the PR MUST be created on a branch named `chore/sync-nldesign-tokens`
+
+#### Scenario: Existing open PR
+- GIVEN a sync PR from a previous run is still open
+- WHEN a new sync run detects additional changes
+- THEN the workflow MUST update the existing branch and PR rather than creating a duplicate
+
+### Requirement: Token Generation Script
+The system MUST include a generation script that converts upstream JSON token files to CSS custom property files.
+
+#### Scenario: Script reads upstream tokens
+- GIVEN the themes repository is cloned to a local path
+- WHEN `node scripts/generate-tokens.mjs /path/to/themes` is executed
+- THEN the script MUST process all directories under `proprietary/` that contain token files
+- AND the script MUST output CSS files to `css/tokens/`
+
+#### Scenario: Script handles malformed input
+- GIVEN an upstream token JSON file contains invalid JSON
+- WHEN the generation script encounters it
+- THEN the script MUST log a warning for that organization
+- AND it MUST continue processing other organizations
+- AND it MUST NOT overwrite the existing CSS file for that organization
+
+#### Scenario: Script updates manifest
+- GIVEN the script processes all upstream organizations
+- WHEN it finishes generating CSS files
+- THEN it MUST update `token-sets.json` with the complete list of processed organizations
+- AND it MUST preserve any manually added metadata (descriptions, display names)
+
+### Requirement: README Sources Section
+The README MUST document the token sync architecture and link to upstream sources.
+
+#### Scenario: Developer reads README
+- GIVEN a developer opens the nldesign README
+- WHEN they look for information about token sources
+- THEN they MUST find links to the NL Design System themes repository
+- AND they MUST find links to the NL Design System design tokens handbook
+- AND they MUST find an explanation of how the nightly sync workflow operates
+- AND they MUST find instructions for adding a new token set manually
diff --git a/openspec/changes/archive/2026-03-21-token-sync-workflow/tasks.md b/openspec/changes/archive/2026-03-21-token-sync-workflow/tasks.md
new file mode 100644
index 0000000..f84d482
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-token-sync-workflow/tasks.md
@@ -0,0 +1,8 @@
+# Tasks: token-sync-workflow
+- [x] 1.1 GitHub Actions workflow with nightly schedule
+- [x] 1.2 Token generation script from upstream JSON
+- [x] 1.3 Change detection and PR creation
+- [x] 1.4 README sources section
+- [x] 2.1 Unit tests — N/A (CI workflow)
+- [x] 3.1 Documentation — workflow documented
+- [x] 4.1 i18n — N/A (CI automation)
diff --git a/openspec/changes/archive/2026-03-21-vng-token-set/.openspec.yaml b/openspec/changes/archive/2026-03-21-vng-token-set/.openspec.yaml
new file mode 100644
index 0000000..d8b0ed0
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-vng-token-set/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-20
diff --git a/openspec/changes/archive/2026-03-21-vng-token-set/design.md b/openspec/changes/archive/2026-03-21-vng-token-set/design.md
new file mode 100644
index 0000000..59c1e6f
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-vng-token-set/design.md
@@ -0,0 +1,9 @@
+# Design: vng-token-set
+
+## Context
+VNG (Vereniging Nederlandse Gemeenten) token set manually converted from tilburg-woo-ui project, not available in upstream repository.
+
+## Decisions
+1. Manual conversion since not in upstream themes repo
+2. VNG blue (#154273) as primary color
+3. Preserve VNG palette tokens
diff --git a/openspec/changes/archive/2026-03-21-vng-token-set/proposal.md b/openspec/changes/archive/2026-03-21-vng-token-set/proposal.md
new file mode 100644
index 0000000..0ae4dad
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-vng-token-set/proposal.md
@@ -0,0 +1,22 @@
+# VNG Token Set Specification
+
+## Problem
+Define requirements for adding VNG (Vereniging Nederlandse Gemeenten) as a selectable design token set in the nldesign Nextcloud app. VNG tokens are manually converted from the tilburg-woo-ui project since they are not available in the upstream nl-design-system/themes repository.
+
+## Proposed Solution
+Implement VNG Token Set Specification following the detailed specification. Key requirements include:
+- Requirement: VNG Token CSS File
+- Requirement: VNG Semantic Color Mapping
+- Requirement: VNG Typography Tokens
+- Requirement: VNG Spacing and Border Tokens
+- Requirement: VNG Header and Background Tokens
+
+## Scope
+This change covers all requirements defined in the vng-token-set specification.
+
+## Success Criteria
+- VNG token file exists and loads
+- VNG palette tokens are preserved
+- Primary colors use VNG blue
+- Status colors use VNG palette
+- Text colors use VNG values
diff --git a/openspec/changes/archive/2026-03-21-vng-token-set/specs/vng-token-set/spec.md b/openspec/changes/archive/2026-03-21-vng-token-set/specs/vng-token-set/spec.md
new file mode 100644
index 0000000..eac35e9
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-vng-token-set/specs/vng-token-set/spec.md
@@ -0,0 +1,107 @@
+---
+status: implemented
+---
+
+# VNG Token Set Specification
+
+## Purpose
+Define requirements for adding VNG (Vereniging Nederlandse Gemeenten) as a selectable design token set in the nldesign Nextcloud app. VNG tokens are manually converted from the tilburg-woo-ui project since they are not available in the upstream nl-design-system/themes repository.
+
+## Requirements
+
+### Requirement: VNG Token CSS File
+The system MUST provide a `css/tokens/vng.css` file containing VNG design tokens in `:root` scope with `--nldesign-*` semantic tokens and `--vng-*` organization palette tokens.
+
+#### Scenario: VNG token file exists and loads
+- GIVEN the nldesign app is installed
+- WHEN the VNG token set is selected in admin settings
+- THEN `css/tokens/vng.css` is loaded into the page
+- AND all `--nldesign-*` semantic tokens are defined with VNG-specific values
+
+#### Scenario: VNG palette tokens are preserved
+- GIVEN the VNG token file is loaded
+- WHEN a developer inspects the CSS custom properties
+- THEN `--vng-color-*` tokens exist for the full VNG color palette (blue, red, green, orange, pink, gray shades)
+- AND these palette tokens use resolved hex values (not var() references to tilburg tokens)
+
+### Requirement: VNG Semantic Color Mapping
+The VNG token file MUST map the VNG color palette to all `--nldesign-*` semantic color tokens.
+
+#### Scenario: Primary colors use VNG blue
+- GIVEN the VNG token set is active
+- WHEN the primary color tokens are evaluated
+- THEN `--nldesign-color-primary` SHALL be `#003865` (VNG dark blue)
+- AND `--nldesign-color-primary-hover` SHALL be `#026596` (VNG medium blue)
+- AND `--nldesign-color-primary-text` SHALL be `#ffffff`
+- AND `--nldesign-color-primary-light` SHALL be a light blue derived from the VNG palette
+
+#### Scenario: Status colors use VNG palette
+- GIVEN the VNG token set is active
+- WHEN status color tokens are evaluated
+- THEN `--nldesign-color-error` SHALL use VNG red (#bf1a12)
+- AND `--nldesign-color-success` SHALL use VNG green (#01745a)
+- AND `--nldesign-color-warning` SHALL use VNG orange (#d45f01)
+
+#### Scenario: Text colors use VNG values
+- GIVEN the VNG token set is active
+- WHEN text color tokens are evaluated
+- THEN `--nldesign-color-text` SHALL be `#333333` (VNG black-txt)
+- AND `--nldesign-color-text-muted` SHALL be a gray from the VNG palette
+
+### Requirement: VNG Typography Tokens
+The VNG token file MUST define typography tokens based on VNG's Avenir font family.
+
+#### Scenario: Font family is set to Avenir
+- GIVEN the VNG token set is active
+- WHEN typography tokens are evaluated
+- THEN `--nldesign-typography-font-family` SHALL include 'Avenir' as the primary font
+- AND a sans-serif fallback SHALL be specified
+
+#### Scenario: Font sizes follow VNG scale
+- GIVEN the VNG token set is active
+- WHEN font size tokens are evaluated
+- THEN heading and body font sizes SHALL be derived from the VNG typography scale (sm: 14px, md: 16px, lg: 20px, xl: 24px, etc.)
+
+### Requirement: VNG Spacing and Border Tokens
+The VNG token file MUST define spacing and border tokens derived from the VNG design system.
+
+#### Scenario: Spacing tokens are defined
+- GIVEN the VNG token set is active
+- WHEN spacing tokens are evaluated
+- THEN `--nldesign-spacing-*` tokens SHALL map to VNG spacing values
+
+#### Scenario: Border radius uses VNG values
+- GIVEN the VNG token set is active
+- WHEN border tokens are evaluated
+- THEN `--nldesign-border-radius` SHALL use VNG border-radius-md (8px)
+
+### Requirement: VNG Header and Background Tokens
+The VNG token file MUST define header and background tokens using VNG colors.
+
+#### Scenario: Header uses VNG dark blue
+- GIVEN the VNG token set is active
+- WHEN header tokens are evaluated
+- THEN `--nldesign-color-header-background` SHALL be `#003865` (VNG dark blue)
+- AND `--nldesign-color-header-text` SHALL provide sufficient contrast (WCAG AA)
+
+### Requirement: Token Set Manifest Entry
+The `token-sets.json` manifest MUST include an entry for VNG.
+
+#### Scenario: VNG appears in manifest
+- GIVEN `token-sets.json` is read by TokenSetService
+- WHEN the available token sets are listed
+- THEN an entry with `"id": "vng"`, `"name": "VNG Vereniging Nederlandse Gemeenten"`, and a description SHALL exist
+
+#### Scenario: VNG appears in admin dropdown
+- GIVEN the admin opens nldesign settings
+- WHEN the token set dropdown is rendered
+- THEN "VNG Vereniging Nederlandse Gemeenten" SHALL appear as a selectable option
+
+### Requirement: No Utrecht Component Token Duplication
+The VNG token file MUST NOT include `--utrecht-*` component tokens, as these are handled by the `utrecht-bridge.css` layer.
+
+#### Scenario: Utrecht tokens are absent from VNG file
+- GIVEN the VNG token file is loaded
+- WHEN the CSS custom properties are inspected
+- THEN no `--utrecht-*` prefixed tokens SHALL be present
+- AND component styling SHALL flow through the existing `--nldesign-component-*` → `--utrecht-*` bridge
diff --git a/openspec/changes/archive/2026-03-21-vng-token-set/tasks.md b/openspec/changes/archive/2026-03-21-vng-token-set/tasks.md
new file mode 100644
index 0000000..aacf7cc
--- /dev/null
+++ b/openspec/changes/archive/2026-03-21-vng-token-set/tasks.md
@@ -0,0 +1,8 @@
+# Tasks: vng-token-set
+- [x] 1.1 VNG token CSS file in css/tokens/
+- [x] 1.2 VNG palette and semantic color tokens
+- [x] 1.3 VNG typography and spacing tokens
+- [x] 1.4 token-sets.json manifest entry
+- [x] 2.1 Unit tests — N/A (CSS file)
+- [x] 3.1 Documentation — token set documented
+- [x] 4.1 i18n — N/A (CSS tokens)
diff --git a/openspec/specs/admin-settings/spec.md b/openspec/specs/admin-settings/spec.md
index a3f0a20..a722233 100644
--- a/openspec/specs/admin-settings/spec.md
+++ b/openspec/specs/admin-settings/spec.md
@@ -1,17 +1,18 @@
 ---
-status: reviewed
+status: implemented
 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/component-tokens/spec.md b/openspec/specs/component-tokens/spec.md
index d85648e..fd2326b 100644
--- a/openspec/specs/component-tokens/spec.md
+++ b/openspec/specs/component-tokens/spec.md
@@ -1,9 +1,13 @@
+---
+status: implemented
+---
+
 # Component Tokens Specification
 
 ## Purpose
 Introduces component-level NL Design System tokens using the `--nldesign-component-*` prefix, with a temporary bridge file that maps the current `--utrecht-*` component tokens to the nldesign namespace.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: NLDesign Component Token Prefix
 All component-level tokens MUST use the `--nldesign-component-*` prefix for consistency with the rest of the nldesign token system.
diff --git a/openspec/specs/css-architecture/spec.md b/openspec/specs/css-architecture/spec.md
index 11896a6..1816dfe 100644
--- a/openspec/specs/css-architecture/spec.md
+++ b/openspec/specs/css-architecture/spec.md
@@ -1,74 +1,119 @@
 ---
-status: reviewed
+status: implemented
 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/custom-css-overrides/spec.md b/openspec/specs/custom-css-overrides/spec.md
index 70a4ed9..a06b119 100644
--- a/openspec/specs/custom-css-overrides/spec.md
+++ b/openspec/specs/custom-css-overrides/spec.md
@@ -1,9 +1,13 @@
+---
+status: implemented
+---
+
 # Custom CSS Overrides Specification
 
 ## Purpose
 Defines the CSS file persistence layer for user-defined token customizations. `custom-overrides.css` is the single write target for all theme editor output. It is loaded last in the CSS stack so user intent always wins. NL Design token set CSS files are read-only presets and are never modified.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Custom Overrides File
 The system MUST maintain a `custom-overrides.css` file in the nldesign app's CSS directory. This file MUST be written exclusively by the theme editor backend — no other write path exists.
diff --git a/openspec/specs/docs-content/spec.md b/openspec/specs/docs-content/spec.md
index 4c09f38..7132aeb 100644
--- a/openspec/specs/docs-content/spec.md
+++ b/openspec/specs/docs-content/spec.md
@@ -1,4 +1,8 @@
-## ADDED Requirements
+---
+status: implemented
+---
+
+## Requirements
 
 ### Requirement: Documentation landing page
 The documentation site SHALL have an `intro.md` file at `docs/intro.md` that serves as the entry point for all documentation. It SHALL provide a high-level overview of what nldesign is, link to key sections (getting started, features, reference), and use the Docusaurus `slug: /` frontmatter to become the docs root.
diff --git a/openspec/specs/extended-token-sets/spec.md b/openspec/specs/extended-token-sets/spec.md
index 724fe6f..08b066c 100644
--- a/openspec/specs/extended-token-sets/spec.md
+++ b/openspec/specs/extended-token-sets/spec.md
@@ -1,9 +1,13 @@
+---
+status: implemented
+---
+
 # Extended Token Sets Specification
 
 ## Purpose
 Expands the nldesign app from 5 manually maintained token sets to all available NL Design System organization token sets (48+), using auto-generation from official upstream JSON token files.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Support All Available Token Sets
 The system MUST support all organization token sets available in the `nl-design-system/themes` repository.
diff --git a/openspec/specs/hide-slogan/spec.md b/openspec/specs/hide-slogan/spec.md
index 57a618c..623625a 100644
--- a/openspec/specs/hide-slogan/spec.md
+++ b/openspec/specs/hide-slogan/spec.md
@@ -1,17 +1,18 @@
 ---
-status: reviewed
+status: implemented
 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..f5704ff 100644
--- a/openspec/specs/menu-labels/spec.md
+++ b/openspec/specs/menu-labels/spec.md
@@ -1,22 +1,24 @@
 ---
-status: reviewed
+status: implemented
 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/nextcloud-variable-mapping/spec.md b/openspec/specs/nextcloud-variable-mapping/spec.md
index 1e5c71c..265abb2 100644
--- a/openspec/specs/nextcloud-variable-mapping/spec.md
+++ b/openspec/specs/nextcloud-variable-mapping/spec.md
@@ -1,9 +1,13 @@
+---
+status: implemented
+---
+
 # Nextcloud Variable Mapping Specification
 
 ## Purpose
 Provides a complete, audited mapping between all Nextcloud CSS custom properties and `--nldesign-*` design tokens, with comprehensive documentation and a defaults layer that ensures all tokens always have a value.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Complete Nextcloud Variable Audit
 The system MUST include a mapping for every CSS custom property defined by Nextcloud's theming system (DefaultTheme.php, CommonThemeTrait.php, and core SCSS files).
diff --git a/openspec/specs/nl-design/spec.md b/openspec/specs/nl-design/spec.md
index 5d3ec9e..cffb351 100644
--- a/openspec/specs/nl-design/spec.md
+++ b/openspec/specs/nl-design/spec.md
@@ -1,3 +1,7 @@
+---
+status: implemented
+---
+
 # NL Design System Compliance — Delta Spec
 
 ## Purpose
diff --git a/openspec/specs/prometheus-metrics/spec.md b/openspec/specs/prometheus-metrics/spec.md
index 94540a5..3603e58 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: implemented
+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-dialog/spec.md b/openspec/specs/theming-sync-dialog/spec.md
index f6e5eb6..288b65f 100644
--- a/openspec/specs/theming-sync-dialog/spec.md
+++ b/openspec/specs/theming-sync-dialog/spec.md
@@ -1,9 +1,13 @@
+---
+status: implemented
+---
+
 # Theming Sync Dialog Specification
 
 ## Purpose
 After an admin selects a different token set in nldesign, offer to automatically update Nextcloud's built-in theming values (primary color, background color, logo, background image) to match the selected token set, preventing a split-brain theming state where CSS tokens and Nextcloud theming are out of sync.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Theming Metadata in Token Sets
 Each token set entry in `token-sets.json` MAY include a `theming` object with optional fields: `primary_color`, `background_color`, `logo`, and `background`.
diff --git a/openspec/specs/theming-sync/spec.md b/openspec/specs/theming-sync/spec.md
index 917a845..6096971 100644
--- a/openspec/specs/theming-sync/spec.md
+++ b/openspec/specs/theming-sync/spec.md
@@ -1,17 +1,18 @@
 ---
-status: reviewed
+status: implemented
 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-editor-ui/spec.md b/openspec/specs/token-editor-ui/spec.md
index bb56262..b2edd98 100644
--- a/openspec/specs/token-editor-ui/spec.md
+++ b/openspec/specs/token-editor-ui/spec.md
@@ -1,9 +1,13 @@
+---
+status: implemented
+---
+
 # Token Editor UI Specification
 
 ## Purpose
 Provides a tabbed admin settings panel for browsing and editing all editable Nextcloud CSS custom properties (`--color-*`) with live preview and per-token reset controls. Changes are previewed in the browser before being committed to `custom-overrides.css`.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Token Editor Panel
 The admin settings page MUST include a token editor panel below the existing NL Design token-set selector. The panel MUST be rendered as a Vue component within the existing nldesign admin settings template.
diff --git a/openspec/specs/token-import-export/spec.md b/openspec/specs/token-import-export/spec.md
index 1069565..276a3d4 100644
--- a/openspec/specs/token-import-export/spec.md
+++ b/openspec/specs/token-import-export/spec.md
@@ -1,9 +1,13 @@
+---
+status: implemented
+---
+
 # Token Import/Export Specification
 
 ## Purpose
 Allows admins to download the current `custom-overrides.css` as a portable file and upload a previously saved file to restore or share a token configuration. Only known, editable Nextcloud `--color-*` tokens are accepted on import — unknown variables are silently rejected and their count is reported.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Export Current Overrides
 The admin settings panel MUST provide a **Download** button that exports the current `custom-overrides.css` as a file download.
diff --git a/openspec/specs/token-set-apply-dialog/spec.md b/openspec/specs/token-set-apply-dialog/spec.md
index 07998a6..6a8ebba 100644
--- a/openspec/specs/token-set-apply-dialog/spec.md
+++ b/openspec/specs/token-set-apply-dialog/spec.md
@@ -1,9 +1,13 @@
+---
+status: implemented
+---
+
 # Token-Set Apply Dialog Specification
 
 ## Purpose
 Defines the modal dialog shown when an admin selects a new NL Design token set. The dialog shows which Nextcloud CSS variable values would change (resolved current value vs the value from the new token set), lets the admin check or uncheck individual changes, and writes only the checked values to `custom-overrides.css`. The NL Design token set CSS file itself is never applied directly.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Dialog Trigger
 Selecting a different NL Design token set from the selector MUST open the apply dialog instead of immediately switching themes.
diff --git a/openspec/specs/token-set-dropdown/spec.md b/openspec/specs/token-set-dropdown/spec.md
index 1c06634..fc1cb87 100644
--- a/openspec/specs/token-set-dropdown/spec.md
+++ b/openspec/specs/token-set-dropdown/spec.md
@@ -1,9 +1,13 @@
+---
+status: implemented
+---
+
 # Token Set Dropdown Specification
 
 ## Purpose
 Replace the radio button list for token set selection with a searchable dropdown (`<select>`) that scales to 400+ entries, improving usability as the number of available token sets grows.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Dropdown Token Set Selector
 The admin settings page MUST use a `<select>` dropdown instead of radio buttons for token set selection.
diff --git a/openspec/specs/token-sets/spec.md b/openspec/specs/token-sets/spec.md
index abe9bc9..f932b8c 100644
--- a/openspec/specs/token-sets/spec.md
+++ b/openspec/specs/token-sets/spec.md
@@ -1,12 +1,13 @@
 ---
-status: reviewed
+status: implemented
 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
diff --git a/openspec/specs/token-sync-workflow/spec.md b/openspec/specs/token-sync-workflow/spec.md
index ef90804..1b5980f 100644
--- a/openspec/specs/token-sync-workflow/spec.md
+++ b/openspec/specs/token-sync-workflow/spec.md
@@ -1,9 +1,13 @@
+---
+status: implemented
+---
+
 # Token Sync Workflow Specification
 
 ## Purpose
 Automates the synchronization of NL Design System token sets from the upstream `nl-design-system/themes` repository via a nightly GitHub Actions workflow that generates CSS token files and opens PRs when changes are detected.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: Nightly Schedule
 The sync workflow MUST run automatically every night to check for upstream token changes.
diff --git a/openspec/specs/vng-token-set/spec.md b/openspec/specs/vng-token-set/spec.md
index 50c9ec7..eac35e9 100644
--- a/openspec/specs/vng-token-set/spec.md
+++ b/openspec/specs/vng-token-set/spec.md
@@ -1,9 +1,13 @@
+---
+status: implemented
+---
+
 # VNG Token Set Specification
 
 ## Purpose
 Define requirements for adding VNG (Vereniging Nederlandse Gemeenten) as a selectable design token set in the nldesign Nextcloud app. VNG tokens are manually converted from the tilburg-woo-ui project since they are not available in the upstream nl-design-system/themes repository.
 
-## ADDED Requirements
+## Requirements
 
 ### Requirement: VNG Token CSS File
 The system MUST provide a `css/tokens/vng.css` file containing VNG design tokens in `:root` scope with `--nldesign-*` semantic tokens and `--vng-*` organization palette tokens.