The system.

Every decision behind flavioclesio.com, with the reasoning that produced it. This page is the source of truth — if the site disagrees with this document, the site is wrong.

§1 Identity

§2 Typography

2.1 — Type families

2.2 — Per-layout scale

2.3 — Code type

§3 Color

3.1 — Light tokens

3.2 — Dark tokens

3.3 — Rejected

§4 Layout

Vertical rhythm derived from font-size. Paragraphs at 1.2em apart. Section heads at 1.5em above / 0.6em below. Line length is the design constant — column widths derived from it (62–68ch target).

§5 Page system

Three writing layouts + the home + podcast. Selected via Jekyll front-matter, never via URL routing.

§6 Components

6.1 — Dateline

6.2 — Footnotes

Kramdown native [^1] syntax. Numbered at bottom; superscript call-out in teal (post/technical) or amber (essay/home).

6.3 — Pull quote · Epigraph

Bar variant: italic 20–26px serif, 2px left border in layout accent color. Epigraph: centered, 18px italic; cite block in mono caps with —.

6.4 — Callouts

Label rendered automatically from class via ::before content.

6.5 — Code blocks

Default: light #f5f5f5, no chrome. Dark: opt-in via Kramdown attribute on the fenced block ({: data-chrome="dark" data-file="path"}).

6.6 — Drop cap

Essay-only. CSS via .essay-body > p:first-child::first-letter. Combine with <span class="smallcaps"> on the first 3 words.

6.7 — Asterism

Markdown * * * → <hr>. In essay, restyled to ∗ ∗ ∗ centered, #c8b896, letter-spacing 0.6em.

6.8 — Podcast player

A single horizontal strip between two thin warm-gray rules. No skip ±15/30, no volume, no share — the URL ?t=N param is the share contract. Composed of: 52px black play/pause circle · 3px progress bar with amber chapter ticks · mono elapsed/total · single speed pill (popover for 0.75/1/1.25/1.5/2).

6.9 — Chapters

Each row: stacked mm:ss (mono caps) · title (italic Newsreader) · [tag] (mono small). Active row: ▶ prefix on time + title in amber. Whole row is clickable, jumps to timestamp.

6.10 — Show notes

Simple list with em-dash — marker. Each entry is a hyperlink.

§7 Navigation & footer

§8 Markdown extensions

Kramdown native, no plugins. Authors mark up posts as normal markdown plus the following recognized class hooks:

{: .callout .note}     → NOTE callout
{: .callout .warning}  → WARNING callout
{: .callout .tip}      → TIP callout
{: .callout .tldr}     → TL;DR (use once, above first H2)

{: .pullquote}         → pull-quote bar variant
{: .epigraph}          → pull-quote epigraph variant

[^1]                   → footnote reference (numbered automatically)
[^1]: footnote text    → footnote definition (placed at end of file)

* * *                  → asterism (renders as ∗ ∗ ∗ in essay layout, hr elsewhere)

<span class="smallcaps">My friend Paulo</span>  → small caps run

Usage example (callout — note the blank line above the attribute block):

> The `scope["type"] != "http"` guard lets this coexist with WebSocket traffic.
{: .callout .note}

§9 Dark mode

Single ◐ button, fixed top-right of every page. Toggles body.dark; persisted in localStorage under key theme. No JS heuristics, no prefers-color-scheme auto-switching — the reader chose for a reason.

§10 Front-matter contract

Every Jekyll source file declares its layout and language. Layout-specific fields are read only by their layout — extra fields never break a build.

# Universal
layout:         post | essay | technical | episode    # required
title:          string                                # required
date:           ISO-8601                              # required
lang:           pt-br | en-us                         # required
permalink:      /:title                               # required
excerpt:        string (<= 200 chars)                 # optional

# Technical-only
series:         slug                                  # links sibling posts
series_index:   integer                               # 1-indexed
series_total:   integer
last_reviewed:  ISO-8601                              # footer "last reviewed"
tags:           [string, ...]

# Episode-only
duration:       hh:mm:ss
audio.mp3.url:  /assets/podcast/epNNN.mp3
audio.mp3.size_mb: number
chapters:       [ { start: mm:ss, title: string, tag: string } ]
shownotes:      [ { url, title } ]
guests:         [ { name, url, role } ]

# Essay-only
location:       string  # defaults to "Lisbon"