SVAII/SURF Design System (PoC)

Welkom bij het SVAII Design System! Deze architectuur benut de kracht van IBM Carbon, Token Studio en Style Dictionary om een schaalbaar en multi-tenant design system te bieden.

Het stelt het Design Systeem Core Team in staat om strikte controle te behouden over componenten en layouts, terwijl individuele productteams de mogelijkheid krijgen om veilig en direct hun eigen merkkleuren te implementeren.

Voor vragen kun je contact opnemen met Jonathan Arends

1. Architectuuroverzicht: De 3-Lagen

Ons systeem werkt door gebruik te maken van de CSS-cascade. In plaats van in te gaan tegen de native theming van IBM Carbon, stapelen we drie afzonderlijke lagen van CSS-variabelen op elkaar. De browser leest deze van onder naar boven, waardoor verschillende merken en weergavemodi (modes) harmonieus naast elkaar kunnen bestaan.

| Laag | Naam | Wat het doet | Hoe het werkt | | :--- | :--- | :--- | :--- | | 1 | IBM Carbon Base (De "Mode") | Bepaalt Light/Dark mode achtergronden, basistekstkleuren en kerninteracties. | Via native Carbon-attributen zoals [data-carbon-theme="g100"]. | | 2 | SVAII Core (Het "Systeem") | Definieert bedrijfsbrede standaarden (bijv. 1rem border-radius voor alle knoppen). | Via een core.css bestand dat zich richt op de :root. | | 3 | Team Themes (Het "Merk") | Overschrijft specifieke semantische variabelen met de merkkleuren van een team. | Via een [team-naam].css bestand dat de rest overschrijft. |

2. Voor Designers: Hoe maak je een Team Theme

Als designer voor een specifiek productteam hoef je geen componenten opnieuw op te bouwen of los te koppelen (detachen) van de officiële library. Je creëert simpelweg een "skin" voor jouw merk.

Stappenplan in Figma:

1. Open Token Studio: Open de Token Studio plugin in het SVAII Figma masterbestand.
2. Dupliceer het Default Theme: Zoek de tokenset genaamd theme-svaii (of theme-default), klik met de rechtermuisknop en dupliceer deze.
3. Hernoem de set: Geef de gedupliceerde set de naam van jouw team (bijv. theme-blue).
4. Bewerk je kleuren: Verander binnen je nieuwe set de hex-waarden zodat ze bij jouw merk passen.

[!IMPORTANT] Verander nooit de namen van de variabelen (houd brand-primary bijvoorbeeld exact zoals het is), verander alleen de waarden. Als je de namen aanpast, breekt de koppeling met de onderliggende IBM Carbon componenten.

5. Preview:

[!TIP] Snel je wijzigingen testen? Vink in Token Studio de vakjes aan voor global, core en je nieuwe theme-blue set. Je ziet de Carbon-componenten op je canvas dan direct magisch updaten naar jouw nieuwe merk!

6. Push naar GitHub: Gebruik de ingebouwde GitHub-integratie van Token Studio om je wijzigingen naar een nieuwe branch te pushen en open een Pull Request.

3. Voor het Core Team: Het Globale Systeem Beheren

Het Core Team beheert de onderliggende motor. Als jullie een structurele wijziging doorvoeren, wordt deze automatisch naar elk team doorgegeven (cascade).

Een globale wijziging doorvoeren:

1. Open Token Studio in Figma.
2. Navigeer naar de core tokenset (of de plek waar de component-overrides zich bevinden).
3. Werk de waarde bij (verander bijvoorbeeld --svaii-button-radius van 1rem naar 2rem).
4. Push de wijzigingen direct naar de main branch.
5. Het Resultaat: De pipeline gaat draaien, NPM publiceert een nieuwe versie, en de eerstvolgende keer dat welk team dan ook npm install uitvoert, worden hun knoppen automatisch geüpdatet naar de nieuwe radius.

4. De Pipeline: Design-to-Code

Wanneer een designer op "Push" klikt in Token Studio, gebeurt het volgende op de achtergrond:

1. GitHub Action Triggert: De repository detecteert een update aan tokens.json.
2. Style Dictionary Draait: Ons sd.config.js script wordt geactiveerd en gebruikt @tokens-studio/sd-transforms om data om te zetten.
3. Kebab-Case Formattering: Alle variabelen worden in CSS kebab-case geforceerd (bijv. --cds-button-primary) voor compatibiliteit met IBM Carbon.
4. Bestandsgeneratie: Het script loopt door de data en genereert de volgende directorystructuur in de output:

dist/
└── css/
    ├── core.css
    └── brands/
        ├── theme-svaii.css
        └── theme-blue.css

NPM Publish: Semantic Release verhoogt het versienummer en publiceert het nieuwe package naar de npm-registry.

[!NOTE] Je hoeft deze pipeline nooit handmatig lokaal te draaien. De GitHub Action en Semantic Release zorgen ervoor dat alles op de achtergrond wordt afgehandeld en gepubliceerd zodra een PR is gemerged.

5. Voor Developers: Implementatiegids

Het gebruik van het design system is ontzettend lichtgewicht. Er zijn geen zware JavaScript-providers of complexe wrappers. Het leunt volledig op standaard CSS-imports.

Stap 1: Installeer het Package

npm install svaii-tokens-poc@latest

Stap 2: Importeer de CSS

Voeg de volgende code toe aan je globale stylesheet (bijv. styles.scss of App.css).

[!WARNING] De volgorde van je imports is essentieel! Omdat dit systeem op de CSS-cascade leunt, moet het team-thema altijd als laatste worden ingeladen, zodat deze de SVAII Core succesvol kan overschrijven.

/* 1. IBM Carbon (Bij gebruik van SCSS, laad hier je gewenste mode) */
@use '@carbon/styles/scss/themes';
@include themes.theme(themes.$g100); /* Voorbeeld: Dark Mode */

/* 2. SVAII Core (Vereist: Laadt de bedrijfsbrede structuur en radiussen) */
@import 'svaii-tokens-poc/dist/css/core.css';

/* 3. Jouw Team Merk (Vereist: Overschrijft Core met jullie specifieke kleuren) */
@import 'svaii-tokens-poc/dist/css/brands/theme-blue.css';