Title Page

The Style Codex — Theme Reference & Template

Each chapter isolates one family of devices and shows both the rendered result and the source that produced it. The theme itself is verified by make styles-golden, which diffs the rendered DOM and the stylesheet against the goldens in styles/golden/.

The Class Index

Every opt-in class of the theme, authored as raw HTML inside Markdown — a plain Markdown file stays plain. This table is the contract: make styles-golden fails if a class listed here is missing from styles/css/fancy.css or is never rendered by any chapter.

Devices that need no class at all: drop caps (automatic on the first paragraph after a chapter title), fleuron rules (---), blockquotes, footnotes, <kbd> keys, <figure>/<figcaption>, tables, code blocks, and Mermaid diagrams.

Copy This to Start

Paste this into a fresh chapter and delete what you do not need:

# Chapter Title

The first paragraph gets an automatic drop cap.

<span class="kicker">a small-caps label</span>

<p class="lead">A larger italic opening paragraph.</p>

<div class="callout warn">

**Warning** — Blank lines around the body are required.

</div>

<div class="aside-note">
<span class="kicker">in the margin</span>
A note floated into the right margin.
</div>

| Column | Column |
|---|---|
| cell | cell |

<figure>
<svg viewBox="0 0 200 80" width="200" role="img" aria-label="Plate"></svg>
<figcaption>Caption set in italics.</figcaption>
</figure>

<p class="finis">❦ ❦ ❦</p>

For a whole book rather than a chapter, copy the skeleton instead:

cp -r styles/template/ newbook/
mdbook build newbook

Verifying the Theme

make styles-golden          # diff rendered DOM + stylesheet against goldens
make styles-golden-update   # regenerate goldens — deliberately, never to go green

make preflight runs the check. See the golden-change playbook in the main book for the update discipline; eyeballing the codex in the light and coal themes is a supplement to the golden check, not a substitute for it.

The Chapters

• Typography & Drop Caps — headings, drop caps, pull quotes, footnotes, ornaments.
• Ornaments & Layout — epigraphs, highlights, tags, timelines, two-column prose.
• Callouts & Asides — note, tip, warning, and danger plates; margin asides.
• Tables & Data — framed, striped tables; the compact ledger.
• Figures & Diagrams — captions, inline SVG, figure grids, and Mermaid plates.
• Code & Terminals — code blocks and keyboard keys inside serif prose.

Typography & Drop Caps

Typography is the first thing a reader feels and the last thing they notice. This chapter opens with a drop cap, flows through small-caps subheadings, and closes with an ornamental rule. Every specimen below is followed by the source that produced it.

the elements of the page

<span class="kicker">the elements of the page</span>

Headings in Small Caps

Second-level headings render in gilded small caps. Third-level headings lean into italics:

A Third-Level Heading, Reclining

Body text uses a classic serif stack — Iowan Old Style, Palatino, Charter, Georgia — with generous 1.75 line height and hyphenation enabled. The stack, size, and leading are spec-driven: they live in spec/config.yaml under books.styles, not in the theme CSS.

The drop cap is automatic on the first paragraph after a chapter title — no class needed:

# Chapter Title

The first paragraph gets the drop cap.

Emphasis & Inline Styles

Prose supports italics for voice, bold for weight, and code for machinery. Keyboard chords render as keys: press Ctrl + Shift + P to summon the palette.

*italics for voice*, **bold for weight**, `code for machinery`,
and <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> for chords.

The Lead Paragraph

A lead paragraph states the promise of the chapter in larger italics. Use one, directly under the title.

<p class="lead">A lead paragraph states the promise of the chapter.</p>

Pull Quotes

Spec just enough. Verify first. Iterate. Succeed.

A pull quote interrupts the column with the book’s accent color, framed by hairlines above and below.

<p class="pullquote">Spec just enough. Verify first. Iterate. Succeed.</p>

Blockquotes

A blockquote carries a hanging quotation mark in the margin and a soft golden wash behind it. Use it for quoted voices, not for warnings — warnings get callout plates.

> A blockquote carries a hanging quotation mark in the margin.

Footnotes

Footnotes step politely out of the text¹ and gather beneath a golden hairline at the foot of the page². The reference is a gold superscript; the definition is set smaller, with tighter leading.

Footnotes step politely out of the text[^marker].

[^marker]: The definition, written at the very end of the chapter file.

The ornament above is a fleuron (❦), rendered by CSS on every horizontal rule. It marks a scene change within a chapter, and is authored as a plain ---.

1. Like this. Clicking the number jumps down; the label links back up. ↩

2. mdBook renders definitions where they are written, so keep them at the very end of the chapter file. ↩

Ornaments & Layout

<div class="epigraph">
The quotation, set in italics above the chapter.
<span class="attribution">Who said it</span>
</div>

Every device in this chapter is opt-in: a plain Markdown file stays plain, and a decorated page declares its intent in raw HTML. This opening paragraph summons a drop cap with class="initial" — the automatic drop cap only follows a chapter title, so use this one mid-book.

<p class="initial">A manual drop cap, for paragraphs that do not follow a title.</p>

Highlights & Tags

Use a gilded highlight when the reader must not skim past a phrase — sparingly, or the gold turns to noise. Tags mark status inline without breaking the sentence: this chapter is codex, its theme is verified, the print run is scheduled, and nothing here is blocked.

<mark>a gilded highlight</mark>

<span class="tag">codex</span>
<span class="tag green">verified</span>
<span class="tag blue">scheduled</span>
<span class="tag red">blocked</span>

A Timeline

A timeline sets a chronology on a golden spine, with a bold lead-in per entry:

• 2022 — the first book is bound: plain styles, plain pages, offline from day one.
• 2024 — the slide compiler is written in Go; decks join the library.
• 2026 — the Style Codex opens, and the spec system takes over fonts and colors.

<ul class="timeline">
<li><strong>2022</strong> — what happened that year.</li>
<li><strong>2024</strong> — and then this.</li>
</ul>

Two Columns

<div class="twocol">

First paragraph. Blank lines keep the Markdown inside working.

Second paragraph.

</div>

The End of a Chapter

A chapter that has said everything should say so. The finis mark below closes the chapter the way a colophon closes a book — reserve it for true endings, not section breaks (those get the fleuron rule).

❦ ❦ ❦

<p class="finis">❦ ❦ ❦</p>

Callouts & Asides

Callouts are the marginalia of this codex: small plates that interrupt the prose to note, advise, warn, or forbid. They are opt-in HTML blocks so plain Markdown stays plain.

The Four Plates

Margin Asides

An aside (<div class="aside-note">) is for commentary that enriches but never interrupts: an etymology, a cross-reference, a wry remark. The main argument must survive with the margin torn off. This paragraph flows around the note the way body text shares a page with marginalia in a medieval manuscript — and in print, the float is preserved.

<div class="aside-note">
<span class="kicker">in the margin</span>
The note itself, one or two sentences.
</div>

Authoring Syntax

Callouts are authored as raw HTML with blank lines around the Markdown body, so mdBook still renders the inner content. The second class picks the plate: note, tip, warn, or danger.

<div class="callout warn">

**Warning** — Snap-confined Chromium cannot print to `/tmp`.

</div>

Tables & Data

Tables in the codex are framed plates: a golden border, small-caps headers, and alternating row washes. They should read like a ledger, not a spreadsheet. Plain Markdown tables need no class at all.

A Ledger of Books

| Book | Directory | Purpose |
|---|---|---|
| Agentic Software Development | `src/` | The main playbook |

A Ledger of Tools

The Compact Ledger

Wrap a table in <div class="compact"> for dense reference data — smaller type, tighter cells. The class index on the front page is set this way:

<div class="compact">

| Device | Class | Verified by |
|---|---|---|
| callout plate | `.callout` | DOM census |

</div>

Figures & Diagrams

Figures are centered plates with italic, em-dash captions. The codex supports two kinds: inline SVG (offline, hand-authored) and Mermaid diagrams rendered by the local mermaid.min.js asset.

An Inline SVG Plate

<figure>
<svg viewBox="0 0 420 120" width="420" role="img" aria-label="Verification funnel">
  <!-- hand-authored, offline, diffable -->
</svg>
<figcaption>The caption, set in italics after an em dash.</figcaption>
</figure>

Plates Side by Side

Wrap figures in <div class="figrid"> to set them as a grid; on narrow pages the plates stack:

<div class="figrid">
<figure>…</figure>
<figure>…</figure>
</div>

A Mermaid Plate

graph LR
    A[Markdown Sources] --> B[mdBook]
    A --> C[Slide Compiler]
    B --> D[Static Website]
    C --> D
    D --> E[PDF via Chromium]

A Mermaid diagram is an ordinary fenced block with the mermaid language tag:

```mermaid
graph LR
    A[Markdown Sources] --> B[mdBook]
    B --> D[Static Website]
```

Code & Terminals

Code is the one place where the codex abandons its serifs. Blocks keep mdBook’s monospace machinery and syntax highlighting; the surrounding prose stays bookish, which makes the contrast deliberate and pleasant. No class is needed anywhere in this chapter — fenced blocks are plain Markdown.

A Go Block

// canary probes the environment before any feature work begins.
func canary() error {
    for _, tool := range []string{"mdbook", "chromium", "go"} {
        if _, err := exec.LookPath(tool); err != nil {
            return fmt.Errorf("missing tool %q: %w", tool, err)
        }
    }
    return nil
}

```go
func canary() error {
    return nil
}
```

A Bash Block

set -euo pipefail

make canary     # prove the environment
make preflight  # prove the code
make build      # only now, build the site

```bash
make canary     # prove the environment
```

Inline Machinery

Inline code like make preflight sits inside serif prose without breaking the line rhythm. Keyboard keys such as q and Ctrl+C get raised keycaps.

Inline code like `make preflight`, and keys such as
<kbd>q</kbd> and <kbd>Ctrl</kbd>+<kbd>C</kbd>.

Nesting a Fence Inside a Fence

To show a fenced block as source — as this chapter does throughout — wrap it in a longer fence:

````markdown
```bash
make preflight
```
````