An open source design system that's fully customizable and agent ready
TypeScript
// 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)
);
}