01 — Brand Identity

“De onboarding is niet een formulier. Het is een gesprek over wie je bent.”

Brand identity in Beam bestaat uit twee fasen die naadloos op elkaar aansluiten:

Onboarding wizard (start.beambuilder.com) — verzamelt merkdata en levert een Brand JSON
Styling Builder (onderdeel van Beam dashboard) — vertaalt Brand JSON naar een levend design system

Het resultaat is merkinfrastructuur als service: één bron van waarheid voor alle visuele en tekstuele uitingen, bewaakt door AI en guardrails.

1. Onboarding Wizard

Een standalone web app op start.beambuilder.com die nieuwe gebruikers doorlopen bij het aanmaken van een site. Het resultaat is een Brand JSON die naar Beam wordt doorgestuurd als fundament voor alle content.

Twee fasen:

Fase A: Wizard — 7 vaste stappen. Snel, voorspelbaar, laagdrempelig.
Fase B: AI verfijning — Na de wizard analyseert de AI de data en stelt 3–5 gerichte vervolgvragen. Altijd overslaanbaar.

Twee entry points:

[ Start met wizard ]   of   [ Importeer bestaande site → URL invoeren ]

Bij URL import extraheert Beam automatisch kleuren, fonts en spacing als startpunt.

Stack:

Vite + React (consistent met Beam dashboard)
Hosting: CF Pages op eigen domein (start.beambuilder.com)
Supabase: gedeeld project met Beam (TBD — zie OQ-2 in README)
AI API: Claude voor verfijningsfase en afbeeldingsbeschrijvingen
R2: voor uploads (logo, teksten, media)

2. Wizard Stappen (1–7)

Stap 1: De Basis

Veld	Type	Verplicht
Bedrijfsnaam	tekst	✅
Slogan / tagline	tekst	❌
Korte beschrijving	textarea (max 300 tekens)	✅
Branche / sector	dropdown + “anders” optie	✅
Website URL (als die al bestaat)	tekst	❌

Stap 2: Doelgroep

Veld	Type	Verplicht
Wie is je ideale klant?	textarea	✅
B2B of B2C of beide?	single select	✅
Leeftijdsrange doelgroep	range slider	❌
Regio / markt	multi-select (lokaal, nationaal, internationaal)	✅

Stap 3: Tone of Voice

Visuele keuze met live voorbeeldtekst die meebeweegt met de sliders.

Dimensie	Type
Formeel ↔ Informeel	slider (0.0–1.0)
Serieus ↔ Speels	slider
Technisch ↔ Toegankelijk	slider
Zakelijk ↔ Persoonlijk	slider

De voorbeeldtekst toont dezelfde boodschap in de gekozen stijl. Bij “informeel + speels” ziet de gebruiker een andere formulering dan bij “formeel + serieus”. De keuze wordt concreet in plaats van abstract.

Stap 4: Visuele Identiteit

Veld	Type	Verplicht
Logo upload	file upload (SVG, PNG)	❌
Primaire kleur	color picker	❌
Secundaire kleur	color picker	❌
Accentkleur	color picker	❌
Font voorkeur	visuele keuze (5 curated opties)	❌
Gewenste sfeer	visuele moodboard keuze	❌

Font opties:

Keuze	Heading	Body
`modern-clean`	Plus Jakarta Sans	DM Sans
`classic-serif`	Playfair Display	Lato
`bold-expressive`	Syne	Inter
`warm-friendly`	Nunito	Source Sans 3
`technical-precise`	Space Grotesk	IBM Plex Sans

AI-assist optie: gebruiker kan een bestaande website URL invoeren → AI extraheert kleuren, fonts en stijl als startpunt.

Stap 5: Content & Media

Veld	Type	Verplicht
Welke pagina’s wil je?	multi-select (Home, Over ons, Diensten, Contact, Blog, Portfolio, Pricing, FAQ)	✅
Heb je al teksten?	ja/nee toggle	❌
Teksten uploaden	file upload (docx, txt, pdf)	❌
Heb je al foto’s?	ja/nee toggle	❌
Foto’s uploaden	multi file upload	❌

Stap 6: Doelen & Conversie

Veld	Type	Verplicht
Hoofddoel van de website	single select (leads, informeren, verkopen, portfolio, community)	✅
Belangrijkste call-to-action	tekst (bijv. “Vraag offerte aan”)	❌
Secundaire CTA	tekst	❌
Contactgegevens	gestructureerde velden (email, telefoon, adres)	❌
Social media links	herhalend veld (platform + URL)	❌

Stap 7: Concurrentie & Differentiatie

Veld	Type	Verplicht
Noem 1–3 concurrenten (of URLs)	herhalend tekstveld	❌
Wat maakt jou anders?	textarea	❌
Wat moeten bezoekers onthouden?	tekst (één zin)	❌

3. AI Verfijning (Fase B)

Na de wizard verschijnt een chat-interface. De AI heeft alle wizard-data als context en stelt gerichte vragen om gaten te dichten.

Hoe het werkt

AI analyseert de ingevulde wizard data
AI identificeert waar meer diepte nodig is
AI stelt maximaal 3–5 vervolgvragen — nooit overweldigend
Gebruiker beantwoordt in vrije tekst
AI vat samen en toont de volledige brand profile ter bevestiging

Voorbeeldvragen

Op basis van wat ontbreekt of vaag is:

“Je beschrijving is vrij breed. Kun je één specifiek probleem noemen dat je voor klanten oplost?”
“Je richt je op B2B in de bouwsector. Spreek je vooral projectleiders, inkopers of directie aan?”
“Je hebt geen slogan ingevuld. Wil je dat ik er een paar voorstel op basis van je beschrijving?”
“Je noemt [concurrent] — wat doe jij beter of anders dan zij?”
“Je wilt leads genereren. Wat bied je aan in ruil voor contactgegevens?”

Skip optie

Altijd prominent aanwezig: “Overslaan en doorgaan”. De wizard data is voldoende als minimale basis.

Wat er met uploads gebeurt

Teksten (docx, txt, pdf) → opgeslagen in R2 + tekst geëxtraheerd als extracted_text
Afbeeldingen → opgeslagen in R2 + AI genereert een ai_description voor slimme matching
Logo → opgeslagen in R2, URL in de JSON

4. Styling Builder

De Styling Builder ontvangt de Brand JSON en vertaalt die naar een levend design system. Het is het bewerkoppervlak — het token schema is de opslag.

Kernfilosofie: “You cannot make it ugly.”

Elke keuze die de gebruiker maakt wordt begrensd door guardrails die professionele kwaliteit garanderen. Niet omdat de gebruiker dom is, maar omdat goed design moeilijk is en Beam dat probleem oplost.

Wat de onboarding aanlevert

Onboarding veld	Wat de builder ermee doet
`visual_identity.colors.*`	Direct inladen als brand color tokens
`visual_identity.logo_url`	Logo direct tonen, geen hernieuwde upload
`visual_identity.font_preference`	Mappt naar curated font-paar
`visual_identity.mood`	Bepaalt preset als startpunt
`tone_of_voice`	Beïnvloedt stijladviezen en AI-gegenereerde teksten
`company.name`	Getoond in preview canvas
`goals.primary_cta`	Getoond op preview button
`archetype.gilde`	Bepaalt welke Style Pack als startpunt wordt geladen
`archetype.class`	Bepaalt welke vertical pack styling wordt toegepast

Principe: de styling builder vraagt niets wat de onboarding al heeft gevraagd. Hij toont de onboarding data als een reeds ingevuld startpunt.

Layout

┌─────────────────────────────────────────────────────┐
│  BRAND & KLEUREN    TYPOGRAFIE    ELEMENTEN          │  ← tabs
├──────────────┬──────────────────────────────────────┤
│              │                          [L][D][M]   │
│  Controls    │         Live Preview Canvas          │
│  (sidebar)   │                                      │
│              │   Bedrijfsnaam                       │
│  ● Colors    │   H1 heading tekst                   │
│  ● Fonts     │   H2 subheading                      │
│  ● Radius    │   Body paragraph tekst...            │
│  ● Spacing   │   [Primary CTA]  [Secondary]         │
│              │                                      │
│  ──────────  │   ┌────────────────────────────┐     │
│  Guardrails  │   │  🃏 Codex Block Card Preview │     │
│  ✅ Contrast  │   │  (hoe blocks eruitzien      │     │
│  ✅ Harmonie  │   │   met jouw tokens)          │     │
│  ✅ Typografie│   └────────────────────────────┘     │
│              │                                      │
│  ──────────  │                                      │
│  Style Pack: │                                      │
│  Healer Calm │                                      │
│  [Wissel →]  │                                      │
└──────────────┴──────────────────────────────────────┘

Canvas toggle rechtsboven: [L] Light · [D] Dark · [M] Mobile
Inline selectie: klik op een element in de canvas → sidebar navigeert automatisch naar de juiste sectie
Codex Card Preview: preview van hoe een block card eruitziet met de huidige tokens
Guardrail dashboard: live status van alle guardrail checks onderaan de sidebar

Sectie Brand & Kleuren

Primary, Secondary, Accent — elk met color picker
Max 3 brand colors (guardrail)
Shade generator: automatisch 50–900 schaal via OKLCH + dark mode equivalenten
WCAG Contrast Check (altijd zichtbaar):

primary op background:  14.2:1  ✅ AAA
primary op surface:     11.8:1  ✅ AAA
text op background:     16.1:1  ✅ AAA
text-muted op surface:   4.8:1  ✅ AA
accent op background:    3.1:1  ⚠️ Alleen grote tekst

Bij ❌: kleur wordt niet geblokkeerd, maar de gebruiker krijgt een duidelijke waarschuwing + gesuggereerde alternatieve tint.

Semantic mapping:

Role          Gekoppeld aan        Voorbeeld
──────────────────────────────────────────────────────
primary       ● brand.primary      [Button] [Link]
background    ○ white (#FFFFFF)    [Card bg]
surface       ○ gray-50            [Section bg]
text          ○ gray-900           [Paragraph]
text-muted    ○ gray-500           [Caption]
border        ○ gray-200           [Table border]
danger        ○ #C92A2A            [Foutmelding]
success       ○ #2F9E44            [Bevestiging]
warning       ○ #E67700            [Waarschuwing]

Sectie Typografie

Heading font + Body font, elk individueel inwisselbaar
Optioneel: mono font voor code/labels
Bronnen: curated Google Fonts subset + eigen WOFF2 upload (opgeslagen in R2)
Font-combinatie guardrail: bij het wisselen van heading font toont de builder alleen body fonts die ermee harmoniëren

Typografische schaal:

Element	Font	Desktop	Mobiel	Weight	Line-height
H1	heading	3rem	2.25rem	700	1.2
H2	heading	2.25rem	1.875rem	600	1.3
H3	heading	1.875rem	1.5rem	600	1.3
H4	heading	1.5rem	1.25rem	500	1.4
H5	heading	1.25rem	1.125rem	500	1.4
H6	heading	1rem	1rem	500	1.4
Body	body	1rem	1rem	400	1.6
Label	body	0.875rem	0.875rem	500	1.4
Caption	body	0.75rem	0.75rem	400	1.4

Sectie Elementen

Per elementtype instelbaar. Alle waarden zijn refs naar tokens:

Buttons: Primary / Secondary / Ghost / Destructive — per variant: bg, text, border, radius, padding
Headings (H1–H6): font, size, weight, color, margin-bottom
Body tekst: font, size, line-height, color, max-width
Links: kleur, underline stijl, hover state
Tabellen: header bg, border, stripe color, cell padding
Formuliervelden: border, focus-ring, label stijl
Badges / Tags: kleur, border-radius, font-size
Codex Block Cards: card achtergrond, rarity badge stijl, merk-doorwerking in rendering

Seasonal Overrides

Style Packs ondersteunen seizoensgebonden aanpassingen:

┌─────────────────────────────────────────────┐
│  Seizoensoverzicht                          │
│                                             │
│  🌸 Lente (mrt-mei)    [Preview] [Bewerk]  │
│     Accent: warmere tint, zachter groen     │
│                                             │
│  ☀️ Zomer (jun-aug)    [Preview] [Bewerk]   │
│     Geen aanpassingen                       │
│                                             │
│  🍂 Herfst (sep-nov)   [Preview] [Bewerk]  │
│     Accent: warmer, surface: crème          │
│                                             │
│  ❄️ Winter (dec-feb)    [Preview] [Bewerk]  │
│     Accent: dieper, shadow: sterker         │
└─────────────────────────────────────────────┘

5. Gilde Style Packs

Elk gilde heeft een eigen Style Pack als startpunt:

Gilde	Style Pack	Kleuren	Fonts	Radius	Spacing
⚕️ Healers	Healer Calm	Warm earth tones, sage green	Serif heading, clean body	Large (zacht)	Spacious
🎨 Creators	Creator Bold	Contrast, statement kleuren	Bold heading, minimal body	Medium	Comfortable
🏪 Merchants	Merchant Trust	Betrouwbaar, professioneel	Clean heading, leesbaar body	Small (scherp)	Normal
📚 Scholars	Scholar Authority	Diep, verfijnd	Sophisticated heading, precise body	Small (strak)	Spacious
🍽️ Hosts	Host Atmosphere	Warm, uitnodigend	Elegant heading, friendly body	Medium	Comfortable
🔧 Builders	Builder Solid	Solide, zakelijk	Strong heading, functional body	None/small	Compact

Mood → Preset fallback (voor gebruikers zonder gilde):

Preset	Radius	Spacing	Shadow
Modern Clean	sharp (2px)	spacious	flat
Classic Warm	balanced (6px)	normal	subtle
Bold Expressive	rounded (12px)	compact	elevated
Luxury Refined	sharp (3px)	spacious	subtle
Friendly Accessible	pill-soft (16px)	normal	subtle

6. Entry Points

Styling Builder: drie startpunten

┌─────────────────────────────────────────┐
│  Hoe wil je starten?                    │
│                                         │
│  [Kies je gilde stijl]     (aanbevolen) │
│  [Kies een sfeer-preset]                │
│  [Begin leeg]                           │
└─────────────────────────────────────────┘

Gilde stijl — primaire entry point, laadt volledige Style Pack
Sfeer-preset — fallback voor gebruikers zonder gilde
Leeg — alleen de tokenstructuur klaar, alles handmatig

Data flow

start.beambuilder.com (Onboarding app)
  Wizard (7 stappen) + AI verfijning
        │
        ▼
  Brand JSON → POST naar Beam API
  + Gilde & Class selectie (archetype)
        │
        ▼
  Styling Builder (Beam dashboard)
  ← pakt brand JSON + gilde Style Pack op als startpunt
  ← gebruiker verfijnt visueel binnen guardrails
        │
        ▼
  Design tokens (levende laag)
        │
        ├── Pagebuilder leest tokens live
        ├── Blocks erven styling automatisch
        ├── Addons respecteren de theming cascade
        ├── AI content generator leest tokens live
        ├── Seasonal overrides passen tokens tijdelijk aan
        └── Publieke token API endpoint

7. Bouwvolgorde

Fase 1: Wizard

Vite + React app opzetten op start.beambuilder.com (CF Pages)
Stap-voor-stap wizard UI (stappen 1–7)
Client-side validatie + progressie-indicator
Uploads naar R2 (logo, teksten, media)

Fase 2: AI Verfijning

Chat interface na de wizard
AI analyse van wizard data → gerichte vragen genereren
Verwerking van antwoorden in de brand JSON
Skip optie altijd prominent

Fase 3: Output & Koppeling

Brand JSON generatie (zie 08-brand-json-spec.md)
API endpoint in Beam voor het ontvangen van brand data
Media library sync (uploads → Beam media library in R2)
Redirect naar Beam dashboard

Fase 4: Styling Builder

brand_profiles tabel + token_versions + style_packs
Token API endpoint (GET /api/sites/{site_id}/tokens)
OKLCH shade generator via culori
Guardrail engine (WCAG contrast, kleurharmonie, font-paar)
6 gilde Style Packs als seed data

Fase 5: Styling Builder UI

Split layout: sidebar + live canvas
Sectie Brand & Kleuren (color picker, shade preview, semantic mapping)
Sectie Typografie (font picker met curated paar-suggesties)
Sectie Elementen (per element type, states)
Canvas light/dark/mobile toggle
Inline selectie + Codex Card Preview

Fase 6: Polish & Export

Seasonal override editor
Versioning (auto-save + named snapshots)
CSS, Tailwind v4 en W3C JSON export
Resolved token API endpoint