← Back to Overview

Quality Assurance & Checklist

28 checkpoints every generated page must pass

01

The 28-Point Checklist

Every generated page passes through 28 quality gates, grouped into five categories. A single failure is enough to reject the page.

6 Points Pipeline Completeness
Each pipeline has produced all planned levels
No surplus levels (Decision Maker max L1, End User max L2)
DE and EN version exists for every page
Filenames follow convention: topic_audience_lang.html
No cross-pipeline dependencies during build
Depth map contains all built and skipped topics
5 Points Audience Separation
Decision maker content contains no source code
Developer content shows real code from the codebase
End user content focuses on workflows and UI
Tone matches the audience (formal/technical/practical)
No content from one pipeline appears in another
6 Points Navigation & Links
All deep-dive links point to existing files
Breadcrumbs correct (L0 → L1 → L2 → ...)
Relative paths correct (L0→L1: "l1/...", L1→L2: "../l2/...")
No dead links
Language links point to correct language version
Audience switch only on L0 pages
5 Points Contrast & Accessibility
WCAG AA minimum (4.5:1 for normal text, 3:1 for large text)
No white text on light backgrounds
Minimum rgba(255,255,255,.85) on dark backgrounds
Tooltips readable (light text on dark code background)
No #9995A0 or similar on light backgrounds
6 Points Content Quality
Max 2–3 sentences per text block
At least 50% visual elements per screen
Every technical term has a tooltip
Quizzes test application, not memorization
Code comes from the real codebase
No recycled metaphors
02

Pipeline Verification

Each pipeline must produce exactly the planned levels — no more, no fewer. Cross-pipeline dependencies during build are prohibited.

📊 Decision Maker max L1
Strategic overview without technical details. No code blocks, no L2/L3 pages.
L0 ✓ L1 ✓ L2 ✗ L3 ✗
👤 End User max L2
Workflow-oriented guides with screenshots and step-by-step instructions. No L3 pages.
L0 ✓ L1 ✓ L2 ✓ L3 ✗
🔧 Developer max L3
Technical depth with real code, architecture diagrams, and API references. All four levels available.
L0 ✓ L1 ✓ L2 ✓ L3 ✓

Forbidden: A pipeline must not reference or depend on files from another pipeline during build. Only in Phase 5 (Polish) are cross-pipeline elements such as the audience switch on L0 pages inserted.

03

Navigation & Links

Correct linking is the fragile backbone of the entire output. Every broken path leads to a dead link — and there is no web server to catch 404 errors.

Relative Path Conventions

// From L0 (root/output/) to L1: href="l1/orchestrator_dev_en.html" // relative to L0 directory // From L1 (root/output/l1/) to L2: href="../l2/phase-detail_dev_en.html" // one level up, then into l2/ // From L2 (root/output/l2/) to L3: href="../l3/state-machine_dev_en.html" // one level up, then into l3/ // From L1 back to L0: href="../index_dev_en.html" // one level up // Language link (same level): href="orchestrator_dev_de.html" // filename only, same directory
Correct
• Breadcrumbs reflect actual hierarchy • Deep-dive links only when HS ≥ 7 • Language links point to exact counterpart • Audience switch only on L0
Common Mistakes
• Deep-dive link to non-existent L2 page • Relative paths with leading / (absolute instead of relative) • Audience switch placed on L1 page • Language link points to DE instead of EN (or vice versa)
04

Contrast & Accessibility

WCAG AA is the minimum. No generated output may fall below this threshold. The most common failures involve light text colors on light backgrounds.

Forbidden Color Combinations

Text Color Background Contrast Verdict
#FFFFFF #F3EFEB 1.2:1 Forbidden
#FFFFFF #FFFFFF 1.0:1 Forbidden
#9995A0 #F3EFEB 2.8:1 Forbidden
#9995A0 #FFFFFF 3.3:1 Forbidden
#1A1A2E #F3EFEB 10.2:1 OK (AAA)
#5C5A6B #FFFFFF 6.4:1 OK (AA)
rgba(255,255,255,.85) #000066 11.8:1 OK (AAA)

Rule of thumb on dark backgrounds: Text on the deep blue gradient or code background (#000066) must use at least rgba(255,255,255,.85). Tooltip color #D0D0E8 on #000066 achieves 9.1:1 — sufficient. Orange text (var(--color-impulse-orange)) on dark achieves 6.2:1 — use only for labels and badges.

05

Content Quality

Good generated content follows strict rules: short text blocks, high visual ratio, tooltips for technical terms, and quizzes that test understanding — not rote memorization.

✍️
Text Length
Maximum 2–3 sentences per text block. Each paragraph must convey a clear message. No filler passages.
max 3 sentences
🎨
Visual Ratio
At least 50% of each screen should be visual: cards, diagrams, code blocks, file trees, or tables.
≥ 50% visual
💬
Tooltips
Every technical term gets a tooltip. Never assume the reader knows the term.
100% coverage
🧠
Quiz Design
Quizzes test application: "What would happen if..." rather than "What is the value of X?". Wrong answers must be plausible to test genuine understanding.
♻️
Anti-Patterns
No recycled metaphors ("Like an iceberg..."). No generic placeholder code. No stock photo screenshots. Every example must come from the real codebase.
✏️ Quick Check

What's the minimum contrast ratio for normal text (WCAG AA)?

3:1 — that's sufficient for most cases
7:1 — that's the AAA standard
4.5:1 — the AA standard for normal text
More deep-dive pages for Developers