@domandigital/craft 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,676 @@
+/**
+ * OKLab / OKLCh conversions, after Björn Ottosson's published M1/M2 matrices.
+ * https://bottosson.github.io/posts/oklab/
+ *
+ * Zero dependencies is a hard constraint for every dd-packages package, so the
+ * colour maths is implemented here rather than pulled from culori/colorjs.
+ */
+interface Oklch {
+    /** Perceptual lightness, 0..1. */
+    l: number;
+    /** Chroma, 0..~0.4 in practice. */
+    c: number;
+    /** Hue angle in degrees, 0..360. */
+    h: number;
+}
+interface Rgb {
+    /** 0..1 */
+    r: number;
+    /** 0..1 */
+    g: number;
+    /** 0..1 */
+    b: number;
+}
+type Gamut = "srgb" | "p3";
+/** Parse `#rgb`, `#rrggbb` or `#rrggbbaa` (alpha ignored) into 0..1 channels. */
+declare function parseHex(hex: string): Rgb;
+/** Serialise 0..1 channels as a lowercase `#rrggbb`, clamping out-of-range input. */
+declare function formatHex({ r, g, b }: Rgb): string;
+/** Convert a hex string to OKLCh. */
+declare function hexToOklch(hex: string): Oklch;
+/** Is this OKLCh colour representable in sRGB, within a small epsilon? */
+declare function inSrgbGamut(colour: Oklch, epsilon?: number): boolean;
+/** Is this OKLCh colour representable in Display P3, within a small epsilon? */
+declare function inP3Gamut(colour: Oklch, epsilon?: number): boolean;
+/** Unclamped OKLCh to sRGB, for callers that have already gamut-mapped. */
+declare function oklchToRgb(colour: Oklch): Rgb;
+/**
+ * Perceptual distance in OKLab. ~0.02 is the just-noticeable difference used as
+ * the house tolerance for a derived colour standing in for a hand-picked one.
+ */
+declare function deltaEOk(a: Oklch, b: Oklch): number;
+/** Convenience: perceptual distance between two hex strings. */
+declare function deltaEOkHex(a: string, b: string): number;
+
+/**
+ * Gamut mapping, per CSS Color 4 §13.2.
+ *
+ * Split from `oklch.ts` so the dependency runs one way: this module imports the
+ * conversions, never the reverse.
+ */
+
+interface OklchToHexOptions {
+    /** Which gamut to map into before serialising. Defaults to sRGB. */
+    gamut?: Gamut;
+}
+/**
+ * OKLCh to hex, gamut-mapped by chroma reduction so hue survives.
+ *
+ * Naive per-channel RGB clipping is rejected here: clipping a saturated violet
+ * pins blue at 1.0 while red keeps falling, which walks the hue toward magenta.
+ * CSS Color 4 §13.2 bisects chroma with lightness and hue held fixed instead.
+ */
+declare function oklchToHex(colour: Oklch, options?: OklchToHexOptions): string;
+/**
+ * Reduce chroma until the colour fits the target gamut, per CSS Color 4 §13.2.
+ * Lightness and hue are preserved exactly; only chroma moves.
+ */
+declare function toGamut(colour: Oklch, gamut?: Gamut): Oklch;
+
+/**
+ * Eleven-step colour ramps derived in OKLCh.
+ *
+ * The governing rule is the anchor guarantee: a hex the caller supplied comes
+ * back out of the ramp as the *same string*, byte for byte. Everything else on
+ * the ramp is generated. That is what lets an existing site adopt craft without
+ * a single pixel moving — the colours already shipped stay literal, and only
+ * the steps nobody had picked by hand are computed.
+ */
+
+/** The eleven steps, light to dark. */
+declare const RAMP_STEPS: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+type RampStep = (typeof RAMP_STEPS)[number];
+/**
+ * Target OKLCh lightness per step. Spacing is tighter at the light end, where
+ * the eye resolves smaller differences, and opens up through the shadows.
+ */
+declare const LIGHTNESS_CURVE: Readonly<Record<RampStep, number>>;
+interface Ramp {
+    /** Step to hex. The anchor step holds the caller's exact input string. */
+    ramp: Record<RampStep, string>;
+    /** Which step the seed was placed at. */
+    anchor: RampStep;
+    /** The seed, in OKLCh. */
+    seed: Oklch;
+}
+interface RampOptions {
+    /** Force the seed onto this step instead of placing it by lightness. */
+    step?: RampStep;
+    /** Gamut to map generated steps into. Defaults to sRGB. */
+    gamut?: Gamut;
+}
+/**
+ * Build an eleven-step ramp from one seed colour.
+ *
+ * The seed is placed on the step its lightness is nearest (or `options.step`),
+ * and that step returns the input string unchanged. Remaining steps hold the
+ * seed's hue, take their lightness from `LIGHTNESS_CURVE`, and scale chroma by
+ * the envelope normalised so the anchor keeps exactly the chroma it had.
+ */
+declare function ramp(seed: string, options?: RampOptions): Ramp;
+interface RampFromAnchorsOptions {
+    gamut?: Gamut;
+}
+/**
+ * Build a ramp from two or more known steps.
+ *
+ * Every hex the caller provides is returned unchanged. Gaps between anchors are
+ * interpolated in OKLCh — lightness, chroma and hue each moving on the shortest
+ * path — and steps outside the anchored span extend the nearest anchor along
+ * `LIGHTNESS_CURVE`. This is the entry point Phase 5 uses, where the 400/500/600
+ * steps are already shipped values that must not move.
+ */
+declare function rampFromAnchors(anchors: Partial<Record<RampStep, string>>, options?: RampFromAnchorsOptions): Record<RampStep, string>;
+
+/**
+ * Contrast: WCAG 2.x ratio and APCA-W3 lightness contrast (Lc).
+ *
+ * Both, deliberately. WCAG 2.x is what an audit, a client and the law ask for.
+ * APCA is what actually tracks readability on dark backgrounds, where WCAG 2.x
+ * is known to pass text that is genuinely hard to read. The house bar is a pair:
+ * clear 4.5:1 *and* Lc 60, or it is not an accent that carries body text.
+ */
+/** WCAG 2.x contrast ratio, 1..21. Order-independent. */
+declare function wcagContrast(a: string, b: string): number;
+/**
+ * APCA-W3 0.1.9 lightness contrast, returned as Lc.
+ *
+ * Sign carries polarity: positive is dark text on a light background, negative
+ * is light text on dark. Callers that only care about legibility take the
+ * absolute value; the house bar is |Lc| >= 60 for body text.
+ */
+declare function apcaContrast(text: string, background: string): number;
+interface ContrastCheck {
+    text: string;
+    background: string;
+    /** WCAG 2.x ratio. */
+    wcag: number;
+    /** APCA Lc, signed. */
+    lc: number;
+    /** Clears 4.5:1 — WCAG AA for body text. */
+    passesAA: boolean;
+    /** Clears 3:1 — WCAG AA for large text and non-text UI. */
+    passesAALarge: boolean;
+    /** Clears |Lc| 60 — the house bar for body text on any surface. */
+    passesLc60: boolean;
+    /** Human-readable, and the string emitted as a CSS comment beside the pair. */
+    note: string;
+}
+/** Measure one text-on-background pair against both models. */
+declare function checkPair(text: string, background: string): ContrastCheck;
+
+/**
+ * Semantic tokens derived from a small set of anchors, with a contrast report.
+ *
+ * The point of deriving rather than hand-picking is not tidiness. It is that a
+ * hand-picked "accessible variant of the accent" is a guess that nobody
+ * re-checks when the accent changes. `accentFork` walks the ramp and returns the
+ * first step that actually clears the bar on every background it will sit on,
+ * and records the measured ratio next to it.
+ */
+
+interface AccentFork {
+    /** The chosen colour. */
+    hex: string;
+    /** Which ramp step it came from. */
+    step: RampStep;
+    /** Measurements against every background it was tested on. */
+    checks: ContrastCheck[];
+    /** Emitted as a CSS comment beside the token, so the ratio is never a guess. */
+    note: string;
+    /**
+     * True when no step cleared both bars and the least-bad was returned. Callers
+     * must surface this: a silently-failing accent is the exact defect this
+     * function exists to remove.
+     */
+    degraded: boolean;
+}
+interface AccentForkOptions {
+    /** Minimum WCAG 2.x ratio. Defaults to 4.5 (AA body text). */
+    minWcag?: number;
+    /** Minimum absolute APCA Lc. Defaults to 60 (house bar for body text). */
+    minLc?: number;
+}
+/**
+ * The first ramp step that clears both contrast bars against every background.
+ *
+ * Searched light-to-dark or dark-to-light depending on which direction the
+ * backgrounds sit, so the answer is the *closest* passing step rather than the
+ * most extreme one — an accent that has been dragged to near-white to pass a
+ * checker has stopped being the brand colour.
+ */
+declare function accentFork(rampSteps: Record<RampStep, string>, on: string[], options?: AccentForkOptions): AccentFork;
+interface SemanticInput {
+    /** Seed or anchored steps for the accent hue. */
+    accent: string | Partial<Record<RampStep, string>>;
+    /** Page background, darkest surface first. */
+    bgCanvas: string;
+    bgBase?: string;
+    bgSurface: string;
+    bgElevated: string;
+    /** Body text ramp. */
+    textPrimary: string;
+    textSecondary: string;
+    textMuted: string;
+    /** Hairlines. */
+    borderSubtle: string;
+    borderStrong: string;
+    /** Status hues. */
+    success: string;
+    warning: string;
+    danger: string;
+    info: string;
+    /** Overrides written verbatim, for values craft cannot derive (rgba, etc). */
+    overrides?: Record<string, string>;
+}
+interface ContrastReport {
+    checks: ContrastCheck[];
+    /** Pairs that fail WCAG AA or the Lc60 house bar. */
+    failures: ContrastCheck[];
+    accent: AccentFork;
+}
+interface SemanticResult {
+    /** The 22 `--craft-*` semantic tokens, name to value. */
+    tokens: Record<string, string>;
+    /** Per-token provenance comment, emitted beside the declaration. */
+    notes: Record<string, string>;
+    report: ContrastReport;
+    /** The accent ramp, for callers that want the raw steps too. */
+    accentRamp: Record<RampStep, string>;
+}
+/** Derive the semantic layer, measuring every text-on-surface pair as it goes. */
+declare function semantic(input: SemanticInput): SemanticResult;
+
+/**
+ * Motion numbers. One set, shared by CSS and by every JS motion library.
+ *
+ * The divergence this replaces was not theoretical: `packages/ui/tokens/
+ * component.css` shipped `--ease-emphasized` byte-identical to `--ease-standard`
+ * (so "emphasized" emphasised nothing), and `--ease-exit` as
+ * `cubic-bezier(0.4, 0, 1, 1)` — an ease-*in* curve, which starts slow and
+ * accelerates out of view. That is the one curve never to use for UI: it makes a
+ * dismissal feel like it is being dragged away from the user.
+ *
+ * `EASE_TUPLE` holds the same four control points as `EASE`, so a Framer Motion
+ * or GSAP transition and a CSS transition on the same element cannot drift.
+ */
+/** CSS `cubic-bezier()` strings. */
+declare const EASE: {
+    /** Entrances and anything arriving. Decelerates hard into place. */
+    readonly out: "cubic-bezier(0.23, 1, 0.32, 1)";
+    /** Moves that start and end on screen: a panel resizing, a value morphing. */
+    readonly inOut: "cubic-bezier(0.77, 0, 0.175, 1)";
+    /** Drawers and sheets — a longer settle than a dropdown wants. */
+    readonly drawer: "cubic-bezier(0.32, 0.72, 0, 1)";
+    /** Scroll-triggered reveals. Gentler than `out`, which snaps at this length. */
+    readonly reveal: "cubic-bezier(0.22, 0.61, 0.36, 1)";
+};
+type EaseName = keyof typeof EASE;
+/** The identical control points, for JS motion libraries. */
+declare const EASE_TUPLE: Readonly<Record<EaseName, readonly [number, number, number, number]>>;
+/**
+ * Durations in milliseconds, scaled to distance travelled and to how often the
+ * user will sit through it. Nothing in UI exceeds 300ms except a drawer and a
+ * one-off reveal.
+ */
+declare const DURATION_MS: {
+    readonly press: 120;
+    readonly tooltip: 150;
+    readonly dropdown: 200;
+    readonly modal: 300;
+    readonly drawer: 400;
+    readonly reveal: 500;
+    readonly stagger: 60;
+};
+type DurationName = keyof typeof DURATION_MS;
+/** The same durations in seconds, for libraries that take seconds. */
+declare const DURATION_S: Readonly<Record<DurationName, number>>;
+/** Spring parameters for libraries that prefer physics to a curve. */
+declare const SPRING: Readonly<{
+    damping: 0.5;
+    stiffness: 0.2;
+}>;
+/** Transform scales. `press` is the tactile dip; `enter` the arrival start. */
+declare const SCALE: Readonly<{
+    press: 0.97;
+    enter: 0.95;
+}>;
+/**
+ * An exit is always faster than the matching entrance.
+ *
+ * Arriving content is asking to be read, so it takes its time. Leaving content
+ * has already been dealt with, and lingering reads as lag.
+ */
+declare const EXIT_RATIO = 0.75;
+/** Milliseconds an exit should take, given its entrance duration. */
+declare function exitDuration(enterMs: number): number;
+
+/**
+ * Whether a thing should animate at all.
+ *
+ * The most common motion defect is not a wrong curve, it is animating something
+ * that should have been instant. An animation the user triggers a hundred times
+ * a day stops being delight and becomes latency they cannot skip, and a
+ * keyboard-driven interaction animating at all fights the person using it.
+ */
+type MotionKind = "entrance" | "exit" | "state" | "reveal" | "signature";
+interface MotionDecision {
+    animate: boolean;
+    /** Suggested duration in ms when `animate`, else 0. */
+    durationMs: number;
+    /** Why — surfaced in review, so a "no" is arguable rather than mysterious. */
+    reason: string;
+}
+interface ShouldAnimateInput {
+    /** Roughly how often one user triggers this in a day. */
+    usesPerDay: number;
+    /** What sets it off. */
+    trigger: "pointer" | "keyboard" | "scroll" | "load" | "system";
+    kind: MotionKind;
+    /** Entrance duration in ms, when the caller has one in mind. */
+    enterMs?: number;
+}
+/** Decide, and say why. */
+declare function shouldAnimate(input: ShouldAnimateInput): MotionDecision;
+
+/**
+ * Fluid space scale and section rhythm, after Utopia.
+ *
+ * Space uses the same `clamp()` maths as type so the two stay in proportion as
+ * the viewport changes. A fixed space scale next to a fluid type scale drifts:
+ * padding that framed a heading at 360px swamps it at 1280px.
+ */
+/** Multiples of the base step, small to large. */
+declare const SPACE_STEPS: {
+    readonly "3xs": 0.25;
+    readonly "2xs": 0.5;
+    readonly xs: 0.75;
+    readonly s: 1;
+    readonly m: 1.5;
+    readonly l: 2;
+    readonly xl: 3;
+    readonly "2xl": 4;
+    readonly "3xl": 6;
+};
+type SpaceStep = keyof typeof SPACE_STEPS;
+interface FluidSpaceOptions {
+    minViewport?: number;
+    maxViewport?: number;
+    /** Base space in px at the small viewport. */
+    minBase?: number;
+    /** Base space in px at the large viewport. */
+    maxBase?: number;
+    rootPx?: number;
+    /** Literal values written through unchanged, for steps a site already ships. */
+    pin?: Partial<Record<string, string>>;
+}
+/**
+ * Build the space scale.
+ *
+ * One-up pairs (`s-m`, `m-l`, ...) are emitted alongside the steps because the
+ * common real need is a gap that grows *faster* than the scale — a stack that is
+ * `s` on mobile and `m` on desktop. Without the pairs that gets hand-written as
+ * a bespoke clamp every time, which is how a space scale stops being a scale.
+ */
+declare function fluidSpace(options?: FluidSpaceOptions): Record<string, string>;
+interface SectionRhythmOptions {
+    /** Vertical padding for a tight section. Literal CSS, or px min/max. */
+    sm?: string | {
+        min: number;
+        max: number;
+    };
+    md?: string | {
+        min: number;
+        max: number;
+    };
+    lg?: string | {
+        min: number;
+        max: number;
+    };
+    minViewport?: number;
+    maxViewport?: number;
+    rootPx?: number;
+}
+/**
+ * Section vertical rhythm: three sizes, not five.
+ *
+ * The shared layer previously shipped five (`xs` through `xl`) with zero
+ * consumers, which is the signature of a scale invented ahead of a need. Three
+ * is what section layouts actually reach for — tight, default, and the one that
+ * gives a section room to breathe.
+ */
+declare function sectionRhythm(options?: SectionRhythmOptions): Record<string, string>;
+
+/**
+ * Fluid type scale, after Utopia (https://utopia.fyi).
+ *
+ * Every step is a `clamp()` interpolating between a size at the small viewport
+ * and a size at the large one, so there are no breakpoint jumps in type.
+ *
+ * The interpolation term is `rem + vw`, never bare `vw`. A bare-`vw` font size
+ * ignores the user's browser text-size setting entirely, which fails WCAG 1.4.4
+ * — text must survive 200% zoom. The `rem` component is what keeps zoom working.
+ */
+/** Steps emitted, small to large. */
+declare const TYPE_STEPS: readonly [-2, -1, 0, 1, 2, 3, 4, 5];
+type TypeStep = (typeof TYPE_STEPS)[number];
+interface FluidTypeOptions {
+    /** Viewport width in px at which the minimum size applies. */
+    minViewport?: number;
+    /** Viewport width in px at which the maximum size applies. */
+    maxViewport?: number;
+    /** Step-0 size in px at the small viewport. */
+    minBase?: number;
+    /** Step-0 size in px at the large viewport. */
+    maxBase?: number;
+    /** Ratio between steps at the small viewport. */
+    minRatio?: number;
+    /** Ratio between steps at the large viewport. */
+    maxRatio?: number;
+    /**
+     * Literal values for specific steps, written through unchanged.
+     *
+     * This is how a live site adopts the scale without its type resizing: pin the
+     * steps it already ships, and only the steps it never defined are generated.
+     */
+    pin?: Partial<Record<TypeStep, string>>;
+    /** Root font size in px. Defaults to 16. */
+    rootPx?: number;
+}
+/**
+ * One `clamp()` interpolating a px range across a viewport range.
+ *
+ * Exported because the space scale needs exactly the same maths.
+ */
+declare function fluidClamp(minPx: number, maxPx: number, minViewport: number, maxViewport: number, rootPx?: number): string;
+interface FluidTypeResult {
+    /** `--craft-step--2` .. `--craft-step-5`, name to value. */
+    tokens: Record<string, string>;
+    /** Which steps were pinned rather than generated. */
+    pinned: TypeStep[];
+}
+/** Build the fluid type scale. */
+declare function fluidType(options?: FluidTypeOptions): FluidTypeResult;
+
+/**
+ * Emit plain CSS custom properties.
+ *
+ * Plain custom properties, not a Tailwind theme and not a JS object, because the
+ * consumers do not agree on a styling engine: the monorepo is on Tailwind v4,
+ * one client site is on Tailwind v3, and another has no Tailwind at all. Custom
+ * properties are the only output all three can read without a build step.
+ */
+
+interface EmitCssOptions {
+    /** Selector the block is written under. Defaults to `:root`. */
+    selector?: string;
+    /** Provenance comments, keyed by token name. */
+    notes?: Record<string, string>;
+    /** Indent for each declaration. Defaults to two spaces. */
+    indent?: string;
+}
+/** Render a token map as one CSS rule, with notes as trailing comments. */
+declare function emitCss(tokens: Record<string, string>, options?: EmitCssOptions): string;
+interface CraftTokensInput extends SemanticInput {
+    /** Selector for the emitted block. Defaults to `:root`. */
+    selector?: string;
+    /** Type scale options. Pass `pin` to reproduce a site's existing sizes exactly. */
+    type?: FluidTypeOptions;
+    /** Space scale options. */
+    space?: FluidSpaceOptions;
+    /** Section rhythm overrides. */
+    section?: Parameters<typeof sectionRhythm>[0];
+}
+interface CraftTokensResult {
+    /** The stylesheet text, ready to write to a `.css` file. */
+    css: string;
+    /** Every token emitted, name to value. */
+    tokens: Record<string, string>;
+    report: SemanticResult["report"];
+    ramps: {
+        accent: Record<RampStep, string>;
+    };
+}
+/** Motion tokens are fixed house numbers, identical for every consumer. */
+declare function motionTokens(): Record<string, string>;
+/**
+ * The whole emitted layer: colour derived from the caller's anchors, motion from
+ * the house constants, and a contrast report the caller is expected to read.
+ */
+declare function craftTokens(input: CraftTokensInput): CraftTokensResult;
+
+/**
+ * Typographic settings that are house habits rather than per-project choices.
+ *
+ * These numbers were already being written by hand, identically, across separate
+ * client repos — `-0.01em` display tracking appears in two codebases that share
+ * no code. Systematising them is the point: quality that depends on somebody
+ * remembering to type `-0.01em` tracks per-build effort rather than the standard.
+ */
+declare const HOUSE_TYPE: {
+    /**
+     * Letter-spacing. Display type is set tighter because tracking that reads as
+     * neutral at 16px reads as loose at 48px; buttons and eyebrows go the other
+     * way, because short all-caps strings need air to stay countable.
+     */
+    readonly tracking: {
+        readonly display: "-0.01em";
+        readonly heading: "-0.005em";
+        readonly body: "0em";
+        readonly button: "0.12em";
+        readonly eyebrow: "0.24em";
+    };
+    /** Line height. Tighter as type gets larger, since the eye tracks a shorter return. */
+    readonly leading: {
+        readonly display: "1.05";
+        readonly heading: "1.1";
+        readonly subheading: "1.3";
+        readonly body: "1.6";
+    };
+    /**
+     * Measure, in `ch`. Below ~45 the eye returns too often; above ~75 it loses
+     * the line on the way back.
+     */
+    readonly measure: {
+        readonly narrow: "45ch";
+        readonly body: "65ch";
+        readonly wide: "75ch";
+    };
+};
+/** Emit the type-feature tokens. */
+declare function typeFeatureTokens(): Record<string, string>;
+
+/**
+ * Row density for data-dense software surfaces.
+ *
+ * Three densities, all on a 4px grid, following the convention Linear and Stripe
+ * both settled on. A back office and a marketing page have genuinely different
+ * needs: a table an operator scans for six hours wants 32px rows, and the same
+ * component on a client-facing dashboard wants 48px so it does not read as a
+ * spreadsheet.
+ *
+ * Emitted under `[data-density]`, so a shell sets it once and every table below
+ * inherits rather than each one taking a prop.
+ */
+declare const DENSITIES: {
+    readonly compact: {
+        readonly rowPx: 32;
+        readonly padXPx: 8;
+        readonly padYPx: 4;
+        readonly fontPx: 13;
+    };
+    readonly comfortable: {
+        readonly rowPx: 40;
+        readonly padXPx: 12;
+        readonly padYPx: 8;
+        readonly fontPx: 14;
+    };
+    readonly spacious: {
+        readonly rowPx: 48;
+        readonly padXPx: 16;
+        readonly padYPx: 12;
+        readonly fontPx: 15;
+    };
+};
+type DensityName = keyof typeof DENSITIES;
+interface DensityCssOptions {
+    /** Which density the bare `:root` block carries. Defaults to comfortable. */
+    base?: DensityName;
+    rootPx?: number;
+}
+/**
+ * Emit the density tokens: a default set plus one `[data-density="..."]` block
+ * per density.
+ */
+declare function densityCss(options?: DensityCssOptions): string;
+/** The density tokens as a flat map, for callers emitting their own CSS. */
+declare function densityTokens(name: DensityName, rootPx?: number): Record<string, string>;
+
+/**
+ * Restraint: the budget that separates designed from decorated.
+ *
+ * Differentiation guards can only tell you a site differs from its siblings.
+ * They pass anything ugly, so long as it is distinctively ugly. What they cannot
+ * see is the commonest quality failure in practice, which is not sameness but
+ * accumulation: eighteen font sizes, six shadows, four competing accent hues,
+ * each added reasonably, together reading as noise.
+ *
+ * Pure over strings. No filesystem, no parser, no dependencies — so a guard, a
+ * CI check and an editor can all run it on the same input and agree.
+ */
+interface RestraintBudget {
+    maxFontSizes: number;
+    maxFontWeights: number;
+    /** Excludes the monospace face, which is a functional choice not a stylistic one. */
+    maxFontFamilies: number;
+    maxRadii: number;
+    maxShadows: number;
+    /** Accent hues must cluster within this many degrees in OKLCh. */
+    accentHueClusterDeg: number;
+    /** Longest permitted UI transition/animation, in ms. */
+    maxUiDurationMs: number;
+}
+declare const HOUSE_BUDGET: RestraintBudget;
+type RestraintSeverity = "error" | "warning";
+interface RestraintViolation {
+    rule: string;
+    severity: RestraintSeverity;
+    message: string;
+    /** The offending values, so the message is actionable rather than a count. */
+    found: string[];
+}
+interface RestraintReport {
+    ok: boolean;
+    violations: RestraintViolation[];
+    /** What was counted, for a report that shows headroom as well as failure. */
+    counts: Record<string, number>;
+}
+interface CheckRestraintInput {
+    /** Concatenated stylesheet text. */
+    css: string;
+    /** Concatenated markup or component source, for class-level rules. */
+    markup?: string;
+    budget?: Partial<RestraintBudget>;
+}
+/**
+ * Check a stylesheet against the restraint budget.
+ *
+ * Returns every violation rather than the first, because a budget report is only
+ * useful if it shows the whole picture at once.
+ */
+declare function checkRestraint(input: CheckRestraintInput): RestraintReport;
+
+/**
+ * Tailwind adapters.
+ *
+ * Two, because the estate is on two major versions and neither is going to move
+ * for the other. Both point at the same `--craft-*` custom properties rather
+ * than restating values, so a Tailwind utility and a hand-written rule cannot
+ * disagree.
+ */
+
+interface TailwindPreset {
+    theme: {
+        extend: Record<string, unknown>;
+    };
+}
+/**
+ * A Tailwind v3 preset, for consumers on the older config format.
+ *
+ * Every entry is a `var()` reference. That matters: a preset that inlined the
+ * computed values would freeze them at build time, and the point of the token
+ * layer is that a site can override an anchor without rebuilding the preset.
+ */
+declare function tailwindV3Preset(): TailwindPreset;
+/**
+ * The Tailwind v4 `@theme inline` block.
+ *
+ * `inline` is required rather than optional: without it Tailwind copies the
+ * value at build time, so a runtime override of the underlying custom property
+ * would not reach the generated utility.
+ */
+declare function tailwindV4Theme(): string;
+/** Density names, re-exported so a consumer can type its shell prop. */
+declare const DENSITY_NAMES: DensityName[];
+
+export { type AccentFork, type AccentForkOptions, type CheckRestraintInput, type ContrastCheck, type ContrastReport, type CraftTokensInput, type CraftTokensResult, DENSITIES, DENSITY_NAMES, DURATION_MS, DURATION_S, type DensityCssOptions, type DensityName, type DurationName, EASE, EASE_TUPLE, EXIT_RATIO, type EaseName, type EmitCssOptions, type FluidSpaceOptions, type FluidTypeOptions, type FluidTypeResult, type Gamut, HOUSE_BUDGET, HOUSE_TYPE, LIGHTNESS_CURVE, type MotionDecision, type MotionKind, type Oklch, type OklchToHexOptions, RAMP_STEPS, type Ramp, type RampFromAnchorsOptions, type RampOptions, type RampStep, type RestraintBudget, type RestraintReport, type RestraintSeverity, type RestraintViolation, type Rgb, SCALE, SPACE_STEPS, SPRING, type SectionRhythmOptions, type SemanticInput, type SemanticResult, type ShouldAnimateInput, type SpaceStep, TYPE_STEPS, type TailwindPreset, type TypeStep, accentFork, apcaContrast, checkPair, checkRestraint, craftTokens, deltaEOk, deltaEOkHex, densityCss, densityTokens, emitCss, exitDuration, fluidClamp, fluidSpace, fluidType, formatHex, hexToOklch, inP3Gamut, inSrgbGamut, motionTokens, oklchToHex, oklchToRgb, parseHex, ramp, rampFromAnchors, sectionRhythm, semantic, shouldAnimate, tailwindV3Preset, tailwindV4Theme, toGamut, typeFeatureTokens, wcagContrast };