@uniflowed/stylex

type

ThemeValue

export type ThemeValue = string | number;

A value a token may hold, and therefore a value a theme may give it.

type

ThemeOverrides

export type ThemeOverrides<Tokens extends { readonly [string]: ThemeValue }> = Partial<{
  [Key in keyof Tokens]: ThemeValue | { readonly [state: string]: ThemeValue },
}>;

What createTheme accepts for one token set.

Every key is optional — a theme that changes one colour is a theme — and no key outside the token set is allowed, so a typo is a Flow error rather than a custom property nothing reads. A value may carry states, which is how a theme follows @media (prefers-color-scheme: dark) without a second theme.

function

create

export function create<T extends { readonly [string]: mixed }>(styles: T): T { ... }

Declare a set of style namespaces.

Never runs. uf transform replaces the whole call with the object it computed, so reaching this means the module was loaded without going through uf — a bundler configured by hand, a plain node invocation — and the styles it declares are in no stylesheet. Throwing says so; returning the input would render an application with no styles and no explanation.

function

defineVars

export function defineVars<T extends { readonly [string]: ThemeValue }>(tokens: T): T { ... }

Declare design tokens, and hand back the var(--…) references to them.

Compile-time, for the same reason as create.

function

createTheme

export function createTheme<
  Tokens extends { readonly [string]: ThemeValue },
  Overrides extends ThemeOverrides<Tokens>,
>(tokens: Tokens, overrides: Overrides): CompiledStyle { ... }

Override a set of tokens, and hand back the class that applies the override.

The result is a compiled namespace like any other, so it is applied by spreading it — <div {...props(ufDarkTheme)}> — and it composes: a second theme merged after the first replaces the tokens it names and leaves the rest alone, because the merge's unit is the property and a token is a property.

Compile-time, for the same reason as create.

variable

stylex

export const stylex: {
  readonly create: typeof create,
  readonly props: typeof props,
  readonly defineVars: typeof defineVars,
  readonly createTheme: typeof createTheme,
} = {
  create,
  props,
  defineVars,
  createTheme,
};

The namespace form, so stylex.create and stylex.props read the way StyleX documents them.

The named exports are the ones a bundler can drop individually; this object is for call sites that prefer the qualified spelling, and the compiler recognises both.

type

CompiledClasses

export type CompiledClasses = { readonly [state: string]: string | null };

The class names one property sets, keyed by the state each applies in.

type

CompiledStyle

export type CompiledStyle = {
  readonly $$css: true,
  readonly [property: string]: string | null | true | CompiledClasses,
};

A compiled style namespace.

$$css marks an object the compiler produced. Every other key is a CSS property — or a custom property, for a theme — mapped to the class name that sets it, to a map of class names when the property has states, or to null, which is how a namespace says it deliberately unsets that property.

type

StyleArgument

export type StyleArgument = mixed;

What a call site may pass: a namespace, something falsy, or a list.

type

StyleProps

export type StyleProps = {
  readonly className?: string,
  readonly style?: { readonly [string]: string | number },
};

What props hands to an element.

function

props

export function props(...styles: $ReadOnlyArray<StyleArgument>): StyleProps { ... }

Merge compiled namespaces into a className, left to right.

Falsy arguments are skipped, because active && styles.on is the idiom this function exists for, and arrays are flattened so a list built elsewhere can be passed without spreading it.

Returns an object rather than a string so the call site stays <div {...stylex.props(a, b)} /> — the same shape whether or not anything survived.

type

Tone

export type Tone = "primary" | "neutral" | "ghost" | "danger";

How loud a control is, and therefore what it is for.

type

Size

export type Size = "sm" | "md" | "lg";

The three sizes every control in the preset comes in.

type

SurfaceKind

export type SurfaceKind = "page" | "card" | "panel" | "sunken";

How much a surface is lifted off the page.

type

TextSize

export type TextSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";

Which of the type scale's steps a piece of text sits on.

type

TextTone

export type TextTone = "ink" | "muted" | "danger";

What a piece of text is: body copy, a secondary note, or an error.

function

surfaceStyles

export function surfaceStyles(options?: { readonly kind?: SurfaceKind }): StyleProps { ... }

A page or a card, with the preset's type already on it.

function

cardStyles

export function cardStyles(): StyleProps { ... }

A card: the surface most application chrome is made of.

function

textStyles

export function textStyles(options?: {
  readonly size?: TextSize,
  readonly tone?: TextTone,
  readonly strong?: boolean,
}): StyleProps { ... }

One step of the type scale, in one of the three text roles.

function

buttonStyles

export function buttonStyles(options?: {
  readonly tone?: Tone,
  readonly size?: Size,
  readonly disabled?: boolean,
}): StyleProps { ... }

A button, in one of four tones and three sizes.

function

fieldStyles

export function fieldStyles(options?: {
  readonly invalid?: boolean,
  readonly disabled?: boolean,
}): StyleProps { ... }

A text input, a select, or anything else that takes typing.

function

backdropStyles

export function backdropStyles(): StyleProps { ... }

The wash behind a modal surface.

function

dialogStyles

export function dialogStyles(): StyleProps { ... }

A centred modal panel.

function

menuStyles

export function menuStyles(): StyleProps { ... }

The box a menu's options sit in.

function

menuItemStyles

export function menuItemStyles(options?: {
  readonly active?: boolean,
  readonly disabled?: boolean,
}): StyleProps { ... }

One option in a menu.

function

tabListStyles

export function tabListStyles(): StyleProps { ... }

The row a set of tabs sits in.

function

tabStyles

export function tabStyles(options?: { readonly selected?: boolean }): StyleProps { ... }

One tab, selected or not.

function

controlStyles

export function controlStyles(options?: {
  readonly shape?: "box" | "track",
  readonly on?: boolean,
  readonly disabled?: boolean,
}): StyleProps { ... }

A checkbox's box or a switch's track.

variable

ufAutoTheme

export const ufAutoTheme = stylex.createTheme(ufTokens, {
  canvas: { "@media (prefers-color-scheme: dark)": "#141413" },
  sunken: { "@media (prefers-color-scheme: dark)": "#0f0f0e" },
  surface: { "@media (prefers-color-scheme: dark)": "#1c1c1a" },
  surfaceHover: { "@media (prefers-color-scheme: dark)": "#262623" },
  border: { "@media (prefers-color-scheme: dark)": "#363632" },
  ink: { "@media (prefers-color-scheme: dark)": "#ecece7" },
  muted: { "@media (prefers-color-scheme: dark)": "#a5a59e" },
  accent: { "@media (prefers-color-scheme: dark)": "#8eaee8" },
  accentHover: { "@media (prefers-color-scheme: dark)": "#a8c1ee" },
  accentInk: { "@media (prefers-color-scheme: dark)": "#101318" },
  accentSoft: { "@media (prefers-color-scheme: dark)": "#1f2838" },
  danger: { "@media (prefers-color-scheme: dark)": "#ee8a80" },
  dangerHover: { "@media (prefers-color-scheme: dark)": "#f3a49c" },
  dangerInk: { "@media (prefers-color-scheme: dark)": "#1d0f0d" },
  dangerSoft: { "@media (prefers-color-scheme: dark)": "#35201d" },
  focus: { "@media (prefers-color-scheme: dark)": "#8eaee8" },
  scrim: { "@media (prefers-color-scheme: dark)": "rgba(0, 0, 0, 0.6)" },
});

The preset, following the reader's operating system.

Every entry is conditional, so this theme is inert in light mode and costs exactly one @media (prefers-color-scheme: dark) block.

variable

ufDarkTheme

export const ufDarkTheme = stylex.createTheme(ufTokens, {
  canvas: "#141413",
  sunken: "#0f0f0e",
  surface: "#1c1c1a",
  surfaceHover: "#262623",
  border: "#363632",
  ink: "#ecece7",
  muted: "#a5a59e",
  accent: "#8eaee8",
  accentHover: "#a8c1ee",
  accentInk: "#101318",
  accentSoft: "#1f2838",
  danger: "#ee8a80",
  dangerHover: "#f3a49c",
  dangerInk: "#1d0f0d",
  dangerSoft: "#35201d",
  focus: "#8eaee8",
  scrim: "rgba(0, 0, 0, 0.6)",
});

The preset in dark, unconditionally.

For a subtree that is dark whatever the system says, and for the stored preference a reader chose.

function

create

export function create<Styles extends { readonly [string]: NativeStyle }>(styles: Styles): Styles { ... }

Compile-time namespaces, checked against the app's React Native styles.

function

props

export function props<Args extends $ReadOnlyArray<NativeStyleArgument<NativeStyle>>>(
  ...styles: Args
): { readonly style: Partial<StyleFields<Args>> } { ... }

Native-only props retain the authored property types and never add className.