Merge pull request #53 from ConductionNL/chore/specs-to-proposals

[Docs] Feature overview with GEMMA/TEC standards

Author: rubenvdlinde

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 |

docs/screenshots/.gitkeep

@@ -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.

openspec/changes/archive/2026-02-15-add-vng-token-set/specs/vng-token-set/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.

openspec/changes/archive/2026-03-02-enhance-docs-website/specs/docs-content/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.

openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/custom-css-overrides/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.

openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/nl-design/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.

openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-editor-ui/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.

openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-import-export/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.

openspec/changes/archive/2026-03-03-nextcloud-theme-editor/specs/token-set-apply-dialog/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.