feat(site): restyle the documentation site dark-first - #3
Conversation
Helium renders the landing page from a template of its own, and that template has no navigation bar in it. So the front page offered a reader exactly two ways onward: a boxed "Documentation" panel in the top-right corner, and the "Where to go next" list at the very bottom of the prose. `titleLinks` puts the routes where a reader looks first — directly under the title, as a row of buttons: Get started, Examples, API reference, and the source repository. The boxed panel is removed in the same change rather than kept alongside, because it listed the same three destinations. A header that says "Getting Started" as a button and "Getting Started" again in a panel four inches to the right is not twice as helpful. It was also the tallest thing in the header, which set the header's height and left the title column beside it looking abandoned. Nothing is lost: every destination the panel held is in the row, and the "Where to go next" list at the foot of the page is unchanged.
The site was stock Helium in the project's original blue: a gradient banner, centred headings, teaser text floating with no container, code blocks with no border, and a sidebar whose section headings were told apart from its page links by a 2px rule. It read as a theme with the colours changed, because that is what it was. This is a design pass, not a theme swap. Helium stays — it already owns the sidebar, the responsive layout, the syntax highlighter and the page navigation, and hand-writing those to end up somewhere worse is not a good trade. What changes is everything Helium lets you change. **Palette.** Near-black (#0b0f14) with one accent hue, azure, in two tones: a bright one for interactive text on dark, a deep one for the same on white. Both colour schemes are now defined in full — before, only the light one was, and dark fell back to Helium's default teal, which no one had chosen. The header keeps its near-black in both schemes, so the site has one first impression rather than two, and its gradient is set to the same colour at both stops, which is how Helium is told to draw a flat surface. **Type.** 16px body, up from 15, in an 820px column rather than 860 — about 75 characters, which is where the eye stops having to hunt for the start of the next line. The heading scale steps 40 / 27 / 20 / 16 so a heading's level is visible without counting. **Components.** These are shapes, not settings, so they live in the new `site/assets/css/site.css`, wired in with `internalCSS` and loaded after Helium's own stylesheets — same specificity, later in the cascade, so nothing needs `!important`. Teasers become cards. Code blocks get a border, a radius, and `white-space: pre` (Helium wraps them, which in Scala breaks lines mid-identifier: `Future[Page[Issue]]` came out as `Futur` / `e[Page[Issue]]`). Inline code becomes a chip so a type name in a sentence is not mistaken for emphasis. Headings take the body colour instead of the accent, leaving the accent to mean "you can click this". Sidebar sections become small caps labels and the current page gets a bar. The home icon moves from the centre of the top bar, where Helium's space-between puts it on a wide screen, to the left where a brand mark goes. Verified by rendering: dark, light, and 390px wide, on the landing page and on a guide. The full pipeline is unchanged and still green — every snippet compiles, every internal link resolves.
|
Warning Review limit reached
Next review available in: 32 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
1 participant
What this does
Redesigns the documentation site. It was stock Helium with the colours changed; this makes it a designed page — near-black canvas, one accent colour, cards, real type hierarchy, and a landing page whose header offers a way into the docs.
Dark is the mode this is designed for. Light is fully supported and derived from the same tokens, not an afterthought.
Why
The site looked dated and, in places, unfinished:
Future[Page[Issue]]rendered asFutur/e[Page[Issue]].space-betweenleaves it on a wide monitor.How it works
Helium stays. It already owns the sidebar, responsive layout, syntax highlighting and page navigation; replacing it means rewriting all of that to end up somewhere worse. Everything here is either Helium configuration or a CSS layer on top.
Two commits.
feat(site): give the landing page a hero action row— addstitleLinksto thelandingPageconfig: Get started, Examples, API reference, source. RemovesdocumentationLinks, which rendered a boxed panel listing the same destinations; it was also the tallest thing in the header, so it set the header's height and left the title column beside it looking empty. Nothing is lost — every destination is still one click away, and the "Where to go next" list at the foot of the page is untouched.feat(site): restyle the site dark-first over Helium— the design pass:site/build/laika.scalagains aPaletteobject holding both schemes in full, plusdarkMode.themeColors, syntax-highlighting quintets for both, a new type scale viafontSizes, and column metrics vialayout. The header's gradient is set to the same colour at both stops, which is how Helium is told to draw a flat surface rather than a gradient.site/assets/css/site.css(new) holds component shapes — the things Helium exposes no setting for. Wired in withinternalCSS(Root / "assets" / "css"), which loads it after Helium's own stylesheets at the same specificity, so every rule is a plain override and nothing needs!important.The split matters and is documented in both files: colours, type scale and metrics are configuration and live in
laika.scala; component shapes are CSS and live insite.css. A colour set in both places will drift.Specifics worth calling out:
white-space: preon code blocksmax(28px, calc(…))#headerto constrain, so the shell is emulated with padding — this aligns the hero's left edge with the cards and prose below itHow to test it
Then open http://localhost:8080/ and toggle your OS between light and dark.
--no-apiskips Scaladoc and is much faster if you are only looking at prose.To check the specific fixes:
guides/04-pagination.html, first snippet:Future[Page[Issue]]is intact on one line, and the block scrolls sideways if it needs to.The pipeline's own guarantees are unchanged and still enforced: every tagged snippet is compiled against the library, and every internal link is validated. A full
./scripts/site.sh --cleanis green, and all 963 generated pages have exactly one</html>.Notes for reviewers
landing.template.html, which means depending on an internal path and re-checking it on every Laika upgrade — and getting it wrong fails silently by falling back to the default.titleLinkscovers the same need through a supported option. Worth revisiting only if Laika makes the template a public extension point.laika.scaladescribes, and rewriting the prose was out of scope for a styling change. Say the word if you want it condensed.