steadygray

Even colour,
line by line.

TypeScript·Canvas pixel sampling·React + Vanilla JS

Compositors call it colour — the aggregate grey of a text block. When some lines are denser than others, the paragraph looks uneven. Gray Value measures ink pixel density per line using Canvas and adjusts letter-spacing until the paragraph has even colour throughout.

Live demo

Max adjustment (em)0.050 em

Sensitivity2.0

Method

The colour of a page — the compositor's term for the aggregate grey of the text block — is determined by the ratio of ink to space across every line. A line with many narrow letters sits lighter than one with wide letters and generous spacing. Print compositors corrected this by hand, adjusting word spaces to equalise the grey. No web tool has automated this measurement. Gray Value uses Canvas to sample the actual ink pixels in each rendered line, then adjusts letter-spacing to bring every line to the same optical density. The adjustment is invisible when correct — all you notice is that the paragraph looks even.

Each line is measured by pixel density and adjusted by ±0.050 em via letter-spacing. E-ink displays and automotive HUDs benefit most — on e-ink, ambient light determines perceived contrast directly; on a windshield HUD, glare can wash out undifferentiated paragraphs entirely.

How it works

Canvas pixel sampling

Each line of text is rendered to an off-screen Canvas at the correct font size and weight. The pixel data is read and ink pixels are counted. The ratio of ink to total pixels gives the line's optical density.

Per-line spacing correction

The average density across all lines becomes the target. Each line gets a letter-spacing adjustment proportional to its deviation from the target, clamped to the maxAdjustment limit. The correction is re-run on resize.

Usage

Drop-in component

import { GrayValueText } from '@liiift-studio/steadygray'

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

Hook

import { useGrayValue } from '@liiift-studio/steadygray'

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

Vanilla JS

import { applyGrayValue, removeGrayValue, getCleanHTML } from '@liiift-studio/steadygray'

const el = document.querySelector('p')
const original = getCleanHTML(el)
applyGrayValue(el, original, { maxAdjustment: 0.05, calibrationFactor: 2 })

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

Options

Option	Default	Description
targetDensity	'auto'	Target density ratio (0–1). 'auto' uses the average of all lines.
method	'letter-spacing'	CSS property to adjust: 'letter-spacing' or 'word-spacing'.
maxAdjustment	0.05	Max spacing correction in em units.
tolerance	0.01	Minimum density difference required before a correction is applied. Adjustments smaller than this threshold are skipped.
calibrationFactor	2.0	Strength of the correction. Higher = more aggressive.
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.

Even colour,line by line.

Even colour,
line by line.