An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file resolveThemeValues.ts
* @input The value-bearing axes of a theme input (typography, color, radius,
* motion, syntax, tokens, components) and an optional resolved seed
* @output A resolved token map and component style map
* @position Theme system core; consumed by defineTheme and themeAdaptations
*
* One resolution pipeline, shared by every layer that turns declarative theme
* axes into concrete values. `defineTheme` runs its top-level input over an
* optional base seed. An adaptation rule completes partial axes from root
* metadata first, then runs its own value without a seed to obtain exactly the
* leaves that rule writes.
*
* Precedence inside one resolved layer, lowest to highest: seed → color → type
* scale → radius → motion → font families → syntax → explicit `tokens`.
* Ordered rule-vs-root and rule-vs-rule precedence is owned by
* `themeAdaptations` and CSS source order, outside this value resolver.
*
* SYNC: When modified, update:
* - /packages/core/src/theme/defineTheme.ts (its only other caller)
* - /packages/core/src/theme/themeAdaptations.ts
*/
import type {ComponentStyleMap, TokenName, TokenValue} from './defineTheme';
import type {TypographyConfig, FontWeight} from './types';
import type {SyntaxThemeDefinition} from './syntax';
import {
expandTypeScale,
generateTypeScaleComponents,
type TypeScaleConfig,
} from './expandTypeScale';
import {
expandThemeMotion,
MOTION_TEMPO_PROPERTY,
preTempoName,
type MotionCharacter,
type ThemeMotionConfig,
} from './themeMotion';
import {expandRadiusScale, type RadiusScaleConfig} from './expandRadiusScale';
import {easeDefaults} from './tokens.stylex';
import {expandColorScale, type ColorScaleConfig} from './expandColorScale';
import {deepMergeComponents} from './mergeComponents';
// =============================================================================
// Types
// =============================================================================
/**
* The value-bearing axes of a theme — everything that resolves to tokens or
* component styles. Deliberately excludes identity (`name`), inheritance
* (`extends`), the registries (`icons`, `indicators`), the surface overrides
* (`onDark`/`onLight`) and the tiers themselves: none of those participate in
* value resolution.
*/
export interface ThemeValuesInput {
/** Typography — fonts, scale, and weights. */
typography?: TypographyConfig;
/** Color scale configuration. */
color?: ColorScaleConfig;
/** Radius scale configuration. */
radius?: RadiusScaleConfig;
/** Motion: the three knobs, a motion scale configuration, or both. */
motion?: ThemeMotionConfig;
/** Syntax highlighting theme. */
syntax?: SyntaxThemeDefinition;
/** Explicit token overrides — highest precedence. */
tokens?: Partial<Record<TokenName, TokenValue>>;
/** Component style overrides. */
components?: ComponentStyleMap;
}
/** Already-resolved values to start from — the lowest precedence layer. */
export interface ThemeValuesSeed {
/** Resolved token values. */
tokens?: Record<string, string>;
/** Resolved component styles. */
components?: ComponentStyleMap;
}
/** The resolved output of one theme layer. */
export interface ResolvedThemeValues {
/** Resolved token CSS values. */
tokens: Record<string, string>;
/** Resolved component style overrides, if any. */
components?: ComponentStyleMap;
}
// =============================================================================
// Value helpers
// =============================================================================
/**
* Resolve a token value to a CSS string.
* - String values pass through as-is
* - [light, dark] tuples become light-dark(light, dark)
*
* `strict` decides what happens to anything else, and the split is a
* compatibility boundary rather than a preference:
*
* - LENIENT (default) is the behavior `defineTheme` has always had. `TokenValue`
* is a compile-time contract only, and themes reach this function through
* casts, broad spreads, generated objects and plain JavaScript, so values
* outside the type genuinely do arrive. Historically a two-element array
* became `light-dark()` and everything else passed through untouched;
* rejecting those now would break themes that build today and have nothing
* to do with adaptations.
* - STRICT is for values authored inside an adaptation rule. That surface is
* new, so there is no established acceptance to preserve, and a malformed
* value there is worth catching before it reaches CSS.
*
* SYNC: packages/core/src/theme/themeAdaptations.ts (strict resolution)
*/
export function resolveTokenValue(
value: TokenValue,
{strict = false}: {strict?: boolean} = {},
): string {
if (typeof value === 'string') {
return value;
}
if (
Array.isArray(value) &&
value.length === 2 &&
typeof value[0] === 'string' &&
typeof value[1] === 'string'
) {
return `light-dark(${value[0]}, ${value[1]})`;
}
if (strict) {
throw new Error(
'Theme token values must be CSS strings or [light, dark] string tuples.',
);
}
// The legacy path, preserved verbatim: any array is read as a light/dark
// pair, and a non-string scalar is emitted as it always was. TypeScript has
// narrowed `value` to `never` by here — by the declared type these cannot
// exist, and that mismatch with runtime is exactly why this path stays.
if (Array.isArray(value)) {
return `light-dark(${value[0]}, ${value[1]})`;
}
return value;
}
/**
* Resolve a FontWeight name to a var() reference.
* Named weights map to var(--font-weight-*); raw values pass through.
*/
export function resolveFontWeight(weight: FontWeight): string {
const named: Record<string, string> = {
normal: 'var(--font-weight-normal)',
medium: 'var(--font-weight-medium)',
semibold: 'var(--font-weight-semibold)',
bold: 'var(--font-weight-bold)',
};
return named[weight] ?? weight;
}
/**
* Build the full CSS font-family value from family + fallbacks.
* Quotes the family name if it contains spaces.
*/
export function buildFontFamily(
family?: string,
fallbacks?: string,
): string | undefined {
if (!family) {
return undefined;
}
const quoted = family.includes(' ') ? `"${family}"` : family;
if (fallbacks) {
return `${quoted}, ${fallbacks}`;
}
return quoted;
}
// =============================================================================
// Axis builders
// =============================================================================
/**
* Build the type-scale config from a typography config, collecting the weight
* overrides its roles imply.
*
* Returns undefined when the config declares no scale — font families and
* weights alone do not produce one.
*/
export function buildTypeScaleConfig(
typo: TypographyConfig,
): TypeScaleConfig | undefined {
if (!typo.scale) {
return undefined;
}
// Collect weight overrides from typography roles
const headingWeights: Partial<Record<1 | 2 | 3 | 4 | 5 | 6, string>> = {};
const headingRole = typo.heading;
if (headingRole?.weights) {
for (const [level, w] of Object.entries(headingRole.weights)) {
if (w) {
headingWeights[Number(level) as 1 | 2 | 3 | 4 | 5 | 6] =
resolveFontWeight(w);
}
}
}
// Default heading weight from role
const defaultHeadingWeight = headingRole?.weight
? resolveFontWeight(headingRole.weight)
: undefined;
if (defaultHeadingWeight) {
for (let i = 1; i <= 6; i++) {
if (!(i in headingWeights)) {
headingWeights[i as 1 | 2 | 3 | 4 | 5 | 6] = defaultHeadingWeight;
}
}
}
// Text weight overrides from roles
const textWeights: Partial<Record<string, string>> = {};
if (typo.body?.weight) {
textWeights.body = resolveFontWeight(typo.body.weight);
}
if (typo.code?.weight) {
textWeights.code = resolveFontWeight(typo.code.weight);
}
return {
base: typo.scale.base,
ratio: typo.scale.ratio,
weights: {
...(Object.keys(headingWeights).length > 0
? {heading: headingWeights}
: {}),
...(Object.keys(textWeights).length > 0 ? {text: textWeights} : {}),
},
};
}
/**
* Build the `--font-family-*` token overrides implied by a typography config.
* Heading inherits from body when it declares no family of its own.
*/
export function buildFontFamilyTokens(
typo: TypographyConfig,
): Record<string, string> {
const tokens: Record<string, string> = {};
const bodyFamily = buildFontFamily(typo.body?.family, typo.body?.fallbacks);
const headingFamily =
buildFontFamily(typo.heading?.family, typo.heading?.fallbacks) ??
bodyFamily;
const codeFamily = buildFontFamily(typo.code?.family, typo.code?.fallbacks);
if (bodyFamily) {
tokens['--font-family-body'] = bodyFamily;
}
if (headingFamily) {
tokens['--font-family-heading'] = headingFamily;
}
if (codeFamily) {
tokens['--font-family-code'] = codeFamily;
}
return tokens;
}
// =============================================================================
// Resolution
// =============================================================================
/**
* Resolve one theme layer's declarative axes into tokens and component styles.
*
* `seed` is the already-resolved layer underneath — the base theme for an
* `extends`, or nothing for a root theme. It sits below everything this input
* declares.
*/
export function resolveThemeValues(
input: ThemeValuesInput,
seed?: ThemeValuesSeed,
{
strictTokens = false,
inheritedCharacter,
standardBeneath,
}: {
strictTokens?: boolean;
/**
* The motion character in effect beneath this layer, from a base theme or
* the theme an adaptation rule belongs to, for a layer that sets none.
*/
inheritedCharacter?: MotionCharacter;
/** The --ease-standard beneath a layer resolved without a seed: a rule's theme's. */
standardBeneath?: string;
} = {},
): ResolvedThemeValues {
const tokens: Record<string, string> = {...seed?.tokens};
const typo = input.typography;
const typeScaleConfig = typo ? buildTypeScaleConfig(typo) : undefined;
// 1. Color-generated tokens (lowest precedence for colors)
if (input.color) {
Object.assign(tokens, expandColorScale(input.color));
}
// 2. Type-scale-generated tokens
if (typeScaleConfig) {
Object.assign(tokens, expandTypeScale(typeScaleConfig));
}
// 3. Radius-generated tokens
if (input.radius) {
Object.assign(tokens, expandRadiusScale(input.radius));
}
// 4. Motion-generated tokens (spec:AST-108 FR2, FR5). A layer that writes
// durations also writes the copies busy loops read (FR4), so an enclosing
// theme's tempo copies never stand in for its own: without a tempo of its
// own, they are its durations. Such a layer also writes a tempo of 1, so
// its springs keep the pace of its durations inside a theme with a tempo.
if (input.motion) {
const motion = expandThemeMotion(input.motion);
Object.assign(tokens, motion);
let writesDurations = false;
for (const [name, value] of Object.entries(motion)) {
const preTempo = preTempoName(name);
if (preTempo !== name) {
writesDurations = true;
if (!(preTempo in motion)) {
tokens[preTempo] = value;
}
}
}
if (writesDurations && !(MOTION_TEMPO_PROPERTY in motion)) {
tokens[MOTION_TEMPO_PROPERTY] = '1';
}
}
// 5. Font family tokens
if (typo) {
Object.assign(tokens, buildFontFamilyTokens(typo));
}
// 6. Syntax theme tokens
if (input.syntax) {
const prefix = '--color-syntax-';
for (const [key, value] of Object.entries(input.syntax.tokens)) {
tokens[prefix + key] = value;
}
}
// 7. Explicit token overrides — highest precedence within this input layer.
// A generated axis in the same root or adaptation value cannot beat them.
if (input.tokens) {
const own = input.tokens as Partial<Record<string, TokenValue>>;
for (const [key, value] of Object.entries(input.tokens)) {
if (value !== undefined) {
tokens[key] = resolveTokenValue(value, {strict: strictTokens});
// An explicit duration beats tempo, so a busy loop reading the
// pre-tempo value reads it too (spec:AST-108 FR4).
const preTempo = preTempoName(key);
if (preTempo !== key && own[preTempo] === undefined) {
tokens[preTempo] = tokens[key];
}
}
}
}
// At 'standard', --ease-entrance and --ease-move equal the resolved
// --ease-standard (spec:AST-108 FR2): the layer's own, else the one beneath
// it. A layer that sets them itself, or whose character, its own or the one
// it inherits, picks its own curve, keeps them.
const own: Partial<Record<string, TokenValue>> = input.tokens ?? {};
const ownCharacter =
input.motion != null && 'character' in input.motion
? input.motion.character
: undefined;
const character = ownCharacter ?? inheritedCharacter;
if (
ownCharacter === 'standard' ||
(own['--ease-standard'] !== undefined &&
(character === undefined || character === 'standard'))
) {
const standard =
tokens['--ease-standard'] ??
standardBeneath ??
easeDefaults['--ease-standard'];
for (const name of ['--ease-entrance', '--ease-move']) {
if (own[name] === undefined) {
tokens[name] = standard;
}
}
}
// Components: generated type-scale rules (lowest) → this input's own →
// all of it over the seed's.
let components = input.components;
if (typeScaleConfig) {
components = deepMergeComponents(
generateTypeScaleComponents(typeScaleConfig),
input.components,
);
}
if (seed?.components) {
components = deepMergeComponents(seed.components, components);
}
return {tokens, components};
}