Skip to content

docs: apply the Greyhaven design system to the docs site - #5

Merged
tito merged 1 commit into
mainfrom
feature/use-greyhaven-design-usw
Aug 28, 2026
Merged

tito merged 1 commit into
mainfrom
feature/use-greyhaven-design-usw

Conversation

@tito

@tito tito commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

What

Applies the Greyhaven design system to the mkdocs-material documentation site. The site shipped stock Material (Roboto, black header, indigo links); the web UI already vendors the design system, so the docs were the odd one out.

  • docs/assets/stylesheets/greyhaven.css — the whole theme in one extra_css file: @font-face rules, two [data-md-color-scheme] blocks of Material variable overrides, and the typography rules. No theme fork, no custom_dir.
  • Colors are vendored from the design system's tokens/color.json: off-white #F9F9F7 / off-black #161614 surfaces, the single orange accent #D95E2A for links and active nav, grey.1/grey.8 for code backgrounds.
  • Type: Source Serif 4 for headings and body prose, Aspekta for nav, tables, admonition titles and search, system mono for code.
  • Fonts are self-hosted (both OFL). Aspekta is copied from ui/public/fonts/; Source Serif 4 is the latin subset. The published site makes no Google Fonts request.
  • Greyhaven symbol as header logo, ui/public/favicon.svg as favicon.
  • mkdocs.yml palettes move from primary: black / accent: indigo to primary: custom / accent: custom. This is required: without it the theme's own attribute selectors override the stylesheet and links stay indigo.
  • CLAUDE.md gains one sentence recording that docs styling is vendored tokens, re-vendor rather than hand-tune.

Why

The docs are the most public surface of the project and looked like generic Material. This makes them consistent with the web UI and the rest of the org's design system, at the cost of one CSS file and ~350 KB of font binaries (the repo already commits the same Aspekta files under uidist/).

Testing

  • mkdocs build --strict — no warnings, no broken links.
  • Served locally and clicked through home, a guide, reference/configuration (wide tables), concepts/architecture (long prose), and search, in both light and dark schemes.
  • Background pixels sampled from rendered screenshots land exactly on token: #F9F9F7 light, #161614 dark.
  • Docs-only change: no Go or UI code touched, no CI or workflow changes. mkdocs build --strict copies docs/assets/ as-is and the docs workflow already triggers on docs/** and mkdocs.yml.

Follow-ups / things to weigh

  • Contrast: orange links on the light background are 3.6:1, below AA for normal text. This is the brand's own pairing (same orange on the same off-white in the web UI), so I followed the brand rather than deciding unilaterally. Darkening links to about #C14F1E reaches 4.5:1 if AA matters more than fidelity here.
  • Serif body copy is the design system's call for reading content, but its consumers so far have been marketing pages and an app UI, not dense operational docs with inline code. If it reads wrong, the fallback is one rule: keep serif for headings, put body back on Aspekta.
  • Logo choice: uses the bare Greyhaven symbol, matching the current web UI favicon. The design system also carries a greyproxy wordmark, so if a product-brand decision is pending this may want revisiting.
  • A custom_dir overrides directory (for a real landing page) stays open as a later step; colors and type did not need it.

Vendor the design system's tokens into an extra_css stylesheet:
warm off-white/off-black surfaces, the single orange accent, Source
Serif 4 for headings and prose, Aspekta for nav and UI chrome, and
the Greyhaven symbol as logo and favicon. Fonts are self-hosted
(OFL), so the published site makes no third-party requests. The
palette switches to primary/accent: custom, the material-supported
way to keep the theme's own colors from overriding the stylesheet.
@tito
tito merged commit bea0e33 into main Aug 28, 2026
5 checks passed
@tito
tito deleted the feature/use-greyhaven-design-usw branch August 28, 2026 21:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant