Documentation

@takt/core is a type-and-space system derived from font metrics. It computes line-height, letter-spacing, a modular type scale, rhythm-based spacing, and optional Capsize trimming—then exports CSS variables, Tailwind theme fragments, design tokens, or raw JSON. Try it live in the playground.

Concepts

Font metrics

takt reads the same numbers browsers use: units per em, ascent, descent, cap height, x-height, and average character width. From these it derives ratios like xHeightRatio and avgCharWidthRatio. Those ratios describe how the face occupies vertical and horizontal space—so spacing decisions can follow the font’s shape instead of arbitrary px values.

Line height

computeLineHeight maps body-to-display sizes to a base leading curve (roughly 1.6 for small text down toward 1.1 for large display), then nudges the result using x-height: high x-height faces tend to need slightly tighter leading, low x-height slightly looser. The function returns a numeric value, a CSS-ready string, and a human-readable reasoning string.

Letter spacing

computeLetterSpacing uses size bands: small sizes get slight positive tracking; larger display sizes trend negative. Average character width scales the result—wider faces need less artificial tracking adjustment.

Spacing and rhythm

Body line-height and font size define a rhythm unit: fontSize × lineHeight. The spacing scale (3xs through 5xl) is a set of multipliers on that unit, each with px, rem, and a fluid clamp() between viewport bounds—so vertical spacing stays locked to the type rhythm.

Text trimming

When trim: true, Capsize-style ::before / ::after rules reduce extra leading above cap height and below the baseline. With textBoxTrim: true, CSS text-box-trim metadata is included for engines that support it.

Getting started

Install from npm (or use pnpm, yarn, or bun). The package name is @takt/core.

Install

Pass resolved FontMetrics into createTaktConfig, then pipe the result into any generator.

Quick start

To load metrics from a font URL at runtime, use unpackFont (see below) before calling createTaktConfig.

createTaktConfig

function createTaktConfig(input: TaktInput): TaktConfig

Builds a full TaktConfig: normalised metrics, scale steps with line-height, letter-spacing, optional trim, and rhythm-based spacing. input.font must be FontMetrics (not a string—use unpackFont first for URLs).

Input	Default	Notes
`baseSize`	16	Body step size (px)
`ratio`	1.25	Modular scale ratio
`stepsUp` / `stepsDown`	5 / 2	Named steps above and below base
`viewportMin` / `viewportMax`	320 / 1440	Fluid clamp range (px)
`trim` / `textBoxTrim`	true / false	Capsize trim and optional text-box trim

normaliseMetrics

function normaliseMetrics(metrics: FontMetrics, familyName?: string): NormalisedFontMetrics

Adds familyName (default 'Unknown') and ratio fields used throughout the pipeline.

unpackFont

function unpackFont(source: string): Promise<FontMetrics>

Loads a font from a URL via @capsizecss/unpack and returns raw FontMetrics. Use in async contexts before createTaktConfig.

Async font loading

computeLineHeight

function computeLineHeight(fontSize: number, metrics: NormalisedFontMetrics): { value: number; computed: string; reasoning: string }

Computes optimal unitless line-height for a given font size and normalised metrics.

computeLetterSpacing

function computeLetterSpacing(fontSize: number, metrics: NormalisedFontMetrics): { value: number; css: string }

Returns a unitless em value and a CSS string (e.g. -0.02em or 0em).

computeTrim

function computeTrim(fontSize: number, lineHeight: number, metrics: FontMetrics): TaktStep['trim']

Produces Capsize ::before/::after styles and optional textBox fields for CSS text-box trimming.

computeSpacing

function computeSpacing(bodyFontSize: number, bodyLineHeight: number, viewportMin: number, viewportMax: number): TaktSpacing

Returns rhythmUnit and a named scale (3xs–5xl) with px, rem, and fluid clamp strings.

generateScale

function generateScale(input: ScaleInput): ScaleStep[]

Low-level scale generator (used inside createTaktConfig).ScaleInput includes baseSize, ratio, stepsUp, stepsDown, and viewport bounds. Each ScaleStep has name, min, max, and a fluid clamp string.

CSS custom properties

generateCSS(config) returns a :root block with --takt-type-*, --takt-lh-*, --takt-ls-*, --takt-space-*, and --takt-rhythm.

Excerpt

Tailwind

generateTailwind(config) returns a partial theme object:fontSize entries as [clamp, { lineHeight, letterSpacing }], plus parallel lineHeight, letterSpacing, and spacing maps. Merge into theme.extend.

tailwind.config.ts

Design tokens (DTCG-style)

generateTokens(config) nests typography and spacing with $type and $value fields for tools that consume design-token JSON.

Shape (abbreviated)

Raw JSON

generateJSON(config, pretty?) stringifies the full TaktConfig (default pretty: true).

Types

Key interfaces exported from @takt/core:

FontMetrics — raw font table numbers
NormalisedFontMetrics — extends with ratios + family name
TaktInput — options for createTaktConfig
TaktConfig — font, steps, spacing, meta
TaktStep — one scale step: fontSize, lineHeight, letterSpacing, optional trim
TaktSpacing — rhythm unit + named scale entries