# Chapbook v1.0.0 A small CSS system for documents that want to read like documents. **Monospace carries structure, a second face carries language, and separation comes from rules and space rather than from cards.** MIT. Take it, change it, no credit needed. - Stylesheet: - Skins: - Theme bootstrap: - Specimen: - Source: This file is the complete specification. If you are an agent building a page in this system, you need nothing else. --- ## What this is not It is not a framework, and it is not a component library. It has no build step, no JavaScript requirement, no utility classes, and no reset beyond `box-sizing`. It styles a **named set of components** and leaves the rest of the document alone, deliberately, so it can be dropped into an existing page without a fight. It will not style your headings, paragraphs or links for you beyond the primitives listed here. That is on purpose. If you want a heading styled, put one of these classes on it. --- ## The nine rules These are the system. The CSS is only their implementation. Each was already being followed by two independently built sites before it was written down — a rule that has survived one build is a preference. ### Rule 01 — Two faces, and the mono is the constant One monospace sets every label, number, address, breadcrumb, button and footer line — anything that tells you *what kind of thing* you are looking at rather than *saying something*. A second face carries the language, and it is the site's own. **The test that decides every case:** if a piece of text tells you what kind of thing you are looking at, it is mono, uppercase and tracked. If it says something, it is the language face. `--mono` is shared across sites built on this system. `--language` is not. ### Rule 02 — No cards No radius, no fill, no shadow to say "separate object". Objects are separated by a hairline and by space. The only fill in the system is the row hover at about 1.07:1 — felt rather than seen. If you can identify its colour, it is too strong. The single exception is `.code`, which earns its border by genuinely being a different surface rather than a card drawn around ordinary content. **Never write:** `border-radius`, `box-shadow`, or a background fill on a container. ### Rule 03 — Two weights of rule, and they mean different things - **1px `var(--rule)`** separates peers. - **2px `var(--ink)`** opens and closes the document: under the masthead, above the first block, above the footer. Those three ink lines are what hold a page together at a glance. Do not add a third weight — the moment there are three, none of them mean anything. ### Rule 04 — The numbered rail A sticky left column carrying a number and a mono section name, content on the right. It stays beside its content for as long as that content is on screen, and collapses to a line above the content below 52rem. `align-self: start` is **required**. A grid item stretches to the row height by default, and a stretched item has nothing to stick within. Remove that one line and the rail silently stops moving, with no error anywhere. Omit the number on a single-section page. A section number is a promise that another one follows. ### Rule 05 — One row anatomy, everywhere Mono label left, title in the display face, mark right, then an optional description and a mono line carrying the destination. The whole row is the link; the mark is decorative and must carry `aria-hidden="true"`. On hover the hairline redraws in ink from the left and the mark nudges up and right. Use `↗` for a destination that leaves the site and `→` for one that does not, so the mark keeps meaning something. ### Rule 06 — Tokens declared three times ```css :root { /* light palette, and the fallback */ } @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { /* guarded, so an explicit choice wins */ } } :root[data-theme="dark"] { /* the toggle, so it wins in both directions */ } ``` **Never style a component from inside one of those blocks.** Redefine tokens only. A component rule written there exists in one theme and not the other, and you will not notice for weeks. The two dark blocks must declare identical values. Nothing in CSS enforces that; `build.js` in the source repo checks it. ### Rule 07 — Contrast is measured, and the measurement is written down Every text token carries its ratio, measured against the **worst-case surface** rather than the flat background. The grain overlay sits between the text and the page and moves the surface toward the text in *both* themes, so a ratio taken against `--paper` flatters itself. - Light: the worst pixel is `--paper` composited with black at `--grain`. - Dark: the worst pixel is `--paper` composited with white at `--grain`. Text tokens must clear **4.5:1**. `--rule` and `--sunk` are exempt — they are edges and fills, and WCAG does not ask a hairline to be legible. Ink is never pure black on pure white; at 21:1 that pairing glares on long text. ### Rule 08 — A bordered control, not another word in a row of words A control that *does* something gets a hairline border. Links that only *go* somewhere do not. The theme toggle is a 2rem square for exactly this reason. Ship it with the `hidden` attribute set and let script reveal it, so a visitor without JavaScript is never offered a button that cannot work. A pressed state is a **border in ink, not a fill** — a filled button would be the first card on the page. ### Rule 09 — It prints Ink on white, controls gone, every panel open, `break-inside: avoid` on structural blocks, and link destinations expanded after the link text. A printed page has no hover and no address bar, so a bare "read more" prints as a dead end. Expand `href` on content links only. Applied to every anchor it also prints the address of every nav item, which is noise. --- ## Token contract The eight colour token **names** are the contract. Change every value you like; keep the names, so a diff between two sites built on this system shows only the differences that were intended. | Token | Role | | --- | --- | | `--paper` | Page ground | | `--sunk` | Row hover, code field. Felt rather than seen. | | `--rule` | Hairlines. Decorative; no contrast requirement. | | `--ink` | Body, titles, and the 2px rules | | `--muted` | Ledes, summaries, descriptions | | `--faint` | Mono labels, meta, addresses | | `--accent` | Links, rail numbers, status | | `--accent-deep` | Link hover | Plus `--grain` (0 to disable the surface noise). ### Faces | Token | Role | | --- | --- | | `--mono` | The structural face. Shared across sites. | | `--language` | The reading face. The site's own. | | `--display` | Titles. Defaults to `var(--language)`. | Set `--display` separately only when titles genuinely want a different face. ### Layout Reconciled across the three sites already running this system — they had drifted, and these are the settled values. **Rem everywhere; do not reintroduce px.** | Token | Value | | --- | --- | | `--gut` | `clamp(1.25rem, 5vw, 2.75rem)` | | `--wrap` | `62rem` | | `--rail` | `10rem` | | `--measure` | `34em` | | `--ease` | `cubic-bezier(0.22, 0.61, 0.36, 1)` | --- ## The default palette Neutral: monochrome, no accent. Ratios measured against the worst-case grain pixel — `#f5f5f5` in light, `#161616` in dark. | Token | Light | Ratio | Dark | Ratio | | --- | --- | --- | --- | --- | | `--paper` | `#fcfcfc` | — | `#111` | — | | `--sunk` | `#f4f4f4` | 1.07 | `#191919` | 1.07 | | `--rule` | `#e5e5e5` | — | `#2a2a2a` | — | | `--ink` | `#111` | 17.32 | `#ededed` | 15.46 | | `--muted` | `#444` | 8.93 | `#b4b4b4` | 8.73 | | `--faint` | `#666` | 5.27 | `#8a8a8a` | 5.24 | | `--accent` | `#111` | 17.32 | `#ededed` | 15.46 | | `--accent-deep` | `#111` | 17.32 | `#ededed` | 15.46 | | `--grain` | `0.028` | | `0.02` | | The neutral skin collapses the accent onto the ink deliberately: a monochrome page has no hue to spend, so a link announces itself by decoration and hover changes the underline rather than the colour. --- ## Class reference Everything the system styles. There is nothing else. ### Layout | Class | On | What it does | | --- | --- | --- | | `.wrap` | any | Centres content at `--wrap`, with `--gut` either side | | `.bar` | `
` | Masthead row. Adds the 2px ink rule beneath. | | `.brand` | `` | Site name in the masthead | | `.bar-end` | `
` | Right-hand group: nav plus the toggle | | `.barlinks` | `