# MASTER STYLEGUIDE & FORMATTING RULES
**Versie**: 1.3 (Tiered Model Architecture Edition)
**Datum**: 13 mei 2026
**Auteur**: Kas (Director of Operations)
**Locatie**: /root/.openclaw/workspace/MASTER_STYLEGUIDE.md
**Status**: STANDAARD VOOR ALLE AGENTS

> Één bron van waarheid voor alle visuele regels, branding, en formatting.
> Sub-agents lezen dit document vóór elke deliverable generatie.

---

## §1 Visuele Identiteit (CSS & Styling)

### 1.1 Typografie
| Element | Font | Weight | Size | Line Height |
|---------|------|--------|------|-------------|
| H1 (pagina-titels) | Sans-serif (Roboto, Segoe UI, Arial) | Bold (700) | 42px | 1.3 |
| H2 (sectie-titels) | Sans-serif | Semi-Bold (600) | 36px | 1.3 |
| H3 (module-titels) | Sans-serif | Semi-Bold (600) | 28px | 1.4 |
| H4 (kaart-titels) | Sans-serif | Bold (700) | 20px | 1.4 |
| Body | Sans-serif | Regular (400) | 16px | 1.6 |
| Labels/Capties | Sans-serif | Medium (500) | 14px | 1.5 |

### 1.2 Kleurenpalet

| Naam | Hex | Gebruik |
|------|-----|---------|
| **Primair** | `#003366` | Headers, footers, primaire elementen |
| **Achtergrond Header** | `#003366` of `#0a1628` | Donkere header achtergrond |
| **Succes** | `#00A859` | Positieve feedback, goedgekeurd |
| **Waarschuwing** | `#F59E0B` | Amber alerts, call-outs |
| **Kritiek** | `#FF6D00` | Safety orange, urgente items |
| **Fout** | `#EF4444` | Errors, geweigerd |
| **Info** | `#3B82F6` | Informatief, neutraal |
| **Tekst Donker** | `#1F2937` | Body tekst |
| **Tekst Secundair** | `#374151` | Subtitles, metadata |
| **Achtergrond** | `#FFFFFF` | Hoofd achtergrond |
| **Achtergrond Cards** | `#F8F9FA` | Cards, kopteksten tabellen |
| **Randen** | `#E5E7EB` | Subtiele borders |
| **Footer BG** | `#374151` | Footer achtergrond (met witte tekst) |

### 1.3 Design Elementen
| Element | Stijl |
|---------|-------|
| Content-kaarten | `1px solid #E5E7EB` |
| Definitie/CTA-blokken | `4px solid #003366` |
| Call-out blokken | `3px solid #F59E0B` |
| Header/Footer shadow | `0 2px 6px rgba(0,0,0,0.1)` |
| Card shadow | `0 4px 12px rgba(0,0,0,0.1)` |
| Hover effect | `translateY(-2px)` + verhoogde shadow |

### 1.4 Spacing
| Element | Waarde |
|---------|--------|
| Container | Max 1200px, gecentreerd, padding 40px |
| Header/Footer | Padding 30px |
| Sectie tussenruimte | Margin 40px |
| Card padding | 30px |
| Paragraaf margin-bottom | 20px |
| Lijst-item margin-bottom | 15px |

### 1.5 Knoppen
| Type | Achtergrond | Tekst | Padding | Radius |
|------|-------------|-------|---------|--------|
| Primair CTA | `#003366` | Wit | 12px 24px | 6px |
| Secondair | `#3B82F6` | `#1F2937` | 12px 24px | 6px |

### 1.6 Responsive (NIEUW)
| Breakpoint | Breedte | Aanpassing |
|------------|---------|------------|
| Desktop | >1024px | Volledige layout |
| Tablet | 768-1024px | 2-koloms → 1-koloms, padding 20px |
| Mobile | <768px | 1-koloms, font -2px, H1 28px, H2 24px |

### 1.7 CSS Variabelen (Centraal)
```css
:root {
  --primary: #003366;
  --success: #00A859;
  --warning: #F59E0B;
  --critical: #FF6D00;
  --error: #EF4444;
  --info: #3B82F6;
  --text-dark: #1F2937;
  --text-secondary: #374151;
  --bg-main: #FFFFFF;
  --bg-card: #F8F9FA;
  --border: #E5E7EB;
  --font-family: 'Segoe UI', Roboto, Arial, sans-serif;
  --container-max: 1200px;
}
```

---

## §1.8 Bronverwijzingen (Wetenschappelijke Notatie)

### Formaat
Feitelijke claims in deliverables worden voorzien van een genummerde bronverwijzing:

**In de tekst**:
- "Bij 10-100 ton/jaar is een Chemical Safety Report verplicht [1]."
- "Phoenix Metals verwerkt staalslakken tot vanadium-elektrolyten [3]."

**Bronnenlijst onderaan** (footer, bijlage, of laatste slide):
```
Bronnen:
[1] REACH Verordening (EG) Nr. 1907/2006, Art. 12(2), Annex VII-VIII
[2] CLP Verordening (EG) Nr. 1272/2008, Bijlage I, Deel 2
[3] Phoenix Metals — Registration Chemicals MASTER v2.1.0
[4] ECHA — SCIP Database, geraadpleegd 24 april 2026
```

### Regels
- Elke feitelijke claim die afkomstig is van een brondocument krijgt een bronnummer
- Algemene kennis (bijv. "REACH is een EU-verordening") hoeft geen bronverwijzing
- Interpretaties of adviezen van Kas/sub-agents worden NIET voorzien van een bronnummer
- De bronnenlijst staat onderaan de deliverable (DOCX: bijlage, PPTX: laatste slide, HTML: footer sectie)
- Bronnenlijst is chronologisch genummerd [1], [2], [3]...
- Bij meerdere bronnen voor één claim: [1][3]

### Per Format
| Format | Bronverwijzing in tekst | Bronnenlijst |
|--------|----------------------|-------------|
| DOCX | Superscript [1] of inline (1) | Bijlage of laatste pagina |
| PPTX | Inline (1) op de slide | Laatste slide of notities |
| HTML | Inline [1] | Footer sectie of aparte pagina |

---

## §2 Format: Procedures & Rapporten

### 2.1 Document Header
```
# [DOCUMENTTYPE] - [PROJECTNAAM]
**Project**: [Naam Project]
**Type**: Procedure / Rapport / Memo / Training
**Auteur**: [Naam Agent]
**Versie**: 1.0
**Datum**: [JJJJ-MM-DD]
**Status**: [Draft / Concept / Final]
```

### 2.2 Inhoudsstructuur (Procedures)
1. **Doel** — Max 2 alinea's, direct to the point
2. **Toepassingsgebied** — Doelgroep, specifieke locaties
3. **Definities & Afkortingen** — Alleen relevante termen
4. **Werkwijze / Procedure** — Genummerde stappen, eigenaren
5. **Verantwoordelijkheden** — RACI Matrix (R/A/C/I)
6. **Risico's & Mitigatie** — Identificeer + mitigeer
7. **Registratie & Bijlagen** — Documentatie, hulpmiddelen

---

## §3 Format: Trainingen & Presentaties

### 3.1 Header & Footer
**Header**: Donkere achtergrond (`#003366`), witte tekst, 30px padding
- JvG Consultancy Logo (rechts, base64 inline)
- Project Titel (groot, bold)
- Datums/locaties (links, kleiner)

**Footer**: Achtergrond `#374151`, witte tekst, 14px, gecentreerd
- Regel 1: "JvG Consultancy" | Safety • Governance • Advisory
- Regel 2: [Divisie] | Bijv. HSEQ, Operations
- Regel 3: Copyright 2026 | Auteur, Datum

### 3.2 Module Structuur
- Module Titel: H2 (36px, vetgedrukt, blauw)
- Doelstelling: 1-2 alinea's in grijze box
- Duur: Aantal minuten/uren
- Leerdoelen: Bullet points (max 5)
- Content-kaarten: Grid met 2 kolommen

### 3.3 Visual Hierarchy
- **KPI Cards**: Grote cijfers (42px, bold), labels (16px), kleur-gecodeerde trends
- **Tabellen**: Grijs rand `#E5E7EB`, koptekst `#E5E7EB`, alternating rows `#FFFFFF`/`#F8F9FA`
- **Call-out cellen**: Rand `#F59E0B`, achtergrond `#FFFEBA`

### 3.4 Design Overlay (NIEUW)
Voor HTML deliverables:
- **Lucide SVG icons** inline (niet als externe afbeelding)
- **2-koloms CSS Grid** layout (max 6 regels per blok)
- **Max 6 regels tekst** per content-blok (voorkom "walls of text")
- **KPI cards** in een 3- of 4-koloms grid
- **Priority blocks** met kleurcodering (rood/amber/groen)

---

## §4 Vrijheidsmarge voor Agents

### 4.1 Verplicht
- Professionele taal, geen informele taal
- Feitelijke basis met data, cijfers, percentages
- Corporate flair (Shell/Arcadis niveau)
- Consistente terminologie uit deze Styleguide

### 4.2 Toegestaan (Creatieve Vrijheid)
Extra visuele accenten, iconen, detail in sub-onderdelen — mags het document niet "minder professioneel" maken.

### 4.3 Verboden (AI-clichés)
❌ "Laten we kijken naar..."
❌ "In lijn met..."
❌ "Naar beste kunnen..."
❌ "Dergelijk als..."
❌ "Het is belangrijk om te benadrukken..."

✅ "Implementeer protocollen volgens MAC-regels."
✅ "OSHA-compliance is vereist: 95%."
✅ "Training moet voltooid zijn voor 31 december."

---

## §5 Quality Control Checklists

### 5.1 Documentatie (Procedures/Rapporten)
- [ ] Doel duidelijk geformuleerd?
- [ ] Eigenaren (RACI) gedefinieerd?
- [ ] Risico's en mitigatie beschreven?
- [ ] Taal zakelijk en professioneel?
- [ ] Geen typfouten?

### 5.2 Visual Design (HTML/Trainingen)
- [ ] Kleurenpalet uit §1 gevolgd?
- [ ] Headers/footers correct gestyled?
- [ ] Tabellen leesbaar en professioneel?
- [ ] Typografie correct (font, size, line-height)?
- [ ] Responsive (werkt op mobile)?
- [ ] Hover-states en CTA-knoppen werken?

### 5.3 Corporate Branding
- [ ] JvG Consultancy logo op voorblad? (§8)
- [ ] Randen en schaduwen consistent?
- [ ] High-end uitstraling, niet "basic"?
- [ ] Senior consultant zou dit akkoord vinden?

---

## §6 Voorbeeld: Goede vs. Slechte Documentatie

### ❌ Slecht
```
Het doel van deze training is om veiliger te werken.
We willen dat iedereen zich goed voelt.
Het programma duurt een paar weken.
Zaken die je leert: MAC-regels, Veiligheid.
We hopen dat het lukt!
```

### ✅ Goed (Golden Standard)
```
# WINTERSHALL HSEQ TRAINING PROGRAMMA
**Doel**: Trainen van 1.000+ rig-operatoren in fundamentele HSEQ-principes.
**Doelgroep**: Olie & Gas operatoren (offshore/onshore).

**Module 1: MAC-waarden** (90 min)
- Begrijpen van offshore MAC-waarden
- Toepassen in dagelijkse praktijk
- Verminderen van near-misses
```

---

## §7 Communicatie Guidelines

### 7.1 Feedback Accepteren
"Bedankt voor de feedback, we verwerken dit direct."
Vraag om verduidelijking indien onduidelijk. Geen verdediging.

### 7.2 Verschillen van Interpretatie
Vraag expliciet: "Mijn begrip is dat u X bedoelt. Klopt dat?"

### 7.3 Status Updates
Proactief: "Ik ben bezig met [taak]. Verwachte duur: [tijd]."
Heldere tijdlijnen, geen vage beloftes.

---

## §8 JvG Consultancy Branding

### 8.1 Logo Bestanden
| Bestand | Formaat | Grootte | Gebruik |
|---------|---------|---------|---------|
| `jvg-consultancy-logo.jpg` | JPEG | 754×676 px | Origineel |
| `jvg-consultancy-logo.png` | PNG (transparant) | 754×676 px | Lichte achtergrond |
| `jvg-logo-white-small.png` | PNG | 200×179 px | HTML (base64) |
| `jvg-logo-white-medium.png` | PNG | 400×359 px | DOCX |
| `jvg-logo-white-large.png` | PNG | 600×538 px | PPTX |
| `logo-white-base64.txt` | Text | — | HTML inline (donkere bg) |
| `logo-base64.txt` | Text | — | HTML inline (lichte bg) |

**⚠️ Ratio 1.115:1 is heilig. NOOIT uitrekken.**
**⚠️ Donkere achtergrond? → ALTijd white-bg versies gebruiken.**

### 8.2 Logo Placement
| Formaat | Positie | Afmeting | Bestand |
|---------|---------|----------|---------|
| **PPTX** | Rechtsboven, slide 1 | 1.5" × 1.35" | `jvg-logo-white-large.png` |
| **PPTX Footer** | Links | 0.75" × 0.67" | `jvg-logo-white-large.png` |
| **HTML** | Links/rechts header | height: 40px, width: auto | base64 inline |
| **HTML Voorblad** | Links/rechts | height: 80px, width: auto | base64 inline |
| **DOCX** | Rechts in header | 2.0 cm × 1.8 cm | `jvg-logo-white-medium.png` |
| **PDF** | Links/rechts | Via file:// pad | `jvg-logo-white-small.png` |
| **SCORM** | `../shared/` | Kopieer naar package | `jvg-logo-small.png` |

### 8.3 Sub-Agent Instructie Blok
Bij ELKE `sessions_spawn` voor deliverable generatie:
```
⚠️ LOGO INSTRUCTIE (VERPLICHT):
1. Logo is bijna VIERKANT (754x676 px, ratio 1.115:1) — behoud ALTIJD aspect ratio
2. WITTE ACHTERGROND op donkere achtergronden!
   - PPTX: jvg-logo-white-large.png
   - DOCX: jvg-logo-white-medium.png
   - HTML (donker): Lees /root/projects/jg/assets/branding/logo-white-base64.txt
   - HTML (licht): Lees /root/projects/jg/assets/branding/logo-base64.txt
   - PDF: file:///root/projects/jg/assets/branding/jvg-logo-white-small.png
3. HTML: Gebruik INLINE base64 data URI (niet ../assets/ pad)
4. PPTX: 1.5" breed × 1.35" hoog (width én height instellen)
5. DOCX: 2.0 cm × 1.8 cm (width én height in EMU)
6. Test: Open bestand en verifieer logo zichtbaar EN niet vervormd
```

---

## §9 Kennisdossier DOCX — Vaste Structuur & Opmaak

**Bestandsnaam**: `[ProjectCode]_Kennisdossier_v[versie].docx`  
**Locatie**: `/deliverables/kennisdossier/`  
**Techniek**: python-docx library  
**Agent**: HQ_04 (Technical Writer)

### Hoofdstukindeling (VERPLICHT)

| Hoofdstuk | Titel | Inhoud | Min. pagina's |
|-----------|-------|--------|-------------|
| 1 | Management Samenvatting | Executive summary met kernbevindingen, aanbevelingen en risico's | 1-2 |
| 2 | Methodiek | Sniper & Harvester parameters, zoekstrategie, bronnen per Tier | 1-2 |
| 3 | Tier 1 & 2 Toetsing | Analyse interne procedures vs wetgeving/regelgeving, gaps, compliance status | 3-5 |
| 4 | Tier 3 Markt Intelligence | Harvester data, trends, benchmarks, marktontwikkelingen | 2-4 |
| 5 | Bronnenlijst | Geannoteerde bronnen per Tier, URL's, datum raadpleging | 1-2 |

### Opmaak
- **Headers**: Huisstijl kleuren (Donkerblauw #003366, Grijs #374151)
- **Lettertype**: Calibri 11pt, koppen Calibri Bold 14pt
- **Tabellen**: Stijl "Light Grid Accent 1"
- **Logo**: JVG logo 2.0cm × 1.8cm in header
- **Footer**: ProjectCode + versie + datum
- **Document properties**: Title, Author (agent), Keywords, Created/Modified timestamps

### Metadata (python-docx)
```python
from docx import Document
doc = Document()
doc.core_properties.title = f"{project_code} Kennisdossier v{version}"
doc.core_properties.author = "HQ_04 Technical Writer via Kas"
doc.core_properties.keywords = f"{project_code}; kennisdossier; {tags}"
doc.core_properties.category = "HSEQ Intelligence"
```

### Trigger
Automatisch activeren bij:
- Afsluiting Market Scout / Intelligence taken
- Post-Final Analysis (MASTER_SOP Fase 3.5, Step 4.4)

---

## §10 Inspectierapport DOCX — Vaste Structuur & Opmaak

**Bestandsnaam**: `HSE-IN-[NR]_Inspectierapport_[Project]_v[versie].docx`
**Locatie**: `/deliverables/docx/`
**Techniek**: python-docx library
**Agent**: HQ_09 (Safety Inspector)

### Opmaak
- **Cover pagina**: JvG logo (4.0 × 3.6 cm), titel, project/locatie/inspecteur/datum
- **Documentbeheersing**: Versiebeheer, distributielijst, autorisatie
- **Inhoudsopgave**: Alle 10 categorieën
- **Headers**: Calibri Bold 14pt, kleur #003366
- **Body**: Calibri 11pt, kleur #1F2937
- **Tabel header**: Achtergrond #003366, witte tekst
- **Severity kleuren**: 🟢 #10B981, 🟡 #F59E0B, 🔴 #DC2626, ⛔ #7F1D1D
- **Footer**: HSE-IN-[NR] | v[versie] | datum + paginanummer
- **Logo**: JVG logo wit 2.0cm × 1.8cm in header

### Inspectiesamenvatting (VERPLICHT)
| Veld | Waarde |
|------|-------|
| Project | [Naam] |
| Locatie | [Locatie] |
| Inspecteur | [Naam, Rol] |
| Datum | [DD-MM-JJJJ] |
| Totaal bevindingen | [N] |
| 🟢 Observaties | [N] |
| 🟡 Minor | [N] |
| 🔴 Major | [N] |
| ⛔ Stop Work | [N] |
| Overall Rating | Goed / Acceptabel / Verbetering Nodig / Onvoldoende |

### 10 Categorieën (volgorde vast)
1. Orde & Netheid (Housekeeping)
2. PBM Naleving (PPE Compliance)
3. Steigers (Scaffolding)
4. Uitgravingen (Excavations)
5. Hijsoperaties (Lifting Operations)
6. Werkzaamheden met Brandgevaar (Hot Works)
7. Elektrische Veiligheid (Electrical Safety)
8. Brandpreventie (Fire Prevention)
9. Milieumaatregelen (Environmental Controls)
10. Verzorgingsvoorzieningen (Welfare Facilities)

### Severity Classificatie
| Level | Label | Respons | Deadline |
|-------|-------|---------|----------|
| 🟢 | Observation | 14 dagen | 14 dagen na inspectie |
| 🟡 | Minor Non-Conformance | 7 dagen | 7 dagen na inspectie |
| 🔴 | Major Non-Conformance | 24 uur | Volgende werkdag |
| ⛔ | Stop Work | Onmiddellijk | Direct |

### Trigger
Activeren bij:
- "veiligheidsinspectie", "safety inspection", "site walk"
- Periodieke inspecties (maandelijks minimum)
- Na incident/near-miss
- Bij start nieuwe werkfase

---

## §11 Dashboard Module Styling

### API JSON-respons structuur
Alle API-endpoints retourneren JSON met consistente structuur:
```json
{
  "[hoofdkey]": [...],  // data-array of object
  "totaal": N,          // optioneel: aantal items
  "bron": "...",        // bronverwijzing
  "status": "..."       // bij POST: bevestiging
}
```

### Severity Kleuren (dashboard + rapporten)
| Level | Emoji | Hex | Gebruik |
|-------|-------|-----|----------|
| Observation | 🟢 | `#10B981` | Goed praktijkadvies |
| Minor | 🟡 | `#F59E0B` | Kleine non-conformiteit |
| Major | 🔴 | `#DC2626` | Ernstige non-conformiteit |
| Stop Work | ⛔ | `#7F1D1D` | Onmiddellijk stoppen |

### Compliance Status Kleuren
| Status | Hex | Label |
|--------|-----|-------|
| Compliant | `#10B981` | Voldoet |
| Partial | `#F59E0B` | Deels Voldoet |
| Non-compliant | `#DC2626` | Niet Voldoet |
| Not assessed | `#6B7280` | Niet Beoordeeld |

### Risicomatrix Kleuren
| Score | Hex | Label |
|-------|-----|-------|
| 1-4 | `#10B981` | Laag |
| 5-9 | `#F59E0B` | Gemiddeld |
| 10-16 | `#DC2626` | Hoog |
| 17-25 | `#7F1D1D` | Kritiek |

### Inspectierapport DOCX (§10)
Zie §10 voor volledige structuur.

### Auditrapport DOCX
- Zelfde opmaak als inspectierapport (§10)
- Extra: Control-per-control tabel met status-kleuren
- Score-balk (0-100%) bovenaan executive summary

### Veiligheidsprogramma DOCX
- Per programma: doel, scope, verantwoordelijkheden, procedure-stappen, opleidingseisen, documentatie
- Checklist per element met Vinkje ✅/❌
- Wetgevingsreferentie per element

### Training Curricula DOCX
- Module-per-module tabel (naam, uren, onderwerpen)
- Rollenmatrix tabel (wie welke training nodig heeft)
- Compliance-eisen tabel (wetgeving → training → frequentie → bewijs)

## §13 Post-Delivery Verify Log Format

**Locatie**: `/logs/verify-log.md` (per project) of centraal `/root/.openclaw/workspace/verify-log.md` (voor tools)
**Verantwoordelijke**: Kas (Director) voor automated checks, sub-agents voor steekproeven

### Formaat
```markdown
# TierVerify Log

## [DATUM] — [TOOL/PROJECT]
- **Status**: ✅ PASS / ⚠️ WARNING / ❌ FAIL
- **Tieren gebruikt**: Tier 1 / Tier 2 / Tier 3
- **Bronnen**: [PubChem, ECHA, RIVM, interne procedure X, etc.]
- **Checks uitgevoerd**: [aantal] — [opsomming]
- **Issues gevonden**: [beschrijving of "geen"]
- **Diepte-check**: [1 element geverifieerd: resultaat]
- **Actie**: [gefixt / geëscaleerd / geaccepteerd]
- **Aflevering**: JA / NEE (bij ❌ FAIL)
```

### Verify Checklist Template (per tool-type)

**Chemische Scanner (REACH / PGS15)**:
- [ ] H-zinnen gevonden en consistent met GHS-classificatie?
- [ ] Pictogrammen conform EC 1272/2008 / UN-GHS (OSHA EU / ECHA)?
- [ ] CAS-nummer klopt met PubChem?
- [ ] Compliance matrix logisch (geen lege velden, geen contradicties)?
- [ ] Maatregelen stof-specifiek (geen generieke vulling)?
- [ ] Bron-API bereikbaar en respons data compleet?

**Training Generator**:
- [ ] Inhoud dekt volledig brondocument?
- [ ] Wetgevingsreferenties actueel en correct?
- [ ] Quiz-antwoorden feitelijk juist?
- [ ] Branding conform MASTER_STYLEGUIDE §8?

**Kennisdossier**:
- [ ] Bronverwijzingen kloppen en zijn bereikbaar?
- [ ] Tier 1 vs Tier 2 consistent (geen contradicties)?
- [ ] Gaps eerlijk geïdentificeerd (niet verborgen)?
- [ ] Conclusies feitelijk en onderbouwd?

---

## §12 Changelog

| Versie | Datum | Wijziging |
|--------|-------|-----------|
| 1.3 | 2026-05-13 | §14 Tiered Model Architecture Guidelines toegevoegd. Smart routing, fallback mechanismen, quality gates per tier. |
| 1.2 | 2026-04-24 | §13 Post-Delivery Verify Log Format + TierVerify checklist templates toegevoegd. Scanners, Training Generator, Kennisdossier. |
| 1.3 | 2026-04-23 | §10 Inspectierapport DOCX structuur + opmaak + 10 categorieën + severity classificatie toegevoegd. |
| 1.4 | 2026-04-23 | Dashboard modules toegevoegd: Inspection, Compliance Audit, Workplace Safety, Training Program, Risk & Environment. Nieuwe agenten HQ_08-HQ_16. |
| 1.5 | 2026-04-23 | Milieucompliance, Risicobeheer, ISO Gap Analyse, Regelgeving Monitoring secties toegevoegd. 16 HSEQ agents, 42 totaal. |
| 1.1 | 2026-04-02 | Secties herschikt (1-9). Footer kleur fixed. Header kleur fixed. Responsive toegevoegd. |
| 1.0 | 2026-03-16 | Initiële versie. |

---

*Kas (Director of Operations) — 23 april 2026*