[OpenSpec] full-nextcloud-token-support-from-nldesign

[rubenvdlinde]

Summary

Create a complete, documented mapping between all Nextcloud CSS variables and NL Design System tokens, expand the nldesign app to support all available NL Design System token sets (currently 48 organizations), introduce component-level token support, and automate token updates via a nightly GitHub Actions workflow.

Motivation

• Incomplete Nextcloud coverage — Many Nextcloud CSS variables are not mapped, causing visual inconsistencies
• Limited organization support — 48+ token sets exist in the ecosystem but only 5 are supported
• No component-level tokens — NL Design System component tokens (button, heading, form, etc.) are not yet supported

Task Checklist

1. Nextcloud Variable Audit

• 1.1 Extract all CSS custom properties from Nextcloud theming

2. Defaults Layer

• 2.1 Create defaults.css with all --nldesign-* token defaults

3. Token Generation Script

• 3.1 Create generate-tokens.mjs script
• 3.2 Create token-sets.json manifest generation
• 3.3 Run generation script to produce all 48+ token CSS files

4. Utrecht Bridge

• 4.1 Create utrecht-bridge.css

5. Overrides Rewrite

• 5.1 Rewrite overrides.css with all Nextcloud variables
• 5.2 Update theme.css with new token mappings

6. PHP Changes

• 6.1 Create TokenSetService for filesystem-based token discovery
• 6.2 Update SettingsController for dynamic token validation
• 6.3 Update Admin settings and Application bootstrap

7. GitHub Actions Workflow

• 7.1 Create sync-tokens.yml workflow
• 7.2 Add change detection and PR update logic

8. Documentation

• 8.1 Create mappings.md documentation table
• 8.2 Update README with sources section

9. Verification

• 9.1 Visual regression test with existing 5 token sets
• 9.2 Test with incomplete token set
• 9.3 Test dynamic admin dropdown with all token sets
• 9.4 End-to-end workflow test

OpenSpec Change

• Change: full-nextcloud-token-support-from-nldesign
• Schema: conduction
• Artifacts: proposal, design, specs (5 files), tasks