/* ==========================================================================
documentation-kit.css
Ready material for didactic pages - teaching pages, one-pagers, explainers
read calmly by partners and teams. Hand-written on house-token variables.
NO framework, NO dependency, NO @import. One file, paste and go.
Source: documentation-design.md (9 - System/ui-ux/), captured 2026-07-19.
Under the same two lenses as the rest of the ui-ux folder:
- Teletubbies: the page speaks to the eye before it is read.
- Kennedy: one job, hierarchy by de-emphasis, grayscale first, colour last.
LIGHT THEME ONLY - Frank's house rule. No dark mode, no
prefers-color-scheme, anywhere in this file. Do not add one.
HOW TO USE
1. in .
2. Keep §0 ROOT TOKENS and §1 RESET - every block below depends on them.
3. Delete whole numbered blocks in §4 BLOCKS you don't need on this page.
Each block is self-contained; none depend on each other.
4. Swap --accent (and, if the page needs its own identity, the callout
tint backgrounds) to the PROJECT's own palette hex. Never a CSS named
colour. Keep it to one accent - that is the whole point of §0.
5. Grayscale review before shipping: add class "review-grayscale" to
for a moment (see §5). Anything that goes flat and unreadable
was leaning on colour to do a job that size/weight/space should do.
========================================================================== */
/* ==========================================================================
§0 · ROOT TOKENS - the only place colour, type and space are named.
Everything else in this file references these with var(). That is what
makes "one accent colour" or "double the whitespace" a two-line edit.
========================================================================== */
:root {
/* --- colour: one ink, one soft ink, one paper, one line, one accent --- */
--ink: #1a1a1a; /* body text */
--ink-soft: #666666; /* meta, captions, de-emphasised text */
--paper: #fdfdfb; /* page background */
--surface: #ffffff; /* raised block background (segment, code figure) */
--line: #e4e4e0; /* hairline borders, dividers, table rules */
--accent: #b3261e; /* the ONE scarce colour: links, current state, emphasis */
/* --- semantic tints for callouts only - 3 meanings max, never a rainbow --- */
--info-ink: #2b6cb0; --info-bg: #eef4fb;
--warning-ink: #b7791f; --warning-bg: #fbf3e6;
--success-ink: #2f855a; --success-bg: #eaf7ef;
/* --- three fonts, three jobs - set once, referenced everywhere --- */
--font-body: Georgia, 'Iowan Old Style', 'Palatino Linotype', serif; /* prose */
--font-ui: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif; /* labels, nav, controls */
--font-mono: 'SF Mono', 'Menlo', 'Consolas', monospace; /* code, IDs, literal values */
/* --- type scale: house modular scale, 1.25 ratio, 5 steps + extension --- */
--scale-0: 0.8rem; /* meta, captions, labels */
--scale-1: 1rem; /* UI base, dense reference base */
--scale-2: 1.25rem; /* lead paragraph, h4 */
--scale-3: 1.563rem; /* h3 / h2 in a short page */
--scale-4: 2.441rem; /* h1 / page title */
--scale-5: 3.052rem; /* extension - hero figures, the one big statistic */
/* --- the two reading regimes named in the digest, as their own tokens --- */
--text-prose: 1.125rem; /* 18px */
--leading-prose: 1.6;
--text-dense: 0.9375rem; /* 15px */
--leading-dense: 1.4;
/* --- other line-heights and small rhythm constants, all tokenised so
nothing in §1-§4 below is a bare number --- */
--leading-ui: 1.5; /* body / UI default */
--leading-heading: 1.25; /* h1-h4 */
--leading-tight: 1; /* one-line figures: statistic value */
--rhythm-inline: 0.9em; /* inline code, slightly under body size */
--rhythm-para: 1.6em; /* paragraph / list bottom margin, prose */
--rhythm-indent: 1.4em; /* list indent, prose */
--label-pad-y: 0.2em;
--label-pad-x: 0.6em;
/* --- space by duplication: .25 / .5 / 1 / 2 / 4rem - group gaps double element gaps --- */
--space-1: 0.25rem;
--space-2: 0.5rem;
--space-3: 1rem;
--space-4: 2rem;
--space-5: 4rem;
/* --- measures --- */
--measure-container: 1120px; /* page width cap */
--measure-prose: 68ch; /* reading column cap, 66-72ch */
/* --- shared geometry --- */
--radius: 4px;
--shadow-raised: 0 2px 6px rgba(0, 0, 0, .08);
}
/* ==========================================================================
§1 · RESET & BASE - minimal, not a full reset. Do not delete: everything
below assumes box-sizing, paper background and the UI font are already set.
========================================================================== */
*, *::before, *::after { box-sizing: border-box; }
body {
background: var(--paper);
color: var(--ink);
font-family: var(--font-ui);
font-size: var(--scale-1);
line-height: var(--leading-ui);
margin: 0;
}
h1, h2, h3, h4 {
font-family: var(--font-body);
font-weight: 700;
color: var(--ink);
line-height: var(--leading-heading);
margin: 0 0 var(--space-3) 0;
}
h1 { font-size: var(--scale-4); }
h2 { font-size: var(--scale-3); }
h3 { font-size: var(--scale-2); }
h4 { font-size: var(--scale-1); font-family: var(--font-ui); font-weight: 700; }
a { color: var(--accent); }
code, kbd, samp {
font-family: var(--font-mono);
font-size: var(--rhythm-inline);
}
/* ==========================================================================
§2 · READING - how prose itself reads well (digest A.1–A.4)
Two body regimes that must never mix in one block: .prose for a teaching
paragraph, .dense for tables/specs/definitions.
========================================================================== */
/* A.1 - reading measure: cap at 66-72ch, never full viewport width */
.prose {
max-width: var(--measure-prose);
margin-inline: auto;
}
/* A.2 - prose regime: comfortable reading size and line height */
.prose {
font-family: var(--font-body);
font-size: var(--text-prose);
line-height: var(--leading-prose);
color: var(--ink);
}
/* A.2 - dense regime: reference material, tighter and smaller */
.dense {
font-family: var(--font-ui);
font-size: var(--text-dense);
line-height: var(--leading-dense);
color: var(--ink);
}
/* A.3 - generous paragraph rhythm: silence between ideas reads as organised */
.prose p { margin: 0 0 var(--rhythm-para) 0; }
.prose h2 { margin-top: var(--space-5); }
.prose h3 { margin-top: var(--space-4); }
.prose ul, .prose ol { margin: 0 0 var(--rhythm-para) 0; padding-left: var(--rhythm-indent); }
.prose li { margin-bottom: var(--space-2); }
.prose li:last-child { margin-bottom: 0; }
/* ==========================================================================
§3 · ORIENTATION - never let a long page lose the reader (digest B.5–B.8)
========================================================================== */
/* B.8 - container: cap the page width. Padding shrinks one step on mobile
so text doesn't sit flush against the edge of a phone screen. */
.container {
max-width: var(--measure-container);
margin: 0 auto;
padding: 0 var(--space-4);
}
@media (max-width: 600px) {
.container { padding: 0 var(--space-3); }
}
/* B.8 - text column: cap the prose column tighter, inside the container */
.text-column {
max-width: var(--measure-prose);
margin: 0 auto;
}
/* B.7 - sticky page header: one slim line, no logo clutter */
.page-header {
position: sticky;
top: 0;
z-index: 10;
background: var(--paper);
border-bottom: 1px solid var(--line);
padding: var(--space-2) 0;
}
.page-header .container {
display: flex;
align-items: baseline;
justify-content: space-between;
gap: var(--space-3);
}
.page-header .title {
font-family: var(--font-ui);
font-size: var(--scale-1);
font-weight: 700;
color: var(--ink);
}
.page-header .meta {
font-family: var(--font-ui);
font-size: var(--scale-0);
color: var(--ink-soft);
}
/* B.5 - on-this-page rail: sticky beside the content, collapses on narrow
screens. Markup once as , no JS:
On this page
The summary is hidden at desktop width (rail is always open, no toggle
needed); it reappears as a real toggle once the layout goes narrow. */
.on-this-page {
position: sticky;
top: var(--space-5);
align-self: start;
font-family: var(--font-ui);
font-size: var(--scale-0);
border: none;
}
.on-this-page > summary {
display: none;
}
.on-this-page .rail-label {
font-weight: 700;
color: var(--ink-soft);
text-transform: uppercase;
letter-spacing: .06em;
margin-bottom: var(--space-2);
}
.on-this-page nav { display: flex; flex-direction: column; }
.on-this-page a {
display: block;
padding: var(--space-1) 0;
color: var(--ink-soft);
text-decoration: none;
border-left: 2px solid transparent;
padding-left: var(--space-2);
}
.on-this-page a:hover,
.on-this-page a.current {
color: var(--accent);
border-left-color: var(--accent);
}
@media (max-width: 800px) {
.on-this-page {
position: static;
border: 1px solid var(--line);
border-radius: var(--radius);
padding: var(--space-3);
margin-bottom: var(--space-4);
}
.on-this-page > summary {
display: block;
cursor: pointer;
font-weight: 700;
color: var(--ink);
}
.on-this-page nav { margin-top: var(--space-2); }
}
/* B.6 - anchor links on headings, revealed on hover. Markup: