← Docs hub

Editorial brand system

Status: canonical reference for llmwiki's visual system (v1.2.0 · #115). If you're changing how any part of the generated site looks — or exporting a screenshot / OG image / PDF / slide deck — this document is the source of truth.

llmwiki is a reading-first product. The site is rendered locally from markdown, then handed to the user like a book they wrote. The brand does three things in service of that:

1. Get out of the way of the prose.
2. Make every page feel unmistakably like "an llmwiki page" — so the static site, the PDF export, a screenshot in a tweet, and a slide deck all read as a single product.
3. Work identically in light mode, dark mode, print, and Obsidian.

All tokens live in llmwiki/render/css.py as CSS custom properties on :root + [data-theme="dark"]. This doc mirrors them so contributors don't have to grep the CSS.

1. Typography

CSS tokens: --font (body/headings), --mono (code).

Rules

• Never ship web-font files. Inter and JetBrains Mono have first-class system support on all three major OSes or load via the user's browser; we don't want a network request to render a wiki page.
• Line-height 1.7 for body copy — reading-first density. Denser UI surfaces (nav, cards, tables) use 1.4–1.5.
• Heading weight 600, not 700, below h2. Keeps the hierarchy readable without shouting.
• Monospace blocks use 0.875rem (14 px) at 1.6 line-height. Tools outputs and code samples stay scannable without dominating the page.

Why these two

• Inter — the same type family used by GitHub, Anthropic, Linear, Vercel. Neutral enough to disappear on long sessions, opinionated enough to feel intentional. Ships on macOS/Windows/Android out of the box; Linux gets a close match via the system fallback chain.
• JetBrains Mono — designed for reading code and diff output. Ligatures are left enabled (defaults to on in the typeface) because the audience is engineers.

2. Color palette

Every surface is a CSS variable so the whole palette flips in one place when you toggle light/dark.

Light mode (default)

Dark mode

Applied via either @media (prefers-color-scheme: dark) or explicit :root[data-theme="dark"]:

Accent #7C3AED stays the same in both themes — it's the through-line that makes a screenshot recognizable even without the rest of the palette.

Rules

• WCAG 2.1 AA minimum for every text/bg pair. Muted text in dark mode is explicitly checked to 6.97:1.
• Accent is never used for body copy. Links get it; body stays --text.
• Status colors use the same hues across light/dark:
• success #10b981 / hover #059669
• warning #f59e0b / hover #d97706
• danger #ef4444 / hover #dc2626
• info #3b82f6 / hover #2563eb

3. Elevation + radius

Dark-mode shadows use the same geometry with higher alpha (0.35 → 0.45) so they read against the deep backgrounds.

Rules

• One radius. 8 px everywhere; smaller elements (code snippets, pill badges) use 4 px — see next section.
• Two shadow steps max per page. More than that reads as a UI tour, not a document.
• Never use border-radius: 50% except on avatars — full circles signal "interactive control" and compete with links.

Smaller radius variants

Used inline, not as tokens (small surface area, low reuse):

• 4px — inline code, keyboard chips (<kbd>), per-cell filter pills
• 4px — copy-code-btn, heading deep-link anchors
• 6px — nav controls, theme toggle, secondary buttons

4. Motion

llmwiki is a reading surface — motion should be almost invisible. Every timing, duration, and easing choice below is deliberately boring.

These aren't yet extracted as tokens in css.py — individual rules inline the literal seconds. Extracting is tracked as a future cleanup.

Rules

• Respect prefers-reduced-motion. css.py already sets animation-duration: 0.01ms and transition-duration: 0.01ms when the user-agent asks for it. Any new animation must not opt out.
• No page-level scroll hijacking. scroll-behavior: smooth on html is fine; JS-driven scroll animations are not.
• Hover effects are reversible. If you darken a card on hover, the off state is reached by reversing the same transition, not a new one.
• Never auto-play. Heatmaps, graphs, and timelines render once — they don't loop.

5. Spacing

No scale token yet — spacing is inlined in rules (padding/gap/margin). The canonical steps used across the codebase:

• 2 px — border-radius adjustments, hairline separators
• 4 px — icon gaps, inline-code padding
• 8 px — button padding, card inner gap (gap-2)
• 12 px — paragraph spacing, list indent
• 16 px — card padding (resting), section gap
• 24 px — major section separators, hero padding
• 32–48 px — page-level container padding at ≥ 768 px

A future token pass (--space-1…--space-6) is on the roadmap; until then, stay inside this set when adding rules to keep the rhythm consistent.

6. Export consistency

All generated artifacts must inherit the same tokens:

Social preview image

When a page links externally (OpenGraph / twitter:image):

• Background: #0c0a1d (dark bg)
• Heading: Inter 700, 72 px, #e2e8f0
• Accent stripe: #7C3AED 4 px × full width along the top
• Logo wordmark: "llmwiki" — Inter 800, 120 px, #a78bfa for "llm", #e2e8f0 for "wiki"

7. Do / don't

Do - Let the text breathe — line-height 1.7 for any paragraph > 3 lines. - Keep cards borderless-ish — 1 px --border-subtle with --shadow-card. - Use --accent for one thing per section (a link, a badge, a button — not all three). - Flip the whole palette via data-theme, not per-component opt-ins. - Match existing radius/shadow tokens before inventing new values.

Don't - Don't mix mono and sans in the same run of prose. Pick Inter, drop into mono only for code. - Don't use accent on body copy. - Don't add a third shadow level. - Don't use custom web fonts — Inter + JetBrains Mono are the only two. - Don't build contrast into the HTML (e.g. <span style="color:white">); always go through a variable so the theme toggle works.

8. Changelog for this doc

When you change a token or add a scale step, add a one-line entry to CHANGELOG.md under ### Changed with the new token name + value + where it's used. That keeps the brand history traceable in the release notes.

Related

• llmwiki/render/css.py — source of truth for every CSS variable
• llmwiki/render/js.py — theme toggle + palette sync logic
• docs/reference/cache-tiers.md — also uses the accent palette for badges
• #115 — this issue