Rhythm is a spacing system rooted in font metrics.
Where most systems use a fixed module like 8px, Rhythm uses the gap between lines of text. When the typeface, font size, or line height changes, spacing follows.
* {
text-box: trim-both ex alphabetic;
}
:root {
/* Baseline-to-baseline distance minus x-height */
--gap: calc(1rlh - 1rex);
--gap--relative: calc(1lh - 1ex);
}
p {
margin-block-start: calc(var(--gap) * 2);
}
small + h1 {
margin-block-start: var(--gap--relative);
}By default, CSS measures spacing from the text box, which includes extra space the font reserves above and below the letters. A margin of 8px between two paragraphs adds up to more than 8px on screen. Cards and images have no such reserved space, so the gap between a card and a paragraph comes out smaller than the gap between two paragraphs.
Rhythm’s unit is the gap between lines of text, measured from the visible edges of the letters instead of the text box.
Advantages:
Simple mental model. Rhythm keeps the space around text blocks larger than the space within them. A paragraph’s minimum outer gap is one gap, the visible space between its lines. Other layout spacing derives from that unit.
Responsive by design. Spacing scales with font size and line height, which means fewer media queries and simpler fluid typography.
Typeface-aware. The gap is the line height minus the x-height, so it follows the font. Switch typefaces and spacing recalculates.
How to use · Why it works · Browser support · Use in PostCSS · Use in Tailwind · Use in UnoCSS
With npx skills:
npx skills add lotva/rhythm --skill rhythmWith GitHub CLI:
gh skill install lotva/rhythm rhythmThen ask your agent:
$rhythm install
$rhythm migrate src/components
$rhythm match-font-metrics
First, trim the text container to the visual bounds of the font:
* {
text-box: trim-both ex alphabetic;
}Next, define the base gap—the visual gap between lines of text:
:root {
/* Root-relative: stays consistent across the document */
--gap: calc(1rlh - 1rex);
}Create a relative version that scales with the element’s font size:
:root {
/* Local-relative: scales with the element’s own lh/ex */
--gap--relative: calc(1lh - 1ex);
}Finally, build your spacing scale to fit the project’s needs:
calc(var(--gap) * 0.5);
calc(var(--gap) * 0.75);
calc(var(--gap) * 1.5);
calc(var(--gap) * 2);
calc(var(--gap) * 3);
calc(var(--gap) * 4);Optionally, prevent layout shifts by matching fallback font metrics to your primary typeface:
:root {
font-size-adjust: ex-height 0.×××;
}Get metrics for your font from Richard Rutter’s calculator
Most design systems define a module—a base unit, typically 8px, used to scale everything from font sizes to component dimensions. While a fixed module makes layout decisions predictable, spacing is the one area where this approach breaks down.
In practice, layout spacing is governed by font metrics—the unique, fractional measurements embedded in every typeface: the height of ascenders and descenders, the x‑height, and the built‑in line gap. When you set margins in CSS, the typeface adds its own spacing, which rarely aligns with a fixed 8px grid.
Additionally, the gaps between lines of text are determined by line height, a value chosen by the designer. Together, font metrics and line height create a system where the connection between a fixed module and actual text spacing is, at best, coincidental.
Rhythm introduces its own spacing module, derived directly from font metrics:
:root {
/* In font metrics, the visual gap equals: */
/* ascent + descent + lineGap − xHeight */
--gap: calc(1rlh - 1rex);
}The visual gap between lines is the natural choice for a spacing unit. It’s the primitive designers already look to when balancing the inner and the outer.
Typesetting follows a basic rule: inner ≤ outer. For a heading to look dignified, the gaps between words must exceed the gaps between letters, and the space between lines must exceed the space between words. The same logic applies to the entire layout: the space between elements should exceed the line spacing within them.
If the outer space is too small, elements invade each other’s personal space and the layout looks jammed. Increase the outer, and each element gains independence.
See: The rule of the inner and the outer
For example:
- the space between a heading and its subline should be no smaller than the heading’s own visual gap,
- the margin between an illustration and a paragraph should be at least equivalent to the paragraph’s visual gap.
Rhythm formalizes this pattern by using the visual line gap as its primary module. This standardizes layout decisions and prevents common typesetting errors, such as spacing overlaps.
See also: Avoiding common layout mistakes using visual line gap (Russian)
This approach is made possible by modern CSS features: text-box, rlh, lh, and rex. Current browser support stands at approximately 86%, making it viable for most modern web applications.
For projects requiring wider compatibility, you can polyfill the text-box behavior using the X-Size tool.
// postcss.config.cjs
const { gap, gapRelative } = require('./src/functions')
module.exports = {
plugins: [
require('postcss-functions')({
functions: {
gap,
gapRelative,
},
}),
],
}// functions.js
export const gap = (value = 1) => `calc(var(--gap) * ${value})`
export const gapRelative = (value = 1) => `calc(var(--gap--relative) * ${value})`/* Usage */
pre {
padding: gap() gap(0.5) gap(2);
}/* globals.tailwind.css */
@theme {
/* Set the default spacing unit (e.g., m-1, p-4): */
--spacing: var(--gap);
/* Or define a fixed spacing scale: */
--spacing-0.5g: calc(var(--gap) * 0.5);
--spacing-0.75g: calc(var(--gap) * 0.75);
--spacing-1g: var(--gap);
--spacing-1.5g: calc(var(--gap) * 1.5);
--spacing-2g: calc(var(--gap) * 2);
--spacing-3g: calc(var(--gap) * 3);
--spacing-4g: calc(var(--gap) * 4);
--spacing-1gr: var(--gap--relative);
}The most flexible way to implement Rhythm is through a custom rule, allowing you to use dynamic multipliers (e.g., mt-2.5g):
// uno.config.ts
export default defineConfig({
rules: [
[
/^(min-[wh]|max-[wh]|size|basis|[pmwh]|gap|inset|top|right|bottom|left|start|end)(?:-?([trblxyse]|bs|be))?-(\d*\.?\d+)g(r)?$/,
(match) => {
const [, property, directive, multiplier, isRelative] = match
const gapVariableName = isRelative ? '--gap--relative' : '--gap'
const value = `calc(var(${gapVariableName}) * ${multiplier})`
const basePropertyMap: Record<string, string> = {
p: 'padding',
m: 'margin',
w: 'width',
h: 'height',
'min-w': 'min-width',
'max-w': 'max-width',
'min-h': 'min-height',
'max-h': 'max-height',
basis: 'flex-basis',
gap: 'gap',
inset: 'inset',
top: 'top',
right: 'right',
bottom: 'bottom',
left: 'left',
start: 'inset-inline-start',
end: 'inset-inline-end',
}
const base = basePropertyMap[property]
if (property === 'gap') {
if (directive === 'x') return { 'column-gap': value }
if (directive === 'y') return { 'row-gap': value }
if (!directive) return { gap: value }
return
}
if (property === 'size') {
return directive ? undefined : { width: value, height: value }
}
if (directive && !['p', 'm', 'inset'].includes(property)) return
if (
property === 'inset' &&
directive &&
['t', 'r', 'b', 'l'].includes(directive)
)
return
if (!base) return
const directiveMap: Record<string, string[]> = {
'': [base],
t: [`${base}-top`],
r: [`${base}-right`],
b: [`${base}-bottom`],
l: [`${base}-left`],
s: [`${base}-inline-start`],
e: [`${base}-inline-end`],
bs: [`${base}-block-start`],
be: [`${base}-block-end`],
x: [`${base}-inline-start`, `${base}-inline-end`],
y: [`${base}-block-start`, `${base}-block-end`],
}
const properties = directiveMap[directive ?? '']
if (!properties) return
return Object.fromEntries(properties.map((p) => [p, value]))
},
],
],
})Alternatively, you can define a fixed spacing scale in your theme:
export default defineConfig({
theme: {
spacing: {
'0.5g': 'calc(var(--gap) * 0.5)',
'0.75g': 'calc(var(--gap) * 0.75)',
'1g': 'var(--gap)',
'1.5g': 'calc(var(--gap) * 1.5)',
'2g': 'calc(var(--gap) * 2)',
'3g': 'calc(var(--gap) * 3)',
'4g': 'calc(var(--gap) * 4)',
'1gr': 'var(--gap--relative)',
},
},
})<!-- Usage -->
<pre
class="p-1g -m-0.5g mt-0.5g mbs-2gr gap-x-1g min-w-12g max-w-40g size-4g -top-0.5gr"
></pre>