The terminology, perceptual, and accessibility gaps between typographers and developers — and where paragraf sits

§0 — Hook

A typographer says: "the colour is unbalanced." A developer opens the style sheet and adjusts the colors on the page. The paragraph is still wrong. Neither person made a mistake.

"Colour" in typesetting means the visual density of a paragraph (also called grey) — how evenly ink is distributed across the lines. It has nothing to do with hue. The developer heard the correct English word and acted on a reasonable interpretation. The typographer used the correct technical term and assumed it would be understood. The conversation failed before it began.

This is the first gap: terminology. Two disciplines developed precise vocabularies for the same domain, independently, and the words do not always map to each other.

The second gap is deeper. A typographer looks at a paragraph and perceives something wrong before they can name it — the trained eye reads texture, rhythm, and density as a unified impression. A developer looks at the same paragraph and sees output that matches the specification. The code is correct. The output is wrong. These are not contradictory statements. They describe two different instruments measuring the same object.

The third gap is structural. The tools that produce publication-quality typographic output are desktop applications and command-line systems. They are not callable from a Node.js function. They do not run in a CI pipeline. They do not return a PDF buffer from a single API call.

This article names all three gaps, maps the terminology where it overlaps, and describes where paragraf sits in relation to them.

§1 — The Terminology Gap

Both digital typesetting and software development have spent decades solving the problem of text on a page. They arrived at precise solutions — from different directions, with different tools, and with different names for what they found.

If you have spent years working with type, the terms on the left are familiar. If you have spent years writing code, the terms on the right are familiar. The intersection of the two is not very crowded.

This is not a translation from one language to a simpler one. It is a map between two equally precise vocabularies.

Knuth-Plass (left) produces even paragraph grey with no rivers — spacing is distributed optimally across all lines simultaneously. Greedy (right) fills each line independently, producing uneven grey and visible rivers of white space.

Optical margin alignment (top): punctuation protrudes slightly outside the column boundary, producing a visually straight margin edge. Without it (bottom), the margin reads as ragged even when mathematically flush.

§2 — The Perceptual Gap

The terminology gap is solvable with a shared reference. The perceptual gap is harder.

A typographer's judgment is trained over years of looking at printed pages — recognising rivers in justified text before knowing their name, feeling when leading is too tight before measuring it, seeing when a paragraph's colour is wrong before identifying which lines are causing it. This is not intuition. It is pattern recognition built from sustained exposure to a specific domain. It cannot be transferred as a specification.

A developer's judgment is trained differently — recognising when code is brittle, when an abstraction leaks, when a system will fail under load. These are also not intuitions. They are patterns learned from building and breaking systems. A developer looking at a paragraph of text has no trained apparatus for reading its typographic quality. The code produced correct output. That is the only signal available.

The inverse is equally true. A typographer looking at a codebase has no trained apparatus for reading its structural quality. The document looks correct on screen. That is the only signal available.

Neither gap represents a failure of intelligence or effort. They represent two disciplines that developed different perceptual instruments for different problems, and are now being asked to collaborate on the same artefact.

What changes this is not more training — it is a shared surface. When the typographer can adjust tolerance and see the paragraph grey change in real time, the parameter becomes a perceptual instrument. When the developer can see that the typographer's tolerance: 1.5 approval maps to a specific output quality, the visual judgment becomes a reusable specification. The gap does not close. But it becomes navigable.

§3 — The Accessibility Gap

InDesign is a desktop application. TeX is a command-line system. Both require installation, licensing or configuration, and specialist knowledge to operate. Neither is callable from a Node.js function. Neither runs in a CI pipeline. Neither returns a PDF buffer from a single API call.

This is not a criticism — both tools are mature, reliable, and used in production publishing worldwide. It is a statement about what they are: authoring environments designed for human operators, not pipeline components designed for programmatic integration.

The gap this creates is visible in how publishing automation projects get built. A catalog of ten thousand products needs a PDF for each one. A report needs to be generated on demand from live data. A personalised document needs to be assembled from a template and a data record at request time. These are engineering problems. The tools that produce acceptable typographic output are not designed for them. The tools designed for them do not produce acceptable typographic output.

paragraf is an attempt to occupy that gap: publication-quality typesetting as a Node.js library, callable from TypeScript, with no external processes and no GUI dependency. The same algorithms that production typesetting tools use — Knuth-Plass, OpenType shaping, optical margin alignment — running inside a standard npm install.

That is the claim. Not that paragraf matches the output quality of tools refined over decades. But that the algorithms are the same, the parameters are exposed, and the pipeline is programmable.

The pipeline side is paragraf's current focus. The typographer-facing side — a visual authoring environment built on the same engine — is studio, currently in design. That is the subject of a future article in this series.

§4 — What paragraf Implements

The terminology map is one thing. What paragraf actually exposes is another. This section shows the implementation — with the actual parameters, and with honesty about what is not yet there.

Paragraph colour / whitespace distribution

Controlled by tolerance and looseness in the paragraph composer. tolerance sets how much deviation from ideal spacing is acceptable before a line is considered bad. looseness nudges the algorithm toward fewer or more lines. Together they give the typographer direct control over the grey of a paragraph.

paragraf code

const { lines } = composer.compose({
  text: '...',
  font: { id: 'body', size: 11, weight: 400, style: 'normal', stretch: 'normal' },
  lineWidth: 396,
  tolerance: 2.0,
  looseness: 0,
  alignment: 'justified',
  language: 'en-us',
});

Rivers

Rivers are the visual consequence of a greedy line-breaking algorithm — not a parameter to set, but a problem paragraf avoids by using Knuth-Plass. The algorithm considers all lines simultaneously rather than filling each line independently, which eliminates the whitespace clustering that produces rivers in justified text.

Justified text / line-breaking algorithm

paragraf implements Knuth-Plass with the full parameter set: tolerance, looseness, consecutive hyphen limit, and runt-line penalties. The demo runs Knuth-Plass and greedy side by side — the difference is visible immediately on any paragraph of justified prose.

paragraf code

const { lines } = composer.compose({
  text: '...',
  alignment: 'justified',
  tolerance: 2.0,
  consecutiveHyphenLimit: 2,
});

Leading / line height

Set per style in the paragraf style system. Applied baseline to baseline, consistent with typesetting convention rather than CSS convention (which measures from the top of the line box).

paragraf code

const template = defineTemplate({
  styles: {
    body: {
      font: { family: 'LiberationSerif', size: 11 },
      alignment: 'justified',
      lineHeight: 16, // baseline to baseline, in points
    },
  },
});

Optical margin alignment

Implemented as a two-pass recomposition. The first pass composes normally. The second pass identifies punctuation and soft glyph edges at line starts and ends, applies protrusion values, and recomposes affected lines. The result is a visually straight margin edge on justified text.

paragraf code

const { lines } = composer.compose({
  text: '...',
  alignment: 'justified',
  opticalMargins: true,
});

What is not yet implemented:
Frame-level widow/orphan control, and PDF/X output are in progress. These affect press-ready output but not the typesetting parameters above.

§5 — Close

Three gaps. One platform pursuing all three.

The terminology gap is addressed by exposed, named parameters that map directly to typesetting concepts. The perceptual gap is navigated by making those parameters adjustable and their output immediately visible — so that a typographer's judgment and a developer's integration can operate on the same artefact. The accessibility gap is addressed by building the pipeline as a Node.js library rather than a desktop application or command-line system.

None of these gaps are fully closed. paragraf is pre-1.0, in active development, and honest about what is not yet implemented. What it offers at this stage is a surface — a place where typographic judgment and engineering decisions can meet, with a shared vocabulary for what they are doing.

The paragraf series continues when studio is ready to demonstrate. A parallel series on AI-assisted development starts now — the v0.1 documentation system is the first subject.

paragraf is open source. The repository, the live demo, and the article series are at github.com/kadetr/paragraf.