Meridian

1.1 Color system

Meridian's palette is warm-neutral, high-contrast, and minimal-accent. The palette asks one question of every color decision: does this support reading, or does it compete with it?

Pure white (#FFF) and pure black (#000) are banned on surfaces and body text respectively. Warm off-white (#FAFAF8) and warm off-black (#1A1A1A) replace them. This reduces eye strain during extended reading sessions. The three themes — light, sepia, and dark — are all required; sepia is not a "v2 feature."

Light mode (default)

Sepia mode (extended reading)

Sepia is Meridian's Kindle-style variant. Warm cream surfaces (#F5EFE0) and a shifted purple-blue link color (#6B5B95) reduce eye fatigue during marathon reading sessions.

Dark mode (night reading)

Callout semantic colors (all themes)

These tokens use the same hue across all three themes. The -bg tokens use low-opacity tints; the -rule tokens set the left border.

Accessibility contrast verification (WCAG 2.1)

Faint text (--text-faint) falls below 3:1 in light mode. Use it only for purely decorative separators and timestamps — never for essential information. For captions, use --text-muted (5.1:1 AA).

1.2 Typography

Typography is the most consequential section in Meridian. Every other system archetype defaults to sans-serif body; Meridian defaults to serif. The font choice signals "long reading" the same way a book cover signals genre before a page is opened.

Body size is 17–19px — larger than the web default of 14–16px. Web defaults were tuned for product UI scanning, not reading. Meridian inverts this deliberately. Line height is 1.75 — the academic typography sweet spot for sustained reading.

Serif default vs. sans alternative

Type scale

1.3 Spacing and reading widths

Meridian's spacing is generous but purposeful. Each decision asks: does this support reading rhythm? Paragraph spacing is --space-4 (16px) between consecutive paragraphs — not first-line indent, which is a print convention that reads poorly on screen.

Reading width hard caps

The reading-width tokens are hard limits, not suggestions. Eye fatigue collapses past 80ch on prose. Tables and code blocks are allowed wider because they're scanned, not read line-by-line.

1.4 Elevation

Meridian is flat. Shadows interrupt reading flow by adding visual weight that competes with text. The rule: use shadows only on floating overlays — the search modal, copy-link toasts — never on surface cards in body content.

Banned: shadows on cards in body content (visual weight steals attention from text). Shadows on default page surfaces. Warm oklch shadows.

1.5 Shape

Meridian uses sharp corners by editorial convention. Books, magazines, and academic journals use sharp corners. Rounded corners feel product-like; reading systems lean editorial. The maximum radius in body content is 8px, reserved for dialogs and search popovers.

Banned: radius > 8px on any element in body content. Rounded code blocks (looks like a sticker, not an editor).

1.6 Motion

Motion in body content interrupts reading. The eye follows motion involuntarily. A reading system that animates loses readers. Meridian bans all animation on body content by rule — this is not a recommendation, it is a governance gate.

Motion is allowed only on: search modal open/close · reading progress bar (continuous) · theme toggle (color transition) · anchor link smooth-scroll (with prefers-reduced-motion instant-jump fallback).

prefers-reduced-motion: Meridian's defaults are already minimal. With prefers-reduced-motion: reduce, all transition and animation durations collapse to 0.01ms — effectively instant. The progress bar jumps in 10% increments instead of continuous fill.

1.7 Iconography — Heroicons outline

Meridian uses Heroicons (outline). This is the family Stripe Docs, Vercel Docs, Tailwind Docs, and most modern documentation sites converge on. The 1.5px stroke weight has a refined editorial feel. Outline variants pair quietly with serif body text without competing for visual weight.

Lucide is explicitly banned. Lucide's stroke is heavier — it competes with reading flow. The solid Heroicons variant is allowed sparingly where filled aids recognition: warning callout icons, code-file indicators. Never in general body content.

Grid: 20px standard for chrome (slightly smaller than Sentinel's 24px); 16px inline (external-link indicator). Stroke: 1.5px. Color: currentColor — inherits from parent.

Inline usage: external links show the arrow-up-right icon (16px) inline after link text. Code-block filenames show the document-text icon before the filename. All icons use aria-hidden="true" since adjacent text provides the label.

Example inline indicator: Browse the full Heroicons set

2 Voice

Meridian's voice is second person, present tense, and instructional. Documentation is a contract between the writer and a reader who already has a problem. The reader didn't come to be sold to. Every hype word — "powerful," "seamless," "revolutionary" — is a broken promise. State what the thing actually does.

Meridian adds five rules on top of governance voice requirements: define terms on first use; one idea per sentence; code before prose; active over passive; sentence case headings.

Do / don't pairs

3 Foundation components — Layer 1

Foundation components are the atoms of Meridian. Each is constrained to --reading-width (68ch) unless the spec grants a wider allowance. All headings receive auto-generated IDs and hover-reveal anchor links.

1. Article structural primitive

The Article component is the structural primitive. It wraps the reading column and enforces all reading-width constraints. It carries structured-data markup (schema.org/Article) and OG meta tags for shareable documentation links.

2. Heading with anchor (h2–h4)

Every heading at h2 and deeper receives an auto-generated id. On hover, a hashtag icon appears at the inline-start. Clicking copies the fragment URL and shows the "Link copied" toast. This page demonstrates the pattern throughout.

4. Inline elements

The inline element palette is deliberately minimal. In long-form reading, every inline style competes for attention. Use the minimum needed to communicate semantic meaning, not visual interest.

Internal link (default state) · External link with icon · code-inline · strong emphasis (term-of-art) · italic (term introduction, first use) · highlighted text (search match) · Footnote reference¹

6. Search input → modal

The search input in the nav bar opens the full search modal on focus. The modal provides fuzzy matching, grouped results, match highlighting, and keyboard navigation. Press ⌘K anywhere to open it; press Esc to close.

5. Button (rare in Meridian)

Buttons are rare in Meridian body content. Most CTAs are inline links. Buttons are reserved for end-of-article actions: subscribe, next article, download spec.

3.C Composite components — Layer 2

Composite components combine Foundation primitives with Meridian-specific reading conventions. Each enforces reading-width hard caps, respects the motion ban, and degrades gracefully across themes.

9. Callout box (note / tip / warning / danger)

Callouts are inline, never floating. The 4px left rule and tinted background communicate semantic meaning without color-only encoding (icons provide redundancy). Titles are mandatory.

10. Code block (filename header + copy button + syntax highlighting)

/* Meridian token layer — reading system */
:root {
  /* Body — NEVER below 17px */
  --text-body: clamp(1.0625rem, 0.95rem + 0.4vw, 1.1875rem);

  /* Reading width — HARD CAP */
  --reading-width: 68ch;

  /* Leading — 1.75 for sustained reading */
  --leading-body: 1.75;

  /* Accent — link-only */
  --accent-link: #0066CC;
}

11. Inline tabs — language switcher

const response = await fetch('/api/tokens', {
  method: 'GET',
  headers: { 'Authorization': `Bearer ${apiKey}` }
});
const tokens = await response.json();

import requests

response = requests.get(
    '/api/tokens',
    headers={'Authorization': f'Bearer {api_key}'}
)
tokens = response.json()

curl -X GET https://api.example.com/tokens \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json"

12. Pull quote

Pull quotes use --reading-width-quote (52ch), serif italic, and a left border. No quotation marks — the visual style does the work. Only quote text that appears in the body.

13. Footnote

Footnotes appear as superscript numbers in body text², linking to a numbered list at the article end. Back-links return focus to the inline reference position. Screen readers announce "Footnote 2" and "Return to text" for the back-link.

14. Sidenote (Tufte-style — optional)

15. Reading progress bar

The 2px bar at the top of the viewport fills from 0% to 100% as you scroll this page. It uses --accent-link color and position: fixed at top: 0. With prefers-reduced-motion: reduce, it jumps in 10% increments instead of continuous fill. See it in action as you read this page.

17. Search modal (⌘K / Ctrl+K)

The search modal opens on ⌘K (or Ctrl+K on Windows/Linux). It is display: none until the .open class is added by JavaScript. The modal is centered, uses --shadow-lg, and traps focus until Esc closes it. Results are grouped by section and type, with snippet previews and match highlighting.

18. Theme toggle (light / sepia / dark)

The theme toggle in the top-right nav switches between light, sepia, and dark modes. It persists the user's choice in localStorage. All three themes are defined and functional — use the toggle to see this page in each mode now. The transitions use --duration-slow (300ms) on background and color only — no transform or layout changes.

19. Font controls (Reader Mode)

20. Loading states

Most Meridian pages render statically — loading states are rare. When needed: a 24px circle spinner with --accent-link stroke. Skeletons are banned (motion ban) — use opacity-static placeholder blocks or no loader at all.

20a. Figure container — diagrams, charts, screenshots, equations

The figure container is a new Layer 2 composite for any visual asset that appears mid-body. It uses --reading-width-wide (80ch) — wider than body prose since visual assets are scanned, not read line-by-line. The <figcaption> is mandatory and must describe what the reader should see — not just label the figure.

Variant A — Diagram (architecture / decision tree / flow)

Variant B — Inline chart (line / bar)

Variant C — Screenshot with numbered callouts

3.D Domain layer — Layer 4

Domain components compose Foundation and Composite layers with Meridian's reading rules. All five named examples below are rendered live. Each respects --reading-width-wide (80ch), enforces the motion ban, uses semantic accent only, and ships full accessibility support.

28. API method block (REST / GraphQL docs)

curl -X POST https://api.example.com/v1/tokens/ts_abc123/sync \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"theme":"light","force":false}'

const res = await fetch(`/v1/tokens/${id}/sync`, {
  method: 'POST',
  body: JSON.stringify({ theme: 'light', force: false })
});

29. Versioned changelog entry

30. Glossary term tooltip

A design tokenA design token is a named value that stores a single visual decision — a color, a size, a shadow. Tokens replace raw hex and pixel values in component CSS, creating a single source of truth.Read the full token spec is the most commonly confused term in design systems. Hover or focus the underlined term to see the tooltip definition. Tooltip uses --shadow-md; no animation beyond CSS display toggle.

Critical terms get full inline first-use definitions. Tooltips are recall aids for terms already defined earlier in the document — not substitutes for a clear first-use definition.

31. Citation block (academic / technical writing)

32. Mermaid / diagram embed

4 Patterns

Document layouts D1–D6

Every Meridian page is one of six document layouts. The shapes are conventional — readers should not have to re-learn navigation.

21. Article header pattern

The article header is the first impression. It orients the reader quickly — breadcrumb, title, lede, metadata — and gets out of the way. No hero image taller than 200px (delays first paragraph). No social share buttons above the fold (the reader hasn't read the article yet).

23. End-of-article block

27. Empty state

26. Print stylesheet rules

Every Meridian product ships a print stylesheet by default. This is a governance gate — any product without @media print rules fails build. The print rules on this page: nav/sidebar/TOC/search hidden, full URLs expanded after links, footnotes visible, page-break-before on h1, callouts preserved with simplified borders.

5 Accessibility

Meridian targets WCAG 2.1 AA minimum with AAA on primary body text. Reading-specific criteria add to the universal baseline: minimum body font size 17px (larger than WCAG's 18pt/14pt bold threshold); line height 1.75 (exceeds WCAG SC 1.4.12 text spacing minimums); logical CSS properties for RTL reading direction support.

Keyboard navigation map

Screen reader notes

• All icon-only buttons use aria-label (copy button, expand button, theme toggle buttons, font controls)
• Heading anchor links use aria-label="Permalink to: {heading}" — screen readers hear the destination, not "#"
• Footnote back-links use aria-label="Return to text for footnote N"
• The reading progress bar uses role="progressbar" with aria-valuenow updated by JS
• Search modal uses role="dialog" + aria-modal="true"; focus traps inside until Esc
• Copy toast uses aria-live="polite" + aria-atomic="true" so screen readers announce the confirmation
• All decorative SVGs use aria-hidden="true"; meaningful figure SVGs use role="img" / tabindex="0" + aria-label
• The search modal input has explicit aria-label="Search documentation" (never placeholder-as-label)
• Glossary tooltips are accessible on focus as well as hover — tabindex="0" on the term

prefers-reduced-motion

When prefers-reduced-motion: reduce is set: all CSS transitions and animations collapse to 0.01ms. The reading progress bar jumps in 10% increments. Theme transitions are instant. Anchor scroll is instant. The spinner stops animating. Meridian's defaults are already minimal, so the reduced-motion fallback is nearly imperceptible in practice.

@media (prefers-reduced-motion: reduce) {
  html { scroll-behavior: auto; }
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

Reading-specific WCAG criteria

6 Governance

Meridian inherits universal governance gates from governance.spec.md and adds 11 Meridian-specific overrides. All gates are build-blocking — a PR that violates any gate is rejected.

Versioning (SemVer)

MAJOR — breaking token rename, removed component, breaking API change. MINOR — new component, new variant, new token, deprecation notice. PATCH — bug fix, doc update, non-visual refactor. Deprecated tokens/components ship for 2 MINOR versions before removal. Deprecation warnings log at build time.

BYOC — required color roles

When you use a custom palette instead of Meridian's canonical warm-neutral defaults (Bring Your Own Colors), your palette must cover all three themes (light, sepia, dark) for every text and surface token. Meridian is the most palette-extensive archetype because it ships three reading-comfort variants. Approximately 50 color roles minimum across all three themes.

Light theme — required roles

Sepia theme — required roles

Dark theme — required roles

When to pick Meridian

Pick Meridian when the primary user activity is reading — not navigating, not acting, not scanning. Articles should be 3–15 minutes of focused reading. Content is educational, technical, or editorial, not promotional. Users return to re-read and reference the same content.

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

These adjectives are archetype-selection aids (Finding 5 demoted-adjective routing), not generation inputs. If three or more of your brand adjectives appear in this list, Meridian is likely your archetype.

Real-world examples

Calibrate against these public sites. Each exemplifies different facets of Meridian's principles.

Do not pick Meridian if…

Failure modes

When teams force Meridian onto the wrong use case, predictable failures appear in this order. Recognizing the symptom early saves a rebuild.