Docs site: adopt the calm theme (landing + internal pages)

[adnaan]

Landing page readability improvements.zip

Docs site: adopt the calm theme (landing + internal pages)

Labels: design, docs-site
Attachments: drag design_handoff_docs_theme.zip into this issue before submitting — it contains README.md (the full spec), LiveTemplate Landing.dc.html, LiveTemplate Docs Pages.dc.html and support.js.

---

Context

The landing page is hard to read end to end: the same greeting demo repeats eight times, each
with two stacked code blocks and a wire-frame readout, and there is no wayfinding. The internal
docs pages are styled separately, so the site doesn't read as one thing.

A redesign exists as HTML design references (attached). This issue is to implement it in this
repo.

These are design references, not code to copy. The implementation is tinkerdown config +
CSS. Internal pages are markdown in content/ rendered by tinkerdown's clean theme, so
almost none of this is per-page HTML.

Scope

Files expected to change:

• content/tinkerdown.yaml — styling block (primary_color, font, site_css, custom_css)
• content/assets/brand.css — token custom properties + @font-face
• content/assets/docs.css — new, the docs shell; append to styling.site_css
• content/assets/landing.css — currently 31KB of emerald gradients; expect it to shrink a lot
• content/index.md — landing copy was rewritten; lift the strings verbatim from the attached
  landing design
• content/assets/ — vendor the gopher SVG (see Assets)

No markdown content outside content/index.md should change.

Tasks

• Add design tokens as CSS custom properties in brand.css (full table in README.md)
• Set styling.primary_color: "#2F5D8A" (replaces emerald #047857). Use it for links,
  active nav and focus only — nothing else on the page is tinted
• Switch the body font to IBM Plex Sans: add self-hosted plexsans-400/500/600.woff2 under
  content/assets/fonts/, add matching @font-face rules to brand.css, set
  styling.font: "IBM Plex Sans", and drop the Inter faces (CSP is font-src 'self')
• Keep the self-hosted JetBrains Mono for code — the design specifies IBM Plex Mono but
  does not depend on it, and JetBrains Mono is already shipping
• New content/assets/docs.css implementing the three archetypes
• Rewrite landing.css against the landing design reference
• Port the landing copy into content/index.md
• Vendor gopher-front.svg into content/assets/ and keep the CC BY 3.0 footer attribution
• make test / e2e green

Three archetypes cover every page

• A — docs article (/getting-started/introduction and most pages): 236px sidebar /
  fluid article (max 720px) / 190px sticky TOC, gap 40px. Breadcrumb, h1, lede, h2 sections
  each preceded by a top rule, prev-next cards, "Edit this page on GitHub" using source_path
  from front matter.
• B — section index (/recipes/, /reference/, /guides/): same shell without the TOC.
  Grouped 2-column link lists — title left, short gloss right, hairline rules — replacing the
  current long bulleted lists.
• C — reference entry (/reference/api and friends): 1px top rule per item, mono h3 name +
  category chip, signature code block, prose, then a 130px/1fr definition grid for params and
  returns.

Hard constraints

1. Code-column grids must use minmax(0,1fr), not 1fr. With 1fr, long monospace lines
   set the track's min-content width and the whole page scrolls sideways instead of the <pre>
   scrolling. This was a real defect during design.
2. Any text at or below 13px uses #6B6862 or darker. The muted greys were failing
   contrast at 12px; do not lighten them back.
3. No shadows, no transforms, no scroll animations, no gradients. Hover states change color
   and border only. The point of the redesign is that nothing moves unless the app is updating.
4. Go template syntax in code samples must render literally. {{lvtClientScriptURL}},
   {{.Name}}, {{if .lvt.Pending}} etc. are content, not template calls.

Decisions already made

Accent is #2F5D8A and the body font is IBM Plex Sans. Both are settled — implement them as
written rather than re-opening them.

Acceptance

• document.documentElement.scrollWidth === clientWidth at 924px and 1440px on the landing and
  on all three archetypes; <pre> blocks scroll internally
• No text below 11.5px; nothing at ≤13px lighter than #6B6862
• e2e/responsive_test.go, e2e/docs_ia_test.go, e2e/breadcrumb_test.go pass unchanged —
  they assert on the docs shell and will catch structural drift
• Landing renders every Go template sample literally
• Gopher is served from content/assets/, not hotlinked

For the implementing session

Read README.md from the attachment first — it has the exact token table, type scale, layout
measurements, interaction rules and responsive behavior. Open the two .dc.html files in a
browser (they need support.js beside them) to see the intended result. Where the clean theme's
own markup makes an exact match awkward, keep the theme's structure and match the tokens.

The archetype pages contain sample content transcribed from
content/getting-started/introduction.md, content/recipes/index.md and
content/reference/api.md @ v0.23.0. It is there to show layout — render each page's real
markdown, don't reproduce the samples.