Using topo
Contour lines: a drifting marching-squares relief field across the page that clears around the reading column; Alegreya and Alegreya Sans.
Like every official theme in the gallery, topo implements theme contract 1.1: every colour flows through the tokens below, the stylesheet lives in the theme cascade layer so your unlayered overrides always win, and any template it does not ship falls back to the default theme's copy.
Install
One config line, or one command:
# cherry.exs
theme: "topo"
$ cherry config theme topo
Then cherry build (or cherry serve while you look around). Nothing else moves: your content, your overlays for other themes, and your token overrides for other themes stay where they are.
The styling ladder, applied to topo
Restyling costs exactly as much ownership as you choose to take. In order:
Rung 1 - override a token. The manifest below is topo's public styling API. Overrides land in every page head, survive theme upgrades, and are validated against the manifest (a typo is an error, not a dead line):
$ cherry config tokens.--color-accent "light-dark(#b5451b, #e0895a)"
$ cherry theme.tokens # shows the merged view
Rung 2 - custom.css. Drop assets/custom.css into your site and it links after the theme stylesheet and the tokens block on every page. topo's own CSS lives in the theme cascade layer, so a plain selector in your unlayered file beats the theme without specificity games or !important.
Rung 3 - overlay a template. Write themes/topo/templates/<template>.html.eex (or .html.heex) in your site and it shadows just that template.
Rung 4 - eject. cherry theme.eject <template> copies the original into that overlay directory with a provenance header, so cherry theme.diff can tell you forever after whether upstream moved under your copy.
Rung 5 - a theme of your own. cherry gen.theme mytheme --from topo scaffolds the whole thing - manifest, templates, stylesheet, islands - into themes/mytheme/, yours deliberately.
The theming reference covers every rung in depth; the theme guide walks rung 5.
Token API
Colour tokens are light-dark() pairs: one override sets both renditions, and the theme toggle flips a single color-scheme property.
Surface and text
| Token | Light | Dark | Role |
|---|---|---|---|
--color-bg |
#eef0e4 |
#151a12 |
Page background. |
--color-surface |
#e3e6d6 |
#1d2419 |
Raised ground: code blocks, inline code. |
--color-fg |
#2b2418 |
#ece8da |
Body text. |
--color-muted |
#6b6350 |
#a6a18c |
Secondary text: metadata, nav, footer. |
--color-border |
#cfd2c0 |
#2e3628 |
Hairline rules and control borders. |
--color-accent |
#b5451b |
#e0895a |
Links and interactive accents. |
--color-accent-strong |
#8f3514 |
#f0aa84 |
Hover/active accent. |
--color-selection |
#f3d7c8 |
#4a3322 |
Text selection ground. |
Syntax highlighting
| Token | Light | Dark | Role |
|---|---|---|---|
--syn-keyword |
#b5451b |
#e0895a |
Syntax: keywords. |
--syn-string |
#3e6b2a |
#9ccf7e |
Syntax: strings and characters. |
--syn-comment |
#87846f |
#7c8270 |
Syntax: comments (italic). |
--syn-function |
#6a3d9a |
#c8a6f0 |
Syntax: functions and methods. |
--syn-constant |
#9a5f00 |
#f0c070 |
Syntax: constants, numbers, booleans. |
--syn-type |
#2a5f7a |
#7fc4d6 |
Syntax: types, modules, tags, attributes. |
--syn-variable |
#2b2418 |
#ece8da |
Syntax: variables and default code text. |
--syn-punct |
#6b6350 |
#a6a18c |
Syntax: punctuation and operators. |
Type and measure
| Token | Default | Role |
|---|---|---|
--font-prose |
'Alegreya', Georgia, 'Times New Roman', serif |
Reading face (Alegreya, self-hosted latin subsets, OFL). Structure uses Alegreya Sans. |
--font-mono |
ui-monospace, 'Cascadia Code', 'SF Mono', Consolas, 'DejaVu Sans Mono', monospace |
Structure and code face. |
--measure |
40rem |
Reading column width. |
Templates
topo ships 1 of the 9 templates in the contract; the rest resolve to the default theme's copy, so they stay current without you owning them. Overlay or eject any name in either list.
Shipped by topo
| Template | Assigns | Purpose |
|---|---|---|
layout |
@site, @inner, @page_title, @head_extra, @nav, @search, @page_class |
Outer HTML shell wrapped around every rendered page. |
Inherited from default
| Template | Assigns | Purpose |
|---|---|---|
page |
@site, @doc |
A freeform page from the pages collection. |
post |
@site, @doc |
A single blog post with title, date, and tags. |
post_list |
@site, @posts |
Reverse-chronological index of published posts. |
tag |
@site, @tag, @posts, @story_href |
Published posts carrying one tag; links to the tag's story when one exists. |
portfolio_timeline |
@site, @portfolio, @cv_href |
The timeline mode of the profile: dated entries, open source; cv_href links the switcher back to the CV view when public. |
story |
@site, @tag, @portfolio, @posts |
One tag across the whole story: portfolio entries plus blog posts. |
cv |
@site, @cv |
The employer-shaped CV: cv-curated entries in the careers layout, print-first. |
not_found |
@site |
The 404 page. |
Working with an agent
Cherry ships a skill that teaches a coding agent the operating loop above - the ladder, the CLI verbs, and the recovery playbook - so you can say "make the accent electric blue, the Cherry way" and it will reach for cherry config tokens.--color-accent instead of forking the stylesheet. Install it into your site's .claude/skills/ (sites scaffolded with cherry new already carry AGENTS.md describing the same loop), then ask in terms of outcomes:
- "Warm up topo's palette for both renditions" - the agent lists the manifest with
cherry theme.tokens, overrides rung-1 tokens, and verifies withcherry check. - "Tighten the reading column" - one token:
--measure. - "Restyle the post list" - rung 2 in
assets/custom.cssif CSS reaches it,cherry theme.eject post_listif structure has to change.
The one rule to hold an agent to: never edit the theme's own files under themes/topo/ unless they were ejected there on purpose - cherry theme.diff will name anything that drifts.