spec.json
The normative source. Every value the spec sets, with units. Where an implementation and this file disagree, this file is right.
1{
2 "name": "typeset",
3 "version": "1.0.0",
4 "updated": "2026-08-28",
5 "owner": "Adilson Carvalho",
6 "canonical_url": "https://typeset.adilsoncarvalho.com",
7 "intent": "A normative typographic specification for printed documents — essays, letters, reports. This file is the source of truth. CSS, Typst, LaTeX or any other implementation conforms to it; where an implementation and this file disagree, this file is right.",
8 "target": "Paper and PDF at 100% scale. Not screens, not reflowing layouts.",
9 "conformance": [
10 "Every length is absolute. Points (pt) and millimetres (mm) mean the same thing in every engine; 1pt = 1/72in.",
11 "A length given in em is relative to the font size of the element it is declared on, not to the document base.",
12 "line_height is a multiple of the element's own font size, and defines the baseline-to-baseline advance. An engine whose leading is measured between line boxes rather than between baselines must derive its value from the resulting advance, stated per element in baseline_advance.",
13 "An implementation MUST reproduce every value under `properties`. It MAY add anything the target engine needs to achieve them.",
14 "Where an engine cannot express a property, it must fail visibly or degrade as named in `fallback` — never silently.",
15 "Colour is sRGB. Ink is never pure black: #000 blooms on laser output and glares in a backlit PDF.",
16 "Deriving leading: where the engine measures the gap between line boxes rather than between baselines, pin the line box to the band from the baseline up to 1em (in Typst: top-edge: 1em, bottom-edge: 0pt). The advance is then 1em + leading, so leading = (line_height - 1) em, independent of the font's own metrics."
17 ],
18 "foundation": {
19 "page": {
20 "size": "A4",
21 "size_mm": [
22 210,
23 297
24 ],
25 "alternate_size": "Letter",
26 "margin_top_mm": 25,
27 "margin_bottom_mm": 25,
28 "margin_outer_mm": 22,
29 "margin_inner_mm": 28,
30 "duplex": "Margins mirror: the inner (binding) margin is 28mm on both left and right pages, so the gutter stays put when printed double-sided.",
31 "text_width_mm": 160,
32 "running_head": {
33 "position": "top centre",
34 "content": "the current level-2 heading, uppercased",
35 "font": "sans",
36 "size": "8pt",
37 "tracking": "0.08em",
38 "color": "ink_faint",
39 "suppressed_on": "first page"
40 },
41 "folio": {
42 "position": "bottom centre",
43 "content": "page number",
44 "font": "serif",
45 "size": "9pt",
46 "numerals": "oldstyle",
47 "color": "ink_muted",
48 "suppressed_on": "first page"
49 }
50 },
51 "fonts": {
52 "serif": {
53 "role": "body text — the reading face",
54 "family": "EB Garamond",
55 "license": "OFL",
56 "fallbacks": [
57 "Iowan Old Style",
58 "Palatino",
59 "Georgia",
60 "serif"
61 ],
62 "weights": [
63 400,
64 600
65 ],
66 "styles": [
67 "normal",
68 "italic"
69 ],
70 "features": [
71 "oldstyle figures",
72 "small caps",
73 "standard ligatures",
74 "kerning"
75 ],
76 "note": "Set no smaller than 11pt. Below that the strokes thin out on office laser output."
77 },
78 "sans": {
79 "role": "headings, tables, captions, labels",
80 "family": "Source Sans 3",
81 "license": "OFL",
82 "fallbacks": [
83 "Helvetica Neue",
84 "Helvetica",
85 "Arial",
86 "sans-serif"
87 ],
88 "weights": [
89 300,
90 600,
91 700
92 ],
93 "styles": [
94 "normal",
95 "italic"
96 ],
97 "note": "Humanist, so it sits with an old-style serif instead of fighting it."
98 },
99 "mono": {
100 "role": "code, listings, technical identifiers",
101 "family": "IBM Plex Mono",
102 "license": "OFL",
103 "fallbacks": [
104 "SF Mono",
105 "Menlo",
106 "Consolas",
107 "monospace"
108 ],
109 "weights": [
110 400,
111 600
112 ],
113 "styles": [
114 "normal",
115 "italic"
116 ],
117 "features": [
118 "ligatures disabled"
119 ],
120 "note": "Monospaced faces run optically large beside a serif; every size below is already corrected for it."
121 },
122 "embedding": "Font files MUST be embedded in the output. A document that resolves its fonts at print time is not reproducible."
123 },
124 "scale": {
125 "ratio": 1.2,
126 "base": "11pt",
127 "steps": {
128 "xs": "8pt",
129 "sm": "9.5pt",
130 "base": "11pt",
131 "h4": "12pt",
132 "h3": "14pt",
133 "h2": "18pt",
134 "h1": "24pt"
135 }
136 },
137 "rhythm": {
138 "line_height": 1.45,
139 "line_height_tight": 1.2,
140 "baseline_advance": "15.95pt",
141 "space": "11pt",
142 "space_note": "One unit of vertical space is 11pt — one line of base leading, near enough. Every gap below is a multiple of it.",
143 "measure": "33em",
144 "measure_mm": 126,
145 "measure_chars": 66,
146 "measure_note": "The single largest legibility lever. Past about 75 characters the return sweep fails and readers re-read lines without noticing; below 45 the eye fixates too often.",
147 "measure_variants": {
148 "narrow": "27em",
149 "wide": "40em"
150 }
151 },
152 "color": {
153 "ink": {
154 "hex": "#1a1a1a",
155 "role": "body text"
156 },
157 "ink_muted": {
158 "hex": "#5a5a5a",
159 "role": "captions, attributions, secondary text"
160 },
161 "ink_faint": {
162 "hex": "#8a8a8a",
163 "role": "labels, list markers, running heads"
164 },
165 "rule": {
166 "hex": "#c9c4bd",
167 "role": "hairlines, table body rules"
168 },
169 "rule_strong": {
170 "hex": "#6f6a64",
171 "role": "table header and footer rules, block accents"
172 },
173 "wash": {
174 "hex": "#f4f1ec",
175 "role": "code and callout backgrounds"
176 },
177 "accent": {
178 "hex": "#7a1f1f",
179 "role": "drop caps, note markers, fleurons",
180 "note": "Oxblood. Chosen to read as a dark grey when printed in greyscale."
181 }
182 }
183 },
184 "sections": [
185 {
186 "id": "headings",
187 "title": "Headings",
188 "group": "Structure",
189 "principles": [
190 "Sans against the serif body, so hierarchy reads by contrast rather than by size alone.",
191 "Below level 4 the size stops changing and the register shifts instead — small caps, then italic. Six distinct levels inside a 24pt–11pt range.",
192 "Space above is four times the space below: a heading belongs to what follows it.",
193 "A heading MUST NOT be the last thing on a page. This is the most common defect in printed documents."
194 ],
195 "elements": [
196 {
197 "id": "h1",
198 "name": "Heading 1 — document title",
199 "properties": {
200 "font": "sans",
201 "weight": 300,
202 "size": "24pt",
203 "line_height": 1.2,
204 "baseline_advance": "28.8pt",
205 "tracking": "-0.015em",
206 "color": "ink",
207 "align": "left",
208 "space_before": "0",
209 "space_after": "5.5pt",
210 "break_after": "avoid",
211 "break_inside": "avoid",
212 "wrap": "balanced"
213 }
214 },
215 {
216 "id": "h2",
217 "name": "Heading 2 — section",
218 "properties": {
219 "font": "sans",
220 "weight": 600,
221 "size": "18pt",
222 "line_height": 1.2,
223 "baseline_advance": "21.6pt",
224 "tracking": "-0.01em",
225 "color": "ink",
226 "align": "left",
227 "space_before": "22pt",
228 "space_after": "5.5pt",
229 "break_after": "avoid",
230 "break_inside": "avoid",
231 "wrap": "balanced",
232 "sets_running_head": true
233 }
234 },
235 {
236 "id": "h3",
237 "name": "Heading 3 — subsection",
238 "properties": {
239 "font": "sans",
240 "weight": 600,
241 "size": "14pt",
242 "line_height": 1.2,
243 "baseline_advance": "16.8pt",
244 "color": "ink",
245 "align": "left",
246 "space_before": "22pt",
247 "space_after": "5.5pt",
248 "break_after": "avoid"
249 }
250 },
251 {
252 "id": "h4",
253 "name": "Heading 4",
254 "properties": {
255 "font": "sans",
256 "weight": 600,
257 "size": "12pt",
258 "line_height": 1.2,
259 "baseline_advance": "14.4pt",
260 "color": "ink",
261 "align": "left",
262 "space_before": "22pt",
263 "space_after": "5.5pt",
264 "break_after": "avoid"
265 }
266 },
267 {
268 "id": "h5",
269 "name": "Heading 5",
270 "properties": {
271 "font": "serif",
272 "weight": 600,
273 "size": "11pt",
274 "variant": "all small caps",
275 "tracking": "0.06em",
276 "color": "ink",
277 "space_before": "22pt",
278 "space_after": "5.5pt",
279 "break_after": "avoid"
280 },
281 "notes": [
282 "No size change from body — the register carries the level."
283 ]
284 },
285 {
286 "id": "h6",
287 "name": "Heading 6",
288 "properties": {
289 "font": "serif",
290 "weight": 400,
291 "style": "italic",
292 "size": "11pt",
293 "color": "ink",
294 "space_before": "22pt",
295 "space_after": "5.5pt",
296 "break_after": "avoid"
297 }
298 },
299 {
300 "id": "heading-run-in",
301 "name": "Run-in heading",
302 "properties": {
303 "display": "inline with the first line of its paragraph",
304 "separator": " · ",
305 "separator_color": "ink_faint",
306 "space_before": "0",
307 "space_after": "0"
308 },
309 "notes": [
310 "For dense reports where a full heading line is too much vertical cost."
311 ]
312 }
313 ]
314 },
315 {
316 "id": "numbering",
317 "title": "Section numbering",
318 "group": "Structure",
319 "opt_in": "typeset--numbered",
320 "principles": [
321 "Numbers are generated by a counter, never typed. A typed number drifts the moment a section moves.",
322 "Reports are numbered; essays and letters are not. It must be one switch."
323 ],
324 "elements": [
325 {
326 "id": "number-h2",
327 "name": "Level-2 number",
328 "properties": {
329 "format": "1",
330 "separator": "two spaces",
331 "color": "ink_faint",
332 "numerals": "lining tabular",
333 "resets": "the level-3 counter"
334 }
335 },
336 {
337 "id": "number-h3",
338 "name": "Level-3 number",
339 "properties": {
340 "format": "1.1",
341 "separator": "two spaces",
342 "color": "ink_faint",
343 "numerals": "lining tabular"
344 }
345 }
346 ]
347 },
348 {
349 "id": "paragraphs",
350 "title": "Paragraphs",
351 "group": "Prose",
352 "principles": [
353 "Two conventions, one switch. Spaced paragraphs suit documents that get skimmed. Indented paragraphs with no gap suit continuous prose and are the convention of nearly every printed book.",
354 "The first paragraph after any heading, block or break is flush left: the thing above it has already marked the start."
355 ],
356 "elements": [
357 {
358 "id": "paragraph",
359 "name": "Paragraph — spaced (default)",
360 "properties": {
361 "font": "serif",
362 "weight": 400,
363 "size": "11pt",
364 "line_height": 1.45,
365 "baseline_advance": "15.95pt",
366 "numerals": "oldstyle proportional",
367 "color": "ink",
368 "space_after": "11pt",
369 "first_line_indent": "0",
370 "orphans": 2,
371 "widows": 2,
372 "max_width": "33em"
373 }
374 },
375 {
376 "id": "paragraph-indented",
377 "name": "Paragraph — indented",
378 "opt_in": "typeset--indented",
379 "properties": {
380 "space_after": "0",
381 "first_line_indent": "1.5em",
382 "first_line_indent_after_block": "0"
383 },
384 "notes": [
385 "Applies after a heading, blockquote, figure or section break, and to the first paragraph of the document."
386 ]
387 }
388 ]
389 },
390 {
391 "id": "justification",
392 "title": "Alignment: ragged or justified",
393 "group": "Prose",
394 "opt_in": "typeset--justified",
395 "principles": [
396 "Ragged right is the DEFAULT, and it is a choice rather than an absence — a document states it. Justification buys a clean right edge at the cost of uneven word spacing; a ragged setting keeps the spacing even and gives up the edge. Neither is more correct, but the cost lands differently by document.",
397 "Choose ragged right for a letter, a memorandum, a short note — anything addressed to a person rather than to a readership. Justification reads as institutional, and its even edge is the visual signature of print that was set for strangers.",
398 "Choose justification for continuous prose at a full measure: an essay, a report, a paper. It is mandatory in two columns, where a ragged edge at 47 characters serrates the column.",
399 "These are a single decision. Justification without hyphenation opens rivers of white space; hyphenation without justification breaks words for no gain. Take both or neither.",
400 "Hyphenation is per-language and requires the document language to be declared. An English dictionary applied to Portuguese produces confident nonsense.",
401 "The last line of a paragraph is NEVER stretched. State this explicitly — a paginating engine fragments the text, so the visual last line stops looking like the end of a paragraph and gets justified. It does not reproduce in an unpaginated preview.",
402 "Justification applies to prose only. It MUST NOT reach a subtitle, byline, caption, address block, table cell, heading or listing. In an engine where alignment inherits, every such block declares its own alignment rather than relying on an exception list.",
403 "Alignment inherits, and so does last-line alignment. A block that sets its own alignment — a centred pull quote, a centred section break — must also set its own last-line alignment, or the document's justification flushes its last line (its only line, for a one-liner) to the left."
404 ],
405 "elements": [
406 {
407 "id": "ragged-prose",
408 "name": "Ragged right (default)",
409 "opt_in": "typeset--ragged — names the default; no class needed to get it",
410 "properties": {
411 "align": "left",
412 "align_last_line": "left",
413 "hyphenation": "manual — never automatic",
414 "line_breaking": "high effort: avoid a very short last line, and even out the right edge",
415 "applies_to": [
416 "paragraph",
417 "list item",
418 "blockquote",
419 "definition description",
420 "callout"
421 ]
422 },
423 "notes": [
424 "Hyphenation exists to serve justification. Without justification a hyphen breaks a word for no gain, so it stays off.",
425 "The rag itself is the thing to judge: an even rag reads as deliberate, a rag with one very short line and one very long one reads as an accident."
426 ]
427 },
428 {
429 "id": "justified-prose",
430 "name": "Justified",
431 "properties": {
432 "align": "justify",
433 "align_last_line": "left",
434 "justify_method": "inter-word",
435 "hyphenation": "automatic",
436 "hyphenation_min_word_chars": 6,
437 "hyphenation_min_chars_before_break": 3,
438 "hyphenation_min_chars_after_break": 3,
439 "max_consecutive_hyphens": 2,
440 "applies_to": [
441 "paragraph",
442 "list item",
443 "blockquote",
444 "definition description",
445 "callout"
446 ]
447 }
448 },
449 {
450 "id": "justified-exclusions",
451 "name": "Never justified",
452 "properties": {
453 "align": "left",
454 "hyphenation": "manual",
455 "applies_to": [
456 "all headings",
457 "subtitle",
458 "byline",
459 "dateline",
460 "abstract",
461 "attribution",
462 "epigraph",
463 "verse",
464 "caption",
465 "figure caption",
466 "address block",
467 "table cell",
468 "table header",
469 "code block",
470 "table of contents",
471 "bibliography",
472 "endnotes",
473 "sidenote",
474 "letterhead",
475 "salutation",
476 "closing",
477 "signature",
478 "enclosures",
479 "postscript",
480 "definition term"
481 ]
482 }
483 }
484 ]
485 },
486 {
487 "id": "dropcap",
488 "title": "Drop cap",
489 "group": "Prose",
490 "principles": [
491 "For the opening of an essay or a chapter, and nowhere else.",
492 "The size and line height are tuned together to cover exactly three lines. Change the leading and the cap must be retuned.",
493 "The opening words go in small caps. Without them the jump from 33pt to 11pt is too abrupt and the eye skips the first line."
494 ],
495 "elements": [
496 {
497 "id": "dropcap",
498 "name": "Drop cap",
499 "properties": {
500 "font": "serif",
501 "weight": 400,
502 "size": "3.05em",
503 "size_pt": "33.55pt",
504 "line_height": 0.86,
505 "color": "accent",
506 "float": "left",
507 "lines_covered": 3,
508 "padding_right": "0.06em",
509 "padding_top": "0.02em",
510 "first_line_indent": "0"
511 }
512 },
513 {
514 "id": "dropcap-lede",
515 "name": "Opening words",
516 "properties": {
517 "variant": "all small caps",
518 "tracking": "0.04em",
519 "extent": "the first two to four words"
520 }
521 }
522 ]
523 },
524 {
525 "id": "inline",
526 "title": "Inline emphasis",
527 "group": "Prose",
528 "principles": [
529 "Nested emphasis FLIPS to roman rather than compounding. This is correct typographic behaviour and most engines get it wrong by default.",
530 "Superscripts and subscripts must not disturb the line's leading.",
531 "Underline is reserved for insertions. On paper it is a typewriter's substitute for italic, and there is no reason to imitate a typewriter."
532 ],
533 "elements": [
534 {
535 "id": "strong",
536 "name": "Bold",
537 "properties": {
538 "weight": 600
539 },
540 "notes": [
541 "For the load-bearing clause."
542 ]
543 },
544 {
545 "id": "emphasis",
546 "name": "Italic",
547 "properties": {
548 "style": "italic"
549 },
550 "notes": [
551 "For a title or a term of art."
552 ]
553 },
554 {
555 "id": "emphasis-nested",
556 "name": "Nested italic",
557 "properties": {
558 "style": "normal"
559 }
560 },
561 {
562 "id": "small-caps",
563 "name": "Small caps",
564 "properties": {
565 "variant": "all small caps",
566 "tracking": "0.05em",
567 "numerals": "oldstyle"
568 },
569 "notes": [
570 "Named entities, acronyms, stage directions."
571 ]
572 },
573 {
574 "id": "abbr",
575 "name": "Abbreviation",
576 "properties": {
577 "variant": "all small caps",
578 "tracking": "0.05em",
579 "underline": "0.5pt dotted",
580 "underline_color": "ink_faint"
581 }
582 },
583 {
584 "id": "superscript",
585 "name": "Superscript",
586 "properties": {
587 "size": "0.72em",
588 "baseline_shift": "+0.45em",
589 "line_height": 0,
590 "affects_leading": false
591 }
592 },
593 {
594 "id": "subscript",
595 "name": "Subscript",
596 "properties": {
597 "size": "0.72em",
598 "baseline_shift": "-0.22em",
599 "line_height": 0,
600 "affects_leading": false
601 }
602 },
603 {
604 "id": "deleted",
605 "name": "Deletion",
606 "properties": {
607 "decoration": "line-through",
608 "color": "ink_muted"
609 }
610 },
611 {
612 "id": "inserted",
613 "name": "Insertion",
614 "properties": {
615 "decoration": "underline",
616 "underline_offset": "0.15em"
617 }
618 },
619 {
620 "id": "highlight",
621 "name": "Highlight",
622 "properties": {
623 "background": "wash",
624 "bleed": "2pt beyond the glyphs"
625 }
626 },
627 {
628 "id": "kbd",
629 "name": "Key",
630 "properties": {
631 "font": "sans",
632 "size": "0.85em",
633 "padding": "0.15em 0.35em",
634 "border": "0.5pt rule",
635 "border_bottom": "1.5pt rule",
636 "radius": "2pt"
637 }
638 }
639 ]
640 },
641 {
642 "id": "code-inline",
643 "title": "Inline code",
644 "group": "Prose",
645 "elements": [
646 {
647 "id": "code-inline",
648 "name": "Inline code",
649 "properties": {
650 "font": "mono",
651 "size": "0.86em",
652 "ligatures": "disabled",
653 "background": "wash",
654 "padding": "0.1em 0.28em",
655 "radius": "2pt",
656 "wrap": "may break within a word"
657 },
658 "notes": [
659 "The 0.86em corrects for the monospace face running optically large beside the serif.",
660 "Ligatures off: an arrow rendered as one glyph is charming in an editor and wrong in a document that quotes source."
661 ]
662 }
663 ]
664 },
665 {
666 "id": "links",
667 "title": "Links in print",
668 "group": "Prose",
669 "principles": [
670 "Paper has no hover and no click. A URL that carries information must be printed."
671 ],
672 "elements": [
673 {
674 "id": "link",
675 "name": "Link",
676 "properties": {
677 "color": "inherit",
678 "decoration": "underline",
679 "underline_thickness": "0.5pt",
680 "underline_offset": "0.14em",
681 "skip_descenders": true
682 }
683 },
684 {
685 "id": "link-print-url",
686 "name": "Printed URL",
687 "properties": {
688 "content": "the href in parentheses, after the link text",
689 "font": "mono",
690 "size": "0.82em",
691 "color": "ink_muted",
692 "wrap": "may break anywhere",
693 "applies_to": "external (http/https) links only",
694 "excluded": [
695 "internal anchors",
696 "mailto:",
697 "links marked bare"
698 ]
699 }
700 }
701 ]
702 },
703 {
704 "id": "figures-numeric",
705 "title": "Numerals",
706 "group": "Prose",
707 "principles": [
708 "Three kinds, three jobs. Getting this wrong is the most visible amateur tell in a set document, and it is one setting.",
709 "Old-style figures have ascenders and descenders and sit inside the x-height. Lining figures are uniform cap height. Tabular figures share one advance width, which is the only reason a column of numbers can align."
710 ],
711 "elements": [
712 {
713 "id": "numerals-prose",
714 "name": "In running prose",
715 "properties": {
716 "numerals": "oldstyle proportional"
717 }
718 },
719 {
720 "id": "numerals-display",
721 "name": "In headings and display",
722 "properties": {
723 "numerals": "lining proportional"
724 }
725 },
726 {
727 "id": "numerals-tabular",
728 "name": "In tables and columns",
729 "properties": {
730 "numerals": "lining tabular"
731 }
732 },
733 {
734 "id": "numerals-fractions",
735 "name": "Fractions",
736 "properties": {
737 "form": "diagonal"
738 }
739 }
740 ]
741 },
742 {
743 "id": "quotes",
744 "title": "Quotations",
745 "group": "Blocks",
746 "principles": [
747 "Four jobs, four treatments. A block quote is evidence. An epigraph opens a chapter. A pull quote is display type lifted from the body. Verse preserves the poet's line breaks.",
748 "A pull quote repeats text that already appears in the body, so it MUST NOT be the only place a claim appears — a skimming reader would get the claim without its qualification.",
749 "Attribution always sits outside the quotation. Inside, it becomes part of what was said."
750 ],
751 "elements": [
752 {
753 "id": "blockquote",
754 "name": "Block quote",
755 "properties": {
756 "font": "serif",
757 "size": "10.5pt",
758 "line_height": 1.45,
759 "color": "ink",
760 "space_before": "13.75pt",
761 "space_after": "13.75pt",
762 "indent_left": "16.5pt",
763 "border_left": "1pt rule",
764 "break_inside": "avoid",
765 "last_child_space_after": "0"
766 }
767 },
768 {
769 "id": "attribution",
770 "name": "Attribution",
771 "properties": {
772 "display": "block",
773 "align": "left",
774 "space_before": "5.5pt",
775 "size": "9.5pt",
776 "style": "normal",
777 "color": "ink_muted",
778 "prefix": "em dash and a space"
779 }
780 },
781 {
782 "id": "epigraph",
783 "name": "Epigraph",
784 "properties": {
785 "font": "serif",
786 "style": "italic",
787 "size": "10pt",
788 "color": "ink_muted",
789 "align": "left",
790 "block_alignment": "flush right",
791 "max_width": "24em",
792 "border": "none",
793 "space_after": "22pt"
794 },
795 "notes": [
796 "Cite inside an epigraph is roman, not italic — the surrounding block is already italic."
797 ]
798 },
799 {
800 "id": "pullquote",
801 "name": "Pull quote",
802 "properties": {
803 "font": "sans",
804 "weight": 300,
805 "size": "15pt",
806 "line_height": 1.3,
807 "align": "centre",
808 "wrap": "balanced",
809 "border_top": "1.5pt rule_strong",
810 "border_bottom": "0.5pt rule",
811 "padding_top": "11pt",
812 "padding_bottom": "11pt",
813 "space_before": "16.5pt",
814 "space_after": "16.5pt"
815 }
816 },
817 {
818 "id": "verse",
819 "name": "Verse",
820 "properties": {
821 "font": "serif",
822 "size": "11pt",
823 "align": "left",
824 "line_breaks": "preserved as authored",
825 "indent_left": "22pt",
826 "runover_indent": "1.5em",
827 "border": "none"
828 },
829 "notes": [
830 "Runover lines indent further than the verse line they continue, so a wrapped line cannot be mistaken for a new one."
831 ]
832 }
833 ]
834 },
835 {
836 "id": "lists",
837 "title": "Lists",
838 "group": "Blocks",
839 "principles": [
840 "The marker's colour, weight and width must be under control. A grey marker with black text reads as one thing; a black marker competes with the first word.",
841 "Runover lines align to the text, never to the marker.",
842 "Two levels of nesting is the limit worth designing for.",
843 "Definition lists are underused: they are the right shape for a glossary, a set of terms, or the field-and-value blocks of a letter."
844 ],
845 "elements": [
846 {
847 "id": "list-unordered",
848 "name": "Unordered list",
849 "properties": {
850 "marker": "·",
851 "marker_color": "ink_muted",
852 "marker_weight": 700,
853 "marker_column_width": "1.4em",
854 "indent": "1.4em",
855 "item_space_after": "2.75pt",
856 "space_after": "11pt"
857 }
858 },
859 {
860 "id": "list-unordered-nested",
861 "name": "Unordered list, nested",
862 "properties": {
863 "marker": "–",
864 "marker_weight": 400,
865 "space_before": "2.75pt"
866 }
867 },
868 {
869 "id": "list-ordered",
870 "name": "Ordered list",
871 "properties": {
872 "marker": "1.",
873 "marker_color": "ink_muted",
874 "numerals": "lining tabular",
875 "marker_column_width": "1.4em",
876 "indent": "1.4em",
877 "item_space_after": "2.75pt"
878 },
879 "notes": [
880 "Tabular numerals so 9 and 10 align."
881 ]
882 },
883 {
884 "id": "list-ordered-nested",
885 "name": "Ordered list, nested",
886 "properties": {
887 "marker": "a."
888 }
889 },
890 {
891 "id": "list-tight",
892 "name": "Tight list",
893 "opt_in": "ts-list-tight",
894 "properties": {
895 "item_space_after": "0"
896 },
897 "notes": [
898 "For enumerations that are not prose."
899 ]
900 },
901 {
902 "id": "definition-term",
903 "name": "Definition term",
904 "properties": {
905 "font": "sans",
906 "weight": 600,
907 "size": "9.5pt",
908 "align": "left",
909 "space_before": "6.6pt",
910 "space_before_first": "0",
911 "break_after": "avoid"
912 }
913 },
914 {
915 "id": "definition-description",
916 "name": "Definition description",
917 "properties": {
918 "font": "serif",
919 "size": "11pt",
920 "indent_left": "16.5pt",
921 "space_after": "0"
922 }
923 }
924 ]
925 },
926 {
927 "id": "tables",
928 "title": "Tables",
929 "group": "Blocks",
930 "principles": [
931 "Rules, not grids. Vertical rules are almost never needed — the columns already read as columns, and every added line is ink competing with data.",
932 "Three horizontal rules only: above the header, below the header, below the body.",
933 "A table is scanned, not read. Sans at 9.5pt; the serif's job is reading.",
934 "Numbers align on their right edge, on tabular figures. Units go in the header, not in every cell.",
935 "A table that spans pages MUST repeat its header on each. Without it, page two of a table is unreadable."
936 ],
937 "elements": [
938 {
939 "id": "table",
940 "name": "Table",
941 "properties": {
942 "font": "sans",
943 "size": "9.5pt",
944 "line_height": 1.35,
945 "numerals": "lining tabular",
946 "width": "full measure",
947 "space_before": "13.75pt",
948 "space_after": "13.75pt",
949 "border_collapse": true
950 }
951 },
952 {
953 "id": "table-header-cell",
954 "name": "Header cell",
955 "properties": {
956 "font": "sans",
957 "weight": 600,
958 "size": "8pt",
959 "case": "uppercase",
960 "tracking": "0.07em",
961 "color": "ink_muted",
962 "align": "left",
963 "border_bottom": "1pt rule_strong",
964 "padding": "0.45em 0.7em 0.45em 0",
965 "repeats_across_pages": true
966 }
967 },
968 {
969 "id": "table-cell",
970 "name": "Body cell",
971 "properties": {
972 "align": "left",
973 "vertical_align": "baseline",
974 "border_bottom": "0.5pt rule",
975 "padding": "0.45em 0.7em 0.45em 0",
976 "last_row_border_bottom": "1pt rule_strong"
977 }
978 },
979 {
980 "id": "table-cell-numeric",
981 "name": "Numeric cell",
982 "properties": {
983 "align": "right",
984 "numerals": "lining tabular"
985 }
986 },
987 {
988 "id": "table-footer-cell",
989 "name": "Footer cell",
990 "properties": {
991 "weight": 600,
992 "border_bottom": "none"
993 }
994 },
995 {
996 "id": "table-caption",
997 "name": "Caption",
998 "properties": {
999 "position": "above the table",
1000 "align": "left",
1001 "font": "sans",
1002 "size": "9.5pt",
1003 "color": "ink",
1004 "space_after": "0.5em",
1005 "label": "small caps, weight 600, tracking 0.06em",
1006 "max_width": "none"
1007 }
1008 },
1009 {
1010 "id": "table-row",
1011 "name": "Row",
1012 "properties": {
1013 "break_inside": "avoid"
1014 }
1015 },
1016 {
1017 "id": "table-zebra",
1018 "name": "Zebra striping",
1019 "opt_in": "ts-table-zebra",
1020 "properties": {
1021 "background": "wash on even body rows"
1022 },
1023 "notes": [
1024 "For wide, dense tables only. Not a default."
1025 ]
1026 }
1027 ]
1028 },
1029 {
1030 "id": "codeblock",
1031 "title": "Code blocks",
1032 "group": "Blocks",
1033 "principles": [
1034 "Paper cannot scroll. Lines wrap; they are never clipped.",
1035 "A long listing MUST be allowed to split across pages. Forbidding the break pushes a blank page ahead of it."
1036 ],
1037 "elements": [
1038 {
1039 "id": "codeblock",
1040 "name": "Code block",
1041 "properties": {
1042 "font": "mono",
1043 "size": "8.5pt",
1044 "line_height": 1.45,
1045 "background": "wash",
1046 "border_left": "2pt rule_strong",
1047 "padding": "0.8em 1em",
1048 "space_before": "13.75pt",
1049 "space_after": "13.75pt",
1050 "wrap": "soft-wrap long lines",
1051 "tab_size": 2,
1052 "break_inside": "avoid on screen, allowed in print"
1053 }
1054 }
1055 ]
1056 },
1057 {
1058 "id": "figures",
1059 "title": "Figures & captions",
1060 "group": "Blocks",
1061 "principles": [
1062 "A caption is not a title: it goes below the figure.",
1063 "A figure and its caption stay on one page. This is the one place a no-break rule is unambiguously right.",
1064 "The caption carries a small-caps label so a cross-reference in the text has something to point at."
1065 ],
1066 "elements": [
1067 {
1068 "id": "figure",
1069 "name": "Figure",
1070 "properties": {
1071 "space_before": "16.5pt",
1072 "space_after": "16.5pt",
1073 "break_inside": "avoid",
1074 "image_max_width": "full measure"
1075 }
1076 },
1077 {
1078 "id": "figure-caption",
1079 "name": "Figure caption",
1080 "properties": {
1081 "position": "below the figure",
1082 "font": "sans",
1083 "size": "9.5pt",
1084 "line_height": 1.4,
1085 "color": "ink_muted",
1086 "align": "left",
1087 "space_before": "0.5em",
1088 "border_top": "0.5pt rule",
1089 "padding_top": "0.4em",
1090 "label": "small caps, weight 600, colour ink, tracking 0.06em"
1091 }
1092 }
1093 ]
1094 },
1095 {
1096 "id": "callouts",
1097 "title": "Callouts",
1098 "group": "Blocks",
1099 "principles": [
1100 "A callout is an aside the reader may skip without losing the argument. If skipping it would lose the argument, it is a paragraph.",
1101 "Two variants only. A document with five callout colours has none."
1102 ],
1103 "elements": [
1104 {
1105 "id": "callout",
1106 "name": "Callout",
1107 "properties": {
1108 "font": "serif",
1109 "size": "10pt",
1110 "background": "wash",
1111 "border": "0.5pt rule",
1112 "border_left": "2.5pt rule_strong",
1113 "padding": "0.75em 1em",
1114 "space_before": "13.75pt",
1115 "space_after": "13.75pt",
1116 "break_inside": "avoid"
1117 }
1118 },
1119 {
1120 "id": "callout-title",
1121 "name": "Callout title",
1122 "properties": {
1123 "font": "sans",
1124 "weight": 700,
1125 "size": "8pt",
1126 "case": "uppercase",
1127 "tracking": "0.09em",
1128 "color": "ink_muted",
1129 "space_after": "0.35em"
1130 }
1131 },
1132 {
1133 "id": "callout-warning",
1134 "name": "Callout — warning",
1135 "properties": {
1136 "border_left": "2.5pt accent",
1137 "title_color": "accent"
1138 }
1139 }
1140 ]
1141 },
1142 {
1143 "id": "breaks",
1144 "title": "Section breaks",
1145 "group": "Blocks",
1146 "principles": [
1147 "A blank line cannot survive a page break: if the break falls on the gap, the reader never learns the scene changed. Over a long document this is a certainty, not an accident. The mark MUST be visible.",
1148 "Four registers, one per kind of division."
1149 ],
1150 "elements": [
1151 {
1152 "id": "break-asterisks",
1153 "name": "Break — three asterisks",
1154 "properties": {
1155 "content": "* * *",
1156 "size": "10pt",
1157 "tracking": "0.6em",
1158 "color": "ink_faint",
1159 "align": "centre",
1160 "space_before": "16.5pt",
1161 "space_after": "16.5pt",
1162 "break_after": "avoid"
1163 },
1164 "notes": [
1165 "The default, for a change of scene in prose."
1166 ]
1167 },
1168 {
1169 "id": "break-asterism",
1170 "name": "Break — asterism",
1171 "properties": {
1172 "content": "⁂",
1173 "size": "14pt",
1174 "color": "ink_faint",
1175 "align": "centre"
1176 },
1177 "notes": [
1178 "A heavier division: a change of part."
1179 ]
1180 },
1181 {
1182 "id": "break-fleuron",
1183 "name": "Break — fleuron",
1184 "properties": {
1185 "content": "❦",
1186 "size": "12pt",
1187 "color": "accent",
1188 "align": "centre"
1189 },
1190 "notes": [
1191 "Where the document can afford ornament."
1192 ]
1193 },
1194 {
1195 "id": "break-rule",
1196 "name": "Break — rule",
1197 "properties": {
1198 "border_top": "0.5pt rule",
1199 "content": "none"
1200 },
1201 "notes": [
1202 "Where it cannot. Reports."
1203 ]
1204 }
1205 ]
1206 },
1207 {
1208 "id": "notes",
1209 "title": "Footnotes, endnotes & sidenotes",
1210 "group": "Apparatus",
1211 "principles": [
1212 "Bottom-of-page footnotes require an engine that can measure the page while laying it out. Typst and LaTeX do this natively. WeasyPrint 53+ and Prince implement the CSS footnote model. No browser does.",
1213 "Where footnotes are unavailable the note text MUST still live in the document, degrading to a numbered endnotes block — never to a lost note.",
1214 "Sidenotes are the better default where the page can afford the margin: no page-break arithmetic, and the reader never leaves the sentence they are in.",
1215 "The reference mark must not disturb the leading of the line it sits on."
1216 ],
1217 "elements": [
1218 {
1219 "id": "note-marker",
1220 "name": "Reference mark",
1221 "properties": {
1222 "content": "the note number",
1223 "size": "0.7em",
1224 "baseline_shift": "+0.45em",
1225 "line_height": 0,
1226 "color": "accent",
1227 "numerals": "lining",
1228 "decoration": "none",
1229 "brackets": "none",
1230 "affects_leading": false
1231 }
1232 },
1233 {
1234 "id": "footnote",
1235 "name": "Footnote",
1236 "properties": {
1237 "position": "foot of the page carrying the mark",
1238 "font": "serif",
1239 "size": "9.5pt",
1240 "line_height": 1.35,
1241 "separator": "a rule above the notes area"
1242 },
1243 "fallback": "an endnotes block at the end of the document"
1244 },
1245 {
1246 "id": "endnotes",
1247 "name": "Endnotes block",
1248 "properties": {
1249 "font": "serif",
1250 "size": "9.5pt",
1251 "line_height": 1.4,
1252 "align": "left",
1253 "space_before": "22pt",
1254 "border_top": "0.5pt rule",
1255 "padding_top": "11pt",
1256 "list_indent": "1.8em",
1257 "item_space_after": "0.4em",
1258 "heading": "none — the rule above the block is the only mark it needs"
1259 },
1260 "notes": [
1261 "No 'NOTES' label. In a one-page document the rule plus the numbered list already reads as a notes area, and a heading over two lines of small print is heavier than the thing it labels."
1262 ]
1263 },
1264 {
1265 "id": "sidenote",
1266 "name": "Sidenote",
1267 "opt_in": "typeset--sidenotes",
1268 "properties": {
1269 "font": "sans",
1270 "size": "8pt",
1271 "line_height": 1.4,
1272 "color": "ink_muted",
1273 "align": "left",
1274 "width": "11em",
1275 "position": "the right margin, 2em past the text column's own right edge",
1276 "vertical_offset": "-0.3em from the marker's line",
1277 "marker_prefix": "the note number in accent, weight 600",
1278 "measure_when_active": "27em",
1279 "reserved_margin": "14em — the gap plus the note, with an em to spare"
1280 },
1281 "notes": [
1282 "Anchor the note to the text column's right edge, not to the measure. The measure is a maximum: where the reserved margin is the binding constraint the column is narrower than it, and a note offset from the measure lands on top of the text.",
1283 "Sidenotes are positioned, not flowed: a long note followed closely by another will overlap it. Keep each note short and consecutive notes apart — one per paragraph, and not in every paragraph. An implementation cannot fix this, and should not pretend to; it is a constraint on the writing."
1284 ]
1285 }
1286 ]
1287 },
1288 {
1289 "id": "toc",
1290 "title": "Table of contents",
1291 "group": "Apparatus",
1292 "principles": [
1293 "Page numbers require the engine to resolve a cross-reference after pagination. Where it cannot, the entry MUST omit the number rather than print a wrong one — a TOC with wrong numbers is worse than one with none."
1294 ],
1295 "elements": [
1296 {
1297 "id": "toc-entry",
1298 "name": "Entry",
1299 "properties": {
1300 "font": "sans",
1301 "size": "9.5pt",
1302 "align": "left",
1303 "space_after": "0.35em",
1304 "decoration": "none",
1305 "leader": "dotted 0.5pt rule, colour rule, filling the space between title and number",
1306 "leader_baseline_offset": "-0.15em",
1307 "page_number": "resolved after pagination",
1308 "page_number_numerals": "lining tabular",
1309 "page_number_color": "ink_muted"
1310 },
1311 "fallback": "leaders render, page numbers are omitted"
1312 },
1313 {
1314 "id": "toc-entry-2",
1315 "name": "Entry — level 2",
1316 "properties": {
1317 "indent_left": "1.5em"
1318 }
1319 }
1320 ]
1321 },
1322 {
1323 "id": "bibliography",
1324 "title": "Bibliography",
1325 "group": "Apparatus",
1326 "principles": [
1327 "Hanging indent, always. The surname is what is being scanned, so it must be the leftmost thing on the entry."
1328 ],
1329 "elements": [
1330 {
1331 "id": "bibliography-entry",
1332 "name": "Entry",
1333 "properties": {
1334 "font": "serif",
1335 "size": "9.5pt",
1336 "line_height": 1.4,
1337 "align": "left",
1338 "hanging_indent": "1.8em",
1339 "space_after": "0.55em",
1340 "marker": "none",
1341 "break_inside": "avoid",
1342 "title_style": "italic"
1343 }
1344 }
1345 ]
1346 },
1347 {
1348 "id": "frontmatter",
1349 "title": "Front matter",
1350 "group": "Documents",
1351 "principles": [
1352 "A colophon closes the document, recording how it was made and in what type. It is the one piece of matter that is purely for pleasure, and the cheapest thing here to include."
1353 ],
1354 "elements": [
1355 {
1356 "id": "title-block",
1357 "name": "Title block",
1358 "properties": {
1359 "space_after": "33pt",
1360 "padding_bottom": "11pt",
1361 "border_bottom": "0.5pt rule"
1362 }
1363 },
1364 {
1365 "id": "subtitle",
1366 "name": "Subtitle",
1367 "properties": {
1368 "font": "sans",
1369 "weight": 300,
1370 "size": "14pt",
1371 "line_height": 1.25,
1372 "color": "ink_muted",
1373 "align": "left",
1374 "wrap": "balanced",
1375 "space_after": "11pt"
1376 }
1377 },
1378 {
1379 "id": "byline",
1380 "name": "Byline",
1381 "properties": {
1382 "font": "serif",
1383 "size": "11pt",
1384 "variant": "all small caps",
1385 "tracking": "0.08em",
1386 "align": "left",
1387 "space_after": "0"
1388 }
1389 },
1390 {
1391 "id": "dateline",
1392 "name": "Dateline",
1393 "properties": {
1394 "font": "sans",
1395 "size": "9.5pt",
1396 "color": "ink_muted",
1397 "align": "left",
1398 "space_before": "0.2em"
1399 }
1400 },
1401 {
1402 "id": "abstract",
1403 "name": "Abstract",
1404 "properties": {
1405 "font": "serif",
1406 "size": "10pt",
1407 "line_height": 1.45,
1408 "color": "ink_muted",
1409 "align": "left",
1410 "max_width": "30em",
1411 "space_after": "22pt",
1412 "label": "ABSTRACT — sans, 700, 8pt, uppercase, tracking 0.1em, colour ink_faint, on its own line"
1413 }
1414 },
1415 {
1416 "id": "colophon",
1417 "name": "Colophon",
1418 "properties": {
1419 "font": "serif",
1420 "style": "italic",
1421 "size": "9.5pt",
1422 "color": "ink_muted",
1423 "align": "left",
1424 "max_width": "26em",
1425 "space_before": "33pt",
1426 "padding_top": "11pt",
1427 "border_top": "0.5pt rule",
1428 "break_before": "avoid"
1429 }
1430 }
1431 ]
1432 },
1433 {
1434 "id": "letter",
1435 "title": "Letter",
1436 "group": "Documents",
1437 "principles": [
1438 "A letter is set ragged right. It is addressed to a person, and justification reads as institutional.",
1439 "The sender block is address data, not a masthead: one style throughout, at body size, in the reading face. Nothing bold, nothing in the sans. A personal letter does not announce itself.",
1440 "Address blocks are line-broken data, not prose: tighter leading, never justified, line breaks as authored.",
1441 "The signature is the typed name with room above it to sign. No ruled line — a rule is a form to be filled in.",
1442 "A letter carries no running head and no folio.",
1443 "Footnotes belong in a letter as much as in an essay. Where the engine cannot set them at the page foot, the rule plus the numbered note at the end of a one-page letter reads as a footnote area regardless."
1444 ],
1445 "elements": [
1446 {
1447 "id": "letter-page",
1448 "name": "Letter page",
1449 "properties": {
1450 "margin_top_mm": 32,
1451 "margin_bottom_mm": 28,
1452 "margin_sides_mm": 25,
1453 "running_head": "none",
1454 "folio": "none"
1455 },
1456 "notes": [
1457 "The deeper top margin puts the letterhead where an envelope window expects it."
1458 ]
1459 },
1460 {
1461 "id": "letterhead",
1462 "name": "Sender block",
1463 "properties": {
1464 "font": "serif",
1465 "weight": 400,
1466 "size": "11pt",
1467 "line_height": 1.35,
1468 "color": "ink",
1469 "align": "left",
1470 "line_breaks": "as authored — name, street, suburb and postcode, country",
1471 "space_after": "27.5pt"
1472 },
1473 "notes": [
1474 "Every line is the same style, including the name. Setting the name larger or bolder turns a letter into stationery.",
1475 "Omit what you do not use. A personal letter needs no email address and no telephone number."
1476 ]
1477 },
1478 {
1479 "id": "address-block",
1480 "name": "Address block",
1481 "properties": {
1482 "font": "serif",
1483 "size": "11pt",
1484 "line_height": 1.35,
1485 "style": "normal",
1486 "align": "left",
1487 "line_breaks": "as authored",
1488 "space_after": "16.5pt",
1489 "label": "sans, 8pt, uppercase, tracking 0.1em, colour ink_faint, on its own line"
1490 }
1491 },
1492 {
1493 "id": "letter-date",
1494 "name": "Date line",
1495 "properties": {
1496 "numerals": "oldstyle",
1497 "align": "left",
1498 "space_after": "16.5pt"
1499 }
1500 },
1501 {
1502 "id": "date-note",
1503 "name": "Line under the date",
1504 "properties": {
1505 "font": "serif",
1506 "style": "italic",
1507 "size": "11pt",
1508 "color": "ink",
1509 "align": "left",
1510 "space_before": "0.1em — it belongs to the date, and takes no gap of its own",
1511 "space_after": "16.5pt"
1512 },
1513 "notes": [
1514 "A dedication, a feast, a devotion — whatever the writer puts under the date. Italic, at body size, immediately beneath."
1515 ]
1516 },
1517 {
1518 "id": "salutation",
1519 "name": "Salutation",
1520 "properties": {
1521 "align": "left",
1522 "space_after": "11pt"
1523 }
1524 },
1525 {
1526 "id": "closing",
1527 "name": "Closing",
1528 "properties": {
1529 "align": "left",
1530 "space_before": "16.5pt"
1531 }
1532 },
1533 {
1534 "id": "signature",
1535 "name": "Signature block",
1536 "properties": {
1537 "font": "serif",
1538 "size": "11pt",
1539 "align": "left",
1540 "space_before": "33pt — the room to sign",
1541 "rule": "none",
1542 "break_inside": "avoid",
1543 "signature_image_max_height": "16mm"
1544 },
1545 "notes": [
1546 "The typed name only. A ruled line above a name is a form; a letter is not a form."
1547 ]
1548 },
1549 {
1550 "id": "enclosures",
1551 "name": "Enclosures",
1552 "properties": {
1553 "font": "serif",
1554 "size": "11pt",
1555 "align": "left",
1556 "space_before": "22pt",
1557 "label": "same style as the text it introduces — no small caps, no weight change"
1558 },
1559 "notes": [
1560 "Same reasoning as the postscript: \"Enc.\" introduces a sentence, it does not head a section."
1561 ]
1562 },
1563 {
1564 "id": "postscript",
1565 "name": "Postscript",
1566 "properties": {
1567 "font": "serif",
1568 "size": "11pt",
1569 "align": "left",
1570 "space_before": "11pt",
1571 "label": "same style as the text it introduces — no small caps, no weight change"
1572 },
1573 "notes": [
1574 "A postscript is a sentence that happens to begin with \"P.S.\". The label is not a heading."
1575 ]
1576 },
1577 {
1578 "id": "letter-footnote",
1579 "name": "Footnote",
1580 "properties": {
1581 "marker": "as the note marker in Apparatus — superscript, accent, no brackets",
1582 "position": "foot of the page where the engine can; otherwise after the signature block",
1583 "font": "serif",
1584 "size": "9.5pt",
1585 "separator": "0.5pt rule above the notes area",
1586 "heading": "none"
1587 },
1588 "fallback": "a numbered note after the signature, under a rule — which on a one-page letter is the page foot anyway"
1589 }
1590 ]
1591 },
1592 {
1593 "id": "utilities",
1594 "title": "Pagination utilities",
1595 "group": "Documents",
1596 "principles": [
1597 "The small set of overrides reached for while proofing a real document. Every one of them is a manual decision about a specific page, not a style."
1598 ],
1599 "elements": [
1600 {
1601 "id": "util-break-before",
1602 "name": "Break before",
1603 "properties": {
1604 "effect": "start this element on a new page"
1605 },
1606 "notes": [
1607 "Chapter openings."
1608 ]
1609 },
1610 {
1611 "id": "util-break-after",
1612 "name": "Break after",
1613 "properties": {
1614 "effect": "start the next element on a new page"
1615 }
1616 },
1617 {
1618 "id": "util-keep-together",
1619 "name": "Keep together",
1620 "properties": {
1621 "effect": "never split this element across pages"
1622 },
1623 "notes": [
1624 "A short table, a signature block, a callout."
1625 ]
1626 },
1627 {
1628 "id": "util-no-hyphens",
1629 "name": "No hyphenation",
1630 "properties": {
1631 "hyphenation": "manual"
1632 }
1633 },
1634 {
1635 "id": "util-tie",
1636 "name": "Tie",
1637 "properties": {
1638 "effect": "no line break inside"
1639 },
1640 "notes": [
1641 "A figure with its unit, an initial with a surname, a section mark with its number."
1642 ]
1643 },
1644 {
1645 "id": "util-print-only",
1646 "name": "Print only / screen only",
1647 "properties": {
1648 "effect": "present in one medium, absent in the other"
1649 },
1650 "notes": [
1651 "The URL list a page needs and a screen does not; the navigation a screen needs and a page does not."
1652 ]
1653 },
1654 {
1655 "id": "util-color-adjust",
1656 "name": "Exact colour",
1657 "properties": {
1658 "effect": "backgrounds and rules survive the output device's ink-saving"
1659 },
1660 "notes": [
1661 "Without it a print dialog can strip every rule in a table."
1662 ]
1663 }
1664 ]
1665 }
1666 ],
1667 "templates": {
1668 "default": "single-column",
1669 "note": "A template sets the page and the scale. Everything under `foundation` and `sections` still applies; a template states only what it overrides, and what it forbids.",
1670 "single-column": {
1671 "name": "Single column",
1672 "use_for": "Essays, letters, reports, memoranda — anything read continuously from start to finish.",
1673 "page": "as foundation.page",
1674 "scale": "as foundation.scale",
1675 "rhythm": "as foundation.rhythm",
1676 "justification": "optional",
1677 "notes": [
1678 "The default. Nothing to opt into."
1679 ]
1680 },
1681 "two-column": {
1682 "name": "Two column, equal",
1683 "opt_in": "typeset--two-column",
1684 "use_for": "Papers, journal articles, newsletters, technical notes — documents that are scanned and referenced as much as read, and where a figure is worth more than an uninterrupted argument.",
1685 "derivation": {
1686 "text_width_mm": 160,
1687 "column_gap_mm": 6,
1688 "column_width_mm": 77,
1689 "characters_per_line": {
1690 "11pt": 40,
1691 "10.5pt": 42,
1692 "10pt": 44,
1693 "9.5pt": 47,
1694 "9pt": 49
1695 },
1696 "floor": 45,
1697 "conclusion": "A 77mm column carries 40 characters at the 11pt base — below the 45-character floor this spec sets for a line of prose. The base size therefore DROPS to 9.5pt, which restores 47. This is arithmetic, not preference: an implementation that keeps 11pt in two columns violates the measure rule, which is the rule everything else in this spec is downstream of.",
1698 "recompute_when": "The page size, the margins or the gutter change. Characters per line = 0.524 x column_mm x (11 / base_pt)."
1699 },
1700 "page": {
1701 "size": "A4",
1702 "margin_top_mm": 25,
1703 "margin_bottom_mm": 25,
1704 "margin_outer_mm": 22,
1705 "margin_inner_mm": 28,
1706 "columns": 2,
1707 "column_widths": "equal — the two columns are the same width, always",
1708 "column_gap_mm": 6,
1709 "column_width_mm": 77,
1710 "column_rule": "none by default; an optional 0.5pt hairline in `rule` where the columns need separating",
1711 "column_balance": "the final page balances its columns to equal height",
1712 "lines_per_column": 52,
1713 "running_head": "as foundation.page — spans the full text width, not a column",
1714 "folio": "as foundation.page"
1715 },
1716 "scale": {
1717 "ratio": 1.2,
1718 "base": "9.5pt",
1719 "steps": {
1720 "xs": "7pt",
1721 "sm": "8.5pt",
1722 "base": "9.5pt",
1723 "h4": "9.5pt",
1724 "h3": "11pt",
1725 "h2": "13pt",
1726 "h1": "20pt"
1727 },
1728 "note": "Every step comes down. A 24pt heading inside a 77mm column takes three lines to say two words; 18pt takes two. The h1 keeps display size because it spans both columns."
1729 },
1730 "rhythm": {
1731 "line_height": 1.4,
1732 "baseline_advance": "13.3pt",
1733 "space": "9.5pt",
1734 "measure": "the column — 77mm, not a character count",
1735 "measure_chars": 47,
1736 "note": "Leading tightens with the measure: a shorter line needs less vertical separation to keep the return sweep unambiguous."
1737 },
1738 "requirements": [
1739 "Justification with hyphenation is MANDATORY, not optional. At 47 characters a ragged right edge produces a visibly serrated column and word gaps wide enough to read as rivers. This is the one place the spec removes a choice it otherwise offers.",
1740 "The last line of a paragraph is still flush left. Two columns make a stretched last line more visible, not less.",
1741 "Balance the columns on the final page. A last page with one full column and one empty third reads as a printing error.",
1742 "A spanning element must span BOTH columns fully or neither. An element that spans one and a half columns has no correct reading order.",
1743 "Keep a spanning element at the top or the bottom of the page, never mid-column. Interrupting both columns in the middle forces the reader to find their place twice."
1744 ],
1745 "spanning": {
1746 "always": [
1747 "title block",
1748 "subtitle",
1749 "byline",
1750 "dateline",
1751 "abstract",
1752 "heading 1",
1753 "colophon",
1754 "bibliography heading"
1755 ],
1756 "optional": [
1757 "figure",
1758 "table",
1759 "code block",
1760 "pull quote"
1761 ],
1762 "never": [
1763 "paragraph",
1764 "list",
1765 "blockquote",
1766 "callout",
1767 "heading 2 and below",
1768 "endnotes"
1769 ],
1770 "note": "A wide figure or table opts in per instance. The default is column-width, because a spanning element costs a break in both columns."
1771 },
1772 "forbidden": {
1773 "sidenote": "There is no margin to put it in. Use a footnote or an endnote.",
1774 "dropcap": "A three-line cap at 3.05em is 29pt in a 77mm column — a quarter of the column width for one letter. Open with small caps instead.",
1775 "measure_variants": "narrow and wide are meaningless: the column is the measure."
1776 },
1777 "element_overrides": {
1778 "h1": {
1779 "size": "20pt",
1780 "spans": "both columns",
1781 "space_after": "9.5pt"
1782 },
1783 "h2": {
1784 "size": "13pt",
1785 "space_before": "19pt",
1786 "space_after": "4.75pt"
1787 },
1788 "h3": {
1789 "size": "11pt",
1790 "space_before": "19pt",
1791 "space_after": "4.75pt"
1792 },
1793 "h4": {
1794 "size": "9.5pt",
1795 "space_before": "19pt",
1796 "space_after": "4.75pt"
1797 },
1798 "paragraph": {
1799 "size": "9.5pt",
1800 "line_height": 1.4,
1801 "space_after": "0",
1802 "first_line_indent": "1.25em",
1803 "note": "Indented paragraphs are the default here, not an option: a blank line costs 3% of a column."
1804 },
1805 "blockquote": {
1806 "size": "9pt",
1807 "indent_left": "9.5pt"
1808 },
1809 "table": {
1810 "size": "8pt",
1811 "line_height": 1.3
1812 },
1813 "codeblock": {
1814 "size": "7.5pt",
1815 "line_height": 1.4
1816 },
1817 "figure_caption": {
1818 "size": "8pt"
1819 },
1820 "footnote": {
1821 "size": "8pt",
1822 "note": "Scoped to the page, not the column: one notes area spanning both columns at the page foot."
1823 },
1824 "endnotes": {
1825 "size": "8.5pt"
1826 },
1827 "pullquote": {
1828 "size": "12pt",
1829 "note": "Column width by default. Spanning both columns turns it into a divider, which is a different and heavier thing."
1830 },
1831 "abstract": {
1832 "size": "9pt",
1833 "max_width": "the full text width, set apart above the columns"
1834 }
1835 }
1836 }
1837 }
1838}