# Design System & Conversion Guide **Version 2.0** — March 2026 A dark-mode design system for long-form reference documents. Designed for evidence-forward, research-heavy content with deep information hierarchy. Optimized for readability on screens, with print and reduced-motion support. **Rules:** 1. The CSS block in this document is the single source of truth. It must be copied identically into every HTML file that uses this theme. No per-file CSS modifications. 2. New patterns are added to this spec first, then propagated to all files. 3. Every file's footer must include the spec version alongside the content's own last-updated date. --- ## Fonts The theme uses system font stacks by default. No external font dependencies are required. ``` --font-display: Georgia, 'Times New Roman', serif; --font-body: system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; --font-mono: ui-monospace, 'SFMono-Regular', 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace; ``` **Optional Google Fonts enhancement.** To use custom web fonts, add the following `` elements to `` before the `
[Category or type label]

[Document Title]

[One or two sentence summary]

[Section heading]

[Content]

``` --- ## Component Reference Each entry: class name, HTML pattern, purpose and tone. ### `.banner` ```html ``` **Tone:** Inviting, prominent. "Start here if you want the short version." Use when the document has a clear entry point, summary, or TL;DR. ### `.callout` ```html

Key point: Explanation of the core insight.

``` **Tone:** Warm, authoritative. "Internalize this." Use for key insights, principles, and takeaways the reader should remember. ### `.callout-warning` ```html

Caution: Description of the risk or mistake.

``` **Tone:** Cautionary, urgent. "Stop and pay attention." Use for risks, mistakes, cautions, caveats, and things that could go wrong. ### `.card` ```html

Task Title Verified

Description of the task or exercise.

  1. Step one.
  2. Step two.
``` **Tone:** Task-oriented, self-contained. "Here's something actionable." Use for exercises, tasks, definitions, or any content block that stands alone as a unit. ### `.feature-box` ```html

Highlighted Content

Structured content that deserves visual elevation.

``` **Tone:** Elevated, featured. "This block is important and structured." Use for routines, summaries, featured content, and structured reference blocks that need to stand out. ### `.badge` / `.badge-green` / `.badge-amber` / `.badge-rose` ```html Verified In Progress Preliminary ``` **Tone:** Status indicator. Use for confidence levels, verification states, evidence strength, categories, or any status that benefits from a colored pill. Green = positive/strong/confirmed. Amber = moderate/established/in-progress. Rose = emerging/limited/tentative. ### `.inline-badge` ```html 3 min ``` **Tone:** Inline metadata. Use for time estimates, dates, version numbers, or small factual labels within flowing text. ### `.steps` ```html
  1. First step.
  2. Second step.
``` **Tone:** Sequential, instructional. "Follow these in order." Use for ordered procedures where sequence matters. ### `.checklist` ```html ``` **Tone:** Actionable tracking. "Check these off." Use for preparation lists, verification lists, and to-do items. ### `.aside` / `.aside-label` ```html
Category

Supplementary or categorized content.

``` **Tone:** Supplementary, tangential. "This is related but can be read separately." Use for language-specific sections, categorized tangents, or content grouped by a label. ### `details` / `summary` / `.details-body` ```html
Expandable section title

Content that can be skipped on first read.

``` **Tone:** Depth on demand. "Read this if you want more detail." Use for supplementary explanations, evidence deep-dives, and content the reader may want to skip initially. ### `.references` ```html

Author, A. (2024). Title of work. Journal, 1(2), 3–4.

``` **Tone:** Scholarly, compact. Use for bibliographies and source lists. Hanging indent is automatic. ### `.table-wrapper` + `table` ```html
Header
Data
``` Always wrap `` in `.table-wrapper` for responsive horizontal scrolling. ### `.kicker` ```html Category Label ``` Monospace uppercase overline label. Used in the header above h1 and anywhere a small categorical label is needed above a heading. ### Utilities - `.mono` — inline monospace text that isn't `` (phonetic notation, identifiers, etc.) - `.muted` — muted text color - `.small` — smaller font size (0.88rem) - `.text-center` — centered text --- ## Accessibility Requirements These must be present in every file: 1. **Skip link.** `
` in `