Design system

Map: design-system/ · De derde tier van de fundering: de styling-laag die de frontend-kits consumeren in plaats van herimplementeren.

Waar kits mechaniek leveren en capability-modules een vermogen, levert het design system de visuele taal — merkneutraal, zodat elk product er zijn eigen identiteit overheen legt.

Waarom het naast foundation/ staat en niet erin

Het is functioneel onderdeel van de fundering, maar fysiek een eigen deelproject. Het heeft zijn eigen package-lock.json, zijn eigen build (tokenpipeline + vue-tsc), een geneste Nuxt-docssite onder server/ met een tweede lockfile, en een Playwright-suite — geen daarvan overleeft een root---workspaces-fan-out intact. Dezelfde reden waarom de foundation zijn workspaces liet vallen.

Clone-and-rebrand, geen runtime-theming

Het model is expliciet: je kopieert het design system je product in. Daarna hoort het bij dat product.

Wel	Niet
Clonen per product	Als dependency delen
Eigen versie per kopie	Upstream-koppeling
Rebranden via één bestand	Multi-tenant runtime-theming
Publiceren onder eigen scope: @seifer-webapp-factory/<product>-design-system	Eén gedeeld package

Rebrandkosten horen bijna nul te zijn, en een LLM moet het uit één voor de hand liggend bestand kunnen doen.

De vier tokenlagen

Dit is waarom de rebrand goedkoop is: alles hangt aan één bestand.

De enige regel

Bewerk tokens/brand.json en draai npm run build:tokens. Bewerk niettokens/semantics/ of een <Naam>.tokens.json — die verwijzen indirect naar brand.json. En hardcode nooit een hex in component-SCSS.

rebrand — de skill

Wat je in brand.json zet:

Veld	Wat
name	Productnaam
palette.<rol>.ramp	Welke primitive-ramp hoort bij primary, secondary, accent, success, warning, danger, info, neutral
fonts.{sans, display, mono}	CSS-fontstacks
fonts.faces	@font-face-entries — alleen bij eigen .woff2
feel.radiusScale	fibonacci | linear
feel.shadowDepth	subtle | default | dramatic
feel.useGradients	boolean

De beschikbare ramps staan in tokens/primitives/color.json — neutral, navy, blue, purple, orange, amber, yellow, green, red, pink, teal. Een nieuwe ramp voeg je daar éérst toe, met 12 tinten (50, 100, …, 950).

De verificatiestap

Na npm run build:tokens:

1. Lees dist/css/tokens.css
2. Grep naar de hexcodes van het vorige primaire ramp
3. Blijft er iets staan → er lekt een brand-vorm door. Zoek in tokens/components/*.json naar directe primitive-referenties en vervang ze door semantische refs ({intent.action.*}, {surface.*}, {text.*}, {border.*})
4. Draai npm test en npm run typecheck

Waarom die grep erin staat

Zonder die stap lijkt een rebrand geslaagd terwijl het oude merk nog in een handvol componenten zit. Je ontdekt dat pas als iemand ernaar kijkt.

BRAND.md bevat drie uitgewerkte voor/na-snapshots: serious-fintech, warm-DTC en minimalist-SaaS. Voor precies die looks is apply-preset de kortere weg.

theme-manager — de theming-skill

Waar rebrand het mérk zet, bezit theme-manager de theme-lifecycle bovenop de per-thema co-located tokenarchitectuur.

Operatie	Doet
Toevoegen	"Voeg een high-contrast / print / [naam] thema toe"
Bijstellen	Losse tokenwaarden binnen één thema
Pariteit auditen	Verifiëren dat élk thema dezelfde set tokenkeys heeft
WCAG valideren	Contrast toetsen over alle thema's
Dekking tonen	Welke componenten missen een theme-X-tokenbestand
Extraheren	Een thema afleiden uit een afbeelding of URL — herschrijft het basisthema en her-synct de andere

De skill is tokens-only: hij raakt brand/primitives, .vue-bestanden en SCSS niet aan. En evidence_mode staat op required — elke aanbeveling citeert een pad, elke auditbevinding een file:line.

De overige skills

Skill	Doet
add-component	Een component toevoegen volgens het canonieke patroon — ook om een PrimeVue-component te repliceren
test-component	De drielaagse teststrategie: Vitest-contract + logica, Playwright per-component via de /isolate-route, axe-matrixdekking
apply-preset	Een benoemd preset toepassen
build-prototype-by-design-system	Een runnende multi-page prototype uit journeys, stories en personas — alléén met design-system-componenten
kanban-worker	Het bord autonoom richting DONE draaien
sync-template	Upstream-verbeteringen naar een productkopie halen ⚠️

sync-template werkt niet meer

De skill liet verbeteringen terugvloeien via een template-git-remote en een git merge-base-three-way-merge. Sinds de monorepo-migratie klopt geen van beide: deze map is geen repo-root meer (de paden die hij categoriseert zitten een niveau mis), en de monorepo deelt geen voorouder met bestaande kopieën. Tot hij herbouwd is op een pad-gescopete diff is syncen handwerk.

Wireframe-kit

wireframe-ds/ is een aparte laag met een ander doel: hand-getekende Rough.js-wireframecomponenten voor spoor 4 van de ideation-fase.

Package	@for-the-people-initiative/wireframe-kit
Zichtbaarheid	Publiek — het enige publieke package in deze repo
Gebruikt door	De wireframing-skill, die er een runnende Vue 3 + Vite-app mee scaffoldt
Waarom hand-getekend	Een wireframe die er af uitziet, krijgt feedback over kleuren. Een wireframe die er geschetst uitziet, krijgt feedback over de flow.

Eén scherm per bestand, automatisch ontdekte routes, een screen-picker-navigatie, per-platform device-frame-wrapping en click-through-bedrading via router.push.

Draaien

cd design-system
npm install
npm --prefix server install
npm run dev              # de Nuxt-docssite
npm run build:tokens     # na elke brand.json-wijziging
npm test && npm run typecheck

cd wireframe-ds
npm install
npm run storybook