@geekity/cms 0.11.0 → 0.13.0

package/themes/default/README.md

@@ -23,6 +23,8 @@ themes/default/
     post-list.njk     the h-feed a listing is made of
     pagination.njk    previous/next pager
     tags.njk          macros for tag and category links
+    kicker.njk        the line above an entry naming its kind and date
+    reply-context.njk the citation of what a reply answers
     bio.njk           who an entry is by, as an h-card
     menu.njk          one named menu, as a nav of links
     feeds.njk         macros for the feed links in <head>
@@ -39,12 +41,39 @@ themes/default/
     comment-digest.*.njk    the hourly or daily digest of what is waiting
     comment-reply.*.njk     the notice a commenter gets about a reply
     contact-message.*.njk   a message from a page's contact form
+  src/
+    style.css    the stylesheet's source, compiled with Tailwind
   static/
-    style.css    served at /theme/style.css
+    style.css    the compiled stylesheet, served at /theme/style.css
+    highlight.js the code highlighter
 ```
 
-Plain Nunjucks and plain CSS. There is no build step and no dependency: a site
-that wants Tailwind or anything else brings its own.
+Plain Nunjucks templates and one stylesheet. The stylesheet is written in
+Tailwind v4 (`src/style.css`) and compiled when the package is built, so
+`static/style.css` is a build product: gitignored in this repository, written
+by `pnpm build` (which the root `prepare` runs after an install and before a
+publish), and shipped in the package like every other file here. The compile
+happens once, on the machine that builds the package. A reader gets one plain
+CSS file and no script, web font or CDN request because of it.
+
+The design is Paper (doc-9, decision-22): one warm column, serif throughout,
+sans for small labels, and a kicker above every entry naming its kind.
+
+**Rebuilding the stylesheet.** After editing `src/style.css`:
+
+```
+pnpm --filter @geekity/cms build:theme
+```
+
+Tailwind scans only this theme's `layouts/` and `partials/`, so a utility class
+written in a template here is compiled in and nothing outside the theme is
+read. The templates themselves use the semantic class names below and the look
+lives in `src/style.css`, through `@apply`.
+
+**A site theme owes Tailwind nothing.** Its own `static/style.css` replaces this
+one wholesale, and any CSS that knows the class names in this README will do.
+The demo theme's is plain CSS. A site that only wants different colours
+overrides the `--color-*` custom properties instead; see [Colours](#colours).
 
 ## The manifest
 
@@ -54,7 +83,9 @@ that wants Tailwind or anything else brings its own.
 {
   "name": "Default",
   "kind": "site",
-  "description": "One line about the theme."
+  "description": "One line about the theme.",
+  "colorScheme": "light dark",
+  "themeColor": { "light": "#faf7f2", "dark": "#171412" }
 }
 ```
 
@@ -64,6 +95,14 @@ and `description` is optional. The directory name is the theme's id. A
 directory without a readable manifest, or one naming a kind this CMS does not
 have, is not a theme.
 
+`colorScheme` and `themeColor` are the colours the head declares before the
+stylesheet loads (see [The head](#the-head)). `colorScheme` is one of `normal`,
+`light`, `dark`, `light dark`, `dark light` or `only light`, preferred scheme
+first. `themeColor` is the colour of the browser around the page, one per
+scheme, as a three- or six-digit hex colour with no alpha. Make it the page's
+own background. A value outside those is ignored, and so is one a theme leaves
+out: each falls back to this theme's, just as a template does.
+
 ## Overriding a template
 
 A site keeps its themes under one directory, `themes/` by default and
@@ -122,8 +161,8 @@ packaged ones by name:
 ```
 
 `layouts/base.njk` defines the blocks `title`, `speculationRules`,
-`viewTransitions`, `head`, `alternates`, `header`, `content`, `footer` and
-`scripts`, so most sites never have to copy it.
+`viewTransitions`, `head`, `alternates`, `header`, `breadcrumbs`, `content`,
+`footer` and `scripts`, so most sites never have to copy it.
 
 Two layouts are named for the pages the Reading settings pick:
 
@@ -145,9 +184,10 @@ words above the posts; `layouts/home.njk` already does.
 
 ## The page shell
 
-`layouts/base.njk` is the andrewshell.org design's shell (decision-16): the
-skip link, one `.global-wrapper` at the 42rem measure, `.global-header`,
-`<main id="main">` and the footer, in that order.
+`layouts/base.njk` is the page shell: the skip link, one `.global-wrapper` at the
+42rem measure, `.global-header`, `<main id="main">` and the footer, in that
+order. The shape is the andrewshell.org design's (decision-16) and the look is
+Paper's (doc-9).
 
 **One home for each kind of link.** The header carries the site menu, on every
 page. [The bio](#the-bio) carries the person whose page or post it is. The
@@ -156,7 +196,7 @@ nowhere else.
 
 **The header has one rule, and the menu under it.** On the front page it is the
 site title as `h1.main-heading`, linked home, with `site.tagline` in a
-paragraph under it; on every other page it is `a.header-link-home`, the site
+`p.site-tagline` under it; on every other page it is `a.header-link-home`, the site
 title small and linked home, and no tagline. The wrapper carries
 `data-is-root-path="true"` at `/` and nothing anywhere else, which is how the
 stylesheet tells the two apart. `menus.primary` is printed inside the
@@ -176,6 +216,18 @@ and the copyright line stands on its own. The year is
 rather than parses — so it is the year at the moment the page is rendered, in
 the site's own timezone.
 
+**The breadcrumb** opens `<main>` on a page with a place in the site's
+hierarchy (TASK-150): a post filed under a category, and a category, tag or
+author archive. It is `nav.breadcrumbs` labelled `Breadcrumb`, holding an `ol`
+whose items run Home, then the post's first category and the post, or the
+archive's term or person, then `Page N` past page one. Every crumb but the last
+is a link; the last is the page itself, a `span` with `aria-current="page"`.
+The trail is `breadcrumbs`, a list of `{ name, url }` that `layouts/base.njk`
+sets before anything is printed, and the JSON-LD prints the same list, so the
+two cannot disagree. Every other page has an empty trail and prints nothing. A
+site that wants no visible breadcrumb empties the `breadcrumbs` block, and the
+`BreadcrumbList` stays in the graph.
+
 Webrings, badges, a licence notice and anything else that is markup rather than
 a link are deliberately not in the package. They go in a site theme's `footer`
 block:
@@ -260,13 +312,19 @@ html.geekity-admin-bar {
 
 ### An entry
 
-`layouts/post.njk` and `layouts/page.njk` draw the same thing, the source
-design's entry, and it is a microformats2 `h-entry`:
+`layouts/post.njk` and `layouts/page.njk` draw the same thing, the entry, and it
+is a microformats2 `h-entry`. An article, and a page:
 
 ```html
 <article class="blog-post h-entry">
-  <header>
+  <header class="post-header">
+    <p class="kicker">
+      <span class="kicker-kind">Article</span>
+      <span class="kicker-dot" aria-hidden="true">·</span>
+      <a href="/category/notes/" class="p-category" rel="category">notes</a>
+    </p>
     <h1 class="p-name">Hello</h1>
+    <p class="post-deck p-summary">The description the author wrote.</p>
   </header>
   <section class="e-content">
     <p>The rendered body.</p>
@@ -279,38 +337,47 @@ design's entry, and it is a microformats2 `h-entry`:
           >Published 2 September 2026</time
         ></a
       >
-      <br /><time class="small dt-updated" datetime="2026-09-05T09:00:00.000Z"
+      <span aria-hidden="true">·</span>
+      <time class="small dt-updated" datetime="2026-09-05T09:00:00.000Z"
         >Updated 5 September 2026</time
       >
     </p>
   </section>
-  <p class="post-categories">…categories…</p>
   <p class="post-categories">…tags…</p>
   <hr />
   <footer>…the bio…</footer>
 </article>
-<nav class="blog-post-nav">…the posts either side…</nav>
+<nav class="blog-post-nav" aria-label="Neighbouring posts">…</nav>
 ```
 
+**The kicker names the kind.** `p.kicker`, from `partials/kicker.njk`, opens
+every entry: the kind word in `span.kicker-kind` (Article, Note or Reply for a
+post, from its `postType`; Page for a page), then the categories it is filed
+under as `p-category` links. It is the only place the kind is said, small and
+once, and an article is additionally the only kind with a visible headline.
+The deck is the front matter's `description` as a `p.post-deck.p-summary`,
+printed only when the author wrote one.
+
 **The Published line is inside the `e-content`**, which is the one thing about
 this shape worth knowing. It is what the source theme does: the date and the
-permalink are part of the words, so a reader — or a fediverse peer reading the
-`e-content` — takes them with the post. The permalink wraps the `dt-published`
-time as a `u-url`, and a `dt-updated` line follows it only when the update
-happened on a different day in the site's own timezone; a typo fixed an hour
-later is not news. A post tagged `indienews` opens the line with a
+permalink are part of the words, so a reader, or a fediverse peer reading the
+`e-content`, takes them with the post. The permalink wraps the `dt-published`
+time as a `u-url`, and a `dt-updated` follows it after a middle dot only when
+the update happened on a different day in the site's own timezone; a typo fixed
+an hour later is not news. A post tagged `indienews` opens the line with a
 `u-category` link to <https://news.indieweb.org/en>, which is how IndieNews is
 told the post is for it; a page never prints one, and its line is a
 `p.page-meta` rather than a `p.entry-meta`.
 
 **Every post's page has one `h1`.** A post with a name of its own is headed by
 it, as above. A note, or a reply without a title, opens on its words instead,
-so it has no `header`; in its place is an `h1` a screen reader and a crawler
-navigate by and a sighted reader never sees, saying what the post is, who wrote
-it and when:
+set larger, so it has no `header`; in its place is an `h1` a screen reader and
+a crawler navigate by and a sighted reader never sees, saying what the post is,
+who wrote it and when, and then the kicker:
 
 ```html
 <h1 class="screen-reader-text">Note by Ada Lovelace, 11 September 2026</h1>
+<p class="kicker"><span class="kicker-kind">Note</span></p>
 ```
 
 It says `Reply` for a reply and leaves out the name or the date the post does
@@ -319,16 +386,24 @@ for an article. The headings under it step down one level at a time: the
 conversation and the comment form are `h2`, and a refused form's error summary
 is an `h3` inside the form's section.
 
-What it is filed under is printed under the words and inside the article, so
-that each link is a `p-category` of this entry: the categories first, then the
-tags, each as one `p.post-categories` from `partials/tags.njk`.
-
-After the entry a post prints `nav.blog-post-nav`, `rel="prev"` and
-`rel="next"` links to `previous` and `next` with an arrow either side, and
-nothing at all at the ends of the archive; then the conversation and the
-comment form. A page prints the contact form when its front matter asked for
-one. A page has no neighbours, no taxonomy and no IndieNews link, because none
-of those are things a page has.
+**A reply cites what it answers** with `partials/reply-context.njk`, a
+`div.reply-context.cite.u-in-reply-to.h-cite`: a rule on the start side, a
+`p.cite-line` saying "In reply to" and the target's name, author and date as
+far as they are known, and its excerpt as a `blockquote.cite-quote.p-content`.
+An untitled reply prints it under the kicker; a titled reply prints it above
+its header. The same partial cites a reply in a feed.
+
+The tags are printed under the words and inside the article, so that each link
+is a `p-category` of this entry, as one `p.post-categories` from
+`partials/tags.njk`. The stylesheet draws the `#` in front of each, so the
+category a parser reads is the tag and not the hash.
+
+After the entry a post prints `nav.blog-post-nav`: the `previous` and `next`
+posts as two cards, `rel="prev"` and `rel="next"`, each opening on a
+`span.blog-post-nav-label`, and nothing at all at the ends of the archive; then
+the conversation and the comment form. A page prints the contact form when its
+front matter asked for one. A page has no neighbours, no tags and no IndieNews
+link, because none of those are things a page has.
 
 ### The bio
 
@@ -352,7 +427,16 @@ What the bio prints: a round `u-photo` at 50px when they have an avatar,
 their archive, then `p-job-title` and `p-locality` when the profile says, then
 their `p-note` and their `rel="me"` links as a `ul.hlist.bio-links` — each
 link's `rel` is on it ready to print, `me` first and then whatever else the
-Links box typed. Each of
+Links box typed. Set `bioRelMe` to `false` to keep the card and drop its
+claims: the name is linked `rel="author"` alone and `me` comes off every
+link.
+
+**The homepage** speaks for the site's author only on a solo author blog,
+which `soloAuthor` on the context says. Then both `layouts/home.njk` at `/` and
+`layouts/front-page.njk` end with that person's card, with its `rel="me"`
+claims, and their author archive's link home carries `rel="me"` back, so the
+homepage and the archive name each other. On any other site a listing homepage
+prints no card, and the front page prints its card with `bioRelMe` false. Each of
 those is printed only when the profile says it, so a profile holding a name
 alone prints a name alone. A name this site has no account for is printed
 unlinked, because the file still said somebody wrote this.
@@ -387,49 +471,66 @@ byline under the title rather than a bio in the footer, so it writes one.
 
 ### A listing
 
-`partials/post-list.njk` is the feed every listing is made of — the home page,
-the posts page, a tag, category or author archive — and it is a microformats2
-`h-feed`:
+`partials/post-list.njk` is the feed every listing is made of (the home page,
+the posts page, a tag, category or author archive, and the front page's recent
+posts) and it is a microformats2 `h-feed` of `h-entry` items, each opening on
+its kicker:
 
 ```html
 <div class="feed h-feed">
   <article class="feed-item h-entry">
-    <div class="feed-content">
-      <h2 class="feed-title p-name">
-        <a href="/2026/09/hello/" class="u-url">Hello</a>
-      </h2>
-      <div class="feed-excerpt p-summary">
-        <p>What the post is about, in about 280 characters...</p>
-      </div>
-      <p class="feed-more">
-        <a href="/hello/" aria-label="Continue reading: Hello">
-          Continue reading<span aria-hidden="true"> &rarr;</span>
-        </a>
-      </p>
-      <div class="feed-meta">
-        <p>
-          <time class="feed-date dt-published" datetime="…"
-            >2 September 2026</time
-          >
-        </p>
-        <p class="post-categories">
-          <a href="/category/notes/" class="p-category" rel="category">notes</a>
-        </p>
-      </div>
+    <p class="kicker">
+      <span class="kicker-kind">Article</span>
+      <span class="kicker-dot" aria-hidden="true">·</span>
+      <time class="feed-date dt-published" datetime="…">2 September 2026</time>
+      <span class="kicker-dot" aria-hidden="true">·</span>
+      <a href="/category/notes/" class="p-category" rel="category">notes</a>
+    </p>
+    <h2 class="feed-title p-name">
+      <a href="/2026/09/hello/" class="u-url">Hello</a>
+    </h2>
+    <div class="feed-excerpt p-summary">
+      <p>What the post is about, in about 280 characters...</p>
     </div>
+    <p class="feed-more">
+      <a href="/2026/09/hello/" aria-label="Continue reading: Hello">
+        Continue reading<span aria-hidden="true"> &rarr;</span>
+      </a>
+    </p>
   </article>
   <hr class="feed-separator" />
-  <article class="feed-item h-entry">…</article>
+  <article class="feed-item h-entry">
+    <p class="kicker">
+      <span class="kicker-kind">Note</span>
+      <span class="kicker-dot" aria-hidden="true">·</span>
+      <a href="/2026/09/coffee/" class="u-url"
+        ><time class="feed-date dt-published" datetime="…"
+          >3 September 2026</time
+        ></a
+      >
+    </p>
+    <div class="feed-excerpt e-content"><p>The whole note.</p></div>
+  </article>
 </div>
 ```
 
-The excerpt is the entry's `summary` — the very line the feeds publish, so a
-reader and a feed cannot be told two different things — through Nunjucks'
+**Only an article has a headline.** A note, which has no title, is printed
+whole as its `e-content`, and the date in its kicker is its `u-url`. A reply is
+a note that first cites what it answers with `partials/reply-context.njk`, and
+a reply with a title is an article that does. An article's categories are in
+its kicker; a note's are on its own page.
+
+The excerpt is the entry's `summary`, the very line the feeds publish, so a
+reader and a feed cannot be told two different things, through Nunjucks'
 `truncate(280)`, which cuts at the last space before 280 characters and adds an
 ellipsis. A `description` shorter than that is printed whole. It is plain text
 rather than markup, deliberately: an excerpt with half a code block in it is
 not an excerpt.
 
+Each entry of a listing carries `replyContext` beside `inReplyTo` when it is a
+reply whose target has been fetched, the same object a reply's own page gets,
+so the feed can cite it in full.
+
 An entry's tags are not in a feed item. They belong under the entry, where
 there is one post's worth of them rather than twenty.
 
@@ -445,21 +546,24 @@ before including it, so the outline never skips a level:
 
 A listing with nothing on it says `No posts found.` in `p.empty`.
 
-`partials/pagination.njk` prints two arrows in `nav.pagination` — `← Previous`
+`partials/pagination.njk` prints two links in `nav.pagination`, `← Previous`
 to the page before this one and `Next →` to the page after it, with `rel="prev"`
-and `rel="next"` — and nothing at all on a listing of one page. The arrows
+and `rel="next"`, and nothing at all on a listing of one page. The arrows
 themselves are `aria-hidden`, because a screen reader that announced them would
 read the decoration and then the word.
 
 Each listing layout heads its own page: `layouts/home.njk` with the listing's
-title, `layouts/tag.njk` and `layouts/category.njk` with the term, and
-`layouts/author.njk` with the person as an `h-card`. The category archive puts
-its heading in a `header.category-header` and prints a `div.category-description`
-under it when the context carries a `categoryDescription`; the CMS has no store
-of term descriptions, so nothing writes one today and the header is the heading
-alone.
-
-`layouts/404.njk` says `Content not found.` and links home and to the search.
+title, and the three archives with a `header.archive-header` whose kicker says
+what kind of archive it is (Tag, Category, Author) over an `h1.page-title`
+naming whose: the term, or the person, followed by their `h-card`. The
+category archive's header is also a `header.category-header` and prints a
+`div.category-description` under the name when the context carries a
+`categoryDescription`; the CMS has no store of term descriptions, so nothing
+writes one today and the header is the heading alone.
+
+`layouts/404.njk` says `Content not found.` under a `Not found` kicker and
+links home and to the search. The 500 and 503 pages below open on a kicker the
+same way.
 
 `layouts/500.njk` is the page a request gets when the server fails while
 answering it (TASK-129). It says `Something went wrong.` in an
@@ -583,25 +687,52 @@ the entry's `summary` — the line the feeds publish — else `site.tagline`. It
 printed once, as `<meta name="description">`, and the Open Graph and Twitter
 descriptions say the same thing.
 
+**The colours** come from the theme's `theme.json` (see
+[The manifest](#the-manifest)), on the context as `theme`.
+`<meta name="color-scheme">` comes before the stylesheet, so a reader in dark
+mode gets a dark canvas rather than a white flash while the stylesheet loads.
+`<meta name="theme-color">` is printed twice, once with
+`media="(prefers-color-scheme: light)"` and once for dark.
+
 **The card.** `og:title` is the page's title, or the site's on the front page;
 `og:site_name` is always the site's. `og:type` is `article` on a rendered post
 or page and `website` everywhere else, a listing carrying a page's front matter
-included. `og:url` is the canonical URL. `twitter:card` is `summary`, the small
-square picture beside the words, because the picture is usually a face rather
-than a wide photograph.
-
-**The picture** is the `image` in the entry's front matter, else `site.avatar`.
-A site with neither prints no `og:image` and no `twitter:image` rather than an
-empty one.
-
-**The icons** come from the site's avatar through the derived images
-(decision-10): `icon` at 32 and 16 pixels and `apple-touch-icon` at 180, each a
-square PNG cropped from the middle of the avatar and encoded the first time a
-browser asks for it. They are on the context as `icons`, a list of
-`{ rel, sizes, href }`, which is empty — and the links are not printed at all —
-when the site has no avatar, when its avatar is a file no icon can be made of,
-or when image optimization is off. There is no web manifest; a site that wants
-one adds it in its own `head` block.
+included. `og:url` is the canonical URL. An article also carries
+`article:published_time`, `article:modified_time` (the `updated` date, else the
+publish date), `article:author` (the author's profile URL here, else their
+name) and one `article:tag` per tag.
+
+**The picture** is the `image` in the entry's front matter, else `site.avatar`,
+on the context as `shareImage`. A site with neither prints no `og:image` and no
+`twitter:image` rather than an empty one. The picture always carries
+`og:image:alt` and `twitter:image:alt`. For the entry's own picture, the alt
+text is its `imageAlt` front matter, else what the media library says about the
+upload, else the entry's title. For the avatar, it is the media library's text,
+else the site's author. `og:image:width` and `og:image:height` are printed when
+the image's variants have been derived, because the size is read from their
+sidecar rather than from the file. `twitter:card` is `summary_large_image` for a
+picture at least 1200 pixels wide and wider than it is tall. Everything else,
+the avatar included, is `summary`, the small picture beside the words.
+
+**The icons** come from the site's `icon` setting in `site.json`, else
+`site.avatar`, through the derived images (decision-10). `icon` exists for a
+site whose avatar is a face and whose mark is a logo. The head links `icon` at
+32 and 16 pixels and `apple-touch-icon` at 180, each a square PNG cropped from
+the middle of the picture and encoded the first time a browser asks for it. An
+SVG icon is linked first as itself, with `type="image/svg+xml"` and no
+`sizes`, and the PNGs are rasterised from it. They are on the context as
+`icons`, a list of `{ rel, sizes, type, href }`, which is empty, and the links
+are not printed at all, when the site has neither setting, when it names a
+file no icon can be made of, or when image optimization is off.
+
+**The favicon and the manifest** are routes, not templates. `/favicon.ico`
+holds 16, 32 and 48 pixel frames drawn from the same picture, because browsers
+and crawlers ask the root for it whatever the head links; it answers 404 on a
+site with no icon. `/manifest.webmanifest` gives the site's title as `name` and
+`short_name`, `start_url` `/`, `display` `minimal-ui`, the theme's light
+`themeColor` as `theme_color` and `background_color`, and icons at 192 and 512
+pixels plus a maskable 512 whose picture sits inside the middle 80%, padded
+with its own dominant colour. The head links it on every page.
 
 **The structured data** is `partials/jsonld.njk`, one `<script
 type="application/ld+json">` holding one `@graph` per page, and it is the only
@@ -611,7 +742,8 @@ IndieWeb. The graph holds:
 
 - `WebSite`, always, with the site's title, tagline and URL, and a `publisher`
   pointing at the Person, and a `potentialAction` that is a `SearchAction` on
-  `/search/?q={search_term_string}`.
+  `/search/?q={search_term_string}`. On the homepage of a solo author blog it
+  also has an `about` pointing at the site author's Person.
 - `Person`, from `siteAuthor`: their name, archive URL, avatar, bio, job title
   and location, and a `sameAs` of their profile links and their actor id, which
   is what asserts that the schema.org Person and the fediverse actor are one
@@ -622,6 +754,9 @@ IndieWeb. The graph holds:
 - `BlogPosting` on a post and `Article` on a page, with the headline, URL,
   `mainEntityOfPage`, `datePublished`, `dateModified`, description, image,
   `author` and `publisher`.
+- `BreadcrumbList` wherever the page prints a breadcrumb (see
+  [The page shell](#the-page-shell)): one `ListItem` per crumb with its
+  `position`, `name` and absolute URL as `item`.
 
 A site that wants a different graph — more types, an `Organization` publisher,
 nothing at all — writes its own `partials/jsonld.njk` and that file replaces
@@ -682,38 +817,48 @@ to its own stylesheet.
 
 ### Colours
 
-`static/style.css` is the source design: a serif body and sans headings at an
-18px root on a 1.2 minor-third scale, warm paper with near-black text, a rust
-primary and a blue secondary, one column, links that invert to the primary
-colour on hover, and a rule in the primary colour. Everything is a custom
-property on `:root`, so a site that only wants different colours overrides the
-half-dozen `--color-*` tokens rather than the stylesheet.
-
-The source is light only. The theme adds a second scheme under
-`@media (prefers-color-scheme: dark)` that redefines the same colour tokens on
-dark paper, with the rust and the blue lifted until they read on it, and
-`color-scheme: light dark` so a browser paints its own form controls and
-scrollbars to match. There is no toggle: the reader's system setting is the
-setting.
-
-Both schemes meet WCAG 2.2 AA — 4.5:1 for body text, 3:1 for large text, rules
-and focus outlines — and that is a test rather than a claim.
-`src/web/theme-colors.test.ts` reads the custom properties out of this
-stylesheet and computes the ratios for every pair the design puts on screen, so
-a colour changed here that breaks one fails the build.
-
-| Token                     | What it colours                                    |
-| ------------------------- | -------------------------------------------------- |
-| `--color-body`            | The paper, and the text of an inverted link.       |
-| `--color-text`            | The ink.                                           |
-| `--color-primary`         | Links, the rule, the focus outline, table headers. |
-| `--color-secondary`       | Blockquote text and its border.                    |
-| `--color-base`            | A warm sunk surface: rules between entries.        |
-| `--color-base-2`          | A cooler sunk surface.                             |
-| `--color-base-3`          | The raised surface: the focused skip link, inputs. |
-| `--color-code-background` | Behind `code` and a fenced block.                  |
-| `--color-code-text`       | Code with no highlighting on it.                   |
-| `--color-error`           | A form field that will not do.                     |
+Every colour is a custom property on `:root`, and these tokens are the
+override contract: a site that only wants different colours redefines them in
+its own stylesheet rather than replacing this one. Tailwind's own palette is
+cleared in `src/style.css`, and its utilities (`text-ink`, `bg-paper`,
+`border-edge` and the rest) are mapped onto these properties with
+`@theme inline`, so redefining a token recolours every rule that uses it.
+
+A second scheme under `@media (prefers-color-scheme: dark)` redefines the same
+tokens on dark paper, and `color-scheme: light dark` lets a browser paint its
+own form controls and scrollbars to match. There is no toggle: the reader's
+system setting is the setting.
+
+Both schemes meet the Colour contrast rule of the
+[specification.website checklist](https://specification.website/checklist.md):
+every run of text, the small kickers, dates and meta lines included, at 7:1
+(WCAG 1.4.6, AAA) on whatever it sits on, and every border a reader relies on
+(a field, a card, a code block, the focus outline, the citation and blockquote
+rules) at 3:1 (1.4.11). Nothing a reader needs is drawn at reduced opacity.
+That is a test rather than a claim: `src/web/theme-colors.test.ts` reads the
+tokens out of the compiled stylesheet and computes the ratio of every pair the
+design puts on screen, so a colour changed in `src/style.css` that breaks one
+fails the build.
+
+| Token                     | Utility    | What it colours                                                        |
+| ------------------------- | ---------- | ---------------------------------------------------------------------- |
+| `--color-body`            | `paper`    | The paper, and the words on a submit button.                           |
+| `--color-text`            | `ink`      | Body text and headlines.                                               |
+| `--color-muted`           | `muted`    | Kickers, dates, meta lines, decks, quotes, the bio note, the footer.   |
+| `--color-primary`         | `accent`   | Links, a kicker's kind word, the citation rule, the submit button.     |
+| `--color-secondary`       | `accent-2` | Tag links and the focus outline.                                       |
+| `--color-rule`            | `rule`     | Decorative hairlines only: between entries, above the footer.          |
+| `--color-edge`            | `edge`     | Borders a reader relies on: fields, the previous and next cards, code. |
+| `--color-base`            | `surface`  | A sunk surface: fields, notices, a face with no avatar.                |
+| `--color-base-2`          | —          | A cooler sunk surface.                                                 |
+| `--color-base-3`          | —          | The raised surface: the focused skip link.                             |
+| `--color-code-background` | `code`     | Behind `code` and a fenced block.                                      |
+| `--color-code-text`       | —          | Code with no highlighting on it.                                       |
+| `--color-error`           | `error`    | A field that will not do, and what the form says about it.             |
+
+`--color-rule` is the one token in no contrast pair, because it is decoration:
+a site that recolours it may make it as faint as it likes. Anything drawn with
+`--color-edge` has to stay at 3:1 against the paper and the surface.
 
 ### Code highlighting
 
@@ -750,11 +895,12 @@ a different version of highlight.js than the one installed.
 **The palette is Tomorrow**, the one both of the sites this design comes from
 used: Chris Kempson's Tomorrow on light paper and Tomorrow Night on dark, from
 highlight.js's own base16 themes, which is also what decides which `hljs-`
-scope takes which slot. Five of the light colours are not the stock ones — a
-syntax theme is drawn for an editor, where a faint comment is a feature, and on
-this paper the stock greys, orange, yellow, green and teal read between 1.7:1
-and 3.5:1. Each was darkened along its own hue until it made 4.5:1 and no
-further; on the dark scheme only the `base0F` brown needed lifting. Every one
+scope takes which slot. None of the light colours is the stock one: a syntax
+theme is drawn for an editor, where a faint comment is a feature, and here code
+is text like any other and meets 7:1 on its block, the bar every run of text
+on the page meets. Each light colour was darkened along its own hue until it
+did and no further, and four of the dark ones (the comment grey, the red, the
+blue and the `base0F` brown) were lightened toward white the same way. Every one
 of them is in the contrast test beside the rest of the palette.
 
 | Token                             | base16   | What it colours                            |
@@ -871,7 +1017,11 @@ Every template gets:
 | `site`       | `content/_data/site.json`, if the site has one, over the defaults `title` and `url`. Any key in the file is readable, so `site.tagline`, `site.author` and anything else a site adds are all available. |
 | `menus`      | Every menu the site stores, by name, marked for this page: `menus.primary`, `menus.footer`, and any other name. See [Navigation](#navigation).                                                          |
 | `siteAuthor` | Who the page is by, as a profile. **Absent** when nobody matches. See [Bylines and author archives](#bylines-and-author-archives).                                                                      |
-| `icons`      | The site's icons, as `{ rel, sizes, href }`. Empty until the site has an avatar to derive them from. See [The head](#the-head).                                                                         |
+| `soloAuthor` | The site author's profile, on a site whose Solo author blog setting is on. **Absent** when it is off or the author setting names nobody. See [The bio](#the-bio).                                       |
+| `icons`      | The site's icons, as `{ rel, sizes, type, href }`. Empty until the site has an icon or an avatar to derive them from. See [The head](#the-head).                                                        |
+| `theme`      | The colours the theme declares, as `{ colorScheme, themeColor: { light, dark } }`, each absent when no theme declares it. See [The manifest](#the-manifest).                                            |
+| `shareImage` | The picture a shared link shows, as `{ url, alt, size: { width, height }, card }`. `size` is absent when it is not known. **Absent** when there is no picture. See [The head](#the-head).               |
+| `llmsTxt`    | The path of `/llms.txt`, while the site serves it. **Absent** when the site has turned it off. The default theme links it from the front page only.                                                     |
 
 A document — one post, one page, or one entry of a listing — adds:
 
@@ -891,6 +1041,7 @@ A document — one post, one page, or one entry of a listing — adds:
 | `page.inputPath`                            | The source file, relative to the content directory.                                                               |
 | `type`                                      | `post` or `page`.                                                                                                 |
 | `permalink`, `slug`, `draft`, `description` | Straight from the front matter.                                                                                   |
+| `lang`                                      | The `lang` front matter as a canonical tag, such as `fr-CA`. Absent when it names none or no tag.                 |
 | `author`                                    | Who wrote it, as a profile rather than a string. See [Bylines and author archives](#bylines-and-author-archives). |
 | `activityStreams`                           | The post's ActivityPub object id, absolute. Only on a rendered published post.                                    |
 | `previous`                                  | The published post before this one by date, as `{ title, url }`. Absent on the oldest post.                       |
@@ -921,7 +1072,10 @@ archive — adds:
 How many posts a listing page holds comes from `postsPerPage` in
 `content/_data/site.json`, and defaults to 10. How many entries a feed holds
 comes from `feedSize` in the same file, and defaults to 20. The `<html lang>`
-comes from `language`, and defaults to `en`. The rssCloud and WebSub server the
+comes from `language`, and defaults to `en`. A document whose `lang` names
+another language carries it on its own `<article>`, in an entry, a listing and
+search results alike, through `partials/lang.njk`, and the dates inside that
+article are written in it (see the `date` filter). The rssCloud and WebSub server the
 feeds advertise comes from `notifyServer`, and is empty for none; the theme
 writes nothing for it, because a cloud is advertised in the feed rather than on
 the page.
@@ -1169,6 +1323,15 @@ site that has turned them off advertises nothing. The CMS also sends the same
 endpoint as a `Link` header on every representation of a document, so a sender
 that does not parse HTML still finds it.
 
+On the front page it also writes the site's index for language models:
+
+```html
+<link rel="describedby" type="text/markdown" href="/llms.txt" />
+```
+
+It comes from `llmsTxt` on the context, which is absent once the site turns the
+file off. The CMS sends the same link as a `Link` header on the front page.
+
 `layouts/tag.njk` and `layouts/category.njk` override that block, call `super()`
 and add the archive's own three feeds:
 
@@ -1275,8 +1438,11 @@ The packaged partial draws each entry as the source design does: an
 `li.comment.h-entry` carrying `id="comment-{{ reply.id }}"` and a
 `comment-{{ reply.source }}` class, holding an `article.comment-body` whose
 `footer.comment-meta` is the author as a `.comment-author.vcard.p-author.h-card`
-and the permalink as a `.comment-metadata` link around a `time.dt-published`,
-then the words in `div.comment-content.e-content`. Answers nest in an
+(their avatar, or the first letter of their name in a `span.comment-avatar-empty`
+when there is none) and the permalink as a `.comment-metadata` link around a
+`time.dt-published`, with a `span.comment-source` saying "via webmention" or
+"via the fediverse" when it came that way, then the words in
+`div.comment-content.e-content`. Answers nest in an
 `ol.children` inside what they answer. A Reply link in a `div.reply` goes on the
 ones written here — `source == "comment"` — when the post is still open; it
 carries the comment's id to the form as `?reply_to=`, so threading needs no
@@ -1285,7 +1451,8 @@ webmention on the page that sent it, so neither gets one.
 
 Above the thread, `group()` draws one `div.reaction-group` per kind that has
 anything — `p-like`, `p-repost` and `p-mention`, the source theme's classes — as
-an `h2.reaction-title` of the label and the count beside a `div.facepile` of
+an `h2.reaction-title` of the label and the count, in a `span.reaction-count`,
+beside a `div.facepile` of
 `a.u-url` faces. A face is a round `u-photo` avatar; a reaction whose author the
 site knows no picture of is the emoji badge of its kind and a `.reaction-name`
 instead. Likes and boosts link to the person, and a mention to the page it came
@@ -1352,7 +1519,10 @@ The packaged partial is a `section#respond.comment-respond` with an
 `h2.comment-reply-title`, one paragraph per field and the button in a
 `p.form-submit` — the source design's names, so the stylesheet styles every
 label, field and button of both forms through `.comment-respond` and a site
-that has CSS for the WordPress theme can bring it.
+that has CSS for the WordPress theme can bring it. The name and email fields sit
+in a `div.field-row`, side by side on a wide screen, in both forms. On a site
+that takes webmentions a `p.comment-help` under the heading says a reader can
+reply from their own site instead.
 
 | Key                        | What it holds                                                                                                                                                             |
 | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1508,18 +1678,29 @@ the import above carries `with context`: a macro imported without it cannot see
 
 ## Filters
 
-| Filter               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `date(format, zone)` | Formats a `Date` or a date string. `readable` (the default) gives `2 September 2026`, `html` gives `2026-09-02` for a `<time datetime>`, `year` gives `2026`, `month` gives `September 2026`, `iso` gives the full ISO 8601 instant. A date in a file is a UTC instant; every format but `iso` is rendered in the site's `timezone` setting, and `iso` stays the instant. Pass `zone` — an IANA name — to override the setting for one call. A value that is not a date renders as the empty string. |
-| `url`                | Prefixes a root-relative path with the base URL's path, so a site served from a subdirectory links correctly. Eleventy's filter of the same name.                                                                                                                                                                                                                                                                                                                                                    |
-| `absoluteUrl`        | The same path as a fully qualified URL against the site's `baseUrl`.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `asset`              | The URL of a file in the theme's `static/` directory, with the base path in front and a hash of the file's bytes on the end: `{{ "style.css" \| asset }}` gives `/theme/style.css?v=3f2a9c01b7d4`. The file is found the way `/theme/` finds it, the chosen theme first. A hashed URL is served with `Cache-Control: public, max-age=31536000, immutable`, and editing the file changes the hash on the next render. A file no theme has gets its plain `/theme/` URL.                               |
+| Filter                       | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `date(format, zone, locale)` | Formats a `Date` or a date string. `long` gives `2 September 2026` on an `en` site and `2 septembre 2026` on an `fr` one; `full`, `medium` and `short` are Intl's other date styles, and `readable` (the default) is `long`. `month` gives `September 2026`, `year` gives `2026`, `html` gives `2026-09-02` for a `<time datetime>`, and `iso` gives the full ISO 8601 instant. Every format but `html` and `iso` is written in the site's locale: the `locale` setting, or the `language` when that is empty. Bare `en` writes the day first, as `en-GB` does; `en-US` gives `September 2, 2026`. A date in a file is a UTC instant; every format but `iso` is rendered in the site's `timezone` setting, and `iso` stays the instant. Pass `zone` — an IANA name — to override the setting for one call. Pass `locale` — a BCP 47 tag — to write the words in another language for one call; it comes after `zone`, so pass `none` for the zone to keep the site's: `{{ date \| date("readable", none, lang) }}`. An empty locale, or one that is no tag, writes in the site's. A value that is not a date renders as the empty string. |
+| `plural(forms, locale)`      | Picks the form for a count by its plural category in the site's locale, through `Intl.PluralRules`: `{{ n \| plural({ one: "# reply", other: "# replies" }) }}`. The keys are the CLDR categories (`zero`, `one`, `two`, `few`, `many`, `other`), a category the forms leave out falls back to `other`, and `#` is the count in the locale's digits. Pass `locale` when the strings are in a language of their own: the default theme's words are English, so it passes `"en"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `url`                        | Prefixes a root-relative path with the base URL's path, so a site served from a subdirectory links correctly. Eleventy's filter of the same name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `absoluteUrl`                | The same path as a fully qualified URL against the site's `baseUrl`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `asset`                      | The URL of a file in the theme's `static/` directory, with the base path in front and a hash of the file's bytes on the end: `{{ "style.css" \| asset }}` gives `/theme/style.css?v=3f2a9c01b7d4`. The file is found the way `/theme/` finds it, the chosen theme first. A hashed URL is served with `Cache-Control: public, max-age=31536000, immutable`, and editing the file changes the hash on the next render. A file no theme has gets its plain `/theme/` URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 
 `date` reads one word rather than parsing it: `{{ "now" | date("year") }}` is
 the year at the moment the page is rendered, in the site's own timezone. It is
 what the footer's copyright line is written with, and it is the one date a page
 has that no file carries.
 
+The default theme passes the document's `lang` as that locale for every date
+inside its `<article>`: the Published and Updated lines, the hidden heading of
+a note, the kicker in a listing or a search result (`kicker.line(…,
+lang=post.lang)`), and the date of the post a reply answers. So a post that
+says `lang: fr` on an `en` site reads `Published 2 septembre 2026`, while the
+navigation, the conversation under it, the archive's month headings and the
+footer stay in the site's locale. A theme that wants the same passes `lang`
+on an entry and `post.lang` in a listing; one that passes nothing writes every
+date in the site's locale, as before.
+
 Nunjucks' own filters — `default`, `join`, `urlencode`, `safe` and the rest —
 are all available. Autoescaping is on, so rendered Markdown is the one thing
 that has to be passed through `safe`.