Steady Gray

an experiment in paragraph texture


npm ↗
GitHub ↗
TypeScriptCanvas pixel samplingReact + Vanilla JS

Compositors call it colour — the aggregate grey of a text block. steadyGray estimates each line’s raster density off-screen and applies bounded spacing changes toward a shared target. The result depends on the text, font and settings; reading benefit has not been evaluated.

Live demo

Max adjustment (em)0.050 em
Sensitivity2.0

Choose Before and After to compare at the same width. After applies the selected settings; some lines may receive no correction. Reset restores letter-spacing, ±0.05 em and sensitivity 2.

After — bounded correction

A paragraph’s texture depends on its letterforms, spaces and line breaks. steadyGray estimates density for each detected line, then applies a bounded correction. This example lets you explore that change while keeping the detected words on each line. Some lines may receive no correction at the default tolerance. Spacing changes can affect line width and rhythm, so compare the result at the intended reading size. These measurements describe raster output; they do not establish a preference or reading benefit.

Aesthetic experiment: an off-screen raster estimate drives one bounded correction pass. It does not measure perception or establish a reading benefit. Spacing can change line width and rhythm; scroll the preview horizontally if a corrected line overflows.

Selected limit: ±0.050 em via letter-spacing.

How it works

Canvas pixel sampling

Each detected line is redrawn on an off-screen Canvas using its computed font style, weight, size and family. A fixed pixel threshold gives a raster-density estimate over the text’s own width and line height. This redraw is not a measurement of the final screen output; inline styling and variable-font settings can differ.

Per-line spacing correction

The average estimate across all lines, including the final line, becomes the target. Each line gets a bounded correction proportional to its deviation from that target. The React wrapper re-runs on resize and after fonts load. Each run is one pass; it does not verify that the corrected output reaches the target.

Start with native wrapping

For rag, short last lines and hyphenation, try text-wrap: pretty and hyphens: auto with the correct language first. Browser behavior varies. Use steadyGray when you specifically want to explore per-line correction and accept its spacing and width tradeoffs.

Usage

Drop-in component

import { GrayValueText } from '@overpunch/steadygray'

<GrayValueText maxAdjustment={0.05} calibrationFactor={2}>
  Your paragraph text here...
</GrayValueText>

Hook

import { useGrayValue } from '@overpunch/steadygray'

const ref = useGrayValue({ maxAdjustment: 0.05, calibrationFactor: 2 })
<p ref={ref}>{children}</p>

Vanilla JS

import { applyGrayValue, removeGrayValue, getCleanHTML } from '@overpunch/steadygray'

const el = document.querySelector('p')
// Call getCleanHTML BEFORE the first applyGrayValue — it strips injected spans,
// so calling it on the clean element captures the true original markup.
const original = getCleanHTML(el)
applyGrayValue(el, original, { maxAdjustment: 0.05, calibrationFactor: 2 })

// Later — restore original:
removeGrayValue(el, original)

Options

steadyGray API options reference
OptionDefaultDescription
targetDensity'auto'Target density ratio (0–1). 'auto' uses the average of all lines.
densityMode'canvas''canvas' renders each line off-screen and counts ink pixels. 'glyph-path' uses opentype.js for an outline-area estimate from a supplied font file. It requires opentype.js and a CORS-accessible font URL and does not measure final screen pixels. Falls back to 'canvas' while the optional dependency or font is unavailable.
fontUrl—URL of the font file for glyph-path measurement. Required when densityMode is 'glyph-path'. Must be same-origin or CORS-enabled.
method'letter-spacing'CSS property to adjust per line: 'letter-spacing', 'word-spacing', 'font-weight', or 'font-width'.
maxAdjustment0.05Max correction magnitude: 0.05 em for letter/word-spacing; method-specific defaults are 100 weight units or 30 wdth units.
tolerance0.01Minimum calibrated adjustment to apply. At calibrationFactor 2, tolerance 0.01 skips density deviations below 0.005.
calibrationFactor2.0Correction strength per density-unit difference. Axis methods also apply a 1000× unit scale. This is a controller coefficient, not physiological or display calibration.
lineDetection'bcr''bcr' reads actual browser layout — ground truth, works with any font and inline HTML. 'canvas' uses @chenglou/pretext for arithmetic line breaking with no forced reflow on resize. Install pretext separately. Note: avoid 'canvas' with system-ui — canvas resolves system fonts differently on macOS and will produce incorrect line breaks.
linePreservation'none''none' — line widths vary with the correction. 'scale' — scales each corrected line back to its width before the correction, so the column edge doesn't move.
mode'equalize''equalize' targets a shared estimated density. 'readability' uses experimental word-length or syllable-weighted targets; reading benefit has not been evaluated.
complexity'word-length'Complexity metric used in readability mode: 'word-length' (avg chars/word, no deps), 'syllable' (requires npm install syllable), or 'pos' (reserved; currently falls back to 'word-length').
strength0.5How aggressively to weight complex lines in readability mode. Range 0–1. At 0: same as equalize mode.
activetrueSet false to skip the correction entirely and restore the element to its original HTML.

Additional exports

import { measureLineDensity, GRAY_VALUE_CLASSES } from '@overpunch/steadygray'

// Estimate a plain line off-screen (not the corrected DOM output):
const canvas = document.createElement('canvas')
const density = measureLineDensity('Sample text', '400 18px Georgia', 28, canvas)

// CSS class names injected into the DOM — useful for custom styling or selectors:
// GRAY_VALUE_CLASSES.word   → 'gv-word'  (per-word span)
// GRAY_VALUE_CLASSES.line   → 'gv-line'  (per-line wrapper span)
// GRAY_VALUE_CLASSES.probe  → 'gv-probe' (measurement probe span)
console.log(GRAY_VALUE_CLASSES)

Accessibility & display compatibility

If the browser reports (update: slow) through matchMedia, steadyGray restores the original markup and skips measurement and correction. Media-query support varies; this is not device identification or a validated display-specific benefit.

no-code

Use it in Webflow & Framer

The same effect, no build step — drop it straight into your design tool.

Webflow

One script tag, then mark any element with data-steadygray. Configure it with data-* attributes.

<!-- Site Settings → Custom Code → Footer, or an Embed element -->
<script src="https://cdn.jsdelivr.net/npm/@overpunch/steadygray/dist/steadygray.webflow.min.js"></script>

<!-- Then add data-steadygray to any text element -->
<h1 data-steadygray>Your headline</h1>

Framer

Insert → Code → New Component, then paste SteadyGray.tsx ↗. It imports the core from esm.sh and exposes every option in the property panel — no build step.

import { /* core */ } from "https://esm.sh/@overpunch/steadygray"