# Meridian · Archetype Spec Sheet · v1.0 **Status:** authored from v1 Ch11 (Meridian section) + Finding 12 mock + reading-system conventions (Stripe Docs, MDN, Notion, Substack, academic typography). Source of truth for the long-form reading archetype. **Use:** two-paste workflow per prompt. 1. Paste [governance.spec.md](governance.spec.md) first (universal gates — non-negotiable). 2. Paste the fenced block below second (Meridian-specific rules). Consumed by Prompt 1 (token generation), Prompt 03 (foundation components), Prompt 04 (composite components), Prompt 05 (UI patterns), Prompt 08 (spec page), Prompt 09 (article assembly). **Origin:** [reference/book-v1.html](../../reference/book-v1.html) Ch11 lines 3192–3331. Mock pattern: [finalbookplan.md](../../finalbookplan.md) Finding 12. --- ``` ═══════════════════════════════════════════════════════════════ MERIDIAN · ARCHETYPE SPEC · v1.0 Long-form reading / Documentation / Knowledge bases ═══════════════════════════════════════════════════════════════ TAGLINE: a design system for long-form documentation, knowledge bases, and reading-optimized products. Body text is the hero. Chrome is minimal. PREREQUISITE: governance.spec.md MUST be loaded before this spec. Meridian inherits all universal gates and adds the overrides at the end of this block. ─────────────────────────────────────────────────────────────── THEME ─────────────────────────────────────────────────────────────── Mode: LIGHT-FIRST; sepia/warm-cream variant for extended reading; dark mode for night reading Palette character: warm-neutral, high-contrast, minimal accent. Body text is the protagonist — every chrome decision is "does this support reading or compete with it?" Pure #FFF banned (sterile in long-reading contexts; use warm off-white #FAFAF8) Pure #000 banned (harsh on warm bg; use warm off-black #1A1A1A) Sepia mode (Meridian-specific): --surface-page #F5EFE0 warm cream --text-body #2B2B2B Use for: extended-reading apps (Kindle-style) Reason: documentation is read for hours. The eye fatigues on high-contrast white-on-black or black-on-white. Warm neutrals reduce strain. Sepia variant respects readers who customize for marathon sessions. ─────────────────────────────────────────────────────────────── THE READING DOCTRINE — Meridian's keystone ─────────────────────────────────────────────────────────────── Body text IS the hero. Every other element exists to serve reading. Implications: - Body size LARGER than web default (17–19px, not 14–16px) - Reading-width HARD CAPPED at 65–72ch (eye fatigue past 80ch) - Line height GENEROUS (1.7–1.8 — Sentinel/Lattice use 1.5) - Chrome MINIMAL (no carousels, no hero promos, no popups) - Imagery TEACHES (diagrams, screenshots) — never decorates - Voice INSTRUCTIONAL (you-form, present tense, no hype) Meridian is the inversion of Lattice. Where Lattice maximizes density, Meridian maximizes comprehension. ─────────────────────────────────────────────────────────────── TOKEN NAMING ─────────────────────────────────────────────────────────────── Strategy: SEMANTIC + reading-specific aliases (article, footnote, sidenote, callout, code-inline, code-block, pull-quote) Examples: --text-body, --text-lede, --text-muted, --text-link, --text-h1, --text-h2, --text-h3, --text-h4 --reading-width, --reading-width-lede, --reading-width-quote, --reading-width-wide --callout-bg-note, --callout-bg-warning, --callout-bg-danger, --callout-bg-tip --code-inline-bg, --code-block-bg --footnote-text, --footnote-link, --sidenote-text Reason: reading systems have specialized roles that don't exist in product UI (footnotes, sidenotes, callouts with semantic flavor, lede vs body distinctions). The naming mirrors editorial typography vocabulary. ─────────────────────────────────────────────────────────────── COLOR TOKENS (canonical defaults — substitute equivalents) ─────────────────────────────────────────────────────────────── ▼ LIGHT MODE (default) Surfaces: --surface-page #FAFAF8 warm off-white (NEVER pure #FFF) --surface-card #FFFFFF slightly raised --surface-sunken #F5F5F0 code blocks, sidebar bg --surface-quote #FAF7F0 pull quote bg (subtle warm tint) Text (NOTE: COLOR tokens use -color suffix to avoid collision with size tokens like --text-body / --text-lede that exist in :root): --text-body-color #1A1A1A warm off-black (NEVER pure #000) --text-strong-color #000000 acceptable inside body for emphasis --text-muted-color #6B6B6B metadata, captions --text-faint-color #9B9B9B timestamps, breadcrumb separators --text-heading-color #111111 serif headings --text-lede-color #2A2A2A intro/lede paragraphs Borders / dividers: --border-subtle rgba(0,0,0,0.08) --border-default rgba(0,0,0,0.12) --border-strong rgba(0,0,0,0.20) Accent (used SPARINGLY — only for links and a few state markers): --accent-link #0066CC blue link (the only color on the page in pure reading mode) --accent-link-hover #004499 --accent-link-visited #663399 purple (academic convention) --accent-highlight rgba(255,235,153,0.5) highlighted text bg ▼ SEPIA MODE (extended reading variant) --surface-page #F5EFE0 warm cream --surface-card #FAF5E8 --surface-sunken #EDE5D0 --text-body #2B2B2B slightly softer than light mode --text-muted #6B5E48 --text-faint #6F6656 /* WCAG AA: was #9B8E78 (2.56:1 FAIL) → #6F6656 (4.51:1 AA, warm-preserving) */ --accent-link #6B5B95 purple-blue (better on cream) --code-comment #6F6656 /* WCAG AA — same fix as --text-faint */ ▼ DARK MODE (night reading) --surface-page #1A1A1A --surface-card #242424 --surface-sunken #2E2E2E --text-body #E8E8E8 warm off-white --text-muted #999999 --text-faint #949494 /* WCAG AA: was #666666 (2.70:1 FAIL on card) → #949494 (4.48:1+ AA on all dark surfaces) */ --accent-link #66B3FF --accent-highlight rgba(255,235,153,0.2) --code-comment #8B8B8B /* WCAG AA: was #666666 (2.67:1 FAIL on code-block-bg) → #8B8B8B (4.50:1 AA) */ ▼ CALLOUT BACKGROUNDS (semantic — left-rule + tinted bg) --callout-note-bg rgba(0,102,204,0.06) --callout-note-rule #0066CC --callout-tip-bg rgba(0,168,120,0.06) --callout-tip-rule #00A878 --callout-warning-bg rgba(217,119,6,0.06) --callout-warning-rule #D97706 --callout-danger-bg rgba(220,53,69,0.06) --callout-danger-rule #DC3545 ▼ CODE --code-inline-bg rgba(0,0,0,0.06) subtle tint --code-block-bg #F5F5F3 --code-text #1A1A1A --code-keyword #C586C0 syntax keyword --code-string #6A9955 syntax string --code-comment #999999 syntax comment ▼ FOCUS RING --color-focus-ring rgba(0,102,204,0.5) ─────────────────────────────────────────────────────────────── TYPOGRAPHY — the most consequential section in Meridian ─────────────────────────────────────────────────────────────── Approach: fluid clamp() — body is THE thing Family: --font-serif "Charter", "Iowan Old Style", "Source Serif", Georgia, "Times New Roman", serif --font-sans "Inter", system-ui, -apple-system, sans-serif --font-mono "JetBrains Mono", "SF Mono", Menlo, monospace Body font choice (Meridian's defining decision): Default: --font-serif (academic, editorial, signals "long reading") Alternate: --font-sans (Notion-style, technical docs feel) NOTE: this is the ONE archetype where serif body is the default. Choose deliberately based on product voice. Stripe Docs uses sans (technical); Substack uses serif (editorial). Body sizes (LARGER than web default — Meridian's keystone): --text-body clamp(1.0625rem, 0.95rem + 0.4vw, 1.1875rem) 17px → 19px --text-lede clamp(1.1875rem, 1rem + 0.8vw, 1.375rem) 19px → 22px (intro paragraph, "deck" copy) --text-body-sm clamp(0.9375rem, 0.875rem + 0.25vw, 1rem) 15px → 16px (sidebars, captions) --text-caption 13px (metadata, timestamps — fixed) Heading sizes (utilitarian, not decorative): --text-h1 clamp(2rem, 1.5rem + 2vw, 2.75rem) 32–44px --text-h2 clamp(1.5rem, 1.2rem + 1.4vw, 2rem) 24–32px --text-h3 clamp(1.25rem, 1.1rem + 0.7vw, 1.5rem) 20–24px --text-h4 clamp(1.125rem, 1.05rem + 0.4vw, 1.25rem) 18–20px Code sizes: --text-code-inline 0.92em (slightly smaller than body — tucks visually) --text-code-block 0.9375rem (15px fixed) Font weights: --weight-regular 400 body --weight-medium 500 captions, labels --weight-semibold 600 headings, link-emphasis --weight-bold 700 strong emphasis only Line heights — Meridian's signature: --leading-body 1.75 body (LONG-form — generous) --leading-lede 1.6 lede paragraph --leading-heading 1.25 tight on headings --leading-code 1.6 code blocks (vertical breathing room) Letter spacing: --tracking-body 0 body --tracking-heading -0.01em headings (tighter for serif) --tracking-overline 0.08em uppercase metadata labels Text-wrap (for prose quality): --wrap-heading balance (avoid orphan words) --wrap-body pretty (balance last few lines) Reason: 17–19px at 1.75 line-height is the academic-typography sweet spot for sustained reading. Web default of 14–16px at 1.5 was tuned for product UI scanning, not reading. Meridian inverts this default deliberately. ─────────────────────────────────────────────────────────────── DENSITY — reading-comfortable ─────────────────────────────────────────────────────────────── Character: GENEROUS but PURPOSEFUL — every spacing decision asks "does this support reading rhythm?" Spacing scale: --space-1 4px inline gap --space-2 8px tight pair --space-3 12px list bullet to text --space-4 16px between paragraphs (DEFAULT) --space-5 20px between paragraph and following heading --space-6 24px between sub-sections --space-8 32px between major content blocks --space-10 40px between top-level sections --space-12 48px between article and footer --space-16 64px page top spacing --space-20 80px chapter breaks (rare) Paragraph spacing: --space-4 (16px) between consecutive paragraphs (NOT first-line indent — first-line indent is for print, not screen) Heading spacing: margin-top: --space-8 (32px) for h2, --space-6 for h3 margin-bottom: --space-3 (12px) — tight pair with body (heading + first paragraph reads as a unit) Reading widths (HARD CAPS): --reading-width 68ch article body (NEVER exceed) --reading-width-narrow 56ch lede, intro --reading-width-quote 52ch pull quotes, blockquotes --reading-width-wide 80ch tables, code blocks (allowed wider since they don't read line-by-line) THE RULE: body content NEVER exceeds 72ch — eye fatigue collapses past this width. Tables and code blocks may extend to 80ch since they're scanned, not read prose. ─────────────────────────────────────────────────────────────── ACCENT STRATEGY ─────────────────────────────────────────────────────────────── Strategy: MINIMAL — accent reserved almost exclusively for links and highlighted text Default accent: --accent-link blue (#0066CC light, #66B3FF dark) Optional accents (per product brand): --accent-brand for nav active state, logo color, footer Banned: ✗ Multi-accent palette (Current pattern) ✗ Accent backgrounds on chrome surfaces ✗ Gradient backgrounds anywhere ✗ Color in body copy (use --text-strong for emphasis, italic for term-introduction, NOT colored text) Reason: in long-form reading, COLOR IS A DISTRACTION. A colored callout draws the eye away from where it's reading. A colored heading interrupts flow. The only acceptable color in body content is the link color (and visited-link color), because links carry navigational meaning. ─────────────────────────────────────────────────────────────── ELEVATION ─────────────────────────────────────────────────────────────── Default: FLAT — like Lattice, Meridian is one of the flatter archetypes. No shadows on default surfaces. Shadows: reserved for floating overlays only (search modal, table of contents popup, copy-link toast) --shadow-sm 0 1px 2px rgba(0,0,0,0.04) subtle (rare) --shadow-md 0 4px 12px rgba(0,0,0,0.08) search modal --shadow-lg 0 8px 24px rgba(0,0,0,0.12) command palette Banned: shadows on cards in body content (visual weight steals attention from text) Banned: warm oklch shadows (Harbor pattern — too atmospheric for reading) Reason: shadows are visual interruption. Reading flow is fragile — every visual weight decision must justify its cost. ─────────────────────────────────────────────────────────────── RADII ─────────────────────────────────────────────────────────────── Scale (5 steps — minimal, restrained): --radius-none 0 text, code blocks, callouts (sharp = editorial) --radius-xs 2px inline code background, badges --radius-sm 4px buttons (rare in body content), search modal --radius-md 8px dialogs, search popovers --radius-pill 9999px filter chips (in docs nav only) Banned: > 8px radius on any element in body content Banned: rounded code blocks (looks like a sticker) Reason: editorial typography uses sharp corners by convention (books, magazines, academic journals). Rounded corners feel product-y; reading systems lean editorial. ─────────────────────────────────────────────────────────────── MOTION ─────────────────────────────────────────────────────────────── --duration-fast 150ms hover, link state --duration-base 200ms search modal open --duration-slow 300ms page transitions --easing-standard cubic-bezier(0.4, 0, 0.2, 1) Reduced-motion fallback: instant transitions (Meridian's default is already minimal). Use motion ONLY for: - Search modal open/close - Reading progress bar (continuous) - Theme toggle (smooth color transition) - Anchor link smooth-scroll (with prefers-reduced-motion fallback to instant jump) Banned (these all interrupt reading): ✗ Animations on body content (no fade-in paragraphs, no scroll-triggered reveals) ✗ Auto-playing media of any kind ✗ Parallax, scroll-jacking ✗ Rotating headlines, marquee ✗ Skeleton shimmer ✗ Hover animations on cards (cards in reading systems are rare and shouldn't shimmy) Reason: motion in body content interrupts reading. The eye follows motion involuntarily. A reading system that animates loses readers. ─────────────────────────────────────────────────────────────── ICONOGRAPHY ─────────────────────────────────────────────────────────────── Family default: HEROICONS (outline) Reason: Heroicons is the family Stripe Docs, Vercel Docs, Tailwind Docs, and most modern documentation sites converge on. Refined editorial feel; outline variants pair quietly with serif body without competing for visual weight. The "solid" Heroicons variant is allowed sparingly for inline indicators where filled aids recognition (warning callouts, code-file icons). Substitute Iconoir if Heroicons unavailable (similar editorial restraint). NEVER use Lucide for Meridian (Lucide's stroke is heavier — competes with reading flow). Grid: 20px standard for chrome (slightly smaller than Sentinel's 24px); 16px inline (e.g., external-link indicator) Stroke: 1.5px (Heroicons outline default — matches editorial restraint) Color: inherit via currentColor (typically --text-muted in chrome) Style: - Outline icons everywhere in body / chrome - Solid (Heroicons solid set) ONLY for inline indicators where filled aids recognition: warning callouts, code-file icons - Inline indicators for external links (small arrow-up-right), code files (file-type icon), warning callouts (triangle) Banned: ✗ Emoji as icon (governance — applies even in friendly docs) ✗ Filled icons in body content (weight conflicts with reading) ✗ Multi-color icons ✗ Decorative icons in articles (only functional icons) ✗ Animated icons except spinner ✗ Lucide / Material / Phosphor families (heavier strokes compete with reading flow; Heroicons is the editorial-docs convention) Inline icons in body (when used): - External link: arrow-up-right after link text - Code file: file-code icon before code-block filename - Footnote: superscript number (NOT an icon) - Internal anchor: hash "#" on heading hover ─────────────────────────────────────────────────────────────── DOCUMENT LAYOUTS — page composition vocabulary ─────────────────────────────────────────────────────────────── D1 ARTICLE LAYOUT (the dominant pattern) Structure: header (slim, breadcrumb + meta) + article body (centered, --reading-width) + optional sidebar TOC (right or left, scroll-spy) + footer (related articles, prev/next) Sidebar TOC behavior: visible at >1200px viewport; collapses to top-of-page link list below Banned: full-width article body (hard cap at --reading-width) D2 DOC LAYOUT (knowledge base / docs) Structure: top nav + persistent left sidebar (sections / versions / search) + article body + right sidebar (TOC of current page) Three columns at >1280px; collapses gracefully Banned: hiding nav behind hamburger on desktop D3 LANDING / INDEX Structure: hero (compact — title + 1-line description + search) + grouped article cards + footer Use for: docs root page, "browse all guides", search results Banned: marketing-style hero with promotional CTAs (this is docs, not marketing) D4 READER MODE (distraction-free) Structure: minimal header (back button + theme toggle + font controls) + article body only (no sidebars, no chrome) Use for: opt-in distraction-free reading Required: respects user font-size preferences, theme preference (sepia / dark / light) D5 PRINT-FRIENDLY Structure: article body only, sidebars hidden, full URLs expanded for footnoted links, headers/footers collapsed Required: @media print rules included by default D6 SEARCH RESULTS Structure: search field (Cmd/Ctrl+K full-screen modal) + grouped results (by section / by content type) + snippet preview with match highlighting Required: keyboard navigation (Arrow keys), Enter to open, Esc to close Composition rule: every Meridian page is one of these six. The shapes are conventional — readers should not have to re-learn navigation. ─────────────────────────────────────────────────────────────── COMPONENT LIBRARY — generate in this priority order ─────────────────────────────────────────────────────────────── ▼ FOUNDATION (Layer 1 — Prompt 03) 1. Article (the structural primitive) Structure: optional eyebrow (category, --tracking-overline) + h1 + optional lede + author/date metadata + estimated read time + body Body: --reading-width (68ch) max, all paragraphs and inline-elements constrained Required: structured-data markup (article schema), OG meta tags 2. Heading (h1–h4 with anchor) Required: every heading (h2+) has an auto-generated id, hover reveals "#" anchor, click copies URL with fragment Hover: small "#" icon appears at left or right Click: copies anchor URL, shows toast "Link copied" Required: aria-label on the anchor for screen readers ("Permalink to: {heading text}") 3. Body paragraph --text-body, --leading-body (1.75), max-width --reading-width (68ch) First paragraph (lede): --text-lede, --reading-width-narrow (56ch), no first-line indent 4. Inline elements a) Link Style: --accent-link, underline (1px solid by default), underline-offset 2px States: default / hover (--accent-link-hover, underline thickens) / visited (--accent-link-visited) / focus-visible (focus ring) External link: trailing arrow-up-right icon (12px) b) Code-inline Style: --code-inline-bg, --radius-xs, padding 1px 4px, --font-mono, --text-code-inline (0.92em) Banned: line-break inside; use white-space: nowrap c) Strong / bold Use for: noun emphasis, term-of-art introduction Style: --weight-bold + --text-strong d) Italic Use for: term introduction (first-time use), book/work titles, emphasis-not-volume Banned: italic for volume emphasis (use bold instead) e) Mark (highlight) Style: --accent-highlight bg, --text-body color Use for: search match highlight, key term flag f) Footnote reference Style: superscript number, --accent-link color, no underline Hover: tooltip showing footnote content Click: jumps to footnote at end of article (back-link returns) 5. Button Variants: primary (--accent-link bg, white text) / secondary (border + accent text) / tertiary (text-only) Sizes: sm (h:32px) / md (h:40px) Lattice rule: buttons are RARE in Meridian body content — most CTAs are inline links. Buttons reserved for end-of-article actions (Subscribe, Next article) 6. Search input Style: --surface-card bg, 1px border, search-icon leading Width: full sidebar width or --reading-width when standalone Required: opens full search modal on focus (search modal has more powerful UX) ▼ COMPOSITE (Layer 2 — Prompt 04) 7. Sidebar TOC (Table of Contents) Structure: list of headings (h2–h4) with indent reflecting depth, current section highlighted via scroll-spy Position: right sidebar (>1200px viewport) or left (alternative) Behavior: scroll-spy auto-highlights current heading; clicking a TOC item smooth-scrolls (or instant with prefers-reduced-motion) Collapse: on narrow viewport, collapses to "On this page" expandable at top of article Required: keyboard navigation (Arrow up/down through items) 8. Doc nav sidebar (left) Structure: grouped sections (collapsible), current page highlighted, version switcher at top Persistent across doc browsing Required: keyboard navigation, search input at top (Cmd/Ctrl+K opens full search modal) 9. Callout box (note / tip / warning / danger) Structure: left-rule (4px, semantic color) + icon (20px leading) + title (--weight-semibold) + body Variants: note (blue) / tip (green) / warning (orange) / danger (red) Background: tinted (semantic color at 0.06 opacity) Required: title is mandatory ("Note", "Tip", custom title like "iOS-only", etc.) Banned: modal-style callouts that interrupt reading (callouts are inline, not floating) 10. Code block Structure: optional filename header (--surface-sunken, file-type icon + filename + copy button) + syntax-highlighted code (--surface-sunken bg, --space-4 padding, --reading-width-wide max) Required: syntax highlighting per language, copy-to- clipboard button (top-right), optional line numbers (off by default), optional line highlighting for callout Languages: support 20+ common (JS, TS, Python, Rust, Go, CSS, HTML, JSON, YAML, Bash, SQL, etc.) Wrapping: horizontal scroll for long lines (NEVER wrap — breaks code legibility) 11. Inline tabs (multi-language code switcher) Structure: tab strip ("JavaScript / Python / Ruby") + code block per tab Required: keyboard navigation (Arrow keys), persistent selection across page (LocalStorage by group) 12. Pull quote (block-level emphasis) Style: --font-serif italic (matches Harbor pattern), larger than body (--text-lede), --reading-width-quote (52ch), indented from main column, optional attribution below Banned: quotation marks (the visual style does the work) Banned: pull-quote-as-marketing (must be quoting actual text) 13. Footnote Structure: superscript number in body → numbered list at article end with definitions Styling: --text-body-sm (15px), --text-muted, back-link returns to body position Required: numbered sequentially per article, back-link is accessible (aria-label "Return to text") 14. Sidenote (Tufte-style — optional Meridian variant) Structure: marginalia in the right margin (or expanded below paragraph on narrow viewport) Style: --text-body-sm, --text-muted Use for: parenthetical asides, related context, source citations Optional pattern (not all Meridian products use sidenotes — enable per product) 15. Reading progress bar Position: thin (2px) line at top of viewport Behavior: fills 0% → 100% as user scrolls article Color: --accent-link Required: respects prefers-reduced-motion (jumps in 10% increments instead of continuous) 16. Estimated read time Position: at top of article, near metadata Format: "8 min read" Calculation: (word count / 250) rounded to nearest minute, round up if < 1 min --text-caption, --text-muted 17. Search modal (Cmd/Ctrl+K) Structure: search field (focused on open) + grouped results (by section / page / type) + snippet preview with match highlighted + keyboard hints in footer Required: fuzzy match, instant results, keyboard navigation, Esc closes, focus returns to trigger Style: centered modal, --shadow-lg, --radius-md 18. Theme toggle Position: top-right of nav Variants: light / sepia / dark / system Required: respects prefers-color-scheme as default, persists user choice (LocalStorage) 19. Font controls (Reader Mode only) Position: top of Reader Mode header Controls: font-size up/down (3 steps), font-family toggle (serif / sans), line-height toggle (compact / comfortable) Required: persists per-user (LocalStorage) 20. Loading states Spinner: 24px circle, --accent-link stroke (rare — most docs render statically) Skeleton: NEVER use shimmer (Meridian motion ban). Use opacity-static placeholder blocks if needed. 20a. Figure container (diagrams + charts + screenshots — generic wrapper for any visual asset that appears mid-body) Structure:
wrapper + asset (SVG / inline chart / screenshot / Mermaid render) +
(REQUIRED — describes what the reader should see) Width: --reading-width-wide (80ch max — wider than body since assets are scanned, not read line-by-line) Variants: a) Diagram (architecture, decision tree, flow) — SVG rendered from text source (Mermaid / PlantUML / D3), keyboard-accessible, screen-reader text alt b) Inline chart (line / bar / area) — small inline SVG showing technical metric (e.g., "p99 latency over time") with axis labels + legend c) Screenshot — annotated with numbered callouts (matching a numbered list in surrounding prose); width ≤ figure container; alt text describes what's annotated d) Math equation — KaTeX or MathJax rendered (NOT image); inline `$...$` for short expressions, block `$$...$$` for displayed equations Meridian rule: figcaption is MANDATORY — every figure tells the reader what to see. "Figure 2: Token cascade flow" not just "Figure 2." Meridian rule: figures break out of body width (--reading- width 68ch) up to --reading-width-wide (80ch) — captioned and centered Meridian rule: NO decorative figures — every figure must teach. If the figure can be removed without losing meaning, remove it. Meridian rule: dark-mode + sepia variants of figures must be defined (SVGs use currentColor; raster screenshots ship 2-3 versions) A11y:
+ descriptive alt text + tabindex=0 on interactive figures ▼ PATTERNS (Layer 3 — Prompt 05) 21. Article header Structure: breadcrumb + h1 (--text-h1, balance wrap) + lede (--text-lede, --reading-width-narrow) + author/date/read-time metadata row Banned: hero image > 200px tall (delays first paragraph) Banned: social share buttons above the fold (no skin in game yet) 22. Article body composition Pattern: alternating prose paragraphs (max 3–4 sentences) + h3 sub-sections + occasional callouts + code blocks + (rare) inline images with captions Banned: walls of text (paragraphs > 6 sentences); split Banned: 3+ images per screen-page (visual fatigue) 23. End-of-article block Structure: divider + author bio (small) + Subscribe CTA (in-content, NOT modal/popup) + Related articles (static list of 3–5, NOT carousel) + prev/next article navigation (with full title labels) Banned: "Was this helpful?" widget BEFORE the article ends Banned: floating "Subscribe" button that follows scroll Banned: paywall mid-article 24. Doc page composition Structure: breadcrumb + h1 + lede + on-this-page TOC (collapsible) + body sections + related guides + edit-this-page link (for open-source docs) Required: anchor links on all h2/h3, copy-link affordance 25. Search results layout Structure: search field (sticky top) + results grouped by type (Articles / Sections / Code samples) + snippet with surrounding context, match highlighted with --accent-highlight Required: keyboard navigation, "X results in Y ms" caption, "no results" empty state with search-tips link 26. Print stylesheet Pattern: @media print { ... } Behavior: hide nav/sidebar/TOC/search, expand all collapsed sections, show full URLs after links, format footnotes inline, page-break-before on h1, keep callouts visible Required: every Meridian product ships print stylesheet by default 27. Empty state (search no-results, empty section) Structure: small (NOT illustrated) — single line + 2–3 actionable suggestions Tone: helpful, brief Example: "No results for 'foobar'. Try fewer keywords or see all articles in [Section]." ▼ DOMAIN LAYER (Layer 4 — product-specific composites) Domain components compose Layers 1–3 with Meridian rules: respects reading-width, no animation in body, semantic accent only, full a11y, instructional voice. Below are 5 named examples for documentation / knowledge-base / API-reference products. Extend per product domain. 28. API method block (REST / GraphQL docs) Composes: Code block (10) + Inline tabs (11 — language switcher) + Tag/Badge (5 — for HTTP verb) Structure: HTTP-verb badge (GET/POST/PUT/DELETE — color-coded but with text label, never color-only) + endpoint path (mono) + 1-line description + request schema (parameters table) + response schema + code block with language tabs (curl / JS / Python / Ruby) Meridian rule: language selection persists across page via localStorage (per spec — Inline tabs Component 11) Meridian rule: parameter table uses --reading-width-wide (80ch — table is scanned, not read prose) 29. Versioned changelog entry Composes: Article (1) shrunk + Code block (10) + Callout box (9 — for breaking-change warnings) Structure: version badge + date + grouped sections (Added / Changed / Deprecated / Removed / Fixed / A11y) + optional Code blocks for migration examples + warning callout for breaking changes Meridian rule: breaking-change Callout is type "danger" (red left-rule); deprecation is "warning" (orange left-rule); these get visible prominence Meridian rule: per-version anchor link auto-generated (#v-1-2-0 etc.) for shareable migration refs 30. Glossary term tooltip / popover Composes: Tooltip (chrome-only — extended Popover variant) + Code-inline styling for the term Structure: term marker (dotted underline + cursor: help) + on-hover/focus tooltip with definition + "Read more →" link to full glossary entry Meridian rule: critical terms get FULL inline first-use definition, NOT tooltip (tooltip is a recall aid, not a learning aid — same as Lattice rule) Meridian rule: tooltip uses --shadow-md (Meridian's only tooltip-allowed shadow); no animation beyond fade 31. Citation block (academic / technical writing) Composes: Pull quote (12) + Footnote (13) Structure: serif italic blockquote + attribution line below (--text-body-sm muted) + footnote-numbered link to full citation in footnote list at article end Meridian rule: full citation in MLA / APA / Chicago format per product convention; cite per-link, never inline parenthetical (preserves reading flow) Meridian rule: 52ch max-width on quote (--reading-width-quote) 32. Mermaid / diagram embed Composes: Code block (10) container + Caption (--text-body-sm muted) + Optional zoom-in modal trigger Structure: rendered diagram (SVG, generated from text source like Mermaid / PlantUML / D3) + caption ("Figure 2: Token cascade flow") + small icon-button to view at full screen Meridian rule: diagrams render to SVG (not canvas) — keyboard- accessible, screen-reader-readable when text sources include alt descriptions Meridian rule: caption is REQUIRED — every diagram tells the reader what to see in it Meridian rule: full-screen modal for complex diagrams uses --shadow-lg (Meridian's only modal-allowed shadow tier) ─────────────────────────────────────────────────────────────── VOICE RULES — apply to ALL generated copy ─────────────────────────────────────────────────────────────── (Inherits governance Voice rules. Meridian adds:) • Second person, instructional — "You set the token to…", not "The user sets the token" • Active voice, present tense — "The function returns a string", never "A string is returned by the function" • Define the term the FIRST TIME it appears — introduce acronyms inline, never in footnotes • One idea per sentence, one idea per paragraph — paragraphs are 2–4 sentences; long paragraphs break reading cadence • No marketing hype, EVER — "powerful", "seamless", "robust", "cutting-edge", "revolutionary", "blazing fast" are banned • Link text describes the target — "See the token spec", NEVER "click here", "read more", "learn more" • Code BEFORE prose — show the pattern, then explain; readers scan code first anyway • Strong over italic for emphasis-of-volume; italic for term-introduction • Numbers as digits in body ("3 steps") unless starting a sentence ("Three steps remain") • Headings are sentence case ("Get started with tokens", not "Get Started With Tokens") VOICE — Do / Don't pairs: Do → "You set the token to var(--color-primary)" Don't → "The token can be set by the user to a CSS variable" Why: second-person + active voice; concrete example. Do → "See the token spec for the full naming rules" Don't → "Click here for more information" Why: link text describes the target; no "click here". Do → "Tokens stay in sync because they reference one source — the design system." Don't → "Tokens are powerful, seamless, and revolutionary — they unlock effortless consistency!" Why: state the mechanism; never the marketing. Do → "8 min read · Updated April 2026" Don't → "A comprehensive deep-dive guide for the modern design engineer" Why: facts the reader needs; no aspirational framing. Do → "Design tokens: a primer" Don't → "Unlock the Power of Design Tokens" Why: utility heading, not marketing headline; sentence case. Do → "REST is shorthand for Representational State Transfer." Don't → (using REST without defining it) Why: define on first use; respect the reader's first- time-here state. ─────────────────────────────────────────────────────────────── BANNED PATTERNS — the Meridian anti-pattern catalog ─────────────────────────────────────────────────────────────── ▼ Reading-width / chrome antipatterns ✗ Full-width body text (no max-width) Why: readability collapses past 80ch — eye fatigue Use: --reading-width (68ch) hard cap on body ✗ Body text under 16px Why: eye strain during long sessions Use: 17–18px (--text-body) minimum ✗ Body text in narrow column < 45ch Why: zigzag eye motion; reading rhythm broken Use: 56–72ch sweet spot ✗ Multi-column body on desktop (newspaper-style) Why: requires scroll-up-down per column; impossible on long articles Use: single-column, --reading-width centered ✗ Justified text (text-align: justify) Why: creates "rivers" of whitespace in narrow columns; readability fails Use: text-align: left + text-wrap: pretty ✗ First-line indent on every paragraph (book-style) Why: print convention, awkward on screen with paragraph spacing Use: blank line between paragraphs (--space-4 margin), no indent ▼ Marketing-leak antipatterns (docs are not marketing) ✗ Marketing-style hero section on doc/article pages Why: docs aren't promotional; reader is here to learn Use: title + 1-line subtitle + TOC ✗ Decorative imagery mid-article Why: interrupts reading flow; signals "promotional" Use: imagery only when it teaches (diagrams, screenshots, charts) ✗ CTAs interrupting reading ("Try it free!" mid-paragraph) Why: breaks reader mental model; trust drop measurable Use: CTAs only at top (sign up to bookmark) and end (next step / subscribe) ✗ Newsletter popups on scroll Why: interrupts mid-paragraph; trust collapse Use: inline subscribe block at end of article ✗ Carousels of related articles Why: hidden content; engagement killer Use: static list of 3–5 related articles at end ✗ "Was this helpful?" at the TOP of an article Why: asks before earning the right to ask Use: feedback widget at the END, after delivering value ✗ Auto-playing video mid-article Why: breaks reading focus; unannounced motion Use: click-to-play with static poster + caption ✗ Sticky promotional banners Why: interrupts reading; engagement killer Use: in-content section if it's truly editorial ▼ Voice antipatterns ✗ Marketing hype words ("powerful", "seamless", "robust", "cutting-edge", "revolutionary", "blazing fast", "world-class") Why: signals lack of confidence; replaces specifics Use: state what the thing actually does ✗ "Click here" / "read more" / "learn more" link text Why: meaningless out of context (screen-reader users hear list of "click here, click here, click here") Use: link text describes destination ✗ Passive voice ("A string is returned by the function") Why: harder to parse; weakens agency Use: active voice ("The function returns a string") ✗ Acronym without first-use definition Why: forces reader to lookup; lost reading momentum Use: define inline first time ("REST (Representational State Transfer)…") ✗ Long paragraphs (> 5 sentences) Why: reading cadence broken; eyes lose place Use: split into 2–3 sentence units ✗ Conversational fluff in technical docs ("So you might be wondering…", "The cool thing here is…") Why: wastes the reader's time Use: state the fact, then the explanation ▼ Visual antipatterns ✗ Animations on scroll (fade-in, slide-in) Why: interrupts reading; eyes follow motion involuntarily Use: static rendering — content visible at first paint ✗ Skeleton shimmer Why: motion ban; distraction Use: opacity-static placeholders OR no skeleton at all ✗ Hover animations on body content Why: visual noise; reading flow interruption Use: subtle color change only (link hover) ✗ Bold + italic + colored text on the same line Why: weight competition; reader doesn't know what to emphasize Use: pick ONE emphasis style per occurrence ✗ Code blocks with horizontal scrollbar visible by default Why: signals "this code is too wide"; visual noise Use: scrollbar appears on hover; soft-wrap option ✗ Pull quotes that don't quote actual text (decorative pull-out-text) Why: editorial sleight; magazine pattern misapplied Use: only quote text that appears in the body (or remove) ▼ Navigation antipatterns ✗ Hidden TOC behind hamburger on desktop Why: TOC is a primary affordance for long articles Use: persistent sidebar TOC at >1200px ✗ Pagination breaking a single article into 5 pages Why: ad-revenue pattern; ruins reading flow Use: single page, deep linking to sections ✗ Auto-loading "next article" at scroll bottom (infinite scroll) Why: hijacks the user's intent; can't bookmark Use: explicit "Next article" link at end ✗ Modal navigation (opening sub-pages in modal overlays) Why: breaks browser back button; URL doesn't change Use: real navigation with URL change ─────────────────────────────────────────────────────────────── BYOC — REQUIRED COLOR ROLES (Bring Your Own Colors) ─────────────────────────────────────────────────────────────── If you're using Prompt 1b (BYOC variant) instead of Meridian's canonical warm-neutral palette, your supplied palette MUST cover THREE THEMES (light/sepia/dark) for every text and surface token. Meridian is the most palette-extensive archetype because it ships THREE theme variants for reading-comfort. Required (~50 colors minimum across 3 themes): Surfaces × 3 themes (12 colors): Per theme (light, sepia, dark): surface-page base reading bg (warm off-white / cream / dark) surface-card slightly raised (rare in body) surface-sunken code blocks, sidebar bg surface-quote pull-quote bg (subtle warm tint) Text × 3 themes (12 colors): Per theme: text-body warm off-black / dark-on-cream / off-white text-strong bold emphasis variant text-muted metadata, captions text-faint timestamps, breadcrumb separators Borders × 3 themes (3 colors min, ideally 9): Per theme: border-subtle (or single shared rgba opacity) Link state × 3 themes (9 colors): Per theme: accent-link base link accent-link-hover accent-link-visited purple academic convention Highlight × 3 themes (3 colors): Per theme: accent-highlight (mark/search-match bg, low opacity) Callouts (8 colors — same hex across themes, opacity-tinted): callout-note (bg + rule) callout-tip (bg + rule) callout-warning (bg + rule) callout-danger (bg + rule) Code (6+ colors per theme): code-inline-bg + code-block-bg + code-text + 3 syntax tones (keyword + string + comment) × 3 themes = ~18 colors Focus ring × 3 themes (3 colors): Per theme: color-focus-ring (link color at 50% opacity) VALIDATION RULES (Prompt 1b enforces): ✓ All THREE themes (light/sepia/dark) defined — no "sepia is a v2 feature" (Meridian governance override) ✓ Reading width ≤ 72ch enforced on body containers ✓ Body type ≥ 17px on all themes ✓ Body line-height ≥ 1.7 on all themes ✓ Link colors meet 4.5:1 against their respective theme's surface-page (computed per theme) REJECTED palettes (Prompt 1b will fail): ✗ Light-only or dark-only (sepia is REQUIRED for Meridian) ✗ Multi-accent (Meridian is link-color-only — accent backgrounds on chrome are banned) ✗ Pure #FFF surfaces (warm off-white minimum — eye fatigue) ✗ Pure #000 text on light surfaces (warm off-black minimum) ─────────────────────────────────────────────────────────────── WHEN TO PICK MERIDIAN ─────────────────────────────────────────────────────────────── Pick Meridian IF: • Primary user activity is READING, not navigating • Articles are 3–15 minutes of focused reading • Content is educational, technical, or editorial (NOT promotional) • Users return to re-read and reference the same content • Code, diagrams, and tables appear mid-body • Domains: documentation sites, technical blogs, academic publications, knowledge bases, wikis, long-form journalism, newsletters, ebooks, study guides, API references Sample adjectives that route to Meridian (archetype-selection aid — Finding 5 demoted-adjective routing, NOT a generation input): scholarly · considered · instructional · precise · slow · academic · documented · authoritative · referenceable · serif · long-form · reading-optimized · footnoted · printable If three or more of your brand adjectives are in this list, Meridian is likely your archetype. Real-world examples (calibrate against these — public sites that exemplify Meridian's principles): • Stripe Docs (stripe.com/docs) — the canonical modern docs reference; sans body, generous reading column, sidebar TOC + scroll-spy, code blocks with copy • MDN Web Docs — academic, precise, footnoted • Tailwind CSS docs, React docs, Vue docs — sans variant • Substack publications — serif body variant, focused reading • Notion (when used as KB / wiki) — Meridian-aligned reading mode with right-rail TOC • Smashing Magazine articles — editorial-academic hybrid • Medium (legacy reading experience) — body-as-hero • Apple Developer documentation — formal, dense reference • Read the Docs theme for Sphinx — academic baseline DO NOT pick Meridian if: • Marketing site or brand-forward portfolio → [Harbor](harbor.spec.md) (atmospheric, promotional) • Internal tool or dashboard → [Sentinel](sentinel.spec.md) • Mobile-first consumer app → [Current](current.spec.md) • Data-dense terminal → [Lattice](lattice.spec.md) • Reader spends < 1 minute per visit → [Harbor](harbor.spec.md) (atmospheric scan) or Current (mobile glance) ─────────────────────────────────────────────────────────────── FAILURE MODES — what breaks first when Meridian is misapplied ─────────────────────────────────────────────────────────────── When teams force Meridian onto the wrong use case, predictable failures appear in this order. 1. Marketing pretension (Meridian for marketing site) Symptom: Marketing page reads as a docs page — utilitarian headings, no atmospheric hero, no CTAs above the fold. Conversion drops. The site looks "academic" when it should look "exciting." Root cause: Meridian's body-as-hero principle and "no marketing hype" voice rules are deliberately the opposite of what marketing surfaces need. → Switch to [Harbor](harbor.spec.md) for marketing / conversion-focused surfaces. 2. Density famine (Meridian for product UI / dashboard) Symptom: A dashboard built in Meridian shows 5 rows where 30 fit; reading-width caps body to 68ch on a 1920px monitor; sidebar TOC is wasted real estate; users complain the product "feels slow" because each interaction takes more scroll. Root cause: Meridian optimizes for sustained reading; product UI optimizes for scan-and-act. → Switch to [Sentinel](sentinel.spec.md) (compact density, scan-optimized). 3. Mobile reading awkwardness (Meridian on small phones) Symptom: 17px body at 1.75 leading inside a 390px viewport = ~30 lines of body before scroll; sidebar TOC hidden; no font controls without explicit Reader Mode toggle. Generally OK but feels stripped on small screens. Root cause: Meridian's pattern is desktop-optimized; mobile is acceptable but less rich. → Stay with Meridian — accept the mobile experience is different. OR add a [Current](current.spec.md)-styled mobile companion if reading on mobile is primary (rare for docs). 4. Marketing-fluff drift (Meridian written by marketing copywriters) Symptom: Docs slowly fill with hype words ("powerful", "seamless", "robust", "blazing fast"). Reader trust declines as the docs feel less authoritative. Root cause: Meridian's voice rules ban hype words but without enforcement, copywriters drift. → Tighten governance: enable the hype-word copy lint at CI time. Block PRs that introduce banned words in body content. 5. The "no one finds anything" failure (Meridian without ⌘K) Symptom: Docs site has 200 pages; readers can't find what they need; bounce rate from search-engine landing pages spikes. Sidebar TOC is fine for browsing but useless for discovery. Root cause: Meridian requires ⌘/Ctrl+K search wired — teams sometimes ship without it. Discoverability collapses. → Tighten governance: enforce ⌘K search at review time (Meridian governance override). ─────────────────────────────────────────────────────────────── GOVERNANCE OVERRIDES (Meridian adds to universal gates) ─────────────────────────────────────────────────────────────── Inherits governance.spec.md in full. Meridian additionally enforces: ☐ Reading width hard-capped at 72ch on body content (lint flags any prose container > 72ch max-width) ☐ Body type ≥ 17px (lint flags --text-body declared smaller) ☐ Line-height ≥ 1.7 on body (lint flags tighter --leading-body) ☐ Animation on body content banned (lint flags any transition/ animation rule on .article-body or descendants) ☐ Sepia mode + dark mode tokens defined (governance baseline + Meridian-specific sepia variant) ☐ Print stylesheet required (any product without @media print rules fails build) ☐ All headings (h2+) auto-id'd with anchor (lint flags heading without id) ☐ External links flagged with icon (lint warns on a[href^=http] without external-link indicator) ☐ Code blocks have copy button (lint flags any pre>code without copy affordance) ☐ Search shortcut Cmd/Ctrl+K wired (any docs product without Cmd+K search fails review) ☐ Marketing hype words blocked in body ("powerful", "seamless", "revolutionary" etc. fail copy lint) ─────────────────────────────────────────────────────────────── PHILOSOPHY (paste into prompt context as guiding principle) ─────────────────────────────────────────────────────────────── "Documentation is a contract between the writer and a reader who already has a problem. Meridian's constraints — 68ch reading width, 17px body, second-person instructional voice, no hype — exist because readers didn't come to be sold to. They came to find the answer. Everything else is friction." ═══════════════════════════════════════════════════════════════ END MERIDIAN SPEC · v1.0 ═══════════════════════════════════════════════════════════════ ``` --- ## Maintenance notes (do not paste into prompts) - **When you extend Meridian** (new callout type, new content pattern, new code-block variant): edit the spec block above, bump the version, and re-paste into prompts. - **Conflict with v1 Ch11 Meridian section:** the spec wins. v1 covered Meridian lightly; this spec elevates it to first-class status (per Finding 12 Decision 3). - **Sidenote pattern is OPTIONAL.** Tufte-style marginalia work well for academic content but require a wider viewport. Default Meridian products use footnotes; sidenotes are a per-product opt-in. - **The body-font choice (serif vs sans) is consequential.** Serif signals editorial / academic / long-read; sans signals technical / docs. Pick per product brand and stick with it. - **CSS hygiene — `overflow-x: clip` not `hidden` on html/body.** The rendered HTML uses `overflow-x: clip` (not `hidden`) on both `html` and `body`. The `hidden` variant creates a scrolling-ancestor context that breaks `position: sticky` on descendants — including the `.sidebar-toc`. `clip` achieves the same horizontal-scroll suppression without establishing a containing block for sticky. When re-running Prompt 08 to regenerate the spec page, ensure the regenerated CSS does NOT reintroduce `overflow-x: hidden` on html/body — substitute `clip`. - **Publishing footer (post-render step, not part of the spec contract):** the rendered HTML at [build/preview/specs/meridian.html](../../build/preview/specs/meridian.html) appends an inline credit row as the LAST element inside the existing `