Style Guide
Every text element on the site, in one place, for tuning sizes and spacing
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.
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
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
- An ordered list item
- A second ordered list item
- A third ordered list item
Links and inline emphasis
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)
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
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>
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.