---
prompt-id: "08"
name: Spec page assembly — self-contained design system HTML documentation
status: live
mcp: none
model: Sonnet 4.6
environment: Claude.ai or Claude Code
inputs:
  - output/tokens.css
  - output/components/foundation.css
  - output/components/composite.css
  - output/components/patterns.css (if present)
  - output/components/chrome.css (if present)
  - specs/governance.spec.md
  - specs/<archetype>.spec.md
outputs:
  - output/design-system-spec.html
chains: [7, 9]
prereqs: ["01", "02", "03", "04"]
documented-in: Ch10 — The Spec Page
post-render: append the publishing-footer credit row (see source/specs/<archetype>.spec.md maintenance notes)
---

# Prompt 08 — Spec page assembly

Assembles all generated CSS + both specs into a single self-contained HTML documentation page:
live component previews, theme switcher, WCAG contrast table, governance reference, and token browser.

---

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
META-HEADER — run before assembling the HTML
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

STEP -2 — DETECT ENVIRONMENT
  Claude Code: save automatically to output/design-system-spec.html
  Claude.ai:   provide the full HTML as a paste-ready block
               with the save path.

STEP -1 — CONTEXT CHECK
  output/tokens.css             → REQUIRED
  output/components/            → need at least foundation.css
                                   and composite.css; include
                                   patterns.css and chrome.css
                                   if present
  specs/governance.spec.md      → REQUIRED
  specs/<archetype>.spec.md     → REQUIRED
  output/chain-state.md         → read if present — confirms
                                   archetype and component scope

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MAIN PROMPT BODY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PROMPT 08 — DESIGN SYSTEM SPEC PAGE

YOUR ROLE
You are assembling a living specification page — the canonical
reference document for the generated design system. It renders
all components live, documents every token, and includes the
WCAG contrast matrix. The page is self-contained: one HTML file
with all CSS inlined in <style> tags and all JavaScript inline
in <script> tags. No external dependencies.

THE SPEC PAGE STRUCTURE
Build the page with these sections in this order:

  1. Page shell (HTML, head, theme switcher logic)
  2. Sidebar navigation (links to each section)
  3. Introduction (archetype name, description, one-line summary)
  4. Token browser (all tokens from tokens.css, searchable)
  5. Colour palette (visual swatches, hex values, WCAG contrast)
  6. Typography scale (type specimens for every size/weight)
  7. Spacing scale (visual ruler for every spacing token)
  8. Foundation components (live renders)
  9. Composite components (live renders)
  10. Pattern components (live renders, if patterns.css exists)
  11. Chrome (live renders, if chrome.css exists)
  12. WCAG contrast table (AA / AAA pass/fail grid)
  13. Governance reference (key rules from governance.spec.md)
  14. Footer (archetype name, generation date, author credit)

SECTION 1 — PAGE SHELL
  <!DOCTYPE html>
  <html lang="en" data-theme="<archetype-default>">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>[Archetype] Design System — Spec Page</title>
    <style>
      /* Paste full contents of tokens.css here */
      /* Paste full contents of foundation.css here */
      /* Paste full contents of composite.css here */
      /* Paste patterns.css and chrome.css if present */
      /* Plus spec-page layout CSS below */
    </style>
  </head>

  Spec page layout CSS (add inside <style>):
    — Two-column layout: fixed sidebar (240px) + scrollable main
    — Sidebar: sticky, dark surface for dark-first archetypes
    — Smooth scroll: html { scroll-behavior: smooth }
    — Section anchors: offset for sticky header
      (:target { scroll-margin-top: 80px })
    — Token browser: grid of token cards (name, value, swatch)
    — Component preview blocks: white/dark surface alternating
      with section heading above each component

SECTION 4 — TOKEN BROWSER
  For each token in tokens.css:
    — Name: --token-name
    — Value: resolved value or "alias → --other-token"
    — Swatch: coloured box for colour tokens; font sample for
      typography tokens; spacing ruler for spacing tokens
  Include a text filter input:
    <input type="text" placeholder="Filter tokens…" id="token-filter">
    <script>
      document.getElementById('token-filter').addEventListener('input', e => {
        const q = e.target.value.toLowerCase();
        document.querySelectorAll('.token-card').forEach(card => {
          card.style.display =
            card.textContent.toLowerCase().includes(q) ? '' : 'none';
        });
      });
    </script>

SECTION 5 — COLOUR PALETTE
  For every colour token in tokens.css:
    — Render a swatch (64px × 64px) with the token name below
    — Show the raw value (oklch() or hex)
    — Show the WCAG contrast ratio against white and black
    — Mark: AA PASS / AA FAIL / AAA PASS in a small badge

SECTION 6 — TYPOGRAPHY SCALE
  For each font-size token:
    — Render a specimen line: "The quick brown fox jumps over
      the lazy dog" in that size + the paired weight token
    — Show token name and computed px value in a label

SECTION 8-11 — LIVE COMPONENT RENDERS
  For each component in the CSS files:
    — Section heading (e.g., "Button")
    — Render all variants and states as visible HTML:
        <button class="btn btn-primary">Primary</button>
        <button class="btn btn-secondary">Secondary</button>
        <button class="btn btn-ghost">Ghost</button>
        <button class="btn btn-primary" disabled>Disabled</button>
    — Each component in a preview card with white/dark toggle
    — Show the class name used as a code label below each example

SECTION 12 — WCAG CONTRAST TABLE
  Matrix of foreground tokens × background tokens.
  For each pair: compute contrast ratio, mark AA/AAA pass/fail.
  Focus on the pairs the archetype spec actually uses:
    — text-primary on surface-base
    — text-secondary on surface-base
    — cta-text on cta-bg
    — text-primary on surface-raised
    — text-disabled on surface-base
  Format: grid table with colour swatch cells and ratio badge.

SECTION 13 — GOVERNANCE REFERENCE
  Pull key rules from governance.spec.md:
    — Naming conventions
    — Spacing system rules
    — Component size constraints
    — Prohibited patterns
  Format as a readable reference table, not the raw spec.

SECTION 14 — FOOTER
  — Archetype: [name]
  — Generated: [date]
  — Design system: [archetype] v1.0
  — Author: Ishdeep S Sahni · Design Systems That Build Themselves
  — Copyright: © 2026 Ishdeep S Sahni. All rights reserved.

THEME SWITCHER
  Add a theme toggle button in the page header:
  <button id="theme-toggle">Toggle dark / light</button>
  <script>
    document.getElementById('theme-toggle').addEventListener('click', () => {
      const html = document.documentElement;
      html.dataset.theme =
        html.dataset.theme === 'dark' ? 'light' : 'dark';
    });
  </script>
  Default: the archetype's native mode
    (dark for Harbor/Lattice; light for Sentinel/Current/Meridian)

ARTIFACTS (claude.ai)
If running in claude.ai, request the HTML as an Artifact before saving:
  "Output the complete design-system-spec.html as an Artifact so I can
   preview it before writing to disk."
This renders the spec page in the claude.ai preview panel — review
all sections visually before saving to output/design-system-spec.html.

POST-RENDER STEP
After the HTML is complete, append the publishing-footer credit
row inside the <footer> element at the bottom of the page:
  <p class="spec-footer-credit">
    Generated by Design Systems That Build Themselves v2 ·
    © 2026 Ishdeep S Sahni · All rights reserved.
  </p>
See specs/<archetype>.spec.md → "Publishing footer" section
for any archetype-specific markup variations.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
META-FOOTER
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

SAVE INSTRUCTION
Save as: output/design-system-spec.html
Open in a browser to verify:
  — Theme toggle works
  — All components render correctly
  — Token filter searches correctly
  — WCAG contrast table is accurate

CHAIN-STATE LOG
Append to output/chain-state.md:

  ## Prompt 08 — Spec page
  Date: <today>
  Archetype: <confirmed archetype>
  Output: output/design-system-spec.html
  Sections: token browser, colour palette, typography,
    components, WCAG table, governance reference
  WCAG failures: <count or "none">

HANDOFF
  "Spec page assembled. You can open output/design-system-spec.html
   in a browser right now — it's self-contained.
   Next → Prompt 09 — Section templates (page-level layout
   templates per your archetype) — or stop here if your scope
   is complete."
```
