v3 Marketing Site — Design Guide Page — Design

Date: 2026-05-15 Project: A single internal HTML page that visualises the v3 design-token system and reusable UI primitives. Follows on from Sub-projects A (responsive) and B (design tokens), both complete. Baseline branch: v3-agents-and-testimonials-carousel (HEAD 42da88998).

Goal

Give Max a single browsable URL on the v3 site that shows every design token (tokens.css) as a swatch / scale / sample, alongside live examples of the small set of reusable UI primitives in v3.css / product.css. The page is also a working test of the token system — by rendering with tokens.css + v3.css + product.css and using only var(--token) values for its own guide-specific layout, any future regression in the tokens shows up here visually.

Approach

One static HTML file, www/v3/design-guide.html, self-contained:

• Links tokens.css, v3.css, product.css (the same cascade the rest of the v3 site uses — so primitives render exactly as they do in production).
• A single in-body <style> block adds guide-only layout (swatch grid, scale rulers, sample boxes). All values in this block reference var(--token) — the page must not introduce raw px / hex anywhere.
• German labels only, internal, unlinked (no nav/footer entry pointing to it). Reachable at http://127.0.0.1:8123/v3/design-guide.html and the same path on any deployed env.

Rejected: a separate JS-driven Storybook-style app (overkill, breaks the "static HTML site" rule); a separate design-guide.css (no other page uses it — keep it inline); bilingual de/en mirror (only the author will read it, doubles maintenance for no value).

Page structure

Eight sections, single scrollable page, ~400–500 lines of HTML.

1. Header — page title Design Guide, eyebrow tokens.css · v3 marketing, one-paragraph intro: tokens.css is the single source of truth for colour, type, spacing, radius and icon-stroke values across the v3 marketing site. Every raw value in CSS contexts (style="...", <style> blocks, the four shared stylesheets) was snapped to its nearest token. SVG presentation attributes (width="18", stroke-width="1.8") are intentionally left literal — var() does not work in HTML attribute syntax.

2. Farbe — three sub-blocks:

   • Semantic palette as labeled swatches: bg, bg-2, bg-soft, bg-tone, ink, ink-2, ink-3, muted, line, line-2, accent, accent-ink, accent-soft, good, warn, red. Each swatch shows the resolved colour, the token name, and the literal hex from tokens.css. Light swatches get a thin --line border so white-on-white is visible.
   • Categorical palette: cat-1 … cat-5 as the same swatch format.
   • Theme override demo: a small panel that toggles data-mode="systems" on the document via a button, so the user can see how the alternate-mode --bg/--accent/etc. recolour the whole page. The button itself uses the guide's own primary-button styling.

3. Typografie — three sub-blocks:

   • Font families: one line each at var(--text-19), labeled --sans (set in var(--sans)) and --mono (set in var(--mono)), with the family stack underneath in small --mono text.
   • Weight scale: three identical phrases, one each at --weight-regular, --weight-medium, --weight-semibold, labelled.
   • Font-size scale: each of --text-9, 10, 11, 12, 13, 14, 15, 16, 19, 24, 32, 44, 48, 80, 96 rendered as actual text (a short German word like Finanz or Echtzeit), with the token name and Npx value beside it in --mono --text-11. One clamp() example heading underneath (using .h-display) to show the only category that stays inline.

4. Icons — two sub-blocks:

   • Size scale: three identical inline-SVG icons (a plain checkmark or arrow) rendered at --icon-sm, --icon-md, --icon-lg, each labelled.
   • Stroke scale: the same icon rendered twice side-by-side, once at stroke-width: var(--icon-stroke) and once at var(--icon-stroke-bold), each labelled.

5. Abstände — every --space-* step (2/4/6/8/10/12/16/20/24/32/40/48/64/80/120) shown as a horizontal --accent bar of that exact pixel width on a --bg-2 background row, with the token name in --mono to the left and Npx to the right. Visual ruler.

6. Radien — every --radius-* step (2/4/8/12/16 + legacy --radius:10 + --radius-pill) shown as a 64×64 --bg-2 square with 1px solid --line-2, the token's radius applied, the token name centred inside in --mono --text-11. --radius-pill rendered wider (120×40) so the pill shape reads.

7. UI-Elemente — live primitives from v3.css / product.css:

   • Buttons: a .btn.btn-primary ("Demo buchen"), a .btn.btn-ghost ("Mehr lesen"), and a .btn.btn-ghost.btn-arrow ("Weiter") side-by-side.
   • .eyebrow text label.
   • .h-display, .h-section, .lede paragraph — one each, with their CSS class noted underneath in --mono.
   • .italic-swap sample sentence — shows how em swaps to --mono --accent styling.
   • .lede-bullets — three-item checkmark list (hero-style).
   • .check-li — three-item body-level checklist (smaller checkmark).
   • .dot indicators: a row of three .dot elements coloured --good, --warn, --accent.
   • .chip — one pill-style chip with the leading dot, label "Live".

8. Footer — short note: Diese Seite ist intern und unverlinkt. Quelle der Wahrheit: www/v3/css/tokens.css. Rationale: docs/superpowers/specs/2026-05-14-v3-design-tokens-design.md. Plus the date the page was last regenerated.

Token usage and self-check

The page's own <style> block is the test: it must use only var(--token) for every colour, font-size, spacing, radius and font-weight. Verifiable post-implementation by:

grep -nE '#[0-9a-fA-F]{3,8}|font-size:\s*[0-9.]+px|(padding|margin|gap)[a-z-]*:[^;"}]*[0-9]+px|border-radius:[^;"}]*[0-9]+px|font-weight:[[:space:]]*[0-9]+' www/v3/design-guide.html | grep -v 'clamp\|50%'

Expected: only matches inside SVG presentation attributes (the inline icons in section 4 — width="18" stroke-width="1.8" etc., out of scope per spec B).

Out of scope

• Composite section patterns (mock windows, hero variants, card grids, numbered steps) — those are page-specific layouts, not primitives. They're available to inspect on the live marketing pages.
• Interactive code-copy buttons, search, theming UI beyond the single mode toggle.
• Storybook-style isolated component frames.
• Bilingual mirror — DE labels only.
• A nav/footer link to the page.

Acceptance criteria

• www/v3/design-guide.html exists, reachable at /v3/design-guide.html, renders cleanly at 320 / 375 / 768 / 1024 / 1280 px (no horizontal overflow — same gate as the rest of the site).
• Every section listed above is present with the listed content.
• The page's <style> block contains zero raw hex, zero raw Npx font-size or spacing or radius, zero numeric font-weight — only var(--token) references (per the self-check grep, modulo SVG attributes and the intentional 50% circles inside the icon SVGs).
• The data-mode="systems" toggle demonstrates the theme override visibly.
• Not linked from any other page; reaching it requires typing the URL.