@pitlane/theme 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,722 @@
+import { ElementProps, Handle, MixinDescriptor, RemixElement, css as css$1 } from "remix/ui";
+import * as CSS from "csstype";
+//#region src/brands.d.ts
+/**
+ * The twelve DTCG token types, in canonical order.
+ *
+ * @internal
+ */
+declare const TOKEN_TYPES: readonly ["color", "dimension", "duration", "fontFamily", "fontWeight", "number", "cubicBezier", "shadow", "border", "transition", "gradient", "strokeStyle"];
+/** The twelve DTCG token `$type` values. @see {@link AnyToken} */
+type TokenType = (typeof TOKEN_TYPES)[number];
+declare const COLOR: unique symbol;
+declare const DIMENSION: unique symbol;
+declare const DURATION: unique symbol;
+declare const FONT_FAMILY: unique symbol;
+declare const FONT_WEIGHT: unique symbol;
+declare const NUMBER: unique symbol;
+declare const CUBIC_BEZIER: unique symbol;
+declare const SHADOW: unique symbol;
+declare const BORDER: unique symbol;
+declare const TRANSITION: unique symbol;
+declare const GRADIENT: unique symbol;
+declare const STROKE_STYLE: unique symbol;
+/** Compile-time brand for a `color` token. */
+type ColorToken = string & {
+  readonly [COLOR]: true;
+};
+/** Compile-time brand for a `dimension` token. */
+type DimensionToken = string & {
+  readonly [DIMENSION]: true;
+};
+/** Compile-time brand for a `duration` token. */
+type DurationToken = string & {
+  readonly [DURATION]: true;
+};
+/** Compile-time brand for a `fontFamily` token. */
+type FontFamilyToken = string & {
+  readonly [FONT_FAMILY]: true;
+};
+/** Compile-time brand for a `fontWeight` token. */
+type FontWeightToken = string & {
+  readonly [FONT_WEIGHT]: true;
+};
+/** Compile-time brand for a `number` token. */
+type NumberToken = string & {
+  readonly [NUMBER]: true;
+};
+/** Compile-time brand for a `cubicBezier` token. */
+type CubicBezierToken = string & {
+  readonly [CUBIC_BEZIER]: true;
+};
+/** Compile-time brand for a `shadow` token. */
+type ShadowToken = string & {
+  readonly [SHADOW]: true;
+};
+/** Compile-time brand for a `border` token. */
+type BorderToken = string & {
+  readonly [BORDER]: true;
+};
+/** Compile-time brand for a `transition` token. */
+type TransitionToken = string & {
+  readonly [TRANSITION]: true;
+};
+/** Compile-time brand for a `gradient` token. */
+type GradientToken = string & {
+  readonly [GRADIENT]: true;
+};
+/** Compile-time brand for a `strokeStyle` token. */
+type StrokeStyleToken = string & {
+  readonly [STROKE_STYLE]: true;
+};
+/**
+ * Maps each {@link TokenType} to its token brand.
+ *
+ * @internal
+ */
+interface BrandByType {
+  color: ColorToken;
+  dimension: DimensionToken;
+  duration: DurationToken;
+  fontFamily: FontFamilyToken;
+  fontWeight: FontWeightToken;
+  number: NumberToken;
+  cubicBezier: CubicBezierToken;
+  shadow: ShadowToken;
+  border: BorderToken;
+  transition: TransitionToken;
+  gradient: GradientToken;
+  strokeStyle: StrokeStyleToken;
+}
+/**
+ * The union of all twelve token brands. Brands are compile-time tags
+ * naming each token's type; they let {@link css} reject a dimension
+ * where a color belongs. They exist only in the type system — every
+ * ref is a plain string at runtime, so brands cost nothing — and they
+ * are theme-independent, so tokens minted by two different
+ * {@link createTheme} calls mix freely in one {@link css} call.
+ */
+type AnyToken = BrandByType[TokenType];
+//#endregion
+//#region src/types.d.ts
+/**
+ * A DTCG group node: an optional `$type` shared by descendants, plus
+ * nested groups and tokens.
+ *
+ * @internal
+ */
+interface TokenGroup {
+  $type?: TokenType;
+  $description?: string;
+  $extensions?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+/**
+ * The input document {@link createTheme} accepts, shaped by the
+ * [W3C DTCG format](https://www.designtokens.org/tr/drafts/format/). A
+ * node with a `$value` is a token; every other key is a group, and
+ * groups nest to any depth. A token's type comes from its own
+ * `$type`, from the token it aliases, or from the nearest ancestor
+ * group's `$type`, in that order.
+ *
+ * Each `$type` fixes the accepted `$value` forms and how the value
+ * serializes into CSS:
+ *
+ * | `$type` | Accepted `$value` | Serializes to |
+ * | --- | --- | --- |
+ * | `color` | CSS color string, or `{ colorSpace, components, alpha?, hex? }` | the string as written, `hex` when present, or the color-space function (`oklch(…)`, `color(display-p3 …)`) |
+ * | `dimension` | `"16px"`, or `{ value, unit }` with `px` or `rem` | the string verbatim, or concatenation |
+ * | `duration` | `"200ms"`, or `{ value, unit }` with `ms` or `s` | the string verbatim, or concatenation |
+ * | `fontFamily` | string or non-empty array of strings | quoted where needed, comma-joined |
+ * | `fontWeight` | number 1–1000, or a DTCG keyword like `"semi-bold"` | the number (keywords map to numbers) |
+ * | `number` | number | the number |
+ * | `cubicBezier` | `[x1, y1, x2, y2]` | `cubic-bezier(…)` |
+ * | `shadow` | `{ color, offsetX, offsetY, blur?, spread?, inset? }`, or an array of them | a CSS shadow list, `inset` first when `inset` is `true` |
+ * | `border` | `{ color, width, style }` | `width style color` |
+ * | `transition` | `{ duration, timingFunction, delay? }` | `duration timing-function delay` |
+ * | `gradient` | array of `{ color, position }` stops | a color-stop list for use inside `linear-gradient(…)` |
+ * | `strokeStyle` | keyword or object | the keyword, or `dashed` for the object form |
+ *
+ * Gradient stop positions must be literal numbers, though stop colors
+ * may be aliases. `typography` tokens throw — they need one variable
+ * per subproperty, which is not built.
+ *
+ * Only the object form of a `dimension` or `duration` is unit-checked.
+ * The string form is emitted verbatim, which is the way in for units
+ * the DTCG format does not cover (`em`, `ch`, `%`) and for computed
+ * values such as `clamp(…)`.
+ *
+ * A `$value` of `"{path.to.token}"` is an alias: it resolves to
+ * `var()` indirection in the emitted CSS, not a copied value, which is
+ * what makes mode overrides cascade. Aliases work as full token values
+ * and inside composite sub-values (e.g. a shadow's `color`), and they
+ * are type-checked — a token with an explicit `$type` only aliases a
+ * token of that same type. Unknown targets and reference cycles throw.
+ *
+ * @see {@link createTheme}
+ * @see {@link TokenTree} for the resulting accessor shape.
+ * @see {@link DeepPartialTokens} for the mode-override shape.
+ */
+type DTCGDocument = TokenGroup;
+type GroupType<N, Inherited> = N extends {
+  $type: infer Ty extends TokenType;
+} ? Ty : Inherited;
+type BrandOf<Ty> = Ty extends TokenType ? BrandByType[Ty] : never;
+type TokenTypeOf<N, Root, Inherited> = N extends {
+  $type: infer Ty extends TokenType;
+} ? Ty : N extends {
+  $value: `{${infer P}}`;
+} ? TypeAtPath<Root, P, Root, GroupType<Root, undefined>> : Inherited extends TokenType ? Inherited : never;
+type MatchKey<N, S extends string> = keyof N extends (infer K) ? K extends string | number ? `${K}` extends S ? K : never : never : never;
+type TypeAtPath<N, P extends string, Root, Inherited> = P extends `${infer Head}.${infer Rest}` ? MatchKey<N, Head> extends (infer K) ? [K] extends [never] ? never : TypeAtPath<N[K & keyof N], Rest, Root, GroupType<N[K & keyof N], Inherited>> : never : MatchKey<N, P> extends (infer K) ? [K] extends [never] ? never : TokenTypeOf<N[K & keyof N], Root, Inherited> : never;
+type TreeOf<N, Root, Inherited> = { [K in Exclude<keyof N, `$${string}`>]: N[K] extends {
+  $value: unknown;
+} ? BrandOf<TokenTypeOf<N[K], Root, Inherited>> : TreeOf<N[K], Root, GroupType<N[K], Inherited>>; };
+/**
+ * The accessor shape for a document `T`: the same nesting as the
+ * document, with every token leaf replaced by its branded `var(--…)`
+ * reference string. Numeric keys index with brackets
+ * (`t.color.gray[900]`).
+ *
+ * An `any` document (e.g. from `JSON.parse`) short-circuits to
+ * `unknown` — mapping over `any` would otherwise recurse without
+ * bound.
+ *
+ * @see {@link ThemeResult}
+ */
+type TokenTree<T> = 0 extends 1 & T ? unknown : TreeOf<T, T, GroupType<T, undefined>>;
+/**
+ * The mode-override shape for a document `T`: every group is optional
+ * and each token node is reduced to `{ $value }`. A mode overrides a
+ * token's value only, never its `$type` or structure.
+ *
+ * An `any` document short-circuits to `unknown`, as in
+ * {@link TokenTree}.
+ *
+ * @see {@link ThemeOptions}
+ */
+type DeepPartialTokens<T> = 0 extends 1 & T ? unknown : { [K in Exclude<keyof T, `$${string}`>]?: T[K] extends {
+  $value: unknown;
+} ? {
+  $value: unknown;
+} : DeepPartialTokens<T[K]>; };
+//#endregion
+//#region src/theme.d.ts
+/**
+ * Options for {@link createTheme}.
+ *
+ * @see {@link DeepPartialTokens} for the override shape.
+ */
+interface ThemeOptions<T> {
+  /**
+   * Per-appearance token overrides. Each mode is a partial of the
+   * base document that may set `$value` only; its overrides emit
+   * inside an `@media (prefers-color-scheme: <mode>)` block, so the
+   * OS appearance setting flips the affected variables with no
+   * attribute selectors and no JavaScript.
+   */
+  modes?: {
+    /** Overrides applied under `prefers-color-scheme: light`. */
+    light?: DeepPartialTokens<T>;
+    /** Overrides applied under `prefers-color-scheme: dark`. */
+    dark?: DeepPartialTokens<T>;
+  };
+}
+/**
+ * Props for the {@link ThemeComponent}. `nonce` sets the `nonce`
+ * attribute on the emitted `<style>` element for Content Security
+ * Policy setups.
+ */
+type ThemeProps = {
+  /** CSP nonce forwarded to the `<style>` element's `nonce` attribute. */
+  nonce?: string;
+};
+/**
+ * The `<Theme />` component returned by {@link createTheme}. Render it
+ * once near the document root (e.g. inside `<head>`). It renders a
+ * `<style data-pitlane-theme>` element holding the base `:root`
+ * declarations plus one `@media` block per configured mode, streams
+ * identically on the server and the client, and escapes the style
+ * text so token values cannot break out of the tag.
+ *
+ * @see {@link ThemeProps} for the `nonce` prop.
+ */
+type ThemeComponent = (handle: Handle<ThemeProps>) => () => RemixElement;
+/**
+ * The object returned by {@link createTheme}: the typed token
+ * accessor, the `raw` resolver, and the `<Theme />` component.
+ */
+interface ThemeResult<T> {
+  /**
+   * Same-shape accessor over the document: every token leaf is a
+   * branded `var(--…)` reference string. Numeric keys index with
+   * brackets (`t.color.gray[900]`).
+   *
+   * @see {@link TokenTree}
+   */
+  token: TokenTree<T>;
+  /**
+   * Resolves a token ref to its serialized base-mode value, chasing
+   * aliases and composite sub-value references to the end. It always
+   * answers for the base mode, even when a dark override exists,
+   * since mode resolution happens in CSS rather than in JavaScript.
+   * Because refs are plain strings, two themes that mint the same
+   * token path produce identical refs and `raw` cannot tell them
+   * apart, answering for its own theme.
+   *
+   * @param ref - A branded token ref from this theme's accessor.
+   * @throws ThemeError if `ref` names a variable this theme never
+   * minted.
+   */
+  raw(ref: AnyToken): string;
+  /** The `<Theme />` component. @see {@link ThemeComponent} */
+  Theme: ThemeComponent;
+}
+/**
+ * Compiles a DTCG design-token document into a typed accessor, a
+ * `raw` resolver, and a `<Theme />` component. All validation and
+ * serialization happen eagerly here: a malformed document throws
+ * {@link ThemeError} rather than emitting broken CSS.
+ *
+ * Each token becomes a CSS custom property named after its
+ * kebab-cased path — `color.gray.900` becomes `--color-gray-900`.
+ * Two paths that collide after kebab-casing throw, as do names
+ * containing `.`, `{`, or `}`, which the alias syntax reserves.
+ *
+ * Author the document in TypeScript, not imported JSON: `createTheme`
+ * infers a `const` type parameter, so an inline object needs no
+ * `as const`, but a JSON import widens its literals and the token
+ * brands degrade.
+ *
+ * @param config - The token document. Groups nest to any depth; a
+ * node with a `$value` is a token.
+ * @param options - Optional per-mode overrides ({@link ThemeOptions}).
+ * @returns The {@link ThemeResult}: `token`, `raw`, and `Theme`.
+ * @throws ThemeError on any validation failure (unknown or
+ * unresolvable `$type`, reserved characters, variable collision,
+ * unknown or wrong-typed alias, alias cycle, invalid value, or a bad
+ * mode override).
+ *
+ * @see {@link DTCGDocument} for the document shape, the accepted
+ * `$value` forms, and alias semantics.
+ *
+ * @example
+ * ```ts
+ * export let { token: t, raw, Theme } = createTheme(
+ *     {
+ *         color: {
+ *             $type: "color",
+ *             white: { $value: "#fff" },
+ *             gray: { 900: { $value: "#171717" } },
+ *             bg: { $value: "{color.white}" }, // alias → var() indirection
+ *         },
+ *     },
+ *     { modes: { dark: { color: { bg: { $value: "{color.gray.900}" } } } } },
+ * );
+ *
+ * t.color.bg; // "var(--color-bg)"
+ * raw(t.color.bg); // "#fff" (base mode, alias chased to the end)
+ * ```
+ */
+declare function createTheme<const T extends DTCGDocument>(config: T, options?: ThemeOptions<T>): ThemeResult<T>;
+//#endregion
+//#region src/props.d.ts
+type Wide = "inherit" | "initial" | "unset" | "revert" | "revert-layer";
+type ColorLike = ColorToken | "transparent" | "currentColor" | Wide;
+type Size = DimensionToken | 0 | Wide;
+type SizeAuto = DimensionToken | 0 | "auto" | Wide;
+type SizeIntrinsic = DimensionToken | 0 | "auto" | "min-content" | "max-content" | "fit-content" | Wide;
+type SpacingText = DimensionToken | 0 | "normal" | Wide;
+type LineWidth = DimensionToken | 0 | "thin" | "medium" | "thick" | Wide;
+type Easing = CubicBezierToken | "ease" | "linear" | "ease-in" | "ease-out" | "ease-in-out" | "step-start" | "step-end" | Wide;
+type ShadowLike = ShadowToken | "none" | Wide;
+type Numeric = NumberToken | number | Wide;
+type Repeat1to4<V> = readonly [V] | readonly [V, V] | readonly [V, V, V] | readonly [V, V, V, V];
+type PadItem = DimensionToken | 0;
+type MarginItem = DimensionToken | 0 | "auto";
+/**
+ * Longhands whose values must come from the token document. Each one
+ * narrows the matching CSS property to a token brand plus the small
+ * keyword set the property genuinely needs.
+ *
+ * @see {@link ThemedCSSProps}
+ */
+interface TokenMappedProps {
+  color?: ColorLike;
+  backgroundColor?: ColorLike;
+  borderColor?: ColorLike;
+  borderTopColor?: ColorLike;
+  borderRightColor?: ColorLike;
+  borderBottomColor?: ColorLike;
+  borderLeftColor?: ColorLike;
+  borderBlockColor?: ColorLike;
+  borderInlineColor?: ColorLike;
+  outlineColor?: ColorLike;
+  textDecorationColor?: ColorLike;
+  columnRuleColor?: ColorLike;
+  caretColor?: ColorLike;
+  accentColor?: ColorLike;
+  fill?: ColorLike;
+  stroke?: ColorLike;
+  width?: SizeIntrinsic;
+  height?: SizeIntrinsic;
+  minWidth?: SizeIntrinsic;
+  minHeight?: SizeIntrinsic;
+  maxWidth?: SizeIntrinsic;
+  maxHeight?: SizeIntrinsic;
+  blockSize?: SizeIntrinsic;
+  inlineSize?: SizeIntrinsic;
+  minBlockSize?: SizeIntrinsic;
+  minInlineSize?: SizeIntrinsic;
+  maxBlockSize?: SizeIntrinsic;
+  maxInlineSize?: SizeIntrinsic;
+  flexBasis?: SizeIntrinsic;
+  top?: SizeAuto;
+  right?: SizeAuto;
+  bottom?: SizeAuto;
+  left?: SizeAuto;
+  insetBlockStart?: SizeAuto;
+  insetBlockEnd?: SizeAuto;
+  insetInlineStart?: SizeAuto;
+  insetInlineEnd?: SizeAuto;
+  marginTop?: SizeAuto;
+  marginRight?: SizeAuto;
+  marginBottom?: SizeAuto;
+  marginLeft?: SizeAuto;
+  marginBlockStart?: SizeAuto;
+  marginBlockEnd?: SizeAuto;
+  marginInlineStart?: SizeAuto;
+  marginInlineEnd?: SizeAuto;
+  paddingTop?: Size;
+  paddingRight?: Size;
+  paddingBottom?: Size;
+  paddingLeft?: Size;
+  paddingBlockStart?: Size;
+  paddingBlockEnd?: Size;
+  paddingInlineStart?: Size;
+  paddingInlineEnd?: Size;
+  fontSize?: Size;
+  textIndent?: Size;
+  outlineOffset?: Size;
+  borderTopLeftRadius?: Size;
+  borderTopRightRadius?: Size;
+  borderBottomRightRadius?: Size;
+  borderBottomLeftRadius?: Size;
+  rowGap?: Size;
+  columnGap?: Size;
+  letterSpacing?: SpacingText;
+  wordSpacing?: SpacingText;
+  borderTopWidth?: LineWidth;
+  borderRightWidth?: LineWidth;
+  borderBottomWidth?: LineWidth;
+  borderLeftWidth?: LineWidth;
+  outlineWidth?: LineWidth;
+  padding?: Size | Repeat1to4<PadItem>;
+  paddingBlock?: Size | readonly [PadItem, PadItem];
+  paddingInline?: Size | readonly [PadItem, PadItem];
+  margin?: SizeAuto | Repeat1to4<MarginItem>;
+  marginBlock?: SizeAuto | readonly [MarginItem, MarginItem];
+  marginInline?: SizeAuto | readonly [MarginItem, MarginItem];
+  inset?: SizeAuto | Repeat1to4<MarginItem>;
+  insetBlock?: SizeAuto | readonly [MarginItem, MarginItem];
+  insetInline?: SizeAuto | readonly [MarginItem, MarginItem];
+  borderRadius?: Size | Repeat1to4<PadItem>;
+  gap?: Size | readonly [PadItem, PadItem];
+  fontFamily?: FontFamilyToken | Wide;
+  fontWeight?: FontWeightToken | "normal" | "bold" | "lighter" | "bolder" | Wide;
+  lineHeight?: NumberToken | DimensionToken | "normal" | Wide;
+  opacity?: Numeric;
+  zIndex?: Numeric;
+  flexGrow?: Numeric;
+  flexShrink?: Numeric;
+  order?: Numeric;
+  transitionDuration?: DurationToken | Wide;
+  transitionDelay?: DurationToken | Wide;
+  animationDuration?: DurationToken | Wide;
+  animationDelay?: DurationToken | Wide;
+  transitionTimingFunction?: Easing;
+  animationTimingFunction?: Easing;
+  boxShadow?: ShadowLike;
+  textShadow?: ShadowLike;
+}
+/**
+ * Every CSS property [csstype](https://github.com/frenic/csstype) knows
+ * that {@link TokenMappedProps} does not claim, with lengths narrowed to
+ * `dimension` tokens and times to `duration` tokens.
+ *
+ * Properties whose grammar is a closed keyword set (`display`, `resize`,
+ * `position`, …) resolve to that keyword union. Properties that accept
+ * open-ended values (`background`, `transform`, `gridTemplateColumns`, …)
+ * keep csstype's `string` escape, because CSS genuinely allows any
+ * `calc()`, function, or list there.
+ *
+ * @see {@link ThemedCSSProps}
+ */
+type KeywordProps = Omit<CSS.Properties<DimensionToken | 0, DurationToken>, keyof TokenMappedProps>;
+/**
+ * The style-object type accepted by {@link css} and every {@link tva}
+ * slot.
+ *
+ * Two layers stack. Token-mapped longhands enforce the matching token
+ * brand plus a small set of CSS keywords and the literal `0`. Every
+ * other property carries csstype's value union, so closed-grammar
+ * properties such as `display`, `position`, `resize`, and `overflow`
+ * only accept their real keywords. Unknown keys — nested selectors,
+ * at-rules, and CSS custom properties — recurse or stay loose.
+ *
+ * `Wide` below is the CSS-wide keyword union
+ * `"inherit" | "initial" | "unset" | "revert" | "revert-layer"`.
+ *
+ * | Property family | Accepted values |
+ * | --- | --- |
+ * | `color`, `backgroundColor`, `borderColor`, the four per-side and two logical border colors, `outlineColor`, `textDecorationColor`, `columnRuleColor`, `caretColor`, `accentColor`, `fill`, `stroke` | `ColorToken \| "transparent" \| "currentColor" \| Wide` |
+ * | `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight`, their `blockSize`/`inlineSize` logical forms, `flexBasis` | `DimensionToken \| 0 \| "auto" \| "min-content" \| "max-content" \| "fit-content" \| Wide` |
+ * | `top`, `right`, `bottom`, `left`, `marginTop`, `marginRight`, `marginBottom`, `marginLeft`, and their `inset*`/`margin*` logical start/end forms | `DimensionToken \| 0 \| "auto" \| Wide` |
+ * | `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft`, the logical padding start/end forms, `fontSize`, `textIndent`, `outlineOffset`, the four corner radii, `rowGap`, `columnGap` | `DimensionToken \| 0 \| Wide` |
+ * | `letterSpacing`, `wordSpacing` | `DimensionToken \| 0 \| "normal" \| Wide` |
+ * | `borderTopWidth`, `borderRightWidth`, `borderBottomWidth`, `borderLeftWidth`, `outlineWidth` | `DimensionToken \| 0 \| "thin" \| "medium" \| "thick" \| Wide` |
+ * | `padding`, `margin`, `inset`, `borderRadius` (box shorthands) | a single value as the longhand, or a tuple of 1–4 such values, space-joined |
+ * | `gap`, `paddingBlock`, `paddingInline`, `marginBlock`, `marginInline`, `insetBlock`, `insetInline` | the longhand value, or a 2-tuple |
+ * | `fontFamily` | `FontFamilyToken \| Wide` |
+ * | `fontWeight` | `FontWeightToken \| "normal" \| "bold" \| "lighter" \| "bolder" \| Wide` |
+ * | `lineHeight` | `NumberToken \| DimensionToken \| "normal" \| Wide` |
+ * | `opacity`, `zIndex`, `flexGrow`, `flexShrink`, `order` | `NumberToken \| number \| Wide` (plain numbers stay legal) |
+ * | `transitionDuration`, `transitionDelay`, `animationDuration`, `animationDelay` | `DurationToken \| Wide` |
+ * | `transitionTimingFunction`, `animationTimingFunction` | `CubicBezierToken \| "ease" \| "linear" \| "ease-in" \| "ease-out" \| "ease-in-out" \| "step-start" \| "step-end" \| Wide` |
+ * | `boxShadow`, `textShadow` | `ShadowToken \| "none" \| Wide` |
+ * | every other CSS property | csstype's union for that property, with `dimension` tokens for lengths and `duration` tokens for times |
+ *
+ * @see {@link css}
+ */
+interface ThemedCSSProps extends KeywordProps, TokenMappedProps {
+  [key: string]: ThemedCSSProps | string | number | null | undefined | readonly (string | number)[];
+}
+//#endregion
+//#region src/css.d.ts
+type RemixCSSProps = Parameters<typeof css$1>[0];
+/**
+ * The descriptor {@link css} produces. `MixinDescriptor` is invariant
+ * in its node type, so — exactly like `remix/ui`'s own `css` factory —
+ * the node binds per callsite through the generic parameter.
+ *
+ * @see {@link css}
+ */
+type ThemedCSSMixin<node extends Element = Element> = MixinDescriptor<node, [styles: RemixCSSProps], ElementProps>;
+/**
+ * Brand-enforced wrapper over `remix/ui`'s `css()` mixin. Token-mapped
+ * longhands accept the matching token brand, CSS-wide keywords,
+ * property keywords, and `0`; anything else — including a raw
+ * `color: "#ff0000"` — is a type error. Every other CSS property
+ * carries csstype's value union, so `display`, `position`, `resize`,
+ * and the rest of the closed-grammar properties accept only their real
+ * keywords. Nested selectors, at-rules, and custom properties recurse.
+ *
+ * Branded token refs are already `var()` strings and pass through; an
+ * array value joins with spaces, which is how the box shorthands take
+ * a 1–4 tuple. A comma list needs a template string.
+ *
+ * `css()` is node-generic, exactly like `remix/ui`'s own `css`: the
+ * descriptor binds to the element type of the `mix` position it
+ * appears in, so write `css({ … })` inline at each element and share
+ * {@link ThemedCSSProps} objects, never stored descriptors.
+ *
+ * Interpolating a token into a template string
+ * (`` `1px solid ${t.color.line}` ``) yields a plain string, which the
+ * open-grammar shorthands accept.
+ *
+ * @see {@link ThemedCSSProps} for the accepted per-property values.
+ * @see {@link ThemedCSSMixin} for the returned descriptor.
+ *
+ * @example
+ * ```tsx
+ * <div
+ *     mix={css({
+ *         color: t.color.bg,
+ *         padding: [t.space.sm, t.space.md],
+ *         margin: 0,
+ *         "&:hover": { color: t.color.gray[900] },
+ *     })}
+ * />
+ * ```
+ */
+declare function css<node extends Element = Element>(styles: ThemedCSSProps): ThemedCSSMixin<node>;
+//#endregion
+//#region src/tva.d.ts
+type VariantShape = Record<string, Record<string, ThemedCSSProps>>;
+type VariantValue<K> = K extends "true" | "false" ? boolean : K;
+/**
+ * Controller-approved one-token deviation from the brief: `-readonly` strips
+ * the readonly modifier that a homomorphic mapped type would otherwise
+ * inherit from V's const-inferred (deeply readonly) property modifiers.
+ * TVAProps<F> must yield ordinary mutable optional props for consumers;
+ * readonly inheritance here is an artifact of `const V`, not intent.
+ */
+type Selection<V extends VariantShape> = { -readonly [K in keyof V]?: VariantValue<keyof V[K] & string>; };
+/**
+ * Configuration for {@link tva}. Every style slot is
+ * {@link ThemedCSSProps}, carrying the same brand enforcement as
+ * {@link css}.
+ */
+interface TVAConfig<V extends VariantShape> {
+  /** Styles applied to every invocation, before any variant. */
+  base?: ThemedCSSProps;
+  /**
+   * The variant axes. Each axis maps option names to styles; name
+   * an axis's options `true` and `false` to accept a boolean.
+   */
+  variants?: V;
+  /**
+   * Extra styles applied when every listed variant condition
+   * matches, merged after the individual variants in array order.
+   */
+  compoundVariants?: readonly (Selection<V> & {
+    css: ThemedCSSProps;
+  })[];
+  /**
+   * Options used for axes the caller leaves unset. Passing an axis
+   * `undefined` explicitly still falls back to its default.
+   */
+  defaultVariants?: Selection<V>;
+}
+/**
+ * A variant component built by {@link tva}. Call it with a variant
+ * selection to get a `mix`-ready descriptor; call `resolve` for the
+ * merged {@link ThemedCSSProps} without building a descriptor.
+ */
+interface TVAFn<V extends VariantShape> {
+  /**
+   * Resolves the selection and returns a `mix`-ready descriptor.
+   * Node-generic like {@link css}: `MixinDescriptor` is invariant in
+   * its node, so the element type binds per `mix` callsite.
+   */
+  <node extends Element = Element>(props?: Selection<V>): ThemedCSSMixin<node>;
+  /**
+   * Returns the merged style object for a selection without
+   * producing a descriptor. {@link combine} is built on it.
+   */
+  resolve(props?: Selection<V>): ThemedCSSProps;
+}
+/**
+ * Extracts a {@link tva} component's variant props, like cva's
+ * `VariantProps`. All props are optional; wrap the component to
+ * require one.
+ *
+ * @example
+ * ```ts
+ * export type ButtonProps = TVAProps<typeof button>;
+ * // { intent?: "primary" | "secondary"; size?: "sm" | "md" }
+ * ```
+ */
+type TVAProps<F> = F extends TVAFn<infer V> ? Selection<V> : never;
+/**
+ * Builds a variant resolver modeled on [cva](https://cva.style). Where
+ * cva composes class strings, `tva` composes brand-enforced style
+ * objects into a `mix`-ready descriptor.
+ *
+ * Each invocation resolves the selection by deep-merging `base`, then
+ * every matching variant in declaration order, then every matching
+ * compound variant in array order, and feeds the result to a single
+ * {@link css} call. `defaultVariants` fills in unset axes, and boolean
+ * axes come from options named `true` and `false`.
+ *
+ * @see {@link TVAConfig} for the configuration shape.
+ * @see {@link TVAProps} to extract the props type.
+ *
+ * @example
+ * ```ts
+ * export let button = tva({
+ *     base: { borderRadius: t.radius.md },
+ *     variants: {
+ *         intent: {
+ *             primary: { backgroundColor: t.color.accent },
+ *             secondary: { backgroundColor: "transparent" },
+ *         },
+ *         size: { sm: { fontSize: t.text.sm }, md: { fontSize: t.text.md } },
+ *         block: { true: { display: "flex" } },
+ *     },
+ *     compoundVariants: [
+ *         { intent: "secondary", size: "md", css: { fontSize: t.text.lg } },
+ *     ],
+ *     defaultVariants: { intent: "primary", size: "md" },
+ * });
+ *
+ * <button mix={button({ intent: "secondary", block: true })} />;
+ * ```
+ */
+declare function tva<const V extends VariantShape>(config: TVAConfig<V>): TVAFn<V>;
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends ((arg: infer I) => void) ? I : never;
+type CombinedProps<Fns extends readonly TVAFn<VariantShape>[]> = UnionToIntersection<Exclude<Parameters<Fns[number]>[0], undefined>> extends (infer P) ? { [K in keyof P]: P[K]; } : never;
+/**
+ * A component built by {@link combine}. Accepts the union of the input
+ * components' props and honors each input's own defaults.
+ */
+interface CombinedTVAFn<Fns extends readonly TVAFn<VariantShape>[]> {
+  /** Resolves every input and returns a `mix`-ready descriptor. */
+  <node extends Element = Element>(props?: CombinedProps<Fns>): ThemedCSSMixin<node>;
+  /** Returns the merged style object without building a descriptor. */
+  resolve(props?: CombinedProps<Fns>): ThemedCSSProps;
+}
+/**
+ * Composes {@link tva} components, like cva's `compose`. Each input
+ * resolves independently against the shared props, the results
+ * deep-merge in argument order, and one {@link css} call produces the
+ * descriptor. The result accepts the union of the inputs' props and
+ * honors each input's own defaults.
+ *
+ * @see {@link CombinedTVAFn}
+ *
+ * @example
+ * ```tsx
+ * export let pillButton = combine(button, rounded);
+ * <button mix={pillButton({ intent: "primary", pill: true })} />;
+ * ```
+ */
+declare function combine<Fns extends readonly TVAFn<VariantShape>[]>(...fns: Fns): CombinedTVAFn<Fns>;
+/**
+ * A value {@link cx} accepts: a string, a number, a nested array of
+ * the same, or a record whose truthy keys are emitted. `null`,
+ * `undefined`, and `false` are dropped. Compatible with clsx.
+ */
+type ClassValue = string | number | null | undefined | false | readonly ClassValue[] | Record<string, boolean | null | undefined>;
+/**
+ * clsx-compatible `className` joiner for interop with plain
+ * stylesheets, since `mix` and `className` compose on the same
+ * element. Strings and numbers join with spaces, falsy values drop,
+ * arrays flatten, and truthy object keys join.
+ *
+ * @see {@link ClassValue}
+ *
+ * @example
+ * ```tsx
+ * <span className={cx("mono", isAlias && "alias-tag")} />;
+ * ```
+ */
+declare function cx(...inputs: ClassValue[]): string;
+//#endregion
+//#region src/tokens.d.ts
+/**
+ * The error {@link createTheme} throws for every validation and
+ * serialization failure. Validation is eager, so a bad document never
+ * emits CSS. Every message names the offending token path.
+ *
+ * | Condition | Message shape |
+ * | --- | --- |
+ * | Unknown `$type` | `"color.brand" has unknown $type "sparkles"` |
+ * | Unresolvable `$type` | `"color.brand" has no resolvable $type` |
+ * | Typography token | `"heading": typography tokens are not supported in v1` |
+ * | Reserved character in a name | `Token or group name "a.b" contains characters reserved by DTCG references (".", "{", "}")` |
+ * | Empty CSS identifier | `Token path segment "!" produces an empty CSS identifier` |
+ * | Malformed node | `"color.bg" is neither a group nor a token` |
+ * | Variable-name collision | `Tokens "a" and "b" both produce the CSS variable --x` |
+ * | Alias to a missing token | `"color.bg" references unknown token "color.white"` |
+ * | Alias to a wrong-typed token | `"x" references "space.sm" of type "dimension" where "color" is required` |
+ * | Alias cycle | `Alias cycle: a → b → a` |
+ * | Invalid value for a declared type | `"x" has an invalid color value: …` — also `unknown colorSpace`, `unknown fontWeight keyword`, and `unknown strokeStyle keyword`; an empty `fontFamily` array counts |
+ * | Bad mode override | `Mode override "x" does not exist in the base document`, `Mode override "x" may only set $value`, or (via a cross-type alias) the wrong-typed-alias message |
+ * | Unminted `raw()` ref | `raw(): "var(--x)" names a var this theme never minted` |
+ */
+declare class ThemeError extends Error {
+  name: string;
+}
+//#endregion
+export { type AnyToken, type BorderToken, type ClassValue, type ColorToken, type CombinedTVAFn, type CubicBezierToken, type DTCGDocument, type DeepPartialTokens, type DimensionToken, type DurationToken, type FontFamilyToken, type FontWeightToken, type GradientToken, type NumberToken, type ShadowToken, type StrokeStyleToken, type TVAConfig, type TVAFn, type TVAProps, type ThemeComponent, ThemeError, type ThemeOptions, type ThemeProps, type ThemeResult, type ThemedCSSMixin, type ThemedCSSProps, type TokenTree, type TokenType, type TransitionToken, combine, createTheme, css, cx, tva };