DESIGN.md
# Folio — Design System
## Concept
**An image API published as a magazine.** Not documented, not marketed — *published*.
White paper, black ink, one editorial blue, and a page whose grid is not hidden but
**printed**: a measure that never widens, column rules between the columns, hairlines
between the rows, a drop cap opening the lead, a running head across the top and a
folio at the foot. The house style belongs to a print technology monthly; the copy
belongs to an image-processing API. **Two bodies of work that have never shared a leaf,
set on one leaf anyway** — and the setting is the argument.
Start at the name, because everything else was cut to fit it. A **folio** is the page
number printed at the foot of a leaf — the smallest, quietest, most unmistakably
*printed* mark a page can carry, and the one mark no SaaS site has ever put on itself.
Every page here carries one: `1 / 3`, `2 / 3`, `3 / 3`. It is a joke played completely
straight, and it states the thesis in four characters: **this is a three-page
publication, it numbers its pages, and it numbers them because a publication is what it
is.**
The governing principle is inherited whole from the reference and must not be softened:
**it refuses to be a SaaS marketing site.** That refusal is not an attitude; it is an
inventory, and an inventory can be checked against the page item by item. No hero
gradient. No pill. No card. No shadow. No dark band. No icon set. No badge. No monospace.
No accent that isn't the one blue the reference reserves for a link inside an article.
What is left when all of that is removed is a **page**, and the page turns out to be
enough.
The source language is **Wired's** — a strict editorial duet of black on white with no
chromatic accent except a single link blue (`#057dbc`) that lives inside long-form body
copy; a tall high-contrast display serif held at **weight 400 even at 64px**, because
the elegance is in the drawing of the face and not in the weight of it; a humanist serif
beneath it carrying every paragraph; and a sans confined to metadata, captions, eyebrows,
buttons, and nav. Square corners on everything. Hairline dividers instead of elevation.
Its three licensed faces have no exact substitutes, and the three named in its own Font
Substitutes section are the three used here: the display serif becomes **Playfair
Display** at 400, the body serif becomes **Source Serif 4**, and the sans becomes
**Manrope**. Two of its habits are deliberately broken, and the Palette and Components
sections say exactly why: its **black footer band** does not survive (a sheet of paper
has no black slab at its foot, and this design never inverts), and its **circular
icon button** does not survive (there is not one rounded corner in this system). That
lineage is named in this paragraph and **nowhere else**: the built page carries only the
product's own name, **Refract**, in English.
**Why a magazine, and not a costume?** Because of the thing a printer sees in the first
ten seconds of looking at a developer-tool page: **it and a magazine feature want
opposite things from a reader, and only one of them will admit it.** A marketing page
wants a scroll and a click; it hides its grid, softens its corners, and animates a number
upward so that the visitor feels something. A magazine wants the reader to *read* — so it
prints a 680px measure and
holds it, sets the type at a reading size, rules the columns so the eye knows where to
go, and puts the hard numbers in a box where they can be checked. An API reference is a
document. Documents have measures, tables, captions, and footnotes. **The magazine is not
a costume borrowed from another industry; it is the only form that was ever right for
this content, and the developer-tool genre had simply stopped using it.**
**Three other designs answer this brief, and folio stands at a different distance from
each of them — one of those distances needs stating twice.** `aperture` is white, soft,
and photography-led: a 64px hairline-segmented pill at 9999px radius, popovers opening
off it, a circular red orb, and not one square corner. Folio has no pill, no popover, no
circle, and no red. `cutaway` is the dark one — graphite, magenta-and-cyan voltage, an
88px industrial readout, a photograph exploded into a 3D stack — and it is the design
that keeps the **vertical console**, which is right, because an instrument is what it
is and an instrument gets a panel. Folio never goes dark, sets nothing at 88px, never
takes a photograph apart, and **owns no panel at all**: its controls are words inside a
caption (*Signature 1*).
**And this is not `carton`, which is the one that matters.** `carton` is also paper, also
cream-and-ink, and the two of us are the only designs in this brief that a careless eye
could merge. The split is absolute and it runs through every layer. `carton` is
**anti-design scrawl**: typewriter monospace body copy, four type voices mixed on purpose,
hand-drawn wobbly boxes, sticker badges, copy that will not shut up. **Folio is a refined
print grid**: three voices split absolutely by role, **no monospace anywhere in the
system**, not one hand-drawn line, not one badge, and every rule ruled straight because a
press does not wobble. `carton` is loud on purpose and wants you to laugh. **Folio is
quiet on purpose and wants you to read.** Where `carton` mocks the form, folio *keeps*
it: the drop cap is a real drop cap, the table is a real printed table, the footnote is a
real footnote, and the joke — if there is one — is that all of it works.
## Palette
White paper, black ink, one editorial blue. There is no second hue, no semantic palette,
and **no chromatic fill anywhere in this system.**
| Token | Hex | Role |
| -------------- | --------- | ----------------------------------------------------------------------------------------- |
| `--paper` | `#FFFFFF` | Pure white paper — the page floor, every band, the nav, the tables, and the footer. |
| `--paper-tint` | `#F5F5F5` | The one tint. It grounds **exactly one surface: the SDK listing.** Not an elevation tier. |
| `--ink` | `#000000` | Pure black. Display type, the heavy rule, every bounding rule, the caption's editable values, and the one filled button. |
| `--ink-soft` | `#1A1A1A` | The reading ink — every paragraph the body serif sets, the listing, and `button-primary`'s hover fill. |
| `--ink-meta` | `#6B6B6B` | The running words of every caption, running heads, folios, table meta, line numbers, unset table values, the daggered parameters in the credit line, the legal row. |
| `--on-ink` | `#FFFFFF` | The white label on `--ink`. It appears on `button-primary` and on nothing else. |
| `--rule` | `#E0E0E0` | The 1px dividing hairline — table rows, column rules, FAQ rows, ledger rows, the rule that closes a caption. |
| `--blue` | `#057DBC` | The editorial blue. **Rules and non-text marks only** — see the ration below. |
| `--blue-deep` | `#04618F` | The same hue, one stop down. **Every blue that carries text.** |
Rules:
- **Contrast (measured, WCAG 2.1, computed from the sRGB relative-luminance formula).**
On `--paper` (`#FFFFFF`): `--ink` **21.00:1**, `--ink-soft` **17.40:1**, `--ink-meta`
**5.33:1**, `--blue-deep` **6.75:1**. On `--paper-tint` (`#F5F5F5`): `--ink`
**19.26:1**, `--ink-soft` **15.96:1**, `--ink-meta` **4.89:1**, `--blue-deep`
**6.19:1**. On the `--ink` fill: `--on-ink` **21.00:1**. Everything named in this
paragraph clears AA body text (4.5:1) on both surfaces, with margin.
- **The reference's link blue clears AA by one thousandth, and this design refuses to
stand on that.** `--blue` (`#057DBC`) measures **4.501:1 on white** — it passes the
4.5:1 body-text bar by 0.001, which is a rounding artifact, not a margin. And the ratio
is **symmetric**: white *on* `#057DBC` is the same **4.50:1**, so a blue fill under a
white label would carry the identical knife-edge. Worse, the moment the paper takes any
tint at all the number collapses: on `--paper-tint` the same blue measures **4.13:1 and
fails outright** — and `--paper-tint` is precisely where a link inside the SDK listing
would sit. A colour that passes only on one of the design's two grounds, and only by a
thousandth, is not a text colour. So the blue is split into two stops of one hue, and
the split is exact:
1. **`--blue` (`#057DBC`)** — **rules and non-text marks only**, where the 3:1 bar
applies and 4.50:1 clears it with room. It is spent on exactly two marks: the **2px
rule beneath the current option** in an open caption list, and the **2px rule beneath
the active nav link**. It sets no paragraph, no label, no value, no caption, no table
cell, and no button text. It never appears on `--paper-tint` at all.
2. **`--blue-deep` (`#04618F`)** — the same hue one stop down (H 199.9° / S 94.6%
against the reference blue's H 200.7° / S 94.8%; only the lightness moves, 37.8% →
28.8%). **Every blue that carries text**: an inline link in a paragraph, its
underline, and a validation message. **6.75:1 on paper, 6.19:1 on the tint** — it
holds AA on both grounds, which is the whole reason it exists. **The remedy was
found inside the hue, not outside it** — a second stop of the same blue, mixed
darker — and a design that answers a contrast failure by reaching for a fresh
colour has answered the wrong question.
- **Nothing chromatic is ever a fill.** There are exactly two **system-filled surfaces**
in this design: `button-primary` — filled `--ink` at rest and `--ink-soft` on hover and
press (see *Components*), never a third token — and the SDK listing, grounded in
`--paper-tint` and nothing else. No other surface on the site takes a system fill. One
further surface on the site is filled and it is **not the system's**: the letterbox
painted inside the demo plate, which carries **the visitor's own `bg` colour and
appears nowhere else on the page** (see *Signature 1*). **There is no blue fill anywhere and
there never can be** — white on `--blue` is 4.50:1, the same knife-edge, and white on
`--blue-deep` is 6.75:1 but a blue button would make the blue an *accent*, which is
exactly what the reference forbids. The primary action is the ink.
- **The reference's own metadata grey fails AA on its own tint, and this design darkens
it.** The reference sets bylines and timestamps in `#757575`, which measures **4.61:1 on
white** — a pass — but **4.23:1 on `#f5f5f5`**, which is a fail. In this system the
metadata grey has to survive on the tint, because the SDK listing's **line numbers** are
set in it. So it steps down to `--ink-meta` (`#6B6B6B`): **5.33:1 on paper, 4.89:1 on
the tint.** It holds AA on both, and therefore **there is no label-only ink token in
this design at all** — every grey a visitor reads is body-legal, everywhere it appears.
- **A value that is not there is an em dash in a table and a word in a sentence.** There is
no faint ink to ghost anything with, so a default the brief never states is set as an
**em dash (`—`) in `--ink-meta`** (5.33:1) — the mark a table has always printed in a
cell it has nothing to put in. A sentence has no cells to leave empty, so the live
caption does the other thing a page can do and *says so*: an unrotated plate reads
**unrotated**, an unblurred one reads **unblurred**, and both of those words are still
controls (*Signature 1*). Either way, nothing in this design is communicated by making
type harder to see.
- **The hairline carries no meaning.** `--rule` (`#E0E0E0`) measures **1.32:1** on paper —
far below the 3:1 non-text bar — so **no control's identity and no control's state may
rest on a rule alone.** An editable value in the caption is marked by two things at once
and neither of them is a rule: it is `--ink` (21:1) among running words set in
`--ink-meta` (5.33:1), and it is the sans at 600 among running words at 400. Focus is a
**2px `--ink` outline** (21:1), never a blue-only one. The current option in an open
caption list is marked by *three* changes at once — the 2px `--blue` rule beneath it,
the step to weight 600, and `aria-selected="true"` — so no state anywhere in this design
is carried by colour alone.
- **No gradients, and therefore no scrim.** Every surface is flat. A scrim is a
gradient, so this design does not own one — and without a scrim there is no legible
way to lay type over a picture. **Type never sits on top of a photograph here**, and
it costs nothing: the words a plate needs go in the line beneath it, which is where a
printed page has always put them.
- **No dark band. The page never inverts.** No dark hero, no dark section, and **no dark
footer** — the reference's black footer band is its one inversion and it is dropped
here. **`--ink` fills exactly one *surface* on this site — `button-primary`** — and a
button is not a band. Everywhere else the ink touches the page it is type, a rule, or a
mark built out of rules (the FAQ's plus; the `−` and `+` the caption offers a thumb),
never a field of colour. The paper runs from the masthead to the legal row without a
break.
## Typography
**Three voices, split absolutely by role.** All three are self-hosted as woff2 under
`assets/fonts/` via `@font-face` — no font CDN, no Google Fonts `<link>`. All three are
the substitutes the reference's own Font Substitutes section names.
**Display — Playfair Display, weight 400 only.** The high-contrast didone standing in for
the reference's licensed display serif. **It is held at 400 at every size, including the
64px cover line, and it is never bolded: there is no 500, no 600, and no 700 of this face
anywhere in the system.** This is not a preference and it is not a variant. The reference
is explicit that its display elegance comes from the *drawing* of the face — thin, tall,
high-contrast — and not from weight, and a 700-weight didone at 64px is a fashion
magazine, not a technology monthly. **Promoting the display serif to bold destroys this
design.** If a headline feels weak, the fix is a wider margin or a longer line, never a
heavier one.
**Body — Source Serif 4.** The humanist text serif. It carries **every paragraph on the
site** — the lead, the running copy, the deck, the table descriptions, the FAQ answers.
It runs at **400 and its italic, and at no other weight**: emphasis in this system is
italic, never bold. The face carries an `opsz` optical-size axis (8–60, verified in its
`fvar` table), so the 19px lead and the 15px table copy are set at their own optical
sizes rather than one drawing scaled twice — which is what a text serif is for.
**Sans — Manrope.** Confined, absolutely, to **metadata, captions, buttons, nav, running
heads, folios, table heads, and every literal API token** — the parameter keys, their
values, the URL string, and the SDK listing. It never sets a paragraph and it never sets
a headline.
**There is no monospace in this system, and that is a decision, not an omission.** The
reflex of every API page ever built is to reach for a monospace the moment a URL appears;
a printed magazine has no such reflex, and the refusal is the design. The URL string, the
ten parameter names, the seven live values inside the demo's caption, and the SDK listing
are all set in the **sans** — the same voice that sets a caption, because in a magazine a
code listing *is* a caption to a photograph of a machine. What a monospace was buying —
figures that lock into a column — is bought here instead by **`tnum` on the sans's data
roles**, which is a real feature that Manrope really ships, and the listing gets its
structure from **ruled line numbers in the margin**, which is how a print magazine has
always set a listing.
The bill for that arrives in exactly one place and it is paid in the open. A proportional
face sets a URL tighter than a URL wants to be read — a string is taken in one character
at a time, not one word at a time — and Manrope has no slashed zero to hand the reader.
So the URL role is **set at 17px and never set smaller anywhere on the site**, with 0.2px
of tracking opening the string until no two characters touch. *Give a number size and air
or do not print it* is a compositor's rule older than the URL, and it is the one taken
here (see the absent-features list below).
| Role | Face | Size / Leading | Tracking | Features | Use |
| ------------ | ------------------------ | -------------- | -------- | -------- | --------------------------------------------------------------- |
| Display XXL | Playfair Display 400 | 64px / 0.95 | -0.5px | — | The index cover line — the largest **set size** in the system |
| Display XL | Playfair Display 400 | 48px / 1.05 | -0.4px | — | Page openers on docs and pricing |
| Display L | Playfair Display 400 | 32px / 1.1 | -0.3px | — | Section heads, capability heads |
| Display M | Playfair Display 400 | 26px / 1.15 | 0 | — | Sub-heads, tier names, FAQ questions |
| Drop cap | Playfair Display 400 | 3 lines deep | 0 | — | The initial of the lead paragraph. One per page. |
| Figure | Playfair Display 400 | 48px / 1.0 | -0.5px | **lnum** | The four stats figures in the BY THE NUMBERS box |
| Price | Playfair Display 400 | 40px / 1.0 | -0.4px | **lnum** | The three tier prices in the tier table's head |
| Step numeral | Playfair Display 400 | 32px / 1.0 | 0 | **lnum** | The three quickstart numerals, hung in the outer margin |
| Deck | Source Serif 4 400 ital. | 22px / 1.45 | 0 | **onum** | The cover's standfirst and the standing box's |
| Lead | Source Serif 4 400 | 19px / 1.55 | 0 | **onum** | The lead paragraph of each page — the one the drop cap opens |
| Run-in | Source Serif 4 400 | 19px / 1.55 | 0.6px | **smcp** | The first four words after the drop cap, in true small caps |
| Body | Source Serif 4 400 | 16px / 1.6 | 0 | **onum** | Default running copy |
| Body S | Source Serif 4 400 | 15px / 1.55 | 0 | **onum** | Spec-table descriptions, FAQ answers, footnotes |
| Running head | Manrope 700 | 11px / 1.2 | 1.4px | **case** | Uppercase running head at the top of every page |
| Eyebrow | Manrope 700 | 12px / 1.2 | 1.4px | **case** | Uppercase category eyebrow above a display line |
| Standing head| Manrope 700 | 12px / 1.2 | 1.4px | **case** | Uppercase head of a standing box: `AT A GLANCE`, `BY THE NUMBERS` |
| Table head | Manrope 700 | 12px / 1.2 | 1.2px | **case** | Uppercase column heads in the spec and tier tables |
| Nav | Manrope 700 | 14px / 1.3 | 0.4px | — | Top-nav links |
| Button | Manrope 700 | 16px / 1.25 | 0.3px | — | Button labels |
| Key | Manrope 600 | 14px / 1.3 | 0 | — | The ten parameter names — `w`, `fit`, `fm` — wherever they appear |
| Data | Manrope 500 | 15px / 1.5 | 0 | **tnum** | Every figure that stacks in a column: table values, quotas, ledgers |
| Listing | Manrope 400 | 15px / 1.7 | 0 | **tnum** | The SDK listing and its ruled line numbers |
| URL | Manrope 400 | 17px / 1.5 | 0.2px | **tnum** | The live URL string. **Never set below 17px.** |
| Live caption | Manrope 400 / 600 | 17px / 1.6 | 0 | **tnum** | **The demo figure's caption — the site's one control surface.** Its running words at 400 in `--ink-meta`; its seven editable values at 600 in `--ink`. |
| Caption | Manrope 400 | 12px / 1.4 | 0 | — | Captions and figure numbers on every plate but the demo's |
| Folio | Manrope 400 | 12px / 1.2 | 0.6px | — | The page number at the foot: `1 / 3` |
Principles:
- **Serif for the argument, sans for the specification — and the split is absolute.** The
serifs never carry a button label, a nav link, a table head, or a URL. The sans never
carries a paragraph and never carries a headline. The test is not *is this a sentence*;
it is **is this argued, or is this consulted.** A caption is consulted — it is where a
picture's specification is printed, and the secondary face has been setting captions for
as long as a page has had two faces on it. The live caption is therefore a sentence set
in the sans, and it is not an exception to the rule; it is the rule said exactly.
- **Hierarchy is bought with size and air, never with weight.** The display serif sits at
400 forever. The body serif sits at 400 forever. Only the sans has weights (400 / 500 /
600 / 700), and it has them because an 11px uppercase running head needs 700 to hold at
all. **The heaviest weight in this system is the sans's 700, and it never appears above
16px** — that is the Button role, and there is nothing heavier anywhere on the site.
Above 16px, one thing is set in something other than 400: the **live caption's editable
values, at the sans's 600 at 17px** — and that step is not decoration, it is the entire
affordance (*Signature 1*). (The drop cap is measured in *lines*, not points: three lines
of the 19px Lead sit taller than the 64px cover line, and it is still weight 400.)
- **Emphasis in prose is italic.** Source Serif 4's italic is a *style of the body serif*,
not a fourth voice. There is no bold serif in this system, and there is no underline
except on a link.
- **Old-style figures in prose; lining figures in data.** This is the whole print argument
in one line, and both halves are real declarations against real fonts:
- **`onum` on the body serif.** Source Serif 4's default figures are lining, and it
genuinely ships `onum` (verified in its GSUB: the feature maps the base digits `zero`,
`one`, `two` … onto their old-style variants). So `1,000 transforms` and `30 days`,
read inside a paragraph, sit as **text figures** with ascenders and descenders — the
way a magazine sets a number it wants you to *read* rather than *check*.
- **`lnum` on the display serif.** This one is load-bearing and it is easy to get
backwards: **Playfair Display's default figures are old-style.** Verified in its GSUB
— the `lnum` feature maps `zero → zero.lf`, `one → one.lf` and so on, which means the
lining figures are the *opt-in* and the cmap default is the text figure. Without the
declaration, `62%` at 48px in the stats box would render with a descending `6` and a
baseline `2`, which is correct in a sentence and wrong in a readout. So the three
display-serif roles that set figures — **Figure, Price, and Step numeral** — declare
`lnum`, and no other role in the system does. A number in a box is a number you check.
- **Tabular figures where figures stack — and where a figure must hold still.** **`tnum` is
declared on the sans's four data roles — Data, Listing, URL, and Live caption — and
Manrope genuinely ships it** (verified in its GSUB: the feature maps the base digits onto
their `.tf` tabular variants; the face's default figures are proportional, so the
declaration does real work rather than re-asserting a default). It earns itself in **seven**
places: the spec table's value column, the tier table's three stacked figure columns, the
overage ledger, the `AT A GLANCE` box, the URL string, the **SDK listing's ruled line
numbers** — and the live caption, where it is doing something a printed column never asked
of it.
The line numbers are the plainest case in the system and the one that most obviously earns
the feature: a column of digits stacking down a margin behind a 1px rule, running `1` to
`9` and then into two figures, where the only job a numeral has is to hold its column. A
proportional `1` is narrower than a proportional `8`, so without `tnum` the tenth line's
numbers would sit a hair off the ninth's and the ruled margin would stop being ruled. **A
compositor sets a line-number column in tabular figures and always has.** It is why the
Listing role declares the feature, and it is the reason to keep the declaration if a later
hand ever asks what it is buying.
In the caption, `tnum` is buying something else entirely: every digit is one width, so a
numeral being scrubbed from `1200` to `1201` does not shudder under the pointer that is
dragging it. **This is what the absent monospace was for**, and it is why the absence
costs nothing.
- **`case` on the uppercase sans, and it does real work.** Declared on the four uppercase
sans roles — **Running head, Eyebrow, Standing head, and Table head** — and Manrope
genuinely ships it (verified in its GSUB: the feature maps `periodcentered →
periodcentered.case`, `hyphen → hyphen.case`, and the parentheses). The running heads in
this system are built on a middot — `REFRACT · QUICKSTART & REFERENCE` — and `case`
lifts that middot from lowercase height to cap height, which is exactly where an
all-caps line needs it.
- **`smcp` on the run-in, and Source Serif 4 genuinely ships it** (verified in its GSUB:
355 substitutions, mapping `a`, `b`, `q`, `w` … onto true small-cap glyphs). The four
words following each drop cap are set in **true small caps, not faux ones** — no
`font-variant: small-caps` synthesis, no scaled-down capitals. This is the oldest
typographic manner there is for opening a feature, and it is the second half of the drop
cap: an initial with no run-in is a decoration; an initial *with* one is a typeset page.
It is set on the roman only — **the italic of Source Serif 4 ships no `smcp`** (verified
absent), so the run-in is never italic.
- **Exactly five features are declared in this system — `onum` and `smcp` (Source Serif 4),
`lnum` (Playfair Display), `tnum` and `case` (Manrope) — and all five were verified
present in the faces' real GSUB tables.** The refusals are listed too, and a later hand
must not quietly add them back:
- **`tnum` is never declared on Playfair Display.** The face **does not ship it at all**
(verified absent from its GSUB feature list). The consequence is designed around
rather than hidden: **the display serif never sets a figure that has to align with the
figure above it.** The four stats figures each stand alone in their own ruled cell, and
the three tier prices each stand alone at the head of their own column — no cross-cell
alignment is required, so no tabular figures are required. Any figure that *must* lock
into a stacked column is set in the sans Data role, which has `tnum`. If a later hand
finds themselves wanting a numeric column in the display serif, the answer is that the
column belongs in the sans, not that the feature belongs in the font.
- **`tnum` is never declared on Source Serif 4.** The face *does* ship it — but its
default figures are **already tabular lining** (verified: `pnum` is the opt-in that
maps the base digits onto proportional variants, and `tnum`'s own sources are those
proportional and old-style variants, not the defaults). Declaring `tnum` on default
serif text would be a silent no-op that looks like a decision.
- **`zero` is never declared.** Source Serif 4 ships a slashed zero, but the body serif
sets no URL and no listing in this system. **Manrope, which sets both, ships no `zero`
at all** (verified absent from its GSUB), so there is nothing to declare and declaring
it would be a pure void. The URL role settles that debt in size and air rather than in
glyphs, and it settles it in the open — see the monospace paragraph above.
- **`liga` is never declared.** All three faces ship `liga` and it is on by default in
every browser. Declaring it is a compositor writing out an instruction the press has
already followed.
- **`calt` is never declared.** Playfair Display and Manrope ship it (and it, too, is on
by default); **Source Serif 4 ships no `calt` at all** (verified absent), so a
system-wide declaration would be part no-op and part void.
- **`onum` is never declared on the sans, and `smcp` is never declared on the sans.**
Manrope ships **neither** (both verified absent from its GSUB): its figures are lining,
always, and it has no small-cap glyphs. The sans's uppercase roles are **true
uppercase with tracking**, never faux small caps.
## Spacing & layout
The grid is not a scaffold this design hides behind — **it is printed**, and every rule
you can see is a rule the layout is actually built on.
- **4px base unit** (the reference's own). Tokens: 2 · 4 · 8 · 12 · 16 · 20 · 24 · 32 ·
48 · 64 · 96.
- **Section rhythm: 64px** top and bottom between bands. **The cover takes 96px.**
- Content centres in a **1200px container**. **The article measure — the text column — caps
at 680px and never grows.** That is roughly 68 characters of 16px Source Serif, which is
a reading measure, and it is the single most important number in this document. A
marketing page widens its paragraph to fill a monitor; **a magazine does not widen its
column because the paper got bigger.**
- **The two-column article grid.** On index and docs, the page runs a **680px measure and a
300px outer column, divided by a 1px `--rule` column rule.** The outer column is where a
magazine puts a box or a note, and this design uses it for both: the `AT A GLANCE` box on
docs, and — beside the live caption on index — **two marginal notes, stacked in the order
their subjects appear in the caption**: the unkeyed **shoulder note** against the caption's
first line, and the **dagger footnote** beneath it, against the caption's second sentence,
divided by a 1px `--rule` hairline (*Signature 1*). The capability trio and the two big
tables **break the grid** and run the full 1200px measure — which is also a print move, and
which is why the column rule stops where they start.
- **Every rule this design draws is one of four:**
| Weight | Colour | Use |
| ------ | ------- | ------------------------------------------------------------------------------------------------ |
| 1px | `--rule`| The **dividing** hairline — table rows, column rules, FAQ rows, ledger rows, band separators, the rule that closes a caption. |
| 1px | `--ink` | The **bounding** hairline — `button-outline`, the writing rule under an editable value on hover and in edit, the frames of the caption's `−` and `+` marks, the FAQ marker. |
| 2px | `--ink` | The **heavy** rule — above a table head, above a box, bracketing the stats band, above the footer.|
| 2px | `--blue`| The **marking** rule — beneath the current option in an open caption list, beneath the active nav link. Nothing else. |
A 2px black rule above a table head is the oldest typographic signal in print for *this
is a table, read it as data*, and it is the only "elevation" this design owns. **Every
ink mark on this site is one of three kinds: a rule, a letter, or a rectangle ruled out
of four rules. There is no fourth kind of mark**, and nothing in the system needs one.
Three counts are in play in this section and they are not each other: **three** kinds of
mark, **four** weights of rule (the table above), and the *four* in *ruled out of four
rules* is the four sides of a box.
- **Radius is 0px on every element in this system, without exception.** Buttons, plates,
tables, boxes, the listing, the standing box, the caption's `−` and `+` marks. **There is
not one rounded corner and not one circle on this site.** The reference's single circular
shape — its social-share icon button — does not survive. A pill is not a variant here; it
is `aperture`'s language, and it is the fastest way to destroy this design.
- **Elevation: there is none. No `box-shadow` is declared on any element, at rest or on
hover, anywhere in this system** — not on the nav, not on the listing, not on a plate,
not on a button, and not on the list that opens under a word in the caption. **The only
elevation in this design is the paper itself**, and the only depth on the page is the
depth inside a photograph.
Breakpoints:
| Width | Behavior |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mobile <768px | Display steps **64 → 36px**; the **drop cap steps 3 lines → 2**; the article grid collapses to one column and **both marginal notes drop beneath the credit line — the shoulder note first, the dagger note under it**, a hairline between them; the demo's two plates stack; **the caption stays a caption** — its leading opens 1.6 → 2.0 and every editable value takes vertical padding until its touch target reaches 44px; **drag-scrub is off** (a horizontal drag on a phone is a scroll) and a focused numeral is given its `−` / `+` marks instead; the capability trio goes 1-up and its vertical column rules become horizontal hairlines; the spec table's Description column drops beneath its row; the tier table becomes **three stacked ruled blocks — never three cards**; running head and folio stay |
| Tablet 768–1024px | Display **48px**; the article grid stays single-column, the caption still runs the full measure beneath the figure, and **both marginal notes sit beneath the credit line in the same order** — shoulder note, then dagger note; the capability trio holds 3-up on a tighter measure |
| Desktop 1024–1200px | Display **64px**; **the two-column article grid appears** — a 680px measure and a 300px outer column, divided by a 1px column rule; the figure, its caption, and the credit line run in the measure, and the outer column carries **the shoulder note against the caption's first line and the dagger note beneath it**; the capability trio runs 3-up with column rules between the columns |
| Wide >1200px | Content caps at 1200px and the margins absorb the rest. **The measure never exceeds 680px at any width.** |
Band rhythm — **`--paper` from the masthead to the legal row; `--paper-tint` on exactly one
surface; no dark band anywhere:**
- **index** — masthead band (paper, hairline above and below, the wordmark centred) →
running head `REFRACT · TRANSFORM, OPTIMIZE, DELIVER` → **cover** (paper, 96px: the
eyebrow, the 64px display line, an italic deck, a hairline, and the full-measure
`cover-plate` with its caption beneath it) → **the lead** (paper, 680px measure: the
drop cap, the small-caps run-in, and the paragraph that says what Refract is — point it
at an existing image origin, no re-upload, originals fetched on demand and edge-cached,
never stored permanently) → **capability trio** (paper, 64px, full 1200px measure: three
columns divided by 1px column rules — **Transform**, **Optimize**, **Deliver** — each a
plate, a 32px display head, and a body-serif paragraph) → **the live transform** (paper,
64px, the two-column article grid: **Fig. 2** — the before/after plate pair — in the
measure, **the live caption beneath it**, a closing hairline, then the **URL credit line**
with its `button-outline` **Copy**; and in the outer column the two marginal notes — the
**shoulder note** against the caption's first line and the **dagger footnote** beneath it)
→ **BY THE NUMBERS**
(paper, 64px: the four figures in four ruled cells, bracketed by a 2px `--ink` rule
above and a hairline below) → **CTA band** (paper, 64px, hairline-bracketed, one black
`button-primary`: **"Start building" → `./docs.html`**) → folio `1 / 3` → footer.
- **docs** — masthead → running head `REFRACT · QUICKSTART & REFERENCE` → page opener
(paper, 48px display line) → the lead (drop cap, run-in) → **quickstart** (paper, 64px,
680px measure: three numbered article sections, each numeral hung in the outer margin in
the 32px Step-numeral role; the first carries the square `docs-plate` figure with its
caption; the third carries the **SDK listing** on `--paper-tint`) — with **caching &
limits** rendered as the **`AT A GLANCE` standing box in the outer column beside it** →
**parameter reference** (paper, 64px: the ten-row printed spec table, breaking the grid
to the full 1200px measure, closed by a 2px `--ink` rule and the dagger footnote) →
folio `2 / 3` → footer.
- **pricing** — masthead → running head `REFRACT · PLANS & PRICING` → page opener (paper,
48px line) → the lead (drop cap, run-in) with the tall `pricing-plate` figure in the
outer column → **tier table** (paper, 64px, full 1200px measure: three tier columns and
a row-label column, one printed comparison table) → **overage & billing semantics**
(paper, 64px, 680px measure: hairline-divided ledger rows) → **FAQ** (paper, 64px, 680px
measure: four hairline-divided disclosure rows) → folio `3 / 3` → footer.
## Signature
Four devices carry this design. Three of them a magazine has had for centuries and this
one only has to keep; the fourth — the caption that can be edited — is what happens when
you hand a magazine an API and refuse to let it build a control panel.
### 1. The live caption — the parameter playground's control surface
**A magazine sets its parameters in a caption.** It does not stand a console beside a
photograph and invite you to operate it. It prints, under the picture, the line that says
what the picture is — the lens, the exposure, the stock, the crop — and that line is the
one place in the whole publication where a photograph's settings are allowed to be
written down. So that is where this playground is. **The seven browser-honest parameters
are words in a sentence, and the sentence is live.**
At rest, under the demo figure, the caption reads:
> **Fig. 2** — Left, the source. Right, the same source rendered **1200** px wide, at its
> **own** height, **unrotated**, **unblurred**.
>
> Format†, quality† and pixel ratio† are not set in this browser.
Worked, it reads one of these:
> **Fig. 2** — Left, the source. Right, the same source rendered **1200** px wide by
> **800** px tall, fitted **cover**, cropped **smart**, **unrotated**, blurred to **12**.
> **Fig. 2** — Left, the source. Right, the same source rendered **1200** px wide by
> **800** px tall, fitted **contain**, letterboxed against **#F5F5F5**, turned **90°**,
> blurred to **40**.
**No single sentence ever carries all seven at once, and that is a fact about the transform
rather than a shortfall in the caption.** `bg` exists only under `contain`; a crop strategy
exists only under a fit that crops. The two can never appear in the same caption because the
two can never be true of the same image. All seven are reachable; they are not all
simultaneous, because the thing they describe is not.
Every bold word is a control. **There is no panel.** No row list, no key column hung down
the left, no value column ruled down the right, no slider, no swatch row, no box of any
kind, and nothing that could be lifted out of the page and used somewhere else. The key
is the word *around* the value — "px wide" **is** the key `w`, "fitted" **is** the key
`fit` — and the value is the word you change. Everything a control panel needs a row to
say, a sentence says with grammar, and grammar is free.
**The parameter reference lives on docs. What the caption prints is the transform.** The
sentence never sets a key and an equals sign; it names the thing the parameter does. The
literal `w=1200` a developer will paste is printed one line below, in the URL, where a
publication prints its source credit — and the caption and the credit are the same fact
in two registers, which is the ordinary condition of a captioned photograph.
**Why a caption and not a console:** the console belongs to `cutaway`, and it belongs to
it honestly — that design is an instrument, and an instrument earns a panel. Folio is a
page. A page that grew a control panel in its outer column would be a magazine with a
dashboard bolted to the margin, and the whole argument of *Concept* would be over.
**Four states of an editable value, and every one of them is made of type or of a rule.**
- **At rest** — `--ink` (21:1) at the sans's **600**, sitting inside running caption words
set in `--ink-meta` (5.33:1) at **400**. Ink and weight, both, and nothing else: no
underline at rest, no dotted border, no colour, no icon, no chevron. In a grey line of
400, a black 600 word is a word that has been *set* — and in this caption, every word
that has been set is a word you can re-set. The daggered sentence beneath has no black
word anywhere in it, which is exactly how it says *nothing here is yours to change*.
- **On hover** — the value takes the **writing rule**: a 1px `--ink` bounding hairline
under the slug, the width of the word. It is the line a correction is written on, and it
is the same 1px ink rule the rest of the system bounds things with. The cursor is
`ew-resize` over a numeral on a fine pointer and `pointer` over anything that opens a
list.
- **On focus** — the system's one focus mark, unchanged: a **2px `--ink` outline at a 2px
offset** (21:1). The writing rule stays under it.
- **While it is being changed** — the slug **freezes at its widest measure**: four figures
for `w` and `h`, three for `blur`, six for a hex. With `tnum` under it, every digit is
one width, so a numeral counts up under a stationary pointer and **the caption does not
rewrap while you are aiming at it.** The line breaks are re-set only on a commit — a
click, a release, an Enter — never under a moving hand.
**Setting a number, with no slider anywhere near it.**
- **Drag-scrub** (fine pointers): press on the numeral and pull sideways. One unit per 2px
of travel; ×10 with Shift held. The pointer is captured, so the value keeps coming even
when the hand wanders off the line of type.
- **Click without dragging**: the slug takes a caret and becomes an in-place field — no
box, no border, no fill; the writing rule under it is the whole of its chrome, because a
boxed input in a caption is a control panel with one row. `inputmode="numeric"`. Enter or
blur commits; Escape abandons and puts the previous value back.
- **Keyboard**: the value is a `role="spinbutton"` with `aria-valuenow`, `aria-valuemin`,
`aria-valuemax`, and an `aria-valuetext` that reads the clause rather than the digits
("width, 1200 pixels"). Up/Down step by 1, Shift+Up/Down by 10, PageUp/PageDown by 100,
Home and End go to the bounds. `blur` is bounded 0–100, which is the brief's range and
not an invented one.
- **Coarse pointers**: no scrub — a horizontal drag on a phone is a scroll, and stealing it
would be a lie about what the page is. A tap opens the field, and while the field holds
focus a **`−` and a `+`** sit in the flow after the slug: two 24px squares, 1px `--ink`
bounding rule, 0px radius, padded out to a 44px touch target and set in the sans like
every other mark on this page. They leave when focus leaves. They are the one concession
the caption makes to a thumb, and they are made of rules, like everything else.
**Choosing from a list, without a segmented control.** An enum value (`fit`, `crop`, `rot`)
is a `<button aria-haspopup="listbox">`. Enter, Space, or Down opens a short list **hung
directly beneath the word, inside the caption block and in the flow of the page**: one
option per line, left-aligned to the word's own left edge, in the same face at the same
size. The figure above never moves; the hairline, the credit line and the footnote below
move down and come back. The list has **no box, no border, no fill, and no shadow** — it
is set on the paper, and a 1px `--rule` hairline closes it, which is all a printed list
has ever needed. The current option carries the **2px `--blue` rule beneath it**, steps to
**600**, and takes `aria-selected="true"`. Up and Down move; a letter key jumps; Enter
commits; Escape closes and returns focus to the word. Clicking elsewhere on the page closes
it and changes nothing.
**`bg` takes a colour, and there is no swatch row anywhere in this design.** When `contain`
is the fit, the sentence grows a clause — *letterboxed against **#F5F5F5*** — and the value
is **the hex itself**: six characters in a six-character slug, set in the sans with `tnum`,
the `#` in front of it belonging to the sentence rather than to the value. Focus it and it
takes a caret; type, and the letterbox behind the plate changes on the sixth character. A
string that is short or not hexadecimal leaves the last good colour on the plate and prints
the validation message under the credit line in `--blue-deep` (6.75:1) — the same blue as a
link, because this system has no error red and will not grow one. A slug cleared to nothing
prints an em dash.
**And there is no chip beside it, because the plate is the chip.** A printed page does not
show you the same ink twice. The letterbox inside the figure is a specimen of the exact
colour you named, printed at the size of the plate, in the one place the parameter actually
acts — and a row of little squares beside the word would be a second, smaller, worse
rendering of information already on the page, and it would put a field of colour into an
interface that has none anywhere else. **The name is in the caption. The ink is on the
plate.** The cost is
real and it is accepted: a visitor cannot *browse* colours here, only *name* one. That is
the correct cost for a specimen page, and it is the wrong cost for a paint mixer, which this
is not.
**A clause exists when its parameter is doing something, and not one moment before.** This
is the thing prose can do that a panel cannot. A panel has to print a row for `bg` even when
`bg` is inert, and then grey it out and hope you understand why. A sentence simply has not
written the clause yet. **Three clauses are conditional, and every condition is a fact about
the transform rather than a preference:**
1. **The fit clause appears when `h` is set.** With no height, the rendered box takes the
image's own aspect ratio, and a resize mode has no box to resize into: `object-fit` does
nothing at all. So the caption says *at its **own** height* — and *own* is the control,
the same numeric slug as any other, whose unset reading happens to be a word. Give it a
number and the sentence grows *by **800** px tall, fitted **cover***.
2. **The crop clause appears when the fit is one that crops** — `cover` or the brief's own
`crop` mode. Under `contain` or `fill` nothing is being cropped, so a crop strategy has
nothing to choose between, and the caption does not pretend it has.
3. **The `bg` clause appears when the fit is `contain`.** The brief scopes `bg` as the
background fill *for* `contain`; there is no letterbox to paint until there is a letterbox.
The invariant that makes this safe on a keyboard: **the word that removes a clause is never
inside the clause it removes.** `h` opens and closes the fit clause; `fit` opens and closes
the crop and `bg` clauses. Focus is never standing on the word that vanishes.
**And the conditional caption has a price, which this document is going to print rather than
pocket.** Every other design answering this brief keeps a surface on which **all seven
parameters are visible at once** — a bar of segments, a console of channel strips, a scatter
of callouts round a plate — and each of them, when a parameter is inert, prints the control
anyway and marks it dead: greyed, disabled, struck through. **Folio has no such surface, and
giving it up is the one thing this caption cost the brief.** At the request form the brief
itself writes — `?w=1200&fm=auto&q=80` — no height is set, so there is no fit clause, and
therefore no crop clause and no `bg` clause: **the first thing a visitor sees is four
controls, not seven, and three of the seven have no rendered trace on the page at all.** That
is a real cost. It is not rounded down here, and it is not a defect to be repaired by
reprinting the missing rows in grey.
It is accepted for the same reason the hex field's cost is accepted, and the reason is the
whole of what this caption is for: **a dead greyed-out row is the panel logic the sentence
exists to escape.** A greyed `bg` row is an interface talking about itself — *here is a
control, it does not work, do not ask.* An absent `bg` clause is a sentence talking about the
transform — *nothing is being letterboxed, so there is nothing to letterbox against.* The
first is furniture that then has to be explained. The second is simply true, and it costs no
ink. `fit` has no meaning without an explicit height and `bg` has no meaning outside
`contain`; **never printing a dead row is not this design's compromise, it is its best
mechanical idea**, and a visible-but-disabled control would be a return to the panel in the
one design that was built to do without one.
What the design does owe the visitor is not a dead row. It is **a way of knowing that the
sentence has more to say** — and a publication that leaves something out of a sentence puts
the explanation in the margin. That is the shoulder note, and it is next.
**The shoulder note — how a reader learns the sentence grows.**
A magazine has two marginal instruments and this design already owns one of them: the
**footnote**, keyed by a dagger, which is what the caption uses for `fm`, `q`, and `dpr`. The
other is the **shoulder note** — an unkeyed gloss set in the margin against the line it is
about, which is what a margin was for before it was somewhere to put footnotes. The growth of
the caption is a shoulder note and **not** a footnote, and the distinction is exact rather
than decorative: **a footnote mark is a promise that something has been left out of the
sentence and printed elsewhere.** Nothing has been left out here. The clause is not missing;
it is *not true yet*. So the note takes **no mark in the caption** — no dagger, no double
dagger, no asterisk, nothing added to the running words — and it does not disturb the order
of the marks that are already there.
- **What it says.** Set in the margin beside the caption's first line:
> The sentence grows. Set a height and it takes a `fit`; a fit that crops takes a `crop`;
> `contain` opens a letterbox, and a letterbox takes a `bg`. Three of the seven are waiting
> on that height, and none of them is printed until it is doing something.
The counts in it are counts of this page's own controls, set as words; **no figure in this
note is a claim about the product**, and the parameter names are set as literal tokens in the
sans Key role, as they are everywhere else in this system.
- **How it is set.** The **15px Body S role in its italic** — a style of the body serif and
not a fourth voice — in `--ink-soft` (17.40:1 on paper), ragged right, with a **1px `--rule`
hairline above it**. It is quieter than the caption because it is a gloss on the caption,
and it is quiet by *position and italic*, never by a fainter ink: nothing in this design is
communicated by making type harder to see.
- **Where it goes, at every width.** On **desktop (1024–1200px) and wide (>1200px)** it sits
in the **300px outer column**, set against the caption's **first line** — the line whose
height clause it is about — with the **dagger footnote beneath it**, set against the
caption's second sentence, the two divided by a 1px `--rule` hairline. The two notes stack
in the outer column **in the order their subjects appear in the caption**, which is the only
order a margin has ever set notes in. On **tablet (768–1024px)** and **mobile (<768px)** the
article grid is one column, so both notes drop **beneath the credit line, the shoulder note
first and the footnote under it**, in the same order and with the same hairline between
them. It never becomes a tooltip, a popover, or a disclosure: it is prose, and prose is
always already open.
- **It is not a control and it owns nothing, so it takes no stop.** It has no `role`, no
`tabindex`, and no focus state, and it adds **nothing** to the tab order — which is the test
the parent rule sets: a mark that owns no value does not get a stop. But it is not invisible
to a screen reader either, and it is not left to a sighted reader alone: **the note is the
`aria-describedby` of the two words that open what it describes** — the height value, and
the `fit` word once the fit clause exists. So the control that grows the sentence is the
control that announces how, and no new stop was minted to do it.
- **It leaves when it has nothing to say.** Once a height is set *and* a fit is chosen, the
path the note describes has been walked, so the note is **withdrawn** — the hairline with
it. It is a gloss on a sentence that is still growing, not a standing instruction, and a
publication does not keep printing a note about a clause that is now on the page. (It
returns if the height is cleared back to *own*, because the sentence has shrunk back to the
state the note is about.)
**Unset, in a sentence, is a word — not a dash and not a ghost.** `rot` unset reads
**unrotated**; `blur` at zero reads **unblurred**; a height not given reads **own**. Each of
those words is still a control, and each is still black and still 600, because *unset* is a
state of a value and not the absence of one. The em dash keeps the job it has always had and
no other: **a table cell with nothing to put in it** (the spec table's Default column, the
tier table), and a slug a visitor has just cleared. There is no `rot=0` and no `blur=0` in
the URL — the brief defines `rot` as `90` / `180` / `270`, and an unset parameter contributes
nothing to a string.
**Focus order is reading order, and the design got it for free.** Tab moves along the
sentence: `w`, `h`, then the fit and crop and `bg` clauses if they exist, then `rot`, then
`blur`, then the **Copy** button under the credit line. **That is the complete tab order of
this page's control surface, and no object on it owns two stops** — a rule the caption cannot
be built without, because every one of its controls is a word in a live sentence and a
sentence rewrites itself.
The three things that could quietly break it, named so a build cannot ship one of them:
- **The `−` and `+` marks a focused numeral offers a thumb are not stops** (*Components*,
`caption-stepper`). They are `aria-hidden`, they carry `tabindex="-1"`, and they take
`preventDefault()` on `pointerdown` so pressing one never moves focus. **This is not
fastidiousness, it is the only shape the affordance can take**: the marks exist *only while
the numeral holds focus*, so a stepper that could itself be tabbed into would blur the
numeral, remove itself from the page in the same instant, and **destroy the node the visitor
was standing on.** The increment it hands a thumb, the numeral already hands a keyboard and
a screen reader — it is a `role="spinbutton"` with `aria-valuenow`, and assistive technology
drives that directly, which is why the marks can be `aria-hidden` without costing anybody
the ability to step the value.
- **An open `caption-list` is not a set of stops.** It is a listbox owned by the word that
opened it: Up and Down move within it, Enter commits, Escape closes and returns focus to the
word. No option is ever tabbed to, and the list closes before Tab can leave the word.
- **The shoulder note and the dagger footnote are not stops.** They own no value, so they get
no stop. They reach a screen reader as the `aria-describedby` of the controls they are about
(above), which is how a note reaches a reader without becoming a control.
The running words between the values are inert text, and so are the dagger, the folio, the
running head, and every em dash. **The caption is not an `aria-live` region** — a sentence
that re-reads itself into a screen reader every time a numeral ticks is not a caption, it is a
siren. Each value announces itself, as its own widget, with its own name and its own value.
**Manipulating any value mutates the figure immediately and rewrites the URL beneath it.**
Nothing on this page is a mock-up. If a word changes and the photograph does not, the design
has failed and should be thrown away.
Four clauses govern the caption, and they are the ones that keep it honest:
- **`fm`, `q`, and `dpr` are not controls — they are footnoted.** They are named in the
caption's **second sentence**, which is set entirely in `--ink-meta` at 400 and therefore
contains no black word and no control: *Format†, quality† and pixel ratio† are not set in
this browser.* Each of the three carries a **dagger (`†`)**, and on index the footnote is
set once, in the outer column beside the caption, in the 15px Body S serif:
> `†` Not controls. `fm=auto` resolves AVIF → WebP → JPEG from the request's Accept
> header and `q` is applied at the edge — a browser cannot demonstrate either re-encode.
> `dpr` is different: the browser already reports it, honestly, as its own
> `window.devicePixelRatio` — there is nothing to negotiate, only to print.
A badge is what a software page reaches for at this moment. **A magazine has never needed
one, because it has had the dagger for four centuries** — a mark that is a *letter*, not
an ornament; that costs one glyph and no chrome; and that comes with somewhere to put the
explanation. The same dagger marks the same three rows in the docs spec table, and the
same footnote sits beneath that table, because a note to a table goes under the table and
a note to a figure goes in the margin.
The refusal underneath it is the part that matters. **The alternative is to set a number
that is not true** — a payload figure ticking down beside the plate, a byte count under
the credit line. A publication that prints a figure it was not given has committed the
one error a printed page cannot take back, because a page cannot be quietly re-encoded
after it has gone to press. **Every number in this system comes from the brief or it is
not set at all.**
- **The plate carries the visitor's colour, and the interface never does.** The letterbox
inside the figure is the only place on this page where a `bg` value is ever printed, and
it does not travel: no button, no rule, no band, no mark, and no focus outline takes its
ink from it. **A `bg` value can never be read as licensing a second hue in the
interface**, because there is nowhere in the interface for it to go.
- **The caption is prose and it degrades like prose.** Narrow the viewport and it does what a
paragraph does: it takes more lines. There is no mobile control panel, no bottom sheet, no
drawer, and no fallback widget hiding behind a breakpoint. The leading opens, the values
grow their touch targets, drag-scrub gives way to the `−` / `+` marks, and the sentence
simply takes the lines it needs. A sentence is the most responsive layout ever devised,
and it did not need a media query to become one.
- **Nothing here is dressed up as a control that is not one.** No inert row, no disabled
slider, no greyed swatch, no fourth `rot` value invented so the option list would look
balanced. What the browser can do is a black word. What the edge does is a grey one. **That
is the entire vocabulary of the sentence** — and the thing the sentence cannot yet say, the
margin says in prose, which is the shoulder note above and is not a control either.
The **URL prints beneath the caption**, under a 1px `--rule` hairline, the way a magazine
prints a source credit under a plate: 17px sans URL role, `tnum`, `--ink`. It opens at the
brief's own request form — `https://demo.refract.dev/hero.jpg?w=1200&fm=auto&q=80` — and
every word in the caption above rewrites it live. A `button-outline` reading **Copy** sits at
the right of that line, and drops beneath it below 768px. **Nothing in this block is round.**
It is type, a rule, and a squared button — a printed page does not grow a knob underneath its
own photograph.
`dpr` is in the string before the visitor has touched a thing. On load the credit line takes
`&dpr=` and the number **this display actually reports** — `window.devicePixelRatio`, clamped
to the brief's 1–3. Nothing was estimated to get that figure and nothing was invented: the
browser volunteers it, and typesetting it is the only work the design does. It is also why
`dpr` never reads as unset — every display has a ratio, so the string always has one to
print, while an untouched `rot` or `blur` has nothing to contribute and contributes nothing.
The three daggered parameters are set in `--ink-meta` (5.33:1) and the rest in `--ink`
(21:1), so **the credit line is legible as two inks: what happened in this browser, and what
happened at the edge.**
> **`q` reads 75 in one place and 80 in another, and both readings are correct — do not
> "fix" this.** The brief gives `q` a default of 75, and the request form it prints as its
> own example carries `q=80`. A publication does not silently reconcile its sources: the
> spec table sets the default it was given, the credit line sets the URL it was given, and
> the difference between them belongs to the content, faithfully typeset.
### 2. The figure the caption drives
**The caption sets; the plate shows** — and the inversion is one a magazine has lived with
forever. The line under a picture is written after the picture; here it is written *by the
visitor*, and the picture obeys it.
The live-transform demo is **one figure made of two square-cornered plates** in the 680px
measure: the source on the left, the transformed result on the right, the right one *derived
from the left in the browser* by the seven values currently set in the sentence below. There
is no second image asset and no "optimized" version prepared in advance — the right plate is
the left plate under `object-fit`, `object-position`, `transform`, `filter`, and a background
colour. **Seven values are reachable in the caption because the browser honestly performs
seven operations; a caption that offered an eighth would be describing a picture it had not
seen.**
The pair is **one figure and takes one caption**, which is why the caption sits beneath both
plates and runs the full measure, and why it names them: *Left, the source. Right, the same
source…*. The index carries **two numbered figures** — the cover plate is Fig. 1, this pair
is Fig. 2 — because the three capability plates take a display head instead of a caption, and
a figure with no caption takes no number.
The live caption is set at 17px where the site's other captions are set at 12px, and the
reason is not emphasis. **A 12px control is not a control.** This caption is not read past on
the way to the next paragraph; it is *operated*, at the size a hand and a screen reader can
both find it, and 17px is the size this system already holds a URL at for exactly the same
reason.
The plates carry no border, no radius, no shadow, and no scrim, and the paper around them
does all the framing. **No type ever sits on top of either of them.** Below 768px the pair
stacks vertically. **It never becomes a drag-slider comparison**, which hides half of each
image at all times and is a marketing device rather than an editorial one.
### 3. The printed spec table
The ten-parameter reference, and the place the reference's editorial logic pays off hardest.
**It is a printed table, not a documentation component.**
- A **2px `--ink` rule** above the head. The head row in the 12px uppercase sans with `case`.
A **1px `--rule` hairline** beneath the head, **1px hairlines between the ten rows**, and a
**2px `--ink` rule** closing the block. Nothing else: no tint behind alternate rows, no
container, no border, no shadow, no fill — and **not one vertical rule**. A compositor
spends a rule where the eye is likely to lose its place, and the eye loses its place
crossing a row, never running down a column. A column is already a column; it does not
need a fence to prove it.
- **Four columns:** the **parameter** in the sans Key role (`--ink`); the **accepted values**
in the sans Data role with `tnum` (`--ink`); the **default** in the Data role
(`--ink-meta`); and the **description** in the 15px body serif with `onum` (`--ink-soft`).
- **Every row but `q`'s prints an em dash in the Default column, and the dashes are the
argument.** The brief fixes one default — `q` is 75 — and folio does not supply the rest
out of politeness. A column of dashes looks, for about a second, like an unfinished table;
then it reads as what it is, which is a publication declining to print something it was
not told. It is the "no invented facts" rule made **visible**, in the one column a
developer would audit first.
- The `fm`, `q`, and `dpr` rows carry the **dagger** after the parameter name. The footnote
sits beneath the closing rule.
The same table form, at a smaller scale, carries the **tier table** on pricing and the
**overage ledger** beneath it.
### 4. Running heads, folios, and the drop cap — the page furniture
The three marks that no software page has and every printed page does. They are cheap,
they are structural, and **together they are the thing a visitor cannot un-see.**
- **The running head** sits above every page's content, between two hairlines: the product
at the left, the section at the right, in 11px uppercase sans with `case` —
`REFRACT · QUICKSTART & REFERENCE`. It is the page telling you where in the publication
you are.
- **The folio** sits at the foot of every page, above the footer, centred, in the 12px sans:
`1 / 3`, `2 / 3`, `3 / 3`. The site has three pages and it says so.
- **The drop cap** opens the lead paragraph of each page — **the display serif at 400, three
lines deep, `--ink`** — followed immediately by the **run-in**: the next four words in
**true small caps** (`smcp`, Source Serif 4 roman). There is **exactly one drop cap per
page, on the lead paragraph, and nowhere else** — a second one on the same page is not
emphasis, it is noise, and it is the difference between a typeset page and a themed one.
## Components
- **Masthead band.** `--paper`, a 1px `--rule` hairline above and below, 12px 24px padding.
The wordmark **Refract** sits **centred** in the 26px Display M (Playfair Display 400) —
centred because that is where a masthead goes, and this is the one place the layout is
symmetrical.
- **Nav bar.** `--paper`, sitting under the masthead, closed by a 1px `--rule` hairline.
Three page links — **Home · Docs · Pricing** — in the 14px Nav role (Manrope 700),
`--ink`. The active link takes `aria-current="page"`, a **2px `--blue` rule beneath it**,
and no other change of colour. **The links are words.** There is no icon set beside them
and no flag above them: nothing in the content marks a page as new or recommended, and a
design that hangs a flag on a page has invented a fact to fill a component slot. Below
768px the row collapses; **the masthead never does.**
- **`button-primary`.** **`--ink` (`#000000`) fill, `--on-ink` white label** at the 16px
Button role (**21:1**), **0px radius**, 48px tall, 12 × 24px padding. Hover and press step
the fill to `--ink-soft` (`#1A1A1A`, white label at 17.4:1) — **a colour swap and nothing
else: no transform, no lift, no shadow.** This is the site's primary action —
**"Start building" → `./docs.html`** — and it appears **exactly once on the site, in the
index's CTA band.** The nav carries no button, and **docs and pricing carry no filled
button at all**: their actions are outlined. It is a black rectangle. **It is not a
colour; it is the ink.**
- **`button-outline`.** `--paper` fill, `--ink` label, **1px `--ink` bounding rule**, 0px
radius, 48px tall. Used for **Copy** — at the right of the URL credit line, and at the top
right of the SDK listing — and for **all three tier CTAs**, Free, Pro, and Scale alike.
**No tier CTA is ever `button-primary`:** the three columns are set identically, and
filling one CTA with ink would be a typographic recommendation that the content never
made.
- **Inline link.** `--blue-deep` (`#04618F`, **6.75:1**) with a 1px underline in the same
colour, inside body-serif copy only — exactly the place the reference reserves its blue
for. **Colour meets text in exactly two places in this design**: here, and in the
validation message a bad value in the caption prints beneath the credit line. Both are
`--blue-deep`, and **there is no third.**
- **`caption-value` — and there is no boxed input anywhere on this site.** The editable word
inside the live caption, in the Live caption role: **`--ink` at the sans's 600** among
running words at `--ink-meta` 400. Hover and edit draw the **writing rule** — a 1px `--ink`
bounding hairline the width of the slug — and focus draws the **2px `--ink` outline at a 2px
offset**. Editing gives it a caret and nothing else: no fill, no border box, no placeholder
ink. A slug cleared to nothing prints an em dash in `--ink-meta` (5.33:1). A value outside
its range (a `blur` outside the brief's 0–100, a `bg` that is not six hex characters) keeps
the last good value on the plate and prints a message in `--blue-deep` beneath the credit
line — **the same blue as a link, not a semantic second colour**, because this system has no
error red and will not grow one. Three kinds, and no fourth: a **numeral** (drag-scrub on a
fine pointer, `role="spinbutton"` on a keyboard, `−` / `+` marks on a coarse one), an
**enum word** (opens a `caption-list`), and a **hex** (six characters, typed). Full mechanics
in *Signature 1*.
- **`caption-list`.** The short list that hangs beneath an enum word, in the flow of the
caption block: one option per line, left-aligned to the word's left edge, same face, same
size, **no box, no border, no fill, no shadow**, closed by a 1px `--rule` hairline. The
current option takes a **2px `--blue` rule beneath it**, steps to weight 600, and carries
`aria-selected="true"`. **Not a pill, not a chip, not a segmented control, not a dropdown
floating over the page, and never rounded.**
- **`caption-stepper`.** Coarse pointers only, present only while a numeral holds focus: a
**`−`** and a **`+`**, each a 24px square with a 1px `--ink` bounding rule and a 0px radius,
padded to a 44px touch target, sitting in the flow after the slug. Each mark is drawn with
the same rules everything else here is drawn with. **It is `aria-hidden`, it carries
`tabindex="-1"`, and it takes `preventDefault()` on `pointerdown` — so it is not a tab stop,
not a node a screen reader lands on, and not a thing that can steal focus from the numeral
that printed it.** That is load-bearing, not tidy: the marks are conditional on the numeral
holding focus, so **a focusable stepper would blur the numeral, be removed in the same
instant, and destroy the node the visitor was standing on.** It costs nobody the increment —
the numeral is a `role="spinbutton"` with `aria-valuenow` and Up/Down (*Signature 1*), which
is the route a keyboard and an assistive technology already take, and the stepper is only the
route a thumb takes. It is the caption's one concession to a thumb, it is made of rules, and
it leaves when focus leaves.
- **`shoulder-note`.** The unkeyed marginal gloss beside the live caption on index, and the
design's answer to a sentence that grows: the **15px Body S role in its italic** in
`--ink-soft` (17.40:1), ragged right, under a 1px `--rule` hairline, set in the 300px outer
column against the caption's first line — and beneath the credit line, above the dagger
footnote, below 1024px. **It carries no footnote mark**, because a mark promises that
something was left out of the sentence and nothing was: the clause is not missing, it is not
true yet (*Signature 1*). It has no `role`, no `tabindex`, and no focus state, and it **adds
nothing to the tab order** — it reaches a screen reader as the `aria-describedby` of the
height value and of the `fit` word, the two controls that open what it describes. It is
withdrawn once a height is set and a fit chosen, and it returns if the height is cleared.
**It is never a tooltip, a popover, a disclosure, or a badge.** It is prose in a margin,
which is always already open.
- **`credit-line`.** The URL beneath the live caption, under a 1px `--rule` hairline: the
17px sans URL role with `tnum`, the three daggered parameters in `--ink-meta` and the rest
in `--ink`, with a `button-outline` **Copy** at its right (beneath it below 768px). It is
set the way a magazine sets a source credit under a plate, and it is the only place on the
site where the literal `w=1200` a developer will paste is printed.
- **`plate` — and there is no card in this system.** A photograph is a **plate**: a
square-cornered image with **no border, no radius, no shadow, no overlay, and no scrim**,
and a caption beneath it — the 12px sans on every plate but the demo's, which takes the
17px live caption (*Signature 1*). The reference's story-card is a photograph, a
headline, and a paragraph sitting on the page with nothing around them but a column rule —
and that is exactly what the capability trio is. **The three capabilities are three
columns of the grid, not three cards**, and giving them a border would be the first step
back toward the SaaS page this design exists to refuse.
- **Spec table.** As set out in *Signature 3*: 2px `--ink` rule above the head, hairlines
between rows, 2px `--ink` rule below, no fill, no striping, no vertical rules, dagger on
the three server-side rows, footnote beneath.
- **Listing — and it is not a code block.** The SDK snippet sits on **`--paper-tint`**
(`#F5F5F5`) — **the only tinted surface in the design** — with a **2px `--ink` rule above
it and a 1px `--rule` hairline below it**, 0px radius, no border box, no shadow, 32px
padding. It is set in the **sans** Listing role (15px / 1.7, `tnum`) in `--ink-soft`
(15.96:1 on the tint), with **ruled line numbers hung in the left margin** in `--ink-meta`
(4.89:1 on the tint — body-legal) behind a 1px `--rule` vertical. A `button-outline`
**Copy** sits at its top right. **There is no syntax-highlight palette** — this design has
one colour and will not spend it on a language keyword. Emphasis inside the listing, where
it is needed, is weight 700 of the same sans and nothing else.
- **`tier-column` — and there is no tier card in this system.** The three plans are **three
columns of one printed comparison table**, not three cards: a row-label column at the left,
then Free, Pro, and Scale. The head of each tier column carries the tier name in the 26px
Display M and the price beneath it in the 40px **Price** role with `lnum` (`$0`, `$29`,
`$249`), with `/mo` stepping down to the sans. Then hairline-divided rows — transforms,
bandwidth, support, custom domains, uptime SLA, billing — with every value in the sans Data
role with `tnum` **so the figures lock into a column down each tier**, and an **em dash**
wherever a tier does not carry the thing. The block is closed by a 2px `--ink` rule, and
the three `button-outline` CTAs sit beneath their columns. **No tier is marked
"recommended," "popular," or "best value."** The brief ranks nothing, and a publication
does not print a recommendation it was never given. The three columns are set identically
and the reader draws the conclusion, which is what a comparison table has always been for.
- **`ledger-row`.** A hairline-divided full-width row: the label hung at the left in the sans
Key role, the value at the right in the Data role with `tnum`. It carries the overage and
billing semantics on pricing ( `$2` per additional 1,000 transforms · `$0.08`/GB · a
transform is one unique source-and-parameter combination per billing month · cached hits
are free ) and the caching and limits inside the `AT A GLANCE` box on docs ( 50
requests/second per key, all tiers · variants edge-cached 30 days · instant purge by URL or
tag ). **No card, no fill, no shadow.**
- **`standing-box`.** A ruled box in the outer column, made of rules and nothing else: a 2px
`--ink` rule on top, a standing head, a one-line italic deck in the body serif, then
hairline-divided ledger rows, then a hairline at the foot. **No fill, no border box, no
shadow, no radius.** It carries the **`AT A GLANCE`** box on docs. **It holds no controls —
the live caption is the only control surface in this design**, and a box that grew a
control would be the row-panel this design threw away.
- **FAQ row.** A full-width disclosure row, 1px `--rule` between rows, in the 680px measure:
the question in the 26px Display M (Playfair Display 400 — **not bold**), the answer in the
15px Body S with `onum`. The marker at the right of a closed row is a **plus**: a 12px
`--ink` horizontal rule with a vertical one laid across it. Opening the row takes the
vertical stroke away and leaves a minus. Both strokes are pseudo-elements — which is to say
they are rules, like every other mark here. **The site loads no icon font and draws no SVG.**
**No card, no fill, no shadow, no box.** A question, its answer, and a rule between them is
what a printed Q&A has always been.
- **Footnote.** A dagger (`†`) in `--ink` after a key or a word, and a 15px Body S line set
where the block it belongs to can see it. It serves one subject only — the three
server-negotiated parameters — and it appears in two places: **in the outer column beside
the live caption on index**, and **beneath the spec table on docs**. A note to a figure goes
in the margin; a note to a table goes under the table.
- **Folio.** A 12px sans line, centred, above the footer, between two hairlines: `1 / 3`.
- **Footer.** **`--paper` — white, exactly like the page.** A 2px `--ink` rule above it, 48 ×
24px padding, three columns of 14px sans links in `--ink`, closed by a 1px `--rule`
hairline and a 12px `--ink-meta` legal row (5.33:1). **The reference closes on a black
footer band and this design does not: a sheet of paper has no black slab at its foot, and
the page never inverts.**
## Motion
**Essentially none, and never decorative.** A printed page does not move when you look at
it. The only thing motion is spent on here is making a control feel immediate.
- **The figure answers the word within one frame.** Change a value and the plate repaints
immediately. There is no artificial delay, no skeleton, no shimmer — and above all no
spinner, because **there is no request in flight.** Nothing is being fetched, nothing is
being re-encoded, and a page that mimes waiting is lying about the machine it is running
on.
- **A word is substituted, not animated.** No cross-fade when a value changes, no slide when
a conditional clause arrives or leaves, no typewriter effect on the URL as it rewrites. A
numeral counts while a visitor drags it, which is not an animation — it is the visitor's
own hand — and `tnum` plus a frozen slug keep it from shaking the sentence while it does
(*Signature 1*).
- **No scroll animation, no reveal-on-scroll, no parallax, no scroll-jacking, no
hover-zoom on a photograph, no looping anything.** No element in this system carries a
`box-shadow`, at rest or on hover, so there is nothing to lift.
- **No count-up on the stats box.** Ink does not arrive at a number. It is already there
when the page is opened, which is the only tense a printed figure has.
- Hover and focus are **underlines, weight steps, and colour swaps only**, at ~120ms
ease-out, **with no transform — no scale, no lift, no bounce.** A nav link gains an
underline; an editable value gains its writing rule; `button-primary` steps its fill to
`--ink-soft`; an FAQ row's question gains an underline; a table row does not react at all,
because a printed table does not.
- **Focus is a 2px `--ink` outline** (21:1) at a 2px offset, on every interactive element,
and it is never removed.
- Under **`prefers-reduced-motion: reduce`**, every transition is dropped and every element
renders in its final state — the FAQ rows open instantly, a caption list appears with no
easing, the writing rule appears with no fade. **The page is fully legible at rest, which
is the only state paper has ever had.**
## Image treatment
**The bundle runs one picture desk, and it does not commission a second.** Every image in
this system is a **real photograph in a reportage register**: available natural light,
documentary framing, a real object in a real place, unstyled and unretouched-looking — the
kind of frame a technology monthly runs beside a feature. **There is no illustration, no
vector art, no icon set, no diagram, no schematic, no chart, no 3D render, and no
"flat" anything.** If it is not a photograph or type, it does not belong on this site.
The photographs are a **photo essay on light** — a darkroom, an enlarger's projected
rectangle, a stack of filters on a lightbox, a relay tower, a lens throwing a caustic. The
subject of the product is what happens to an image between an origin and a browser, and the
photographs are about exactly that, rather than about developers at desks.
**The reportage register is about the light and the framing, not about people — and this is
the one tension in the transplant, so it is resolved here explicitly.** Reportage normally
means *people*, and the instinct the lineage carries is to put someone in the darkroom.
**Resist it. Every frame in this bundle is unpeopled.** The practical reason is that the
image model cannot draw a hand — it fuses the fingers into a knuckleless mass — and **you do
not re-roll your way out of that. You clear the hands out of the room and photograph what is
left.** The editorial reason is the better one: what runs beside this article is not
lifestyle photography, it is a **specimen** — the raw material the API is about to act on —
and putting a person in a specimen quietly changes what the page is claiming.
**How every image in this system is prompted.** These are binding rules, and a generated
image that breaks one is rejected and re-generated rather than accepted and cropped around.
1. **Nothing in frame carries language.** Every prompt states, explicitly and in its own
clause, that the image contains **no text, no lettering, no numerals, no labels, no
logos, no brand markings, no signage, no dials or scales bearing numbers, and no engraved
or stamped marks of any kind** — not on the equipment, not on the wall, not in the
background, not anywhere. Invented lettering is the single most common failure in a
generated still, it reads as counterfeit branding, and darkroom equipment is exactly the
subject matter that tempts a model into inventing a maker's plate. Every apparatus in
these frames is **unmarked**.
2. **No people and no hands.** Not one, not in the background, not out of focus. See above —
this rule needs stating twice because the reportage lineage fights it.
3. **The frame is quiet and uncluttered.** No props beyond the subject each description
names, no scattered incidental objects, no busy lived-in scenes.
4. **`demo-plate` must survive being taken apart.** It is cropped to 1:1, blurred to 100,
rotated 270°, and letterboxed against a `bg` colour — live, in front of the visitor. **It
has to read as a considered photograph in every one of those states, because the line
printed underneath it is claiming that it does.** And **its subject must sit well
off-centre**:
*smart crop keeps subjects in frame* is a claim the brief makes, and a photograph whose
subject is already dead centre lets `crop=smart` and `crop=center` land on the very same
frame. The caption would then be asserting something the picture cannot show, which is
the one thing a caption must never do.
Beyond those, each prompt carries the constant tone words: **available natural light,
documentary reportage photograph, real place, unstyled, still and quiet, no people, no
text.** Crops hold identical framing across breakpoints — this design never art-directs a
still into a dramatic mobile crop — **no image is ever full-bleed**, every plate is
square-cornered, and **no image ever has type set on top of it.** The caption sits beneath,
in the sans.
Needed images (referenced `./assets/<id>.webp`):
- `cover-plate` (16:9) — A dim darkroom under an amber safelight: three shallow developing
trays set in a long sink, still liquid catching the light, a wet bench, deep shadows,
available light, documentary reportage photograph, nothing else in frame, unmarked
equipment, no text, no lettering, no numerals, no labels, no logos, no brand markings, no
signage, no dials or scales bearing numbers, no engraved or stamped marks, no people, no
hands.
- `demo-plate` (4:3) — A red-painted iron fire escape zig-zagging up the left third of a
plain sunlit brick wall, its hard afternoon shadow thrown across the empty right two-thirds
of the frame, the staircase set well off-centre, available daylight, documentary reportage
photograph, no text, no lettering, no numerals, no labels, no logos, no brand markings, no
signage, no dials or scales bearing numbers, no engraved or stamped marks, no people, no
hands.
- `capability-transform` (4:3) — A darkroom enlarger easel holding a single blank sheet of
photographic paper, a bright rectangle of projected light falling across it at an angle,
dim room around it, unmarked equipment, no dials, no scales, available light, documentary
reportage photograph, no text, no lettering, no numerals, no labels, no logos, no brand
markings, no signage, no engraved or stamped marks, no people, no hands.
- `capability-optimize` (4:3) — A stack of neutral-density glass filters resting edge-on on a
glowing lightbox, each sheet slightly offset from the last so the light deepens through the
stack, sharp macro detail, available light, documentary reportage photograph, no text, no
lettering, no numerals, no labels, no logos, no brand markings, no signage, no dials or
scales bearing numbers, no engraved or etched marks on the glass, no people, no hands.
- `capability-deliver` (4:3) — A lattice relay tower standing on a bare hillside at dusk,
small dishes at its crown, a plain open sky behind it, available light, documentary
reportage photograph, nothing else in frame, no text, no lettering, no numerals, no labels,
no logos, no brand markings, no signage, no dials or scales bearing numbers, no engraved or
stamped marks, no people, no hands.
- `docs-plate` (1:1) — A single thick glass lens element lying on a dark workbench, a shaft
of window light passing through it and throwing a bright refracted caustic across the wood,
available daylight, documentary reportage photograph, nothing else in frame, no text, no
lettering, no numerals, no labels, no logos, no brand markings, no signage, no dials or
scales bearing numbers, no engraved or etched marks, no people, no hands.
- `pricing-plate` (3:4) — A tall column of daylight falling through a high dusty window into
an empty workshop, the beam striking a plain concrete floor, dust suspended in the air,
available light, documentary reportage photograph, tall portrait, nothing else in frame, no
text, no lettering, no numerals, no labels, no logos, no brand markings, no signage, no
dials or scales bearing numbers, no engraved or stamped marks, no people, no hands.
## Do / Don't
Do:
- Keep the paper white (`--paper` `#FFFFFF`) and the ink black (`--ink` `#000000`), and keep
the footer the same white as the page.
- Hold the display serif at **weight 400 at every size**, including the 64px cover line.
- Split the three voices absolutely: **Playfair Display for display, Source Serif 4 for every
paragraph, Manrope for metadata, captions, buttons, nav, and every literal API token.**
- Print the grid: a **680px measure that never widens**, 1px column rules between columns,
hairlines between rows, a 2px `--ink` rule above every table head and every box.
- Give every page its **running head**, its **folio**, and **exactly one drop cap** on its
lead — with the four-word small-caps run-in after it (`smcp`, Source Serif 4 roman).
- Set figures in prose as **old-style** (`onum`, Source Serif 4) and figures in a box or a
table as **lining** (`lnum` on the display serif — its default is old-style; `tnum` on the
sans Data, Listing, URL, and Live caption roles).
- **Build the playground inside the demo figure's caption.** The seven parameters are words
in a live sentence: black at the sans's 600 among grey running words at 400; a numeral that
scrubs and steps; an enum word that opens a short list hung beneath it; a `bg` that is a hex
you type. **No panel, no rows, no key column, no value column, no slider, no swatch.**
- Keep the seven browser-honest parameters (`w` `h` `fit` `crop` `rot` `blur` `bg`)
interactive and genuinely wired to the photograph, and mark `fm` `q` `dpr` with a **dagger
and a footnote** — in the caption's second sentence and in the spec table.
- **Let a clause exist only while its parameter is doing something** — the fit clause needs a
height, the crop clause needs a cropping fit, the `bg` clause needs `contain` — and let an
unset value read as a **word** (*unrotated*, *unblurred*, *own*), never as a greyed-out row.
**The cost is that four controls are visible at load and three are not, and it is paid, not
hidden** (*Signature 1*).
- **Signpost the growth in the margin, and only in the margin.** The **shoulder note** — an
unkeyed italic gloss in the outer column beside the caption's first line — is what tells a
reader the sentence takes a `fit` once a height is set, a `crop` once the fit crops, and a
`bg` once the fit is `contain`. It carries **no footnote mark, no tab stop, and no `role`**;
it reaches assistive technology as the `aria-describedby` of the height value and the `fit`
word; and it is withdrawn once the path it describes has been walked. **It is never a
tooltip, a popover, a badge, or a greyed row** — those are the four answers this design
refuses.
- Print an **em dash** where a table cell has nothing to put in it, and for every default the
brief does not state.
- Set the ten-parameter reference as a **printed spec table** — horizontal rules only, no
striping, no card, no shadow — and the three plans as **three columns of one printed
table**, not three cards.
- Set every corner at **0px**, and let the paper be the only elevation.
- Keep `--ink-meta` (5.33:1 on paper, 4.89:1 on the tint) for metadata and `--blue-deep`
(6.75:1) for every blue that carries text.
Don't:
- **Never bold the display serif.** There is no 500, no 600, and no 700 of Playfair Display
in this system. Promoting it destroys the design, and it is the single easiest way to do so.
- **Never set body copy in the sans, and never set nav, a button, a table head, or a URL in a
serif.** The three-voice split is absolute.
- **No monospace anywhere in this system.** Not in the URL, not in the listing, not in the
parameter names, not in a caption. **A monospace body is `carton`'s language**, and reaching
for one here is the first step toward becoming it.
- **No hand-drawn shape, no wobbly rule, no sticker badge, and never a fourth type voice.**
Every rule in this design is ruled straight, because a press does not wobble; every mark is
set, not scrawled. **These four are `carton`'s signature devices — the other paper design in
this brief — and the split between the two of us is the one that has to stay legible.** The
italic of Source Serif 4 is a *style of the body serif*, not a fourth voice.
- **No dark band anywhere** — no dark hero, no dark section, and **no dark footer.** The page
never inverts. Paper has no night mode; `cutaway` does, and it is welcome to it.
- **No rounded corner and no circle.** Radius is 0px on every element. A pill or an orb is
`aperture`'s language.
- **No `box-shadow` anywhere**, at rest or on hover, on any element. Depth is the rule, the
paper, and the shadow inside a photograph.
- **No second hue.** No green success, no amber warning, no separate error red, no
syntax-highlight palette. One editorial blue, two stops.
- **Never let the blue become a fill.** White on `--blue` (`#057DBC`) is **4.50:1** — the same
knife-edge as blue on white, because contrast is symmetric — and a blue button would make
the blue an accent, which the reference forbids. **`--blue` is rules and marks only; it never
carries text and it never appears on `--paper-tint` (4.13:1 — it fails there).** Blue that
carries text is `--blue-deep` (`#04618F`, 6.75:1 / 6.19:1).
- **No card and no tier card.** The capability trio is three columns of the grid; the three
plans are three columns of one table. A border around either is the first step back to the
page this design refuses.
- **Never rebuild the playground as a panel.** No row list of key · control · value, no
sliders, no swatch row, no segmented control, no boxed input, no bottom sheet on mobile,
and no floating popover over the page. The vertical console belongs to `cutaway` and it
belongs there for a reason. **If a control cannot be said as a word in the caption, this
design does not have it.**
- **Type never sits on top of a photograph.** There is no scrim in this system to make it
legible, and a caption beneath the plate is the correct place for the words.
- **No illustration, no vector art, no icon set, no diagram, no chart.** Every image is a
photograph in a reportage register. Every mark is a rule or a letter: the FAQ's plus is two
rules laid across each other, and the site ships neither an icon font nor a single SVG.
- **No people and no hands in any generated image**, however strongly the reportage lineage
suggests otherwise.
- **No invented facts, and no invented numbers.** No byte count beside the plate, no payload
figure shrinking in an animation, no latency the brief did not supply, no "most popular"
tier, no "NEW" badge, and **no default in the spec table except the one the brief states
(`q` = 75)** — every other row prints an em dash. Every figure this site *asserts* — 62%,
21 ms, 98.6%, 99.95%, 41 edge locations, 89 ms / 340 ms cold, 50 requests per second, 30
days, $0 / $29 / $249, 1,000 / 50,000 / 1,000,000 transforms, 5 GB / 250 GB / 5 TB, $2 per
1,000, $0.08/GB, `q` default 75, `q` 1–100, `dpr` 1–3, `blur` 0–100, `rot` 90/180/270 —
comes from the brief. The only other numbers a visitor will see are the ones **they set
themselves in the caption** and the **pixel ratio their own browser reports**, and not one
of those is a claim this design is making.
- **No count-up animation, no charts, no sparklines, no scroll parallax, no reveal-on-scroll.**
- No emoji anywhere, and **no naming of the source reference in the built page** — the
reference is named in this document's Concept and nowhere else. The site carries the
product's own name, **Refract**, in English, and nothing else.