Scaffold editorial documentation sites with the Vellum design system — OKLCH palette, Bodoni Moda / Source Serif 4 / Inconsolata typography, warm or dark space theme, 35 semantic components (state cards, parity matrices, entity dossiers, stat stacks, utterance blocks, editorial notes, entity flows, fact blocks, sub-navigation, source lists, debugger panels, ring visualizations, phase timelines, glossaries, subject-intro, stat-bar, hero-image with lightbox, gallery/masonry grid, audio player with Web Audio API). Static HTML, zero build step. Use when building competitive intelligence pages, personal archives, internal documentation, roadmaps, or multi-page static sites that need a designed, non-generic aesthetic.
Scaffold editorial documentation sites with the Vellum design system — OKLCH palette, Bodoni Moda / Source Serif 4 / Inconsolata typography, warm or dark space theme, 35 semantic components (state cards, parity matrices, entity dossiers, stat stacks, utterance blocks, editorial notes, entity flows, fact blocks, sub-navigation, source lists, debugger panels, ring visualizations, phase timelines, glossaries, subject-intro, stat-bar, hero-image with lightbox, gallery/masonry grid, audio player with Web Audio API). Static HTML, zero build step. Use when building competitive intelligence pages, personal archives, internal documentation, roadmaps, or multi-page static sites that need a designed, non-generic aesthetic.
argument-hint
["project-name"]
Build editorial documentation sites with the Vellum design system. Two theme variants (warm parchment, dark space), OKLCH color science, three-font typographic hierarchy, 35 semantic components. Static HTML with zero build step — deploys to Cloudflare Pages, GitHub Pages, or any static host.
Creative Direction
Two theme variants, each with a distinct character:
Warm (default): "Vellum manuscript" — warm cream backgrounds with a subtle SVG crosshatch texture, deep ink-brown text, copper accents. Authoritative, like a well-made journal.
Dark: "Space archive" — deep blue-black backgrounds with CSS starfield (box-shadow stars + nebula gradients), bright gold copper accents, cool blue-gray text. Atmospheric, like a command center or digital archaeology site.
Both themes share the same typography, component library, and layout system. The palette transformation is purely in :root custom properties — no structural CSS changes needed.
If the minoan-frontend-design skill is available, read it for broader aesthetic principles. Vellum encodes those principles into a concrete design system. Pages built with Vellum should score 16+/20 on and 28+/40 on .
This generates a deploy-ready site with CSS, starter HTML, OG/Twitter social meta tags, a light/dark theme toggle, and optionally a client-side auth gate and ambient audio player. By default, --deploy-ready generates _headers (CF Pages security headers) and robots.txt (crawl prevention). The --theme dark flag transforms the palette to a dark space aesthetic with CSS starfield background. Open index.html in a browser — fonts load from Google Fonts, icons from Phosphor Icons CDN.
instrument — Manrope typography, grid-dot texture. Precision instrument panel character for technical product overviews.
Templates control the content scaffolding:
landing (default) — Simple 3-section page with overview, features, comparison.
one-pager — 8-section technical overview with TOC, state-card grids, configuration matrix, phase timeline, and deployment section.
Design System
Three fonts: Bodoni Moda (display/headlines, italic), Source Serif 4 (body text), Inconsolata (monospace/labels/badges). All loaded from Google Fonts.
OKLCH palette with 50+ custom properties organized as base / bg / border triples for each semantic color. The core palette — --ink, --copper, --bg, --bg-warm, --bg-card, --border, --text-body, --text-label, --text-muted, --ghost — defines the vellum character. Navigation state (--nav-active / --nav-active-bg / --nav-active-border), severity tiers (--dealbreaker, --high, --moderate), platform colors (--subq, --claude, --cursor, --codex), and status indicators (--planned, --building, --shipped, --blocked) extend it. Content organized by era or category uses additional --era-* color triples.
Full token reference: references/design-tokens.md.
Component Library
35 components across 7 groups: layout (breadcrumb, page-nav, header, section, footer), cards (state-card, hook-card, cap-panel, further-card, quote-card, req-card), data display (matrix, matrix-note, glossary, ring, debugger-panel), indicators (status-dot, status-chip, tier-badge, chip), editorial (toc, pullquote, savings-callout, supersession, advantage-row, phase-timeline), intelligence (dossier, stat-stack, utterance, editorial-note, entity-flow, fact-block, sub-navigation, source-list), and media (subject-intro, stat-bar, hero-image with lightbox, gallery/masonry-grid, audio-player). Each supports multiple color variants following the semantic palette.
Copy-paste HTML snippets for every component: references/component-catalog.md.
Page Architecture
Six page patterns:
Landing page: breadcrumb → page-nav → header (icon, tag, h1, subtitle) → main (numbered sections with ghost section-num) → footer
Every page includes: skip link (<a href="#main" class="skip-link">), _shared.css (core system), _components.css (components), Google Fonts preconnect, Phosphor Icons CDN. Auth gate (_auth.js) loads before body content when enabled. Audio player (_audio-player.js) loads at end of body when enabled.
Full page structure patterns: references/page-architecture.md.
Customization
Adapt for a different client by editing :root custom properties in _shared.css:
Theme selection (scaffold time): Use --theme dark to start with a dark palette, or accept the default warm theme.
Color swap (~5 min): Change --copper hue, adjust --ink/--bg warmth, update platform colors to match client brands.
Era/category colors: Add --era-* triples (base / bg / border) for content organized by time period, category, or entity type. See design-tokens.md for the pattern and lightness guidelines.
Structural additions: Add new component variants following the base / bg / border triple pattern and BEM-like naming.
The 50+ CSS custom properties are the entire theming surface. No build step, no preprocessor.
Auth Gate
Optional client-side courtesy gate using FNV-1a hashing with sessionStorage. Not real security — a visibility gate for non-public docs. Set a password at scaffold time with --password <string> — the init script computes the FNV-1a hash automatically and writes the correct constant into _auth.js. Each project gets a unique sessionStorage key (vellum_auth_{project-name}) to avoid cross-site collisions.
Diagrams (Optional)
Vellum pages can include Mermaid diagrams rendered as inline SVGs via the beautiful-mermaid skill. No JavaScript dependency — diagrams are static SVG inlined at build time.
Generate a vellum-themed SVG:
printf'graph TD\n A --> B --> C' | \
node ~/.claude/skills/beautiful-mermaid/scripts/mermaid.mjs \
-f svg -t vellum --transparent -o diagram.svg -
Inline into a diagram panel:
<figureclass="diagram-panel"><pclass="diagram-panel__label">System Architecture</p><!-- Paste SVG output here (remove width/height, keep viewBox) --><figcaptionclass="diagram-panel__caption">Request flow from API gateway to storage</figcaption></figure>
The vellum theme uses cream/ink/copper colors matching the design system. The --transparent flag lets the panel's --bg-card background show through. Supported diagram types: flowchart, state, sequence, class, ER. See references/component-catalog.md for component variants (--copper, --bleed).
The scaffolded _headers and robots.txt handle security and crawl prevention automatically. Use --no-deploy-ready to skip these files for local-only development.
Social Preview (OG Image)
Every scaffolded page includes OG and Twitter Card meta tags pointing to og-image.png. Generate a 1200x630 OG image with ImageMagick:
Or use /badge-generator for a medallion-style icon, then composite onto the dark background. Test the preview by pasting the deployed URL into Slack or the Twitter Card validator.
Anti-Patterns
Never use border-left accent stripes on cards — use ::before top-bar (like state-card). Never use gradient text (background-clip: text). Never use system-ui or default fonts. Always include skip-link and prefers-reduced-motion. Break up sequences of more than 6 state-cards with a pullquote or section break.
References
File
When to consult
references/design-tokens.md
Building new components or customizing the palette
references/component-catalog.md
Need HTML snippets for any component
references/page-architecture.md
Setting up page structure, nav, TOC, or glossary
references/advanced-patterns.md
Ghost watermarks, asymmetric grids, fluid typography, opacity hierarchy, logo handling
