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.

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. 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"