API — @responsivejs/core
Pure math, zero dependencies, browser-safe. Every module is a subpath export (@responsivejs/core/rect, …); the root re-exports the data-model types flat and the math modules as namespaces (import { rect, curve } from '@responsivejs/core').
/rect — geometry
interface Rect { x; y; width; height; right; bottom; centerX; centerY; area }| Function | Meaning |
|---|---|
rect(x, y, w, h): Rect | Build a Rect with derived fields. |
fromDOMRect({x,y,width,height}): Rect | From a DOMRect-like. |
contains(parent, child, tolerance=1) | Child inside parent. |
overlaps(a, b) / overlapsVertically(a, b) | Intersection tests. |
distance(a, b) | Center-to-center distance. |
horizontalGap(a, b) / verticalGap(a, b) | Edge-to-edge gaps. |
sameHeight(a, b, tol=2) / sameWidth(a, b, tol=2) | Dimension equality. |
alignedLeft(a, b, tol=1) / alignedTop(a, b, tol=1) | Edge alignment. |
inViewport(r, vw, vh?) | Fully inside the viewport. |
widthRatio(a, b) | a.width / b.width. |
/curve — analysis of measured curves
Curve = Map<number, number> (width → value).
| Function | Meaning |
|---|---|
entries(curve) | Sorted [width, value][]. |
isMonotonicUp(curve, tol=0.5) / isMonotonicDown | Never moves against the direction. |
maxJump(curve) | Largest step between adjacent widths. |
isContinuous(curve, maxAllowed) | No jump exceeds the bound. |
discontinuities(curve, threshold) | Every jump above the threshold. |
valueRange(curve) | { min, max, range }. |
ratio(a, b) / ratioInRange(a, b, min, max) | Pointwise ratio of two curves. |
/interpolate — authoring (the inverse of /curve)
type WidthFn = (width: number) => number;
interface Domain { min: number; max: number } // values clamp outside it
type Bezier = [x1, y1, x2, y2];
type EasingName = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out';| Function | Meaning |
|---|---|
linear(min, max, domain): WidthFn | Straight interpolation. |
exponential(min, max, domain, base=4) | Slow start, fast finish — normalized easing on t (zero-safe endpoints). |
logarithmic(min, max, domain, base=4) | Fast start, slow finish — exact inverse of exponential. |
eased(min, max, easing, domain) | Named CSS easing or custom bezier. |
cubicBezier(bezier): (t) => number | Solve a CSS cubic-bezier (Newton + bisection, ~1e-6). |
stepped(values, breakpoints) | Discrete switch, right-open intervals. |
piecewise(points, easing?) | Multi-segment through [width, value] control points. |
sample(f, widths=DEFAULT_WIDTHS): Curve | Bridge back to the analysis half. |
inverse(f, value, domain): number | undefined | Which width produces the value (monotone f only). |
progress(width, domain) | Clamped 0..1 position in the domain. |
EASINGS | The CSS-spec control points per easing name. |
/color — parsing, WCAG, OKLab
| Function | Meaning |
|---|---|
parseColor(css): RGBA | hex (3/6/8), rgb()/rgba() (comma + modern), hsl(), oklch(), transparent. Fallback: opaque black. |
relativeLuminance(rgba) | WCAG 2.1 relative luminance. |
contrastRatio(fg, bg): number | 1–21, alpha-blended. |
meetsAA(ratio, largeText=false) / meetsAAA | 4.5/3 and 7/4.5 thresholds. |
rgbaToOklab(rgba): OKLab / oklabToRgba(oklab): RGBA | Björn Ottosson's matrices; out-of-gamut clamped per channel. |
mixOklab(a, b, t): RGBA | Perceptual mix (what the runtime uses for color fluid). |
formatRgb(rgba): string | Modern rgb(r g b / a) emission. |
/typography — modular scales
| Export | Meaning |
|---|---|
SCALES | Named ratios: minorSecond 1.067 … goldenRatio 1.618. |
detectScale(sizes) | Best-fit { base, ratio, name } for measured font sizes. |
fitsScale(sizes, tolerance=0.05) | Do the sizes fit any known scale? |
usesTokens(values, tokens, tolerance=1) | Are values drawn from a token set? { valid, outliers }. |
/aesthetics — the 17-metric score
score(input, weights?) accepts ScoreInput ({ rects, viewport, colors?, fontSizes? }) and returns an AestheticScore with 15 weighted metrics (balance, equilibrium, symmetry, proportion, rhythm, density, regularity, simplicity, unity, homogeneity, sequence, cohesion, economy, colorHarmony, typographyHarmony), plus birkhoff and the weighted overall — all 0..1. Each metric is also exported as a standalone function. Grounded in Ngo, Teo & Byrne (2003), Modelling interface aesthetics, and Birkhoff (1933), Aesthetic Measure.
/types — the data model
ElementSnapshot (selector, index, Rect, numeric styles, string computed) · ViewportSnapshot (one width) · SnapshotStore (all widths) · Violation (rule, element, width, detail, expected/actual, severity, suggestion, fix, owner/owners) · FixSuggestion ({ selector, property, value, reason, kind } with kind: 'exact' | 'heuristic' | 'runtime-patch' — verbatim-applicable, directional, or patch-the-construct with construct/source/change) · ProvenanceEntry (construct, target, behavior, source, serializable config) · Report · SweepOptions · InteractionSnapshot · DEFAULT_WIDTHS = [320, 375, 390, 768, 1024, 1280, 1440, 1920, 2560].
/snapshot — querying stores
const q = new StoreQuery(store);
q.at(1280).rect('h1'); // Rect | undefined
q.at(1280).style('h1', 'fontSize'); // number | undefined
q.at(1280).elements('.card'); // ElementSnapshot[]
q.curve('h1', 'fontSize'); // Curve across widths (styles or x/y/width/height)
q.rectCurve('h1', 'right'); // Curve over any Rect field
q.computedCurve('h1', 'color'); // Map<width, string>WidthQuery (returned by at()): element, elements, rect, rects, style, children, childRelation, computedProp, allRects.