Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
38.5 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * defineTheme — Create an Astryx theme from a flat token map.
 *
 * Adaptations resolve against the effective root axes and components, retaining
 * authored component pins without repeating root typography defaults.
 *
 * Two distribution modes:
 * - Unbuilt: Theme generates CSS and injects a <style> tag at runtime
 * - Built: `astryx theme build` pre-compiles to a CSS file; Theme just
 *   sets the data-astryx-theme attribute
 *
 * Token values can be:
 * - A string: used as-is for both light and dark modes
 * - A [light, dark] tuple: converted to light-dark(light, dark)
 *
 * @example
 * ```
 * const oceanTheme = defineTheme({
 *   name: 'ocean',
 *   tokens: {
 *     '--color-accent': ['#0077B6', '#48CAE4'],    // [light, dark]
 *     '--color-background-surface': ['#F0F8FF', '#0A1628'],
 *     '--radius-container': '16px',                     // same in both modes
 *   },
 *   icons: oceanIcons,
 * });
 *
 * <Theme theme={oceanTheme}>
 *   <App />
 * </Theme>
 * ```
 *
 * SYNC: `DefineThemeInput` is the theme surface. Adding, removing, or renaming
 * a field means updating:
 * - /packages/cli/assets/theme.template.ts (documents every field; the
 *   drift guard is scripts/check-theme-template.test.mjs)
 * - /packages/cli/assets/docs/theme.doc.mjs (`astryx docs theme`)
 */

import type {ReactNode} from 'react';
import type {
  IconEntry,
  IconName,
  NamespacedIconName,
  StoredComponentIconValue,
} from '../Icon/globalIconRegistry';
import type {ComponentIconMap, ComponentIconStaticMap} from '../Icon/index';

/**
 * Icon overrides a theme may declare: any built-in semantic name, plus the
 * namespaced keys components and libraries own (`'richtext:bold'`). Each entry
 * is a React node or a pure synchronous function of `{size, variant}`, where
 * `variant` is one of `Variant` or `undefined`.
 */
type ThemeIconEntries<Variant extends string> = Partial<
  Record<IconName | NamespacedIconName, IconEntry<Variant>>
>;

/**
 * The variant names a base theme lists: exact for a theme from `defineTheme`,
 * any string for another `DefinedTheme`, none without a base.
 */
type BaseThemeIconVariant<Base> = Base extends DefinedTheme
  ? '__iconVariant' extends keyof Base
    ? Base extends {name: string; __iconVariant?(variant: infer Variant): void}
      ? Extract<Variant, string>
      : string
    : string
  : never;

/**
 * The variant names a theme lists: its own `iconVariants` when it sets the
 * field, otherwise the list it inherits from `extends`.
 */
type ThemeIconVariant<
  IconVariants extends ReadonlyArray<string> | undefined,
  Base,
> = [IconVariants] extends [ReadonlyArray<infer Variant extends string>]
  ? Variant
  : BaseThemeIconVariant<Base>;

/**
 * The same names, as a type `defineTheme` does not infer from: only
 * `iconVariants` and `extends` decide a theme's names, never the parameter
 * types of its icon entry functions.
 */
type ThemeIconEntryVariant<
  IconVariants extends ReadonlyArray<string> | undefined,
  Base,
> = [ThemeIconVariant<IconVariants, Base>][IconVariants extends unknown
  ? 0
  : never];

/** The node-valued view of a theme's icons that public reads return. */
type ThemeIconOverrides = Partial<
  Record<IconName | NamespacedIconName, ReactNode>
>;
import type {IndicatorRegistry} from '../Indicator/types';
import type {TypographyConfig} from './types';
import {
  resolveOnMedia,
  type OnMediaOverrides,
  type ResolvedOnMedia,
} from './onMediaTokens';
import {
  colorDefaults,
  spacingDefaults,
  sizeDefaults,
  borderDefaults,
  focusDefaults,
  radiusDefaults,
  shadowDefaults,
  durationDefaults,
  easeDefaults,
  typographyDefaults,
  textSizeDefaults,
  fontWeightDefaults,
  typeScaleDefaults,
} from './tokens.stylex';
import type {MotionScaleConfig} from './expandMotionScale';
import type {ThemeMotionConfig} from './themeMotion';
import type {RadiusScaleConfig} from './expandRadiusScale';
import type {ColorScaleConfig} from './expandColorScale';
import {resolveThemeValues, type ThemeValuesInput} from './resolveThemeValues';
import {
  normalizeThemeAdaptations,
  resolveThemeAdaptationRules,
  resolveThemeGenerativeAxes,
  type NormalizedThemeAdaptations,
  type ResolvedThemeAdaptationRule,
  type ThemeAdaptations,
  type ThemeGenerativeAxes,
} from './themeAdaptations';

import type {DomainTokenName} from './domainTokens';
import {domainTokenDefaults} from './domainTokens/domainTokenDefaults';
import type {SyntaxThemeDefinition} from './syntax';
import {registerTheme} from './themeRegistry';
import {resolveLocalTokenContract} from './localTokens';

// =============================================================================
// Types
// =============================================================================

/** All valid Astryx core token names */
export type CoreTokenName =
  | keyof typeof colorDefaults
  | keyof typeof spacingDefaults
  | keyof typeof sizeDefaults
  | keyof typeof borderDefaults
  | keyof typeof focusDefaults
  | keyof typeof radiusDefaults
  | keyof typeof shadowDefaults
  | keyof typeof durationDefaults
  | keyof typeof easeDefaults
  | keyof typeof typographyDefaults
  | keyof typeof textSizeDefaults
  | keyof typeof fontWeightDefaults
  | keyof typeof typeScaleDefaults;

/** All valid Astryx token names — core + domain tokens */
export type TokenName = CoreTokenName | DomainTokenName;

/**
 * Token value — either a single string or a [light, dark] tuple.
 * Tuples are converted to CSS light-dark() at theme creation time.
 */
export type TokenValue = string | [light: string, dark: string];

/**
 * CSS property values for a style rule.
 *
 * Keys are camelCase CSS properties with string values, OR pseudo-class
 * selectors (starting with `:`) mapping to nested property objects.
 *
 * Pseudo-class keys generate separate CSS rules with the pseudo appended
 * to the component selector. Supported pseudo-classes include `:hover`,
 * `:focus-visible`, `:active`, `:checked`, `:disabled`, etc.
 *
 * A `:hover` override describes the ENABLED control: it is emitted with a
 * guard that keeps it off disabled and `aria-disabled` elements, which
 * `:hover` would otherwise still match. Style the disabled state through
 * `:disabled` instead.
 *
 * An `:active` override follows the touch press model: it applies to a mouse
 * press, and under a coarse primary pointer it applies while Astryx believes
 * the press, not on the touch or through a scroll.
 *
 * @example
 * ```ts
 * {
 *   borderColor: '#8F9296',
 *   ':hover': { borderColor: 'color-mix(in srgb, #8F9296, black 20%)' },
 *   ':focus-visible': { outline: '2px solid var(--color-accent)' },
 * }
 * ```
 */
export type StyleOverrides = Record<string, string | Record<string, string>>;

/**
 * Component style overrides.
 *
 * Each top-level key is a component name (lowercase). Values are objects
 * mapping style keys to CSS property overrides:
 * - `base` — styles applied to all instances of the component
 * - `prop:value` — styles when a visual prop matches (e.g. `variant:secondary`)
 * - `prop:value+prop:value` — intersection of multiple props
 *
 * The `base` key is optional — omit it to only override specific variants.
 *
 * Style values can include pseudo-class keys (`:hover`, `:focus-visible`, etc.)
 * to override interaction states without CSS custom property escape hatches.
 *
 * @example
 * ```
 * components: {
 *   button: {
 *     base: { fontWeight: '600' },
 *     'variant:secondary': { backgroundColor: 'rgba(0,0,0,0.06)' },
 *     'variant:destructive+size:sm': { padding: '2px 6px' },
 *   },
 *   badge: {
 *     'variant:ghost': { border: '1px solid var(--color-border)' },
 *   },
 *   'radio-indicator': {
 *     base: {
 *       borderColor: '#8F9296',
 *       ':hover': { borderColor: 'color-mix(in srgb, #8F9296, black 20%)' },
 *     },
 *   },
 * }
 * ```
 */
export type ComponentStyleMap = Record<string, Record<string, StyleOverrides>>;

/**
 * Input to defineTheme.
 *
 * `IconVariants` is the theme's own `iconVariants` list and `Base` its
 * `extends` theme; together they type the `variant` an icon entry function
 * receives. `defineTheme` infers both.
 */
export interface DefineThemeInput<
  IconVariants extends ReadonlyArray<string> | undefined =
    ReadonlyArray<string> | undefined,
  Base extends DefinedTheme | undefined = DefinedTheme | undefined,
> {
  /** Theme name — used for data-astryx-theme attribute and identification */
  name: string;

  /**
   * Base theme to extend. When provided, the new theme starts with everything
   * the base resolved to — tokens, component overrides, icons, indicators, and
   * its `onDark`/`onLight` surfaces — then applies this input on top. The base
   * theme's values have lowest precedence.
   *
   * The result is flat: an extended theme carries its inheritance in its own
   * resolved output, so `astryx theme build` emits one self-contained
   * stylesheet and the base's CSS does not need to be loaded alongside it.
   *
   * Use this to create variant themes that customize only a few aspects
   * (e.g. icons, accent color) without re-specifying the full theme.
   *
   * @example
   * ```
   * import {neutralTheme} from '@astryxdesign/theme-neutral';
   *
   * const myTheme = defineTheme({
   *   name: 'my-brand',
   *   extends: neutralTheme,
   *   icons: myIcons,
   *   tokens: { '--color-accent': '#FF0000' },
   * });
   * ```
   */
  extends?: Base;
  /**
   * Unified typography configuration — fonts, scale, and weights.
   *
   * Scale controls sizing; roles (body, heading, code) declare
   * fonts, fallbacks, and weights. Heading inherits from body if omitted.
   *
   * Font loading is the consumer's responsibility — add a <link> or
   * @import for your fonts before rendering the theme.
   *
   * @example
   * ```
   * typography: {
   *   scale: { base: 14, ratio: 1.2 },
   *   body: { family: 'Geist', fallbacks: '-apple-system, sans-serif' },
   *   heading: { weight: 'semibold', weights: { 3: 'bold', 4: 'bold' } },
   *   code: { family: 'Geist Mono', fallbacks: '"SF Mono", monospace' },
   * }
   * ```
   */
  typography?: TypographyConfig;
  /**
   * Motion configuration: two knobs (spec:AST-108), a motion scale, or both.
   *
   * - `tempo` (default 1, clamped to 0.75–1.5) scales every motion duration:
   *   the duration tokens and touch motion's springs.
   * - `character` (`'crisp'`, `'standard'` or `'expressive'`) sets the
   *   entrance and move curves; exits and fades never overshoot.
   *
   * Every theme follows each person's Reduce Motion setting; nothing loosens it.
   *
   * A motion scale computes duration min/max variants from base values and a
   * ratio (min = base × ratio, max = base / ratio); its durations win over
   * `tempo`, and explicit `tokens` overrides win over both. Finger tracking,
   * momentum, the keyboard, hover, the press's onset delay and tap flash, and
   * busy loops never follow the knobs; the press release fade follows
   * `tempo`.
   *
   * @example
   * ```
   * motion: { tempo: 1.2, character: 'crisp' }
   *
   * // A motion scale, as before:
   * motion: { fast: 175, medium: 410, slow: 975, ratio: 0.75 }
   *
   * // Suggested starting points:
   * //   Snappy:    { fast: 100, medium: 250, ratio: 0.75 }
   * //   Default:   { fast: 175, medium: 410, slow: 975, ratio: 0.75 }
   * //   Cinematic: { fast: 200, medium: 500, slow: 1200, ratio: 0.7 }
   * ```
   */
  motion?: ThemeMotionConfig;
  /**
   * Radius configuration. Generates radius token overrides
   * from a base unit and multiplier.
   *
   * --radius-none and --radius-full are always fixed (never affected by multiplier).
   * --radius-inner through --radius-page = base * step * multiplier.
   *
   * When omitted, themes use the hardcoded defaults (base=4, multiplier=1).
   * Explicit `tokens` overrides take precedence over radius-generated values.
   *
   * @example
   * ```
   * radius: { base: 4, multiplier: 1 }
   *
   * // Sharp/brutalist — all radii become 0
   * radius: { base: 4, multiplier: 0 }
   * ```
   */
  radius?: RadiusScaleConfig;
  /**
   * Color scale configuration. Generates color token overrides from an
   * accent seed using the HCT perceptual color model.
   *
   * Only generates tokens derivable from the accent — status colors,
   * categorical hues, and fixed tokens (on-dark/on-light) use defaults.
   *
   * `accent` accepts a single hex (same seed for both color schemes) or a
   * `[light, dark]` tuple, matching `TokenValue`. With a tuple, the light
   * scheme's full palette derives from the light seed and the dark
   * scheme's from the dark seed.
   *
   * `accent` is optional — omit it for a neutral-only theme, which keeps
   * the default accent tokens and only themes the neutrals.
   *
   * Precedence vs `tokens`: explicit `tokens` entries win over generated
   * values, token by token. Because `--color-accent-muted`,
   * `--color-text-accent` and `--color-icon-accent` are generated as
   * `var(--color-accent)` references, a `tokens['--color-accent']`
   * override re-points them at runtime. `--color-on-accent` does NOT
   * follow: it is baked from the `color.accent` seed (a contrast
   * computation CSS cannot express), so overriding the accent through
   * `tokens` without also overriding `--color-on-accent` leaves the two
   * out of sync. To re-seat the whole palette per scheme, prefer a tuple
   * `color.accent` over the `tokens['--color-accent']` workaround.
   *
   * @example
   * ```
   * color: { accent: '#0064E0', neutralStyle: 'cool', contrast: 'standard' }
   *
   * // Per-scheme accents — light palette from the first seed, dark from the second
   * color: { accent: ['#0064E0', '#48CAE4'] }
   *
   * // Neutral-only — accent tokens stay at their defaults
   * color: { neutralStyle: 'warm' }
   * ```
   */
  color?: ColorScaleConfig;
  /** Token overrides — flat map of CSS custom property names to values.
   *  Values can be a string or [light, dark] tuple.
   *  Only include tokens you want to override; defaults fill the rest. */
  tokens?: Partial<Record<TokenName, TokenValue>>;
  /** Theme-family-local values keyed by any valid CSS custom-property name;
   *  prefixes do not establish ownership. */
  localTokens?: Record<string, TokenValue>;
  /**
   * Component style overrides — keyed by component name (lowercase).
   * Each entry maps style keys to CSS property overrides, scoped under
   * the theme's data-astryx-theme attribute via @scope.
   *
   * Use `prop:value` keys to target specific visual props. New values
   * not in the base type are automatically detected by `astryx theme build`
   * and generate TypeScript module augmentations for type-safe extensibility.
   *
   * @example
   * ```
   * components: {
   *   button: {
   *     base: { fontWeight: '600' },
   *     'variant:secondary': { backgroundColor: '...' },
   *     'variant:primary-muted': { backgroundColor: '#ECF5FF' }, // new — generates augmentation
   *   },
   *   banner: {
   *     'status:neutral': { backgroundColor: 'var(--color-background-muted)' }, // new status
   *   },
   * }
   * ```
   */
  components?: ComponentStyleMap;
  /**
   * Icon registry — maps semantic icon names and namespaced keys to artwork.
   *
   * An entry is a React node, or a pure synchronous function of
   * `{size, variant}` that returns one. `Icon` passes the size it renders at
   * (`'xsm' | 'sm' | 'md' | 'lg'`), so the theme can map it to its icon
   * library's own props. A function must not use hooks, measure the DOM, read
   * browser globals or mutable state, or have side effects. Its result is
   * final: returning `null` draws nothing instead of falling back to a
   * registered or built-in icon. A `null` or `undefined` node entry falls back.
   *
   * @example
   * ```
   * icons: {
   *   close: <XMarkIcon />,
   *   info: ({size}) => <InfoIcon weight={size === 'sm' ? 'bold' : 'regular'} />,
   * }
   * ```
   *
   * `variant` is typed as the names in `iconVariants` (or the inherited list).
   */
  icons?: ThemeIconEntries<ThemeIconEntryVariant<IconVariants, Base>>;
  /**
   * The icon variant names this theme supports, listed once for the whole
   * theme — never per icon. Icon entry functions receive `variant` typed as
   * these names.
   *
   * A theme that sets `iconVariants` replaces the list it would inherit from
   * `extends`; a theme that omits it inherits the base's list.
   *
   * @example
   * ```
   * iconVariants: ['outline', 'filled'],
   * icons: {
   *   info: ({variant}) => (variant === 'filled' ? <InfoFilled /> : <InfoOutline />),
   * },
   * ```
   */
  iconVariants?: IconVariants;
  /**
   * Component icon slots — which shared icon a component's own icon role
   * uses, separate from `icons`, which chooses the artwork for each shared
   * name. Keys are the slots in `ComponentIconSlotMap`, such as
   * `code-block-copy`.
   *
   * A value is a shared icon name, `null` to hide the icon, a partial request
   * of `icon`, `variant`, and `size`, or, for a slot with state, a pure
   * synchronous function of that state that returns a request. A missing
   * request field keeps the component's own value; a function that returns
   * `null` hides the icon and one that returns `undefined` changes nothing.
   * A request `size` changes only the icon, never the control around it.
   * `variant` is typed as the names in `iconVariants` (or the inherited
   * list).
   *
   * An entry replaces the inherited entry for the same slot whole; an omitted
   * or `undefined` entry is inherited.
   *
   * @example
   * ```
   * componentIcons: {
   *   'code-block-copy': ({copied}) => ({icon: copied ? 'checkDouble' : 'copy'}),
   * },
   * ```
   */
  componentIcons?: ComponentIconMap<ThemeIconEntryVariant<IconVariants, Base>>;
  /**
   * Indicator overrides — replaces the components that draw stateful control
   * visuals with the theme's own, by name.
   *
   * Replacement is by indicator name, not per call site, so a single entry
   * reaches every component that draws that indicator: mapping `check` to
   * `RadioIndicator` gives radio visuals to every single-selection mark in the
   * app.
   *
   * Each entry is checked against its indicator's family, so a replacement
   * must accept the states that family passes.
   */
  indicators?: IndicatorRegistry;
  /**
   * Default syntax highlighting theme for code components.
   * Sets --color-syntax-* tokens at the theme root. Can be overridden
   * per-region (or per-instance) by wrapping in SyntaxTheme.
   *
   * @example
   * ```
   * import {dracula} from '@astryxdesign/core/theme/syntax';
   * defineTheme({ name: 'my-theme', syntax: dracula, ... })
   * ```
   */
  syntax?: SyntaxThemeDefinition;
  /**
   * Overrides for content on a dark surface (e.g. inverted toast,
   * dark tooltip). Accepts token and component overrides — same shape
   * as the main theme. Token defaults are generated if omitted.
   *
   * Used by `<MediaTheme surface="dark">` to set semantic tokens
   * and component styles so children render correctly against a dark
   * background.
   *
   * @example
   * ```
   * onDark: {
   *   tokens: { '--color-accent': '#90CAF9' },
   *   components: {
   *     button: { 'variant:ghost': { borderWidth: '1px' } },
   *   },
   * }
   * ```
   */
  onDark?: OnMediaOverrides;
  /**
   * Overrides for content on a light surface. Same shape as `onDark`
   * but for the inverse case (e.g. dark-mode page with a light popover).
   */
  onLight?: OnMediaOverrides;
  /**
   * Ordered environment-conditioned token and component adaptations.
   *
   * Width points use the fixed names `sm`, `md`, `lg`, `xl`, and `2xl` and
   * default to 640, 768, 1024, 1280, and 1536 CSS pixels. Breakpoint
   * configuration alone emits no CSS. Rules are emitted in declaration order;
   * fields inside `when` are ANDed and later matching writes win.
   *
   * @example
   * ```
   * adaptations: {
   *   widthBreakpoints: {lg: 1024, xl: 1280},
   *   rules: [
   *     {
   *       when: {
   *         width: {from: 'lg', below: 'xl'},
   *         pointer: 'coarse',
   *       },
   *       value: {
   *         tokens: {'--size-element-md': '44px'},
   *       },
   *     },
   *   ],
   * }
   * ```
   */
  adaptations?: ThemeAdaptations;
}

/** A defined theme — ready to pass to <Theme> */
export interface DefinedTheme {
  /** Theme name */
  name: string;
  /** Token overrides — only the tokens the consumer specified */
  tokens: Record<string, string>;
  /** Resolved theme-family-local token declarations. */
  localTokens?: Record<string, string>;
  /** Component style overrides */
  components?: ComponentStyleMap;
  /**
   * Icon registry as React nodes. A function entry is read at
   * `{size: 'md'}`; `Icon` resolves the entry at the size it renders.
   */
  icons?: ThemeIconOverrides;
  /**
   * Icon entries with their functions, present when any entry is a function.
   * Only Astryx icon resolution reads it.
   * @internal
   */
  __icons?: ThemeIconEntries<never>;
  /**
   * The icon variant names this theme supports: its own `iconVariants`, or
   * the list it inherited. Absent when no theme in its lineage lists any.
   */
  iconVariants?: ReadonlyArray<string>;
  /**
   * The variant list of the theme that defined each inherited function entry,
   * kept where it differs from `iconVariants`, so the entry receives only
   * variants its defining theme lists. Only Astryx icon resolution reads it.
   * @internal
   */
  __iconEntryVariants?: Record<string, ReadonlyArray<string> | undefined>;
  /**
   * Component icon slots as a static view: names, `null`, and static
   * requests. Slots the theme resolves with a function are left out; the
   * component's slot resolution calls them with its state.
   */
  componentIcons?: ComponentIconStaticMap;
  /**
   * Component icon slot values with their functions, present when any value
   * is a function. Only component slot resolution reads it.
   * @internal
   */
  __componentIcons?: Partial<Record<string, StoredComponentIconValue>>;
  /** Indicator overrides for stateful control visuals, keyed by name */
  indicators?: IndicatorRegistry;
  /** Whether this theme has been pre-compiled by theme build CLI */
  __built?: true;
  /**
   * Raw input tokens preserved from defineTheme() input.
   * Keeps [light, dark] tuples intact for programmatic access
   * (e.g. data viz, canvas rendering) without parsing light-dark() strings.
   * @internal
   */
  __inputTokens?: Partial<Record<string, TokenValue>>;
  /** Exact owner theme for every inherited local-token declaration. @internal */
  __localTokenOwners?: Record<string, string>;
  /** Exact enrolled theme lineage; presence marks this theme as enrolled. @internal */
  __localTokenLineage?: string[];
  /**
   * Resolved on-media token overrides for dark surfaces.
   * Generated by defineTheme from defaults + user onDark overrides.
   * Used by MediaTheme and generateThemeRules.
   * @internal
   */
  __onDark?: ResolvedOnMedia;
  /**
   * Resolved on-media overrides for light surfaces.
   * @internal
   */
  __onLight?: ResolvedOnMedia;
  /**
   * Effective breakpoint map and ordered normalized rule inputs retained for
   * source-equivalent extension, including from a built theme.
   * @internal
   */
  __adaptations?: NormalizedThemeAdaptations;
  /** Concrete ordered rule writes used by the runtime CSS compiler. @internal */
  __adaptationRules?: ResolvedThemeAdaptationRule[];
  /** Effective root generative-axis metadata used to resolve child rules. @internal */
  __axes?: ThemeGenerativeAxes;
}

/**
 * A theme produced by the current defineTheme implementation. `IconVariant`
 * is the names in its `iconVariants` list.
 */
export type ResolvedDefinedTheme<IconVariant extends string = string> =
  DefinedTheme & {
    __adaptations: NormalizedThemeAdaptations;
    __axes: ThemeGenerativeAxes;
    /**
     * Type-only: the names in `iconVariants`, so a theme that `extends` this
     * one types its icon entries by the list it inherits. Never set. Method
     * syntax keeps resolved themes with different lists assignable to each
     * other, as they were before the list existed. `astryx theme build` writes
     * the same marker into a built theme's declaration.
     * SYNC: packages/cli/api/theme/build/build.mjs (builtThemeType)
     * @internal
     */
    __iconVariant?(variant: IconVariant): void;
  };

// =============================================================================
// All defaults merged into a single flat map
// =============================================================================

/** All Astryx token defaults as a flat map. Useful for resolving full token sets. */
export const tokenDefaults: Record<string, string> = {
  ...colorDefaults,
  ...spacingDefaults,
  ...sizeDefaults,
  ...borderDefaults,
  ...focusDefaults,
  ...radiusDefaults,
  ...shadowDefaults,
  ...durationDefaults,
  ...easeDefaults,
  ...typographyDefaults,
  ...textSizeDefaults,
  ...fontWeightDefaults,
  ...typeScaleDefaults,
  ...domainTokenDefaults,
};

// =============================================================================
// defineTheme
// =============================================================================

/**
 * Describe a rejected `extends` value for the error message — enough to tell a
 * missed import (`undefined`) from a module namespace or a plain object.
 */
function describeBadBase(value: unknown): string {
  if (value === undefined) {
    return 'undefined';
  }
  if (value === null) {
    return 'null';
  }
  if (typeof value !== 'object') {
    return typeof value;
  }
  const keys = Object.keys(value);
  return `an object with keys [${keys.slice(0, 4).join(', ')}${keys.length > 4 ? ', …' : ''}]`;
}

/** The slow band's duration tokens. */
const SLOW_BAND = [
  '--duration-slow-min',
  '--duration-slow',
  '--duration-slow-max',
] as const;

/**
 * The base's tokens for the duration-scale fields a child leaves unset
 * (spec:AST-108 FR5, field by field): a child that sets no `slow` of its own
 * regenerates only the fast and medium bands, so an inherited slow band stays
 * as the base's tokens hold it, at the ratio it was made with; and a child
 * that sets no `easing` keeps the base's `--ease-standard`, an explicit one
 * included, however many themes down either is inherited.
 */
function inheritedScaleTokens(
  base: DefinedTheme,
  baseMotion: ThemeMotionConfig,
  own: ThemeMotionConfig,
): Partial<Record<string, TokenValue>> | undefined {
  const names = [
    ...('slow' in baseMotion && !('slow' in own) ? SLOW_BAND : []),
    ...('easing' in baseMotion && !('easing' in own)
      ? (['--ease-standard'] as const)
      : []),
  ];
  if (names.length === 0) {
    return undefined;
  }
  const tokens = base.tokens as Record<string, string | undefined>;
  return Object.fromEntries(
    names.flatMap(name =>
      tokens[name] !== undefined ? [[name, tokens[name]]] : [],
    ),
  );
}

/**
 * Refuses a duration scale that is missing `fast`, `medium` or `ratio` after
 * inheritance. The scale applies only when all three are present, so a partial
 * one beside a knob (`{fast: 100, tempo: 1.2}`) would otherwise be dropped
 * silently, though its fields win over `tempo` (spec:AST-108 FR5). Adaptation
 * rules refuse the same in `completeMotion`.
 */
function assertCompleteMotionScale(
  motion: ThemeMotionConfig,
  themeName: string,
): void {
  const scale = motion as Partial<MotionScaleConfig>;
  const writesScale =
    scale.fast !== undefined ||
    scale.medium !== undefined ||
    scale.ratio !== undefined ||
    scale.slow !== undefined ||
    scale.easing !== undefined;
  if (
    writesScale &&
    (scale.fast === undefined ||
      scale.medium === undefined ||
      scale.ratio === undefined)
  ) {
    throw new Error(
      `defineTheme("${themeName}"): \`motion\` sets a duration scale field, so it must supply \`fast\`, \`medium\`, and \`ratio\` unless each missing field is inherited from \`extends\`.`,
    );
  }
}

/**
 * Create an Astryx theme.
 *
 * Pass only the tokens you want to override — everything else
 * inherits from the Astryx defaults.
 *
 * When `typography.scale` is provided, it generates typography token overrides
 * that are merged into the token map. Explicit `tokens` entries take
 * precedence over generated values.
 */
export function defineTheme<
  const IconVariants extends ReadonlyArray<string> | undefined = undefined,
  Base extends DefinedTheme | undefined = undefined,
>(
  input: DefineThemeInput<IconVariants, Base>,
): ResolvedDefinedTheme<ThemeIconVariant<IconVariants, Base>> {
  // Pre-seed from the base theme when `extends` is provided (lowest precedence).
  // A base that is not a theme is refused rather than ignored: `extends` used
  // to inherit nothing when its value was undefined, which is what a named
  // import silently resolving to the wrong module hands over, and the theme
  // then built into a plausible-looking stylesheet missing everything it was
  // supposed to inherit.
  if ('extends' in input && !isDefinedTheme(input.extends)) {
    throw new Error(
      `defineTheme("${input.name}"): \`extends\` must be a theme from defineTheme(), got ${describeBadBase(input.extends)}. ` +
        `Check that the import naming your base theme resolves to its source and exports that name — ` +
        `a generated \`<theme>.js\` artifact sitting next to the source exports \`<name>Theme\`, not the source's own export.`,
    );
  }
  const base = input.extends;

  // The theme's own value axes and the resolved base an `extends` supplies.
  // The same axis metadata is retained so adaptation rules can complete partial
  // configs without approximating values from unrelated built-in defaults.
  //
  // Motion inherits field by field (spec:AST-108 FR5): a duration-scale field
  // or knob the child leaves unset keeps its base's value, so the child's
  // motion tokens come from the merged configuration. They resolve base first,
  // then generated (`architecture:theme-authoring-contract`): what the child
  // generates replaces the base's tokens, its explicit ones included. A
  // child's motion regenerates only what it sets: an inherited slow band and
  // an inherited easing keep the base's tokens.
  const baseMotion = base?.__axes?.motion;
  const motion: ThemeMotionConfig | undefined =
    input.motion != null && baseMotion != null
      ? {...baseMotion, ...input.motion}
      : input.motion;
  if (motion != null) {
    assertCompleteMotionScale(motion, input.name);
  }
  const inheritedScale =
    input.motion != null && base != null && baseMotion != null
      ? inheritedScaleTokens(base, baseMotion, input.motion)
      : undefined;
  const ownValues: ThemeValuesInput = {
    typography: input.typography,
    color: input.color,
    radius: input.radius,
    motion,
    syntax: input.syntax,
    tokens:
      inheritedScale != null && Object.keys(inheritedScale).length > 0
        ? {...inheritedScale, ...input.tokens}
        : input.tokens,
    components: input.components,
  };
  const ownAxes: ThemeGenerativeAxes = {
    typography: input.typography,
    color: input.color,
    radius: input.radius,
    motion: input.motion,
  };
  const seed = base
    ? {tokens: base.tokens, components: base.components}
    : undefined;

  // An explicit --ease-standard follows the character the theme inherits
  // when it sets no motion of its own (FR2).
  const {tokens, components} = resolveThemeValues(ownValues, seed, {
    inheritedCharacter: baseMotion?.character,
  });

  // On-media token overrides (base's resolved surface, then defaults, then
  // this theme's own overrides). They compile after adaptations so the
  // media-surface value stays more specific in the authored cascade.
  const __onDark = resolveOnMedia('dark', input.onDark, base?.__onDark);
  const __onLight = resolveOnMedia('light', input.onLight, base?.__onLight);

  const localTokenContract = resolveLocalTokenContract(
    input,
    base,
    tokens,
    tokenDefaults,
  );

  // Adaptations inherit their breakpoint map and ordered rules. Every rule is
  // re-resolved against this theme's effective root axes, so a child can change
  // the root scale while preserving the base rule's authored intent.
  const __axes = resolveThemeGenerativeAxes(base?.__axes, ownAxes);
  const __adaptations = normalizeThemeAdaptations(
    input.name,
    base?.__adaptations,
    input.adaptations,
  );
  const __adaptationRules = resolveThemeAdaptationRules(
    input.name,
    __adaptations,
    __axes,
    tokens,
    localTokenContract?.localTokens,
    components,
  );

  // Icons — input entries override base entries by key. The base's entries
  // include its function entries, which its node-valued `icons` does not.
  const baseIcons = base?.__icons ?? base?.icons;
  const iconEntries =
    input.icons && baseIcons
      ? {...baseIcons, ...input.icons}
      : (input.icons ?? baseIcons);
  const icons = readThemeIconNodes(iconEntries);

  // The variant list is theme-level: a list this theme sets replaces the
  // inherited one; an omitted list is inherited.
  const iconVariants: ReadonlyArray<string> | undefined =
    input.iconVariants !== undefined
      ? [...input.iconVariants]
      : base?.iconVariants;

  // An inherited function entry keeps the list of the theme that defined it,
  // so it receives a variant only when both lists contain it.
  const iconEntryVariants = resolveIconEntryVariants(
    iconEntries,
    input.icons,
    base,
    iconVariants,
  );

  // The base's static `componentIcons` view omits its slot functions, so read
  // its `__componentIcons` first.
  const componentIconValues = mergeComponentIcons(
    base?.__componentIcons ?? base?.componentIcons,
    input.componentIcons,
  );
  const componentIcons = staticComponentIcons(componentIconValues);

  // Indicator overrides merge by name, like icons: a child theme replacing one
  // indicator keeps the ones its base replaced.
  const indicators =
    input.indicators && base?.indicators
      ? {...base.indicators, ...input.indicators}
      : (input.indicators ?? base?.indicators);

  const theme: ResolvedDefinedTheme = {
    name: input.name,
    tokens,
    ...(localTokenContract
      ? {
          localTokens: localTokenContract.localTokens,
          __localTokenOwners: localTokenContract.owners,
          __localTokenLineage: localTokenContract.lineage,
        }
      : {}),
    components,
    icons,
    ...(icons !== iconEntries ? {__icons: iconEntries} : {}),
    ...(iconVariants !== undefined ? {iconVariants} : {}),
    ...(iconEntryVariants !== undefined
      ? {__iconEntryVariants: iconEntryVariants}
      : {}),
    ...(componentIcons !== undefined ? {componentIcons} : {}),
    ...(componentIcons !== componentIconValues
      ? {__componentIcons: componentIconValues}
      : {}),
    indicators,
    __inputTokens:
      base?.__inputTokens || input.tokens
        ? {...base?.__inputTokens, ...input.tokens}
        : undefined,
    __onDark,
    __onLight,
    __adaptations,
    __adaptationRules,
    __axes,
  };

  registerTheme(theme);
  return theme;
}

/**
 * For each function entry this theme inherits, the variant list of the theme
 * that defined it, where that list is not this theme's own. Entries this theme
 * defines use its own list, so they need no record.
 */
function resolveIconEntryVariants(
  entries: ThemeIconEntries<never> | undefined,
  ownEntries: Readonly<Record<string, unknown>> | undefined,
  base: DefinedTheme | undefined,
  iconVariants: ReadonlyArray<string> | undefined,
): Record<string, ReadonlyArray<string> | undefined> | undefined {
  if (entries == null || base == null) {
    return undefined;
  }
  const baseRecord = base.__iconEntryVariants;
  let record: Record<string, ReadonlyArray<string> | undefined> | undefined;
  for (const [name, entry] of Object.entries(entries)) {
    if (
      typeof entry !== 'function' ||
      (ownEntries != null && Object.hasOwn(ownEntries, name))
    ) {
      continue;
    }
    const definingVariants =
      baseRecord != null && Object.hasOwn(baseRecord, name)
        ? baseRecord[name]
        : base.iconVariants;
    if (definingVariants !== iconVariants) {
      record ??= {};
      record[name] = definingVariants;
    }
  }
  return record;
}

/**
 * A theme's slot values: the base's, then this theme's own, by slot. An own
 * entry replaces the inherited one whole; an `undefined` entry is omitted, so
 * the inherited one stays.
 */
function mergeComponentIcons(
  inherited: Partial<Record<string, StoredComponentIconValue>> | undefined,
  own: object | undefined,
): Partial<Record<string, StoredComponentIconValue>> | undefined {
  if (own == null) {
    return inherited;
  }
  const merged: Partial<Record<string, StoredComponentIconValue>> = {
    ...inherited,
  };
  for (const [slot, value] of Object.entries(own)) {
    if (value !== undefined) {
      merged[slot] = value as StoredComponentIconValue;
    }
  }
  return merged;
}

/**
 * The static view of a theme's slot values, without its slot functions.
 * Values without a function are returned as the same object.
 */
function staticComponentIcons(
  values: Partial<Record<string, StoredComponentIconValue>> | undefined,
): ComponentIconStaticMap | undefined {
  if (
    values == null ||
    !Object.values(values).some(value => typeof value === 'function')
  ) {
    return values;
  }
  const view: Partial<Record<string, StoredComponentIconValue>> = {};
  for (const [slot, value] of Object.entries(values)) {
    if (typeof value !== 'function') {
      view[slot] = value;
    }
  }
  return view;
}

/**
 * The node-valued view of a theme's icon entries: each function entry read at
 * `{size: 'md'}`. Entries without a function are returned as the same object.
 */
function readThemeIconNodes(
  entries: ThemeIconEntries<never> | undefined,
): ThemeIconOverrides | undefined {
  if (
    entries == null ||
    !Object.values(entries).some(entry => typeof entry === 'function')
  ) {
    return entries as ThemeIconOverrides | undefined;
  }
  const nodes: Record<string, ReactNode> = {};
  for (const [name, entry] of Object.entries(entries)) {
    nodes[name] = typeof entry === 'function' ? entry({size: 'md'}) : entry;
  }
  return nodes as ThemeIconOverrides;
}

// =============================================================================
// CSS generation — re-exported from ./generateThemeRules.ts
// =============================================================================

export {
  generateThemeRules,
  generateThemeRulesSplit,
  generateOnMediaCSS,
  generateAdaptationCSS,
  generateThemeCSS,
  type ThemeRulesSplit,
  type ThemeCSSOutput,
} from './generateThemeRules';

// =============================================================================
// Type guard
// =============================================================================

/** Check if a theme object was created with defineTheme */
export function isDefinedTheme(theme: unknown): theme is DefinedTheme {
  return (
    typeof theme === 'object' &&
    theme !== null &&
    'name' in theme &&
    'tokens' in theme &&
    !('styles' in theme)
  );
}