Style Guide

Every text element on the site, in one place, for tuning sizes and spacing

ux · 18 Jul 2026

This is the reasoning behind how the site was built, not just the result. Nothing here was abstract. Every element, every naming convention, was considered and argued with before it landed.

Every heading level, blockquote, list, and shortcode the site currently knows how to render, shown together — both a visual reference for tuning sizing and spacing, and a usage guide for the shortcodes themselves, parameters included. Still a working draft, not finished prose.

Since July this guide has grown from a reference into the site’s law. What the later passes added, and where it is written down here:

  • The reading toggles (dark/sepia, easy-read) — why they exist, the dyslexia reasoning, and what each one changes and never changes: see “The reading toggles — dark/sepia and easy-read, and why” below.
  • Noto Serif on all surfaces — the default reading face everywhere; the only swap is the easy-read toggle’s Atkinson Hyperlegible, and it swaps only the body reading face, never the sans furniture, never the palette.
  • Line-height matched to the typeface’s own metrics — Atkinson Hyperlegible renders at the specimen’s own 1.5; the accessibility work lives in letter spacing, word spacing, and open letter shapes, not inflated line gaps.
  • Paired spacing rhythm — elements that belong together read as one unit: the section marker and its hint (2px), the band header and its stations (4px), each station title and its dek (tightened to the same rhythm). When a title floats free of what it labels, the fix is measured, not guessed: the numbers come from live DOM measurement at phone width.
  • Owned fonts — three families, self-hosted woff2, zero third-party requests (the tiny Material icon is the sole exception): Noto Serif for reading, Montserrat for furniture, Atkinson Hyperlegible for the easy-read toggle. Lexend was retired 2026 Oct 17.
  • Footnotes are the citation apparatus — native kramdown [^n] syntax everywhere, including essays: numbered references stay visible at the bottom as part of the argument, multi-source footnotes chain with ` · `, parenthesized URLs get angle-bracket wrapping. The Vision, Not the Theatrics carries 18 in live use.
  • Measured, not estimated — every spacing decision on this list came from reading the rendered DOM at phone width, not from arithmetic on stylesheet values. Green builds certify nothing; the rendered page is the verdict.

Heading levels

H1 — used for post titles (.post__title) and section labels (.section-label)

H2 — used for post-card titles in feeds (.post-card__title)

Note Both are in active use — they just aren't sized for heavy visual weight, so the hierarchy reads structurally (accessibility, SEO) rather than as an obvious size jump on the page.

H3 — not currently used anywhere on the site, default browser size

H4 — not currently used anywhere on the site, default browser size

H5 — not currently used anywhere on the site, default browser size
H6 — not currently used anywhere on the site, default browser size

Subtitle

This is what .post__subtitle / .post-card__subtitle looks like — italic, sits directly under a title, used for the “Lie 40.” style epigraph line.

Meta line

the-floor · 18 Jul 2026

This is .post__meta — small caps-adjacent sans, low opacity, sits under the subtitle on an actual post page.

Body paragraph

This is a standard paragraph inside .post__body — the reading type, Noto Serif, the size and line-height every scene and essay actually reads at. A second sentence here so line-wrapping and paragraph-to-paragraph spacing can be seen, not just a single line in isolation. A third sentence, longer than the others, specifically so a paragraph wraps across three or four lines at typical phone width, the way real prose actually does.

A second paragraph, to show the gap between paragraphs (margin-bottom: var(--space-3) currently) — is it too tight, too loose, once real prose sits here instead of a placeholder line.

Diamond divider

The scene-break used throughout Black Cat pieces:

No parameters.

{% include divider.html %}

Pull-quote

This is the pull-quote shortcode — accent-coloured left border, italic, breaks out of the paragraph flow for a line worth setting apart.

Optional attribution line

A visually distinct pulled quote, for a striking line worth setting apart — not for the subtitle/epigraph, that’s the post’s own front matter. text required, attribution optional.

{% include pull-quote.html text="The line you want pulled out." attribution="Optional source" %}

Plain markdown blockquote

This is a plain > blockquote — bootcamp convention: accent left border, tinted background, small radius. Decided 2026-07-18: distinct from the pull-quote shortcode, which is for a striking line pulled out of prose. A blockquote is for actually quoting something.

Callout

Note

This is the callout shortcode — full tinted background, bordered box, rounded corners, optional label. Distinct from a blockquote: a callout is an aside from the writer, not a quotation of someone else.

A bordered, tinted box for an editorial aside — distinct from a blockquote (quotes someone else) and a pull-quote (pulls out the writer’s own line). text required, label optional.

{% include callout.html label="Note" text="The aside you want to highlight." %}

Code block

Syntax highlighting via Rouge (kramdown’s built-in highlighter, already active — no extra config needed), coloured to match the site’s warm palette rather than the cool blues most syntax themes default to:

.example {
  color: var(--color-accent);
  background: #1a1814;
}

Lists

Note Currently unstyled — browser defaults, not yet designed.

  • An unordered list item
  • A second unordered list item
  • A third, slightly longer unordered list item, to see how a wrapped line looks against the bullet indent
  1. An ordered list item
  2. A second ordered list item
  3. A third ordered list item

A link inside a sentence uses the accent colour, same as everywhere else on the site. Here is some bold text and some italic text inline, to see how emphasis reads against the body serif.

Footnotes

Native Kramdown syntax, no shortcode needed — a superscript reference1 in the accent colour, linking down to a small reference list at the very bottom of the post, each one with its own return arrow back up to where it was cited2.

Note The actual footnote text doesn't appear here — Kramdown always collects every footnote on the page into one list at the very bottom of the post, regardless of where in the source they're defined. Scroll to the end to see these two.

A superscript reference[^1] in the body text.

[^1]: The footnote text, placed anywhere in the document — usually at the end.
[^2]: A second footnote, same syntax, numbers itself automatically.

Image with caption — polaroid (default)

Yogi, a small apricot poodle, lying on a bed looking at the camera
Yogi

Not full-width — deliberately narrower than the text column (65%) and tilted, so it reads as a small physical photo rather than a hero image. Off-white frame, heavier border on the bottom than the sides or top, caption sits inside that bottom margin in a marker font. src and alt required, caption optional.

{% include image.html src="/assets/images/photo.jpg" alt="description" caption="Optional caption or credit" %}

Image with caption — full width

Yogi, a small apricot poodle, lying on a bed looking at the camera
Yogi, full width

No frame, no tilt, fills the text column — for when the image should carry full visual weight rather than sit as an incidental object. Same parameters, plus full=true.

{% include image.html src="/assets/images/photo.jpg" alt="description" caption="Optional caption or credit" full=true %}

YouTube embed

Responsive 16:9 embed, scales to the text column width. Not rendered live here to avoid pulling in an external video inside a style reference. id required — the video ID from the URL (the part after v=, or from Share → Embed).

{% include youtube.html id="VIDEO_ID" %}

Dev note

Note This is a dev note — muted aside for a working doc like this one, visually distinct from real body content. Not a shortcode, just raw HTML with a class.

<p class="dev-note"><span class="dev-note__label">Note</span> The note text goes here.</p>

The reading toggles — dark/sepia and easy-read, and why (Claire, 2026 Oct 17)

Two independent toggles, fixed bottom-right on every page. They exist for a reason worth writing down, because the reason is the site’s own argument.

Noto Serif stays on all surfaces. The default reading face for the whole site is Noto Serif. The only exception is the easy-read toggle, for readers who need it.

I am dyslexic. Words jump and rearrange. Growing up in the 80s and 90s there was no such thing as being dyslexic. I was not seen to — my mother thought I was lazy, but I had to use a finger to guide myself through reading. I realised space — negative space — was an aid. When mobile phones, the internet and scrolling pages arrived, I found I could use my finger or the mouse to scroll up, and my eyes somehow had an anchor. Other colleagues and friends found that annoying and asked me why I did that. But I could read better.

So the site is built the way I read: dark ground first (a dark room rests eyes that had to fight paper), generous negative space (the anchor), short reading lines, open letter shapes. And the two toggles:

  • Sepia light — for eyes that read better on paper tones. Swaps the whole palette: sepia ground, dark brown ink, burnt orange accent. Noto Serif stays.
  • Easy read — swaps the reading serif to Atkinson Hyperlegible (Braille Institute, open letter shapes, every letter drawn to be told apart). Swaps ONLY the body reading face; the sans furniture keeps Montserrat; the palette never changes. State remembered between visits, one localStorage key per toggle.

Legibility beats serif tradition — that trade was made deliberately, for the reader who is me and the readers who are like me.

This card, in the feed

This post is filed under UX at /ux/style-guide/ — not linked in nav yet, since UX isn’t built as a real section. Findable directly by URL.

  1. The footnote text can go anywhere in the source file — Kramdown collects them and renders the list at the bottom regardless of where they’re written. Numbering follows citation order. This is the site’s citation apparatus: essays keep numbered references visible at the bottom as part of the argument (see The Vision, Not the Theatrics for 18 in live use). Multiple sources on one footnote: chain them with ` · ` between links. A URL containing parentheses (Lancet/ICRC-style paths) must be wrapped in angle brackets inside the link or it truncates: [source](<https://...(...)...>). ↩

  2. Numbering is automatic and follows citation order, not the order the footnotes are written in. ↩