@uniflowed/stylex 0.0.0-alpha.10

package/index.js

@@ -0,0 +1,158 @@
+// @flow
+//
+// `@uniflowed/stylex`: uf's style engine, and the preset it ships.
+//
+// Almost all of StyleX happens at compile time. `uf transform` rewrites every
+// `stylex.create({ … })` into a plain object of class names, turns every
+// `stylex.defineVars({ … })` into CSS custom properties, turns every
+// `stylex.createTheme(tokens, { … })` into the classes that override them, and
+// collects the rules into a stylesheet. By the time this module is loaded there
+// are no style values left — only names.
+//
+// This module is the front door. The merge lives in `./props.js` beside its
+// compile-time twin; the preset lives in `./tokens.stylex.js`, `./preset.js`
+// and `./theme.js`. What is here is the merge re-exported, and the three
+// functions that must never run.
+//
+// # What "preset" means here
+//
+// A framework's styling default is worth something only if it removes work
+// without removing control, so uf's preset is three things and stops there:
+//
+// 1. **A token set that already exists.** `@uniflowed/stylex/tokens.stylex.js`
+//    is a real `stylex.defineVars` module — colour roles, a type scale,
+//    spacing, radii, elevation and motion — so a project has a coherent palette
+//    without authoring one, and gets it as `:root` custom properties the build
+//    inlined rather than as anything computed in a browser.
+// 2. **A base layer over those tokens.** `@uniflowed/stylex/preset` is
+//    `stylex.create` namespaces for the surfaces a real application has, behind
+//    small functions that answer with `{ className }`. A project gets a default
+//    look by spreading them and nothing else.
+// 3. **A way to replace any of it.** `stylex.createTheme(ufTokens, { … })`
+//    compiles to one class per overridden token; put that class on an ancestor
+//    and every `var(--…)` beneath it resolves differently. `./theme.js` ships
+//    two, and a project writes its own the same way.
+//
+// It is deliberately *not*: a global reset (uf emits no rule a project did not
+// ask for), a component library (`@uniflowed/ui` ships behaviour and no
+// styles, and must keep doing so — nothing here appears in its types), or a
+// configuration flag. The preset is reached by importing it, so a project that
+// does not import it pays nothing, and one that imports half of it keeps half.
+//
+// # Where the token values come from
+//
+// `@uniflowed/brand` owns uf's visual identity — the palette, the type,
+// spacing and radius scales — and it stays there. It cannot own the token
+// module: a StyleX token's name is computed by the compiler from the binding
+// and key it was declared under, `defineVars` accepts only literals, and
+// brand's `--uf-*` names are hand-written for a different consumer. So brand
+// holds the identity values and `./tokens.stylex.js` is their StyleX-shaped
+// projection into semantic roles — `accent`, `ink`, `canvas` — which is the
+// layer a design system needs and an identity does not have.
+//
+// # Readiness
+//
+// **Implemented.** `props`, `create`, `defineVars`, `createTheme`, pseudo-class
+// and pseudo-element conditions, at-rule conditions (`@media`, `@supports`),
+// shorthand-versus-longhand ordering, unit inference, the preset tokens, the
+// base layer, and the shipped themes. Every one of them is compiled: the
+// runtime half of this package is `props` and three functions that throw.
+//
+// **Experimental.** The preset's own visual choices. The token *names* are the
+// contract and are meant to be stable; the values behind them are uf's opinion
+// and may change within the alpha series. A project that wants them pinned
+// should say so with a theme.
+//
+// **Not there.** `keyframes`, `firstThatWorks` and `positionTry`. Each needs a
+// rule shape the sheet does not have — a named `@keyframes` block, several
+// declarations of one property in one rule, and an `@position-try` block
+// respectively — and the sheet's whole guarantee is that a rule is one class,
+// one declaration, one state, ordered by what it is. Widening that is a change
+// to the ordering model, not an addition to it, so none of the three is
+// half-present: writing any of them is a compile error today, not a call that
+// silently does nothing. A preset does not need them, which is why they are
+// not in the way.
+
+import { nativeRuntimeRequired } from "@uniflowed/core/native";
+
+import type { CompiledStyle } from "./props.js";
+import { props } from "./props.js";
+
+const MODULE = "@uniflowed/stylex";
+
+export type { CompiledClasses, CompiledStyle, StyleArgument, StyleProps } from "./props.js";
+export { props } from "./props.js";
+
+/** A value a token may hold, and therefore a value a theme may give it. */
+export type ThemeValue = string | number;
+
+/**
+ * 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.
+ */
+export type ThemeOverrides<Tokens extends { readonly [string]: ThemeValue }> = Partial<{
+  [Key in keyof Tokens]: ThemeValue | { readonly [state: string]: ThemeValue },
+}>;
+
+/**
+ * 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.
+ */
+export function create<T extends { readonly [string]: mixed }>(styles: T): T {
+  return nativeRuntimeRequired(MODULE, "stylex.create");
+}
+
+/**
+ * Declare design tokens, and hand back the `var(--…)` references to them.
+ *
+ * Compile-time, for the same reason as `create`.
+ */
+export function defineVars<T extends { readonly [string]: ThemeValue }>(tokens: T): T {
+  return nativeRuntimeRequired(MODULE, "stylex.defineVars");
+}
+
+/**
+ * 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`.
+ */
+export function createTheme<
+  Tokens extends { readonly [string]: ThemeValue },
+  Overrides extends ThemeOverrides<Tokens>,
+>(tokens: Tokens, overrides: Overrides): CompiledStyle {
+  return nativeRuntimeRequired(MODULE, "stylex.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.
+ */
+export const stylex: {
+  readonly create: typeof create,
+  readonly props: typeof props,
+  readonly defineVars: typeof defineVars,
+  readonly createTheme: typeof createTheme,
+} = {
+  create,
+  props,
+  defineVars,
+  createTheme,
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@uniflowed/stylex",
+  "version": "0.0.0-alpha.10",
+  "description": "Flow declarations for @uniflowed/stylex, part of the Unified Toolchain for Flow.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/stylex"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./props": "./props.js",
+    "./preset": "./preset.js",
+    "./theme": "./theme.js",
+    "./tokens.stylex.js": "./tokens.stylex.js"
+  },
+  "files": [
+    "*.js"
+  ],
+  "dependencies": {
+    "@uniflowed/core": "0.0.0-alpha.10"
+  }
+}

package/preset.js

@@ -0,0 +1,486 @@
+// @flow
+//
+// `@uniflowed/stylex/preset`: the default look, as props you spread.
+//
+//   import { buttonStyles, cardStyles } from "@uniflowed/stylex/preset";
+//   import { Dialog } from "@uniflowed/ui";
+//
+//   <div {...cardStyles()}>
+//     <button {...buttonStyles({ tone: "primary" })}>Save</button>
+//   </div>
+//
+// This is the second of the three things uf's preset is: a base layer over
+// `./tokens.stylex.js`, so a project has a coherent default look without
+// authoring a declaration. Every function answers with `{ className }` and
+// nothing else, which is why a `@uniflowed/ui` primitive takes them without
+// knowing they exist — `className` is a DOM prop, not a StyleX type, and
+// keeping it that way is what lets the headless package stay headless.
+//
+// # Why this is a separate module
+//
+// It is the only module in the package that has opinions. `props` is a merge,
+// the tokens are names, the themes are values; this is where uf says a card has
+// a 16px radius. A project that wants its own look drops this import and keeps
+// everything else, and a bundler drops the rules with it because nothing else
+// references them.
+//
+// # Why functions rather than exported namespaces
+//
+// A namespace would make the caller responsible for the merge order —
+// `props(button.base, button.primary, button.md)` — and getting that order
+// wrong is silent. The functions own it, and they take the *variants* a caller
+// actually has an opinion about. `match` makes each mapping exhaustive, so a
+// tone added to the type without a rule is a Flow error rather than an
+// unstyled button.
+//
+// # What the merge order here has to get right
+//
+// Every recipe puts `base` first and the variant after it, because the merge's
+// unit is the property and the later argument wins. Two of them rely on that
+// deliberately: `menuItemStyles({ active: true })` replaces the item's
+// `backgroundColor` *including* its `:hover` state, which is what a selected
+// row should do, and `buttonStyles({ disabled: true })` replaces the tone's
+// cursor. Neither works if the arguments are swapped, and the compile-time
+// model in `crates/uf_stylex/src/props.rs` is where that is pinned down.
+
+// `stylex` comes from the package's own name because that is the specifier the
+// compiler resolves a StyleX binding from; `props` and its types come from the
+// module that owns them, which is the same module either way.
+import { stylex } from "@uniflowed/stylex";
+
+import type { StyleProps } from "./props.js";
+import { props } from "./props.js";
+import { ufTokens } from "./tokens.stylex.js";
+
+/** How loud a control is, and therefore what it is for. */
+export type Tone = "primary" | "neutral" | "ghost" | "danger";
+
+/** The three sizes every control in the preset comes in. */
+export type Size = "sm" | "md" | "lg";
+
+/** How much a surface is lifted off the page. */
+export type SurfaceKind = "page" | "card" | "panel" | "sunken";
+
+/** Which of the type scale's steps a piece of text sits on. */
+export type TextSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+
+/** What a piece of text is: body copy, a secondary note, or an error. */
+export type TextTone = "ink" | "muted" | "danger";
+
+const surfaces = stylex.create({
+  base: {
+    color: ufTokens.ink,
+    fontFamily: ufTokens.fontSans,
+    fontSize: ufTokens.textMd,
+    lineHeight: ufTokens.leadingBase,
+  },
+  page: {
+    backgroundColor: ufTokens.canvas,
+  },
+  card: {
+    backgroundColor: ufTokens.surface,
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: ufTokens.border,
+    borderRadius: ufTokens.radiusLg,
+    padding: ufTokens.space6,
+    boxShadow: ufTokens.shadowCard,
+  },
+  panel: {
+    backgroundColor: ufTokens.surface,
+    borderRadius: ufTokens.radiusXl,
+    padding: ufTokens.space6,
+    boxShadow: ufTokens.shadowPanel,
+  },
+  sunken: {
+    backgroundColor: ufTokens.sunken,
+    borderRadius: ufTokens.radiusMd,
+    padding: ufTokens.space4,
+  },
+});
+
+const texts = stylex.create({
+  base: {
+    fontFamily: ufTokens.fontSans,
+    lineHeight: ufTokens.leadingBase,
+    margin: 0,
+  },
+  xs: { fontSize: ufTokens.textXs },
+  sm: { fontSize: ufTokens.textSm },
+  md: { fontSize: ufTokens.textMd },
+  lg: { fontSize: ufTokens.textLg, lineHeight: ufTokens.leadingTight },
+  xl: { fontSize: ufTokens.textXl, lineHeight: ufTokens.leadingTight },
+  xxl: { fontSize: ufTokens.text2Xl, lineHeight: ufTokens.leadingTight },
+  ink: { color: ufTokens.ink },
+  muted: { color: ufTokens.muted },
+  danger: { color: ufTokens.danger },
+  strong: { fontWeight: ufTokens.weightBold },
+});
+
+const buttons = stylex.create({
+  base: {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: ufTokens.space2,
+    fontFamily: ufTokens.fontSans,
+    fontWeight: ufTokens.weightMedium,
+    lineHeight: ufTokens.leadingTight,
+    borderRadius: ufTokens.radiusMd,
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: "transparent",
+    cursor: "pointer",
+    transitionProperty: "background-color, border-color, color",
+    transitionDuration: ufTokens.durationFast,
+    transitionTimingFunction: ufTokens.easing,
+    // The ring is drawn only for a keyboard focus, which is the whole reason
+    // `:focus-visible` exists: a mouse click should not light the control up.
+    outlineWidth: { default: "0", ":focus-visible": "2px" },
+    outlineStyle: "solid",
+    outlineColor: ufTokens.focus,
+    outlineOffset: "2px",
+  },
+  primary: {
+    backgroundColor: { default: ufTokens.accent, ":hover": ufTokens.accentHover },
+    color: ufTokens.accentInk,
+  },
+  neutral: {
+    backgroundColor: { default: ufTokens.surface, ":hover": ufTokens.surfaceHover },
+    borderColor: ufTokens.border,
+    color: ufTokens.ink,
+  },
+  ghost: {
+    backgroundColor: { default: "transparent", ":hover": ufTokens.surfaceHover },
+    color: ufTokens.ink,
+  },
+  danger: {
+    backgroundColor: { default: ufTokens.danger, ":hover": ufTokens.dangerHover },
+    color: ufTokens.dangerInk,
+  },
+  sm: {
+    fontSize: ufTokens.textSm,
+    paddingBlock: ufTokens.space1,
+    paddingInline: ufTokens.space3,
+  },
+  md: {
+    fontSize: ufTokens.textSm,
+    paddingBlock: ufTokens.space2,
+    paddingInline: ufTokens.space4,
+  },
+  lg: {
+    fontSize: ufTokens.textMd,
+    paddingBlock: ufTokens.space3,
+    paddingInline: ufTokens.space6,
+  },
+  disabled: {
+    opacity: 0.55,
+    cursor: "not-allowed",
+  },
+});
+
+const fields = stylex.create({
+  base: {
+    display: "block",
+    width: "100%",
+    fontFamily: ufTokens.fontSans,
+    fontSize: ufTokens.textSm,
+    lineHeight: ufTokens.leadingBase,
+    color: ufTokens.ink,
+    backgroundColor: ufTokens.surface,
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: ufTokens.border,
+    borderRadius: ufTokens.radiusSm,
+    paddingBlock: ufTokens.space2,
+    paddingInline: ufTokens.space3,
+    outlineWidth: { default: "0", ":focus-visible": "2px" },
+    outlineStyle: "solid",
+    outlineColor: ufTokens.focus,
+    outlineOffset: "1px",
+  },
+  invalid: {
+    borderColor: ufTokens.danger,
+    backgroundColor: ufTokens.dangerSoft,
+  },
+  disabled: {
+    backgroundColor: ufTokens.sunken,
+    color: ufTokens.muted,
+    cursor: "not-allowed",
+  },
+});
+
+const overlays = stylex.create({
+  backdrop: {
+    position: "fixed",
+    inset: 0,
+    backgroundColor: ufTokens.scrim,
+  },
+  panel: {
+    position: "fixed",
+    top: "50%",
+    left: "50%",
+    transform: "translate(-50%, -50%)",
+    width: "calc(100% - 32px)",
+    maxWidth: "32rem",
+    backgroundColor: ufTokens.surface,
+    color: ufTokens.ink,
+    fontFamily: ufTokens.fontSans,
+    borderRadius: ufTokens.radiusXl,
+    padding: ufTokens.space6,
+    boxShadow: ufTokens.shadowPanel,
+  },
+});
+
+const menus = stylex.create({
+  list: {
+    minWidth: "12rem",
+    margin: 0,
+    padding: ufTokens.space1,
+    listStyle: "none",
+    backgroundColor: ufTokens.surface,
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: ufTokens.border,
+    borderRadius: ufTokens.radiusMd,
+    boxShadow: ufTokens.shadowPanel,
+  },
+  item: {
+    display: "flex",
+    alignItems: "center",
+    gap: ufTokens.space2,
+    width: "100%",
+    paddingBlock: ufTokens.space2,
+    paddingInline: ufTokens.space3,
+    borderRadius: ufTokens.radiusSm,
+    fontFamily: ufTokens.fontSans,
+    fontSize: ufTokens.textSm,
+    textAlign: "start",
+    color: ufTokens.ink,
+    backgroundColor: { default: "transparent", ":hover": ufTokens.surfaceHover },
+    cursor: "pointer",
+  },
+  active: {
+    backgroundColor: ufTokens.accentSoft,
+    color: ufTokens.accent,
+  },
+  disabled: {
+    color: ufTokens.muted,
+    cursor: "not-allowed",
+  },
+});
+
+const tabs = stylex.create({
+  list: {
+    display: "flex",
+    gap: ufTokens.space1,
+    borderBottomWidth: "1px",
+    borderBottomStyle: "solid",
+    borderBottomColor: ufTokens.border,
+  },
+  tab: {
+    // `borderWidth: 0` before `borderBottomWidth: "2px"` is the case the sheet's
+    // ordering exists for: both are one class selector, and the longhand only
+    // survives because the shorthand is emitted before it.
+    borderWidth: 0,
+    borderStyle: "solid",
+    borderColor: "transparent",
+    borderBottomWidth: "2px",
+    backgroundColor: "transparent",
+    paddingBlock: ufTokens.space2,
+    paddingInline: ufTokens.space3,
+    fontFamily: ufTokens.fontSans,
+    fontSize: ufTokens.textSm,
+    fontWeight: ufTokens.weightMedium,
+    color: { default: ufTokens.muted, ":hover": ufTokens.ink },
+    cursor: "pointer",
+  },
+  selected: {
+    color: ufTokens.ink,
+    borderBottomColor: ufTokens.accent,
+  },
+});
+
+const controls = stylex.create({
+  base: {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    flexShrink: 0,
+    padding: 0,
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: ufTokens.border,
+    backgroundColor: ufTokens.surface,
+    color: ufTokens.accentInk,
+    cursor: "pointer",
+    transitionProperty: "background-color, border-color",
+    transitionDuration: ufTokens.durationFast,
+    transitionTimingFunction: ufTokens.easing,
+    outlineWidth: { default: "0", ":focus-visible": "2px" },
+    outlineStyle: "solid",
+    outlineColor: ufTokens.focus,
+    outlineOffset: "2px",
+  },
+  box: {
+    width: ufTokens.sizeControl,
+    height: ufTokens.sizeControl,
+    borderRadius: "5px",
+  },
+  // A switch's track is the one piece of geometry here that is not a token:
+  // nothing but a switch reads it, and a theme that changed it would leave the
+  // thumb somewhere else.
+  track: {
+    width: "36px",
+    height: "20px",
+    justifyContent: "flex-start",
+    borderRadius: ufTokens.radiusPill,
+  },
+  on: {
+    backgroundColor: ufTokens.accent,
+    borderColor: ufTokens.accent,
+  },
+  disabled: {
+    backgroundColor: ufTokens.sunken,
+    cursor: "not-allowed",
+    opacity: 0.6,
+  },
+});
+
+/** A page or a card, with the preset's type already on it. */
+export function surfaceStyles(options?: { readonly kind?: SurfaceKind }): StyleProps {
+  const kind = options?.kind ?? "card";
+  return props(
+    surfaces.base,
+    match (kind) {
+      "page" => surfaces.page,
+      "card" => surfaces.card,
+      "panel" => surfaces.panel,
+      "sunken" => surfaces.sunken,
+    },
+  );
+}
+
+/** A card: the surface most application chrome is made of. */
+export function cardStyles(): StyleProps {
+  return surfaceStyles({ kind: "card" });
+}
+
+/** One step of the type scale, in one of the three text roles. */
+export function textStyles(options?: {
+  readonly size?: TextSize,
+  readonly tone?: TextTone,
+  readonly strong?: boolean,
+}): StyleProps {
+  const size = options?.size ?? "md";
+  const tone = options?.tone ?? "ink";
+  return props(
+    texts.base,
+    match (size) {
+      "xs" => texts.xs,
+      "sm" => texts.sm,
+      "md" => texts.md,
+      "lg" => texts.lg,
+      "xl" => texts.xl,
+      "2xl" => texts.xxl,
+    },
+    match (tone) {
+      "ink" => texts.ink,
+      "muted" => texts.muted,
+      "danger" => texts.danger,
+    },
+    options?.strong === true && texts.strong,
+  );
+}
+
+/** A button, in one of four tones and three sizes. */
+export function buttonStyles(options?: {
+  readonly tone?: Tone,
+  readonly size?: Size,
+  readonly disabled?: boolean,
+}): StyleProps {
+  const tone = options?.tone ?? "neutral";
+  const size = options?.size ?? "md";
+  return props(
+    buttons.base,
+    match (tone) {
+      "primary" => buttons.primary,
+      "neutral" => buttons.neutral,
+      "ghost" => buttons.ghost,
+      "danger" => buttons.danger,
+    },
+    match (size) {
+      "sm" => buttons.sm,
+      "md" => buttons.md,
+      "lg" => buttons.lg,
+    },
+    options?.disabled === true && buttons.disabled,
+  );
+}
+
+/** A text input, a select, or anything else that takes typing. */
+export function fieldStyles(options?: {
+  readonly invalid?: boolean,
+  readonly disabled?: boolean,
+}): StyleProps {
+  return props(
+    fields.base,
+    options?.invalid === true && fields.invalid,
+    options?.disabled === true && fields.disabled,
+  );
+}
+
+/** The wash behind a modal surface. */
+export function backdropStyles(): StyleProps {
+  return props(overlays.backdrop);
+}
+
+/** A centred modal panel. */
+export function dialogStyles(): StyleProps {
+  return props(overlays.panel);
+}
+
+/** The box a menu's options sit in. */
+export function menuStyles(): StyleProps {
+  return props(menus.list);
+}
+
+/** One option in a menu. */
+export function menuItemStyles(options?: {
+  readonly active?: boolean,
+  readonly disabled?: boolean,
+}): StyleProps {
+  return props(
+    menus.item,
+    options?.active === true && menus.active,
+    options?.disabled === true && menus.disabled,
+  );
+}
+
+/** The row a set of tabs sits in. */
+export function tabListStyles(): StyleProps {
+  return props(tabs.list);
+}
+
+/** One tab, selected or not. */
+export function tabStyles(options?: { readonly selected?: boolean }): StyleProps {
+  return props(tabs.tab, options?.selected === true && tabs.selected);
+}
+
+/** A checkbox's box or a switch's track. */
+export function controlStyles(options?: {
+  readonly shape?: "box" | "track",
+  readonly on?: boolean,
+  readonly disabled?: boolean,
+}): StyleProps {
+  const shape = options?.shape ?? "box";
+  return props(
+    controls.base,
+    match (shape) {
+      "box" => controls.box,
+      "track" => controls.track,
+    },
+    options?.on === true && controls.on,
+    options?.disabled === true && controls.disabled,
+  );
+}

package/props.js

@@ -0,0 +1,147 @@
+// @flow
+//
+// `@uniflowed/stylex/props`: the merge, and the only part of StyleX that runs.
+//
+// `uf transform` rewrites every `stylex.create({ … })` and
+// `stylex.createTheme(tokens, { … })` into a plain object of class names, so by
+// the time this module is loaded there are no style values left. What is left
+// is the merge, and it is here because it cannot be anywhere else: a call site
+// writes `active && styles.on`, and a compiler cannot fold a value it does not
+// know.
+//
+// # This file has a twin
+//
+// The same merge is modelled in `crates/uf_stylex/src/props.rs`, at compile
+// time, which is what lets its ordering be tested against the sheet the
+// compiler emits. The two have to agree, and they agree on the two things that
+// are observable:
+//
+// * **which classes survive.** The *property* is the unit of merging — a later
+//   namespace that sets `color` replaces everything an earlier one said about
+//   `color`, its `:hover` value included. That is what a later `color:` in a
+//   stylesheet does, and it is why a later namespace cannot leave a stray
+//   hover state behind.
+// * **that every class of a surviving property survives.** A property written
+//   with states compiles to a *map* — `{ "default": "x1", ":hover": "x2" }` —
+//   and both classes belong in the class attribute. A runtime that kept only
+//   the first, or skipped the map because it is not a string, would silently
+//   drop every conditional style in an application while every test that used
+//   plain values kept passing.
+//
+// They deliberately do not agree on the *order* of the class attribute, and
+// nothing depends on it: the compiler sorts globally by sheet position because
+// it has the priorities to hand, this file emits in the order properties were
+// first claimed because it does not. Which rule wins is decided by the sheet,
+// never by the attribute, so the two orders render identically. Within one
+// property the orders do match, because the compiler writes that property's
+// states in sheet order and this file reads them in the order it finds them.
+
+/** The class names one property sets, keyed by the state each applies in. */
+export type CompiledClasses = { readonly [state: string]: string | null };
+
+/**
+ * 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.
+ */
+export type CompiledStyle = {
+  readonly $$css: true,
+  readonly [property: string]: string | null | true | CompiledClasses,
+};
+
+/** What a call site may pass: a namespace, something falsy, or a list. */
+export type StyleArgument = mixed;
+
+/** What `props` hands to an element. */
+export type StyleProps = { readonly className?: string };
+
+/** What one property contributed, once the merge has picked a winner. */
+type Winner = string | null | CompiledClasses;
+
+/**
+ * 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.
+ */
+export function props(...styles: $ReadOnlyArray<StyleArgument>): StyleProps {
+  const winners: { [string]: Winner } = {};
+  collect(styles, winners);
+
+  let className = "";
+  for (const property of Object.keys(winners)) {
+    const winner = winners[property];
+    // `null` is a deliberate unset: the property has an owner, and that owner
+    // said there should be no class for it.
+    if (winner == null) {
+      continue;
+    }
+    if (typeof winner === "string") {
+      className = join(className, winner);
+      continue;
+    }
+    // A property with states. Every one of its classes belongs in the
+    // attribute: the base rule and the `:hover` rule are separate rules in the
+    // sheet, and dropping either is a style that never applies.
+    for (const state of Object.keys(winner)) {
+      const name = winner[state];
+      if (name != null) {
+        className = join(className, name);
+      }
+    }
+  }
+
+  return className === "" ? {} : { className };
+}
+
+/**
+ * Fold arguments into `winners`, flattening arrays.
+ *
+ * Insertion order is the order a property was *first* claimed, and assigning
+ * over an existing key does not move it — so two namespaces that both set
+ * `color` produce one entry in the position the first one had. The class list
+ * is a function of the properties involved, not of how many namespaces
+ * mentioned them.
+ */
+function collect(styles: $ReadOnlyArray<StyleArgument>, winners: { [string]: Winner }): void {
+  for (const style of styles) {
+    if (style == null || style === false || style === true) {
+      continue;
+    }
+    if (Array.isArray(style)) {
+      collect(style, winners);
+      continue;
+    }
+    if (typeof style !== "object") {
+      continue;
+    }
+    // The one place an untyped value enters. This object was written by `uf
+    // transform`, and its shape is the compiler's promise rather than something
+    // Flow can see from a call site; everything below reads it through
+    // `CompiledStyle`, so the trust boundary is this line and no wider.
+    const namespace: CompiledStyle = style as $FlowFixMe;
+    for (const property of Object.keys(namespace)) {
+      const value = namespace[property];
+      // `$$css` is the marker, not a property. Skipping it by value as well as
+      // by name means a plain object that happens to carry `true` somewhere
+      // cannot put `true` into a class attribute.
+      if (property === "$$css" || value === true) {
+        continue;
+      }
+      winners[property] = value;
+    }
+  }
+}
+
+/** Append one class name to a space-separated attribute. */
+function join(className: string, name: string): string {
+  return className === "" ? name : className + " " + name;
+}

package/theme.js

@@ -0,0 +1,112 @@
+// @flow
+//
+// `@uniflowed/stylex/theme`: the shipped themes, and how to replace them.
+//
+//   import { props } from "@uniflowed/stylex";
+//   import { ufAutoTheme } from "@uniflowed/stylex/theme";
+//
+//   <body {...props(ufAutoTheme)}>…</body>
+//
+// This is the third of the three things uf's preset is, and the one that makes
+// the other two a default rather than a decoration. A theme is a set of
+// overrides for `./tokens.stylex.js`; `uf transform` turns each override into
+// one class whose rule writes that token's custom property, so putting the
+// theme's class on an ancestor changes what every `var(--…)` beneath it
+// resolves to. No rule in `preset.js` knows a theme happened.
+//
+// # Two themes, because there are two questions
+//
+// [`ufAutoTheme`] answers "follow the reader's operating system". It overrides
+// nothing at all in light mode — every entry is written *only* under
+// `@media (prefers-color-scheme: dark)`, so outside dark mode its class matches
+// no rule and the tokens keep their declared values. That is why it costs one
+// media block rather than two full sets of custom properties.
+//
+// [`ufDarkTheme`] answers "this subtree is dark, whatever the system says": a
+// preview pane, a code surface, a reader who chose. Its overrides are
+// unconditional, so it also works as the thing a stored preference applies.
+//
+// Both can be composed, and the merge decides the same way it decides anything
+// else: `props(ufAutoTheme, ufDarkTheme)` is dark, because the later argument
+// wins token by token.
+//
+// # Writing your own
+//
+// `createTheme` takes the token set and a subset of its keys, and Flow rejects
+// a key the set does not declare — so a renamed token is a type error rather
+// than a custom property nothing reads:
+//
+//   export const brandTheme = stylex.createTheme(ufTokens, {
+//     accent: "#0f766e",
+//     accentHover: "#115e59",
+//   });
+//
+// Overriding four colours is a complete theme; there is no requirement to
+// restate the set. Two themes that give the same token the same value compile
+// to the same class and one rule, wherever they were written.
+//
+// # Contrast
+//
+// The dark values below meet WCAG AA at 4.5:1 for every pair the preset
+// actually pairs, and `crates/uf_stylex/src/tests/preset.rs` computes those
+// ratios from the compiled stylesheet.
+
+import { stylex } from "@uniflowed/stylex";
+
+import { ufTokens } from "./tokens.stylex.js";
+
+/**
+ * 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.
+ */
+export const ufAutoTheme = stylex.createTheme(ufTokens, {
+  canvas: { "@media (prefers-color-scheme: dark)": "#0b1220" },
+  sunken: { "@media (prefers-color-scheme: dark)": "#0f1726" },
+  surface: { "@media (prefers-color-scheme: dark)": "#131c2e" },
+  surfaceHover: { "@media (prefers-color-scheme: dark)": "#1b2540" },
+  border: { "@media (prefers-color-scheme: dark)": "#26324a" },
+  ink: { "@media (prefers-color-scheme: dark)": "#e8eefc" },
+  muted: { "@media (prefers-color-scheme: dark)": "#9fb0cc" },
+  accent: { "@media (prefers-color-scheme: dark)": "#8f8bff" },
+  accentHover: { "@media (prefers-color-scheme: dark)": "#a49fff" },
+  accentInk: { "@media (prefers-color-scheme: dark)": "#0b1220" },
+  accentSoft: { "@media (prefers-color-scheme: dark)": "#1e2547" },
+  danger: { "@media (prefers-color-scheme: dark)": "#ff6b5e" },
+  dangerHover: { "@media (prefers-color-scheme: dark)": "#ff8378" },
+  dangerInk: { "@media (prefers-color-scheme: dark)": "#2a0b08" },
+  dangerSoft: { "@media (prefers-color-scheme: dark)": "#2a1512" },
+  focus: { "@media (prefers-color-scheme: dark)": "#7fb0ff" },
+  scrim: { "@media (prefers-color-scheme: dark)": "rgba(2, 6, 16, 0.62)" },
+  shadowCard: { "@media (prefers-color-scheme: dark)": "0 1px 2px rgba(0, 0, 0, 0.40)" },
+  shadowPanel: { "@media (prefers-color-scheme: dark)": "0 16px 48px rgba(0, 0, 0, 0.55)" },
+});
+
+/**
+ * The preset in dark, unconditionally.
+ *
+ * For a subtree that is dark whatever the system says, and for the stored
+ * preference a reader chose.
+ */
+export const ufDarkTheme = stylex.createTheme(ufTokens, {
+  canvas: "#0b1220",
+  sunken: "#0f1726",
+  surface: "#131c2e",
+  surfaceHover: "#1b2540",
+  border: "#26324a",
+  ink: "#e8eefc",
+  muted: "#9fb0cc",
+  accent: "#8f8bff",
+  accentHover: "#a49fff",
+  accentInk: "#0b1220",
+  accentSoft: "#1e2547",
+  danger: "#ff6b5e",
+  dangerHover: "#ff8378",
+  dangerInk: "#2a0b08",
+  dangerSoft: "#2a1512",
+  focus: "#7fb0ff",
+  scrim: "rgba(2, 6, 16, 0.62)",
+  shadowCard: "0 1px 2px rgba(0, 0, 0, 0.40)",
+  shadowPanel: "0 16px 48px rgba(0, 0, 0, 0.55)",
+});

package/tokens.stylex.js

@@ -0,0 +1,114 @@
+// @flow
+//
+// `@uniflowed/stylex/tokens.stylex.js`: the tokens a project gets for free.
+//
+// This is an ordinary `stylex.defineVars` module — the compiler binds it by its
+// `.stylex.js` suffix like any other — and it is the first of the three things
+// uf's preset is. Import it and every name below is a `var(--…)` the build
+// already declared on `:root`; nothing here is computed in a browser, and a
+// project that never imports it ships none of it.
+//
+// # Roles, not colours
+//
+// The names are what a token is *for*, never what it looks like. `accent` is
+// the colour a primary action wears; it is indigo today and a theme can make it
+// anything, and no rule in `preset.js` has to change when it does. A token
+// named `indigo500` would have made the preset unthemeable the moment someone
+// wanted a green product.
+//
+// The values are uf's identity, and `@uniflowed/brand` is where that identity
+// is decided: `accent`, `ink`, `canvas` and `muted` are brand's Indigo, Ink,
+// Mist and Slate, and the type, spacing and radius steps are brand's scales.
+// Brand cannot hold the token module itself — a StyleX token's name is computed
+// by the compiler, and `defineVars` takes literals, not an imported array — so
+// this module is brand's projection into the semantic roles a design system
+// needs and an identity does not have.
+//
+// # What is not a token
+//
+// Geometry that exactly one control uses. A switch's track is 36×20 because
+// that is what a switch is, and promoting it to a token would invite a theme to
+// change it into something the thumb no longer fits. A token is a decision more
+// than one rule reads.
+//
+// # Contrast
+//
+// Every foreground/background pair the preset actually pairs meets WCAG AA at
+// 4.5:1, in both the light default and the shipped dark theme, and
+// `crates/uf_stylex/src/tests/preset.rs` computes the ratios from the compiled
+// stylesheet rather than trusting this comment.
+
+import { stylex } from "@uniflowed/stylex";
+
+// Deliberately unannotated: `defineVars` hands back exactly what it was given,
+// so the inferred type is the token set itself — which is what makes
+// `ThemeOverrides<typeof ufTokens>` reject a token this module does not declare.
+export const ufTokens = stylex.defineVars({
+  // Surfaces, from furthest back to nearest front.
+  canvas: "#f8fafc",
+  sunken: "#eef2f7",
+  surface: "#ffffff",
+  surfaceHover: "#f1f5f9",
+  border: "#dbe3ec",
+
+  // Text.
+  ink: "#0f172a",
+  muted: "#475569",
+
+  // The colour a primary action wears, and what is legible on it.
+  accent: "#5c49ff",
+  accentHover: "#4a37f0",
+  accentInk: "#ffffff",
+  accentSoft: "#eeecff",
+
+  // The colour a destructive action wears.
+  danger: "#b42318",
+  dangerHover: "#9a1c12",
+  dangerInk: "#ffffff",
+  dangerSoft: "#fef3f2",
+
+  // Focus ring, and the wash behind a modal surface.
+  focus: "#2677ff",
+  scrim: "rgba(15, 23, 42, 0.48)",
+
+  // Type.
+  fontSans: "ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif",
+  fontMono: "ui-monospace, SFMono-Regular, Menlo, monospace",
+  textXs: "12px",
+  textSm: "14px",
+  textMd: "16px",
+  textLg: "20px",
+  textXl: "28px",
+  text2Xl: "40px",
+  leadingTight: 1.25,
+  leadingBase: 1.55,
+  weightRegular: 400,
+  weightMedium: 500,
+  weightBold: 700,
+
+  // Space.
+  space1: "4px",
+  space2: "8px",
+  space3: "12px",
+  space4: "16px",
+  space6: "24px",
+  space8: "32px",
+  space12: "48px",
+
+  // Shape.
+  radiusSm: "8px",
+  radiusMd: "12px",
+  radiusLg: "16px",
+  radiusXl: "24px",
+  radiusPill: "999px",
+
+  // The size of a control a finger or a pointer aims at.
+  sizeControl: "18px",
+
+  // Elevation and motion.
+  shadowCard: "0 1px 2px rgba(15, 23, 42, 0.06), 0 1px 3px rgba(15, 23, 42, 0.10)",
+  shadowPanel: "0 16px 48px rgba(15, 23, 42, 0.24)",
+  durationFast: "120ms",
+  durationBase: "200ms",
+  easing: "cubic-bezier(0.2, 0, 0, 1)",
+});