Compile-time unit safety for numeric, unit-bearing CSS values via typed measurements.
npm install css-calipersCSS is code. Measure it like one.
Compile-time unit safety for numeric, unit-bearing CSS values, no surprises at runtime.
CSS-Calipers is a tiny layer for typed CSS measurements. Stop parsing CSS
strings and concatenating units. Do your math on real numbers, get
compile-time unit safety, and output CSS only at the edges.
This README is a general overview. Deeper module guides live in their own files.
Module guides:
- Measurements core: README_MEASUREMENT.md
- Media queries: README_MEDIAQUERIES.md
At a glance:
- Create measurements with m from a number and a unit; if you omit the unit, it defaults to px and is typed as the px measurement type.
- Do unit-safe math with methods like add and multiply, then call .css()
at the edge to get a CSS string (for example "10px").
``bash`
npm install css-calipers
> 🚧 Work in progress.
> API surface and docs may change between 0.x releases until the first stable version.
- Status: early 0.x release. Backwards compatibility is not guaranteed until 1.0.0.package.json
- Questions or bugs: open an issue on GitHub (see the repository link at the top of this page or in ).
- Tooling: tested primarily with TypeScript 5.6+ on Node 18+.
---
`ts
import { m } from "css-calipers";
// Declare vars
const paddingBase = m(4); // defaults to px (and is typed as a px measurement) when no unit is specified
const rotation = m(45, "deg"); // equivalent to a dedicated helper: mDeg(45)
// Do safe arithmetic
const margins = paddingBase.add(4);
const offset = paddingBase.add(margins).multiply(2).subtract(1);
// Emit only at the end in CSS (at runtime or in a build step)
const style = {
padding: paddingBase.css(),
transform: rotate(${rotation.double().css()}), // 90deg`
};
If you prefer, you can also import unit helpers from dedicated subpaths. For example, mPercent is available from the root entrypoint and from css-calipers/units/percent, and all unit helpers are aggregated under css-calipers/units.
---
`ts
import { m } from "css-calipers";
import { mediaQueryFactory } from "css-calipers/mediaQueries";
const media = mediaQueryFactory({
queries: {
mobile: { maxWidth: m(639) },
desktop: { minWidth: m(640) },
},
config: {
label: "layout",
},
});
const styles = {
...media({
mobile: { gridTemplateColumns: "1fr" },
desktop: { gridTemplateColumns: "repeat(4, 1fr)" },
}),
};
`
See README_MEDIAQUERIES.md for the full media queries guide.
---
- Compile-time unit validation. Prevents mixing incompatible units.
- Arithmetic safety. Operate only within matching units; explicit when
converting.
- Explicit emission. .css() outputs a typed string literal only when
needed.
- Light runtime footprint. Near-zero cost when emitted at build time.
- Framework-agnostic. Works anywhere TypeScript does.
Any numeric, unit-bearing CSS value is supported: m accepts any unit string you’d use in CSS'px'
(, 'rem', '%', 'vw', 'deg', 'ms', …), and you can model newmPx
measurements without waiting for a dedicated helper. For convenience and better
types, every standard CSS unit also has a named helper (for example, mPercent, mVw, mEm, mMs, mFr), which are equivalent to callingm(value, 'unit') directly.
CSS-Calipers focuses exclusively on numeric, unit-bearing CSS values. Keywords
like auto, fit-content, or max-content, full shorthand strings,var(--token), or calc(...) expressions should remain explicit strings or
dedicated keyword types in your app or styling layer. Everything else stays as
plain CSS (see "Philosophy & Boundaries" below for more detail). For a concrete
example of this separation in a mixed-input helper, see
examples/lineHeight-normalizer.example.ts,
which keeps keywords and CSS variables as plain strings while using measurements
for numeric values.
---
CSS-Calipers is a good fit if:
- You already use TypeScript (or plan to) and want compile-time guarantees around CSS units.
- You have a design system or token layer where layout math and unit conversions matter.
- You care about catching unit mismatches and layout invariants early, in dev or tests.
This library is opinionated about types and emitting valid CSS at the edges,
but intentionally loose about how you structure or apply styles in between.
It’s probably overkill if:
- Your project has minimal custom layout math or relies mostly on utility classes/framework CSS.
- You don’t use TypeScript and aren’t looking for stronger typing around CSS values.
- You’re comfortable relying on manual discipline instead of typed measurements for units.
---
`ts
import { m, mPercent, mVw, mVh, assertCondition } from "css-calipers";
// Token-style measurements (px by default)
const spacing = m(8); // Defaults to px and is typed as a PxMeasurement
const cardPadding = spacing.multiply(2); // 16px
const gutter = spacing.multiply(1.5); // 12px
// Responsive bounds expressed in other units
const minWidthPercent = mPercent(75); // 75%; same as m(75, "%")
const maxWidthViewport = mVw(100); // 100vw; same as m(100, "vw")
// Derived content width in px
const contentBase = m(320);
const minCardWidth = m(260);
const maxCardWidth = m(360);
// In real code, these bounds typically come from tokens or configuration,
// so keeping the clamp in measurement space ensures units stay consistent.
const cardWidth = contentBase.clamp(minCardWidth, maxCardWidth);
// Unitless ratio you can reuse elsewhere
const ratio = contentBase.getValue() / spacing.getValue(); // returns a number, no unit
// Apply ratio to a different unit family
const heroHeight = mVh(40).multiply(ratio);
// Invalid arithmetic (different units) fails at compile time
const exampleError = cardWidth.add(heroHeight); // ❌ Type error (px vs vh) see error handling below
// Use plain numbers where they are just counts
const columns = 3;
// In development, enforce simple invariants so layout mistakes fail fast.
// In production, you can either rely on earlier validation or add a separate
// fallback path if this invariant is ever broken.
if (process.env.NODE_ENV !== "production") {
assertCondition(
() => columns > 0,
"cardGridStyles: columns must be greater than zero"
);
}
// Compose a simple grid layout
const cardGridStyles = {
display: "grid",
gap: gutter.css(),
// Keep fraction units as plain CSS alongside measurement-derived values
gridTemplateColumns: repeat(${columns}, 1fr),calc(${heroHeight.css()} + 10vh)
// width driven by card width + gutters
width: cardWidth
.multiply(columns)
.add(gutter.multiply(columns - 1))
.css(),
// container bounds in percent/viewport units
minWidth: minWidthPercent.css(),
maxWidth: maxWidthViewport.css(),
// derived hero height based on px ratio, expressed in vh and used inside a calc() string
// calc() stays plain CSS; CSS-Calipers only provides the numeric pieces
minHeight: ,`
};
---
CSS-Calipers will happily enforce units anywhere you choose, but it stays
unopinionated about where those guards live. Drop assertions in a component, in
a theme override, hardcode a debug routine, or wire a global invariant; the
structure is up to you:
`ts
import { assertMatchingUnits } from "css-calipers";
import { formTokens } from "@/tokens/forms.tokens";
if (process.env.NODE_ENV !== "production") {
assertMatchingUnits(
formTokens.field.paddingBlock,
formTokens.field.paddingInline,
"Form control padding mismatch"
);
}
`
You can apply the same checks globally (e.g., during app bootstrap), only
inside the components that need them, or in dedicated test helpers. For more
complete patterns, see the examples folder: the validation unit-tests example
(examples/validation-unit-tests.example.ts) shows how to
enforce spacing token invariants in a test suite, and the validation and runtime
checks example (examples/validation-and-runtime-checks.example.ts)
shows how to apply dev-only guards around shared tokens in two different
consumers (an HTML snippet and a style object) using the same line-height
measurement.
---
- Operations are fail-fast: when you call helpers like add, divide, clamp,measurementMin
/ measurementMax, or the assertion helpers with invalidError
input (for example, mismatched units or non-finite values), CSS-Calipers
throws a normal .css-calipers.Measurement.divide
- Error messages include the operation name (for example,
or css-calipers.assertMatchingUnits), theif (process.env.NODE_ENV !== 'production')
relevant values/units, and any context string you pass in.
- The library does not catch these errors for you. You choose where to place
assertions and where (if anywhere) to catch and handle exceptions.
- In production, a common pattern is to wrap assertions in dev-only guards
(such as ) or to enforce
invariants in tests, so checks stay cheap and predictable at runtime.
For concrete uses of these errors in tests and dev-only guards, see
TESTING.md and the validation examples in
examples/validation-unit-tests.example.ts and
examples/validation-and-runtime-checks.example.ts.
---
Example
`
css-calipers.m: Non-finite measurement value: undefined [code=CALIPERS_E_NONFINITE | helper=m | inputs=value=undefined, unit=px | stack=...]
What it means
- A measurement was constructed with undefined, NaN, or Infinity.
How to fix
- Provide a real numeric value and a unit (m(12), m(12, "px")).
- Add a context label so the error points to the calling helper or token (m(12, { context: "tokens.cardWidth" })).
Example
`
css-calipers.assertMatchingUnits: measurement unit mismatch: px vs em [code=CALIPERS_E_UNIT_MISMATCH]
What it means
- You mixed units without an explicit conversion.
How to fix
- Normalize units at the source (convert em to px or vice versa).
- Add an assertMatchingUnits call where the values enter your system.
Example
`
css-calipers.Measurement.divide: Cannot divide 10px by zero [code=CALIPERS_E_DIVIDE_BY_ZERO]
What it means
- You attempted to divide by zero in a measurement operation.
How to fix
- Guard inputs before dividing or replace zero with a safe fallback.
Example
`
css-calipers.Measurement.clamp: clamp: min (20px) must be <= max (12px) [code=CALIPERS_E_CLAMP_INVALID_RANGE]
What it means
- The clamp minimum is greater than the clamp maximum.
How to fix
- Ensure min and max come from the same source or swap them before calling clamp.
For m and unit helpers, errors include a trimmed stack hint in non-production by default.
You can disable or force stack hints globally:
`
import { setErrorConfig } from "css-calipers";
// Disable stack hints everywhere (for production).
setErrorConfig({ stackHints: "off" });
// Force stack hints everywhere (useful in dev or tests).
setErrorConfig({ stackHints: "on" });
`
---
If you want instance-scoped configuration and a single re-export surface, use
the factory entrypoint. The instance includes core helpers, unit helpers, and
mediaQueries.
`
import { createCalipers } from "css-calipers/factory";
const calipers = createCalipers({
errorConfig: { stackHints: "on" },
});
export const { m, mPx, mediaQueries, units } = calipers;
`
See examples/factory-wrapper.example.ts
for a wrapper module you can re-export across your project.
---
You don’t have to convert everything at once, or at all. If it fits your setup,
you can write small adapters that accept existing CSS strings, CSS-Calipers
measurements, or plain numbers and turn them into CSS values. CSS-Calipers can
be dropped into an existing styling system or used from the ground up; it
focuses narrowly on numeric, unit-bearing values and leaves the rest of your
styling approach up to you. For a more realistic adapter pattern that
normalizes mixed inputs (including CSS variables) into a single css-like value,
see the line-height normalizer example referenced below.
When helpers must _exclude_ CSS-Calipers–emitted numeric, unit-bearing CSS values from a keyword union,
use the exported MeasurementString type together with your existing CSSProperty
property typings (for example, the types from the csstype
package):
`ts
import type { MeasurementString } from "css-calipers";
import type { Property } from "csstype";
type SpacingKeyword = Exclude<
Extract
MeasurementString
>;
`
This lets helpers stay strict: IMeasurement for numeric, unit-bearing CSS values; targeted stringMeasurementLike
keywords for symbolic CSS values, without reintroducing vague unions like.
- Typed helpers: Accept either IMeasurement or a constrained keyword type,assertUnit()
never a generic string.
- Pre-emission transforms: Compose all math in CSS-Calipers, emit once at
the style boundary.
- Build-time pipelines: Run measurement math in Node or a build step
(scripts, codegen, or bundler plugins) and emit plain CSS or tokens for your
existing styling system so runtime only sees static values.
- Unit guards in debug: Use in dev-only blocks to confirm.css()
consistency between related measurements.
- CSS variables: Pass CSS-Calipers output into style layers thatvar(--token)
interpolate them, but don’t try to store inside the library.
---
- Measurement math lives here; string composition lives elsewhere.
Use CSS-Calipers for unit-aware calculations, then hand results to
helpers/adapters that emit CSS literals. Keep calc()/linear-gradient() logic outside
the library so measurement objects remain pure.
- .css() at runtime is an edge, not a habit.
You can call .css() at runtime, but prefer emitting once to avoid hot-path
string churn.
- Numbers are operands, not CSS-Calipers values.
You cannot create a CSS-Calipers value without a unit. Pass plain numbers as
operands (add, subtract, multiply, divide) or combine with anotherIMeasurement
, but never store bare numbers inside library state. If a value
lacks both number and unit, CSS-Calipers won’t track it; you own whatever
logic wraps it.
- Model keywords explicitly (not “escape hatches”).
If a helper needs symbolic CSS (e.g., 'auto', 'fit-content'), define a
precise keyword type and purposely exclude the emitted string type from
CSS-Calipers so numeric, unit-bearing CSS values remain the default path.
- CSS custom properties coexist; they don’t mix.
Third-party primitives exposing var(--token) should keep those values as rawvar(...)
CSS strings. CSS-Calipers is intentionally narrow: it works with numeric
measurements and unit-safe conversions, not tokens or CSS variables. You can
still use and token strings anywhere in your styling system; they
just sit outside the library. If you want those values to flow through
CSS-Calipers, first extract the numeric value and unit in your own code and
then pass that measurement into the library.
CSS is inherently flexible: the same property can accept numbers, unit-bearing
strings, keywords, and CSS variables. CSS-Calipers is one focused piece of that
ecosystem. It keeps the numeric, unit-bearing parts typed and predictable, and
lets the rest of your styling system own tokens, variables, and higher-level
APIs.
For a worked example of this pattern, see
examples/lineHeight-normalizer.example.ts. It shows a helper that accepts a
lineHeight value from a CMS or configuration (numbers, numeric strings with"normal"
units, keywords like , or CSS variables such as"var(--body-line-height)") and normalizes them into a value with a .css()
method. CSS-Calipers only participates when there is a concrete measurement
(numbers and units); keywords and CSS variables remain plain CSS strings owned
by your styling layer. That’s the intended scope: CSS will always be a mix of
values, but the library gives you a tight, unit-safe boundary for the numeric
parts inside a broader styling solution.
The examples/ folder contains a few non-published usage sketches:
- examples/lineHeight-normalizer.example.ts —
mixed input normalization for lineHeight (numbers, strings, CSS variables).css()` method.
into a single value with a
- examples/validation-unit-tests.example.ts —
simple unit tests that enforce spacing token invariants (shared units and
small ≤ large).
- examples/validation-and-runtime-checks.example.ts —
dev-only validation around shared tokens in two different consumers (HTML
string and style object) using the same line-height measurement.
- examples/factory-wrapper.example.ts —
instance-scoped factory wrapper that re-exports the helpers.