PDF Typography

PDF Typography Skill

Version: 0.1.1 Created: 2026-04-08 Author: Dojo Genesis Purpose: Fine-tune the Pretext typography engine for optimal PDF output across different content types, audiences, and aesthetic goals.

I. The Philosophy: Measure Twice, Render Once

Pretext does one thing exceptionally well: it measures text on a real Canvas surface, then reports exact dimensions. This means every line break, every paragraph spacing, every margin is computed from actual glyph metrics — not CSS approximations. Typography configuration is the lever that controls how this precision manifests in the final PDF.

II. When to Use This Skill

• Content-specific tuning: Code needs different settings than prose. Chat needs different settings than reports.
• Audience adaptation: A client-facing PDF needs different typography than an internal code review.
• Brand alignment: Match typography to organization design tokens or brand guidelines.
• Disposition mapping: Map ADA agent personality traits to typographic choices (DojoChat export).

III. Steps

Step 1: Identify Content Type

Each content type has an optimal typography profile:

Step 2: Configure Font Stack

The Pretext bridge supports three font families with variable axes:

Inter (body text):

• Axes: opsz (optical size), wght (weight)
• Range: 100-900 weight, 14-32 optical size
• Default: 400 weight, 16 optical size

Recursive (code):

• Axes: MONO (monospace), CASL (casual), slnt (slant), wght (weight)
• For code: MONO=1, CASL=0, slnt=0, wght=400
• For casual: MONO=0, CASL=1, slnt=-15, wght=400

Fraunces (display/headings):

• Axes: SOFT (softness), WONK (wonkiness), opsz (optical size), wght (weight)
• For headings: SOFT=50, WONK=1, opsz=48, wght=700

Step 3: Set Page Geometry

interface PageGeometry {
  size: 'letter' | 'a4' | 'legal';    // Default: 'letter'
  margins: {
    top: number;     // Default: 72pt (1in)
    right: number;   // Default: 72pt
    bottom: number;  // Default: 72pt
    left: number;    // Default: 72pt
  };
  columns: 1 | 2;                      // Default: 1
  headerHeight: number;                 // Default: 36pt
  footerHeight: number;                 // Default: 36pt
}

Step 4: Configure Pretext Measurement

Pretext's prepare() and layout() functions take specific parameters:

// One-time per text block
const prepared = pretext.prepare(text, fontDescriptor);

// Fast re-layout at any width
const layout = pretext.layout(prepared, maxWidth, lineHeight);
// Returns: { width, height, lines[] }

Key: the fontDescriptor must match the actual font loaded in the Canvas context. Mismatches cause measurement drift.

Step 5: Apply and Validate

After configuration, export a test page and verify:

• Body text line length is 45-75 characters (optimal readability)
• Code blocks don't overflow margins
• Headings have appropriate visual weight
• Page breaks respect orphan/widow rules (min 2 lines)

IV. Quality Checklist

Before handing a typography configuration to pdf-export, verify:

• Content type was identified (prose / code / chat / mixed) and the matching profile was used as the starting point — not the generic default
• Body text line length will fall in the 45-75 character range at the chosen font size and margin
• Code blocks use Recursive with MONO=1 and minimum 1.3 line height
• Heading optical size (opsz) matches the intended render size, not the body default
• No system-ui in any fontDescriptor — explicit family names only (Inter, Recursive, Fraunces)
• Measurement units are consistent: pt/px conversion is handled by the bridge exactly once
• Orphan/widow rule is respected: minimum 2 lines before or after a page break
• Two-column layouts were checked for tall code blocks that cannot be split across columns
• For DojoChat exports: dispositionToTypography was called per agent, not a single shared config applied to all bubbles
• A test page was rendered and inspected before committing to the full export

V. Reflection Questions

• Is the content primarily prose, code, or mixed? Each has different optimal settings.
• Who is the audience? Technical readers tolerate denser typography; general audiences need more whitespace.
• Does the content have a brand or design system to align with?
• Are there accessibility requirements (minimum font size, contrast ratios)?

VI. Common Mistakes

• Using system-ui in Canvas context. Canvas and DOM resolve system-ui differently on macOS. Always specify exact font family names.
• Ignoring optical sizing. Inter and Fraunces have opsz axes — using body optical size for headings produces thin, fragile letterforms.
• Setting line height too tight for code. Code blocks with 1.0 line height make indentation guides invisible. Minimum 1.3 for code.
• Mixing measurement contexts. Pretext measures in CSS pixels. PDF uses points. The bridge handles conversion — don't double-convert.

VII. Variations

Disposition-Driven Typography (DojoChat)

Map ADA agent personality traits to typographic choices:

function dispositionToTypography(disposition: Disposition): TypographyConfig {
  return {
    fontFamily: disposition.tone === 'formal' ? 'Inter' : 'Recursive',
    fontSize: mapVerbosity(disposition.verbosity), // verbose → smaller
    lineHeight: mapDepth(disposition.depth),        // deep → tighter
    maxBubbleWidth: mapBrevity(disposition.brevity), // brief → narrower
    fontVariationSettings: buildVariations(disposition),
  };
}

Two-Column Reference

For dense reference material (API docs, skill catalogs):

{
  columns: 2,
  fontSize: 9,
  lineHeight: 1.3,
  margins: { top: 54, right: 54, bottom: 54, left: 54 }
}

VIII. Example

Scenario: Configure typography for exporting a Go backend specification as a client-facing PDF.

1. Content type: Mixed prose + code → start with prose defaults
2. Audience: Client (non-technical stakeholders) → increase font to 12pt, line height 1.6
3. Code blocks: Go syntax → Recursive MONO=1, 10pt, 1.35 line height
4. Headings: Fraunces 700, SOFT=30, WONK=1 for professional warmth
5. Page: Letter, 1-inch margins, single column
6. Validate: Body line length = 58 characters (within 45-75 range)

IX. See Also

• pdf-export — Main export workflow that consumes typography configuration
• Pretext source: @chenglou/pretext — Canvas-based typography engine
• DojoChat disposition mapper: src/lib/disposition/typography.ts

Output

A TypographyConfig object ready for consumption by the Pretext prepare()/layout() pipeline, plus page geometry settings for the PDF renderer. Concretely: validated font descriptors, line height values per content zone (body/code/headings), page margins in points, and column count. When used with pdf-export, the output becomes embedded in the rendered PDF — font choices and spacing are baked into the byte stream, not post-processable.

Examples

Scenario 1 — Client-facing Go spec PDF (mixed prose + code): Content type: prose primary, code secondary. Audience: non-technical client.

• Body: Inter 12pt, opsz=16, line height 1.6
• Code: Recursive MONO=1, 10pt, line height 1.35
• Headings: Fraunces 700, SOFT=30, WONK=1
• Page: Letter, 72pt margins, single column
• Validate: body line ~58 chars (within 45-75 target)

Scenario 2 — Dense code review PDF: Content type: code-primary (diff output, function signatures). Audience: senior engineers.

• Body: Inter 9pt, opsz=14, line height 1.3
• Code: Recursive MONO=1, 9pt, line height 1.3 (same size as body — intentional)
• Headings: Inter 700, no Fraunces
• Page: Letter, 54pt margins, potentially 2-column
• Validate: code blocks fit within 504pt max width without overflow

Edge Cases

• Canvas vs. DOM font resolution on macOS: system-ui resolves to different faces in Canvas and DOM contexts. Always pass explicit family names (Inter, Recursive, Fraunces) to fontDescriptor.
• Optical sizing mismatches at large scales: Inter at 48pt (heading) with opsz=16 (body default) produces thin, fragile letterforms. Set opsz to match intended display size.
• Mixed content with extremely long code lines: If source code has 120+ char lines and the page is letter-width, either reduce font size or switch to landscape. The layout engine will not auto-truncate — overflow is clipped.
• Recursive CASL axis in monospace mode: Setting MONO=1, CASL=1 simultaneously produces undefined intermediate rendering on some PDF engines. Use CASL=0 when MONO=1.
• Two-column layout with tall code blocks: Page-break logic does not split code blocks across columns. A single tall block will overflow into the gutter.

Anti-Patterns

• Specifying system-ui in any Pretext context. Breaks cross-machine reproducibility and causes Canvas/DOM measurement drift. Use explicit font family names.
• Ignoring opsz at heading sizes. Using body opsz (14-16) for large headings (24-48pt) produces optically incorrect letterforms. Set opsz to match render size.
• Setting line height below 1.3 for code. At 1.0-1.2, indentation guides and leading dots between columns become invisible. Minimum 1.3 for monospace content.
• Double-converting pt/px units. Pretext measures in CSS pixels internally; the bridge converts to PDF points. Manually converting before passing to the API results in double-scaling (typically 72/96 = 0.75x error).
• Applying a single TypographyConfig across all zones. Body, code, captions, and headings each need separate configuration. A one-size config either makes code unreadable or body text too large.