@uniflowed/stylex 0.1.0 → 0.3.0

package/index.js

@@ -21,7 +21,7 @@
 //
 // 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
+//    spacing, radii 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
@@ -67,14 +67,17 @@
 //
 // # 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.
+// `@uniflowed/brand` owns uf's visual identity — the logo, its spectrum, the
+// type and spacing scales — and it stays there. The interface borrows brand's
+// type and spacing, and chooses its own colours and corners: a UI dressed in
+// the logo's cyan-to-magenta spectrum and round corners looks generated, so
+// `./tokens.stylex.js` holds a neutral-first palette of its own
+// (`docs/ui-visual-language.md` says why). Brand could not own the token
+// module anyway: a StyleX token's name is computed by the compiler from the
+// binding and key it was declared under, and `defineVars` accepts only
+// literals. So `./tokens.stylex.js` is where the semantic roles — `accent`,
+// `ink`, `canvas` — get their values, which is the layer a design system needs
+// and an identity does not have.
 //
 // # Readiness
 //
@@ -129,13 +132,22 @@ export type ThemeOverrides<Tokens extends { readonly [string]: ThemeValue }> = P
 /**
  * Declare a set of style namespaces.
  *
+ * Typed as what the compiler hands back, not what was written: every key of
+ * `styles` becomes a {@link CompiledStyle}, a map of property to class name
+ * marked with `$$css`. Typing the result as the input (`T`) said a namespace
+ * held `{ color: "black" }` when at run time it holds `{ $$css: true, color:
+ * "x1e2nbdu" }`, so code reading the compiled marker, and `props`'s own
+ * tests, were type errors against the truth.
+ *
  * 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 {
+export function create<T extends { readonly [string]: mixed }>(
+  styles: T,
+): { readonly [Key in keyof T]: CompiledStyle } {
   return nativeRuntimeRequired(MODULE, "stylex.create");
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/stylex",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Flow declarations for @uniflowed/stylex, part of the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,7 @@
     "!*.test.js"
   ],
   "dependencies": {
-    "@uniflowed/core": "0.1.0"
+    "@uniflowed/core": "0.3.0"
   },
   "peerDependencies": {
     "react-native": ">=0.86.0"

package/preset.js

@@ -20,9 +20,9 @@
 //
 // 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.
+// a 6px radius and a 1px border rather than a shadow. 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
 //
@@ -84,13 +84,14 @@ const surfaces = stylex.create({
     borderColor: ufTokens.border,
     borderRadius: ufTokens.radiusLg,
     padding: ufTokens.space6,
-    boxShadow: ufTokens.shadowCard,
   },
   panel: {
     backgroundColor: ufTokens.surface,
-    borderRadius: ufTokens.radiusXl,
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: ufTokens.border,
+    borderRadius: ufTokens.radiusLg,
     padding: ufTokens.space6,
-    boxShadow: ufTokens.shadowPanel,
   },
   sunken: {
     backgroundColor: ufTokens.sunken,
@@ -131,7 +132,20 @@ const buttons = stylex.create({
     borderStyle: "solid",
     borderColor: "transparent",
     cursor: "pointer",
-    transitionProperty: "background-color, border-color, color",
+    // Press: the button gives a little under the pointer, to 97% of its size
+    // in `durationFast`, and comes back on release without passing 1. Under
+    // reduced motion it does not move; only the colours still change.
+    transform: {
+      default: "none",
+      ":active": "scale(0.97)",
+      "@media (prefers-reduced-motion: reduce)": "none",
+    },
+    // The focus ring draws itself outward from the edge (`outline-width`
+    // 0 → 2px) rather than blinking on, in `durationFast`.
+    transitionProperty: {
+      default: "background-color, border-color, color, outline-width, transform",
+      "@media (prefers-reduced-motion: reduce)": "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
@@ -191,7 +205,7 @@ const fields = stylex.create({
     borderWidth: "1px",
     borderStyle: "solid",
     borderColor: ufTokens.border,
-    borderRadius: ufTokens.radiusSm,
+    borderRadius: ufTokens.radiusMd,
     paddingBlock: ufTokens.space2,
     paddingInline: ufTokens.space3,
     outlineWidth: { default: "0", ":focus-visible": "2px" },
@@ -226,9 +240,11 @@ const overlays = stylex.create({
     backgroundColor: ufTokens.surface,
     color: ufTokens.ink,
     fontFamily: ufTokens.fontSans,
-    borderRadius: ufTokens.radiusXl,
+    borderWidth: "1px",
+    borderStyle: "solid",
+    borderColor: ufTokens.border,
+    borderRadius: ufTokens.radiusLg,
     padding: ufTokens.space6,
-    boxShadow: ufTokens.shadowPanel,
   },
 });
 
@@ -243,7 +259,6 @@ const menus = stylex.create({
     borderStyle: "solid",
     borderColor: ufTokens.border,
     borderRadius: ufTokens.radiusMd,
-    boxShadow: ufTokens.shadowPanel,
   },
   item: {
     display: "flex",
@@ -314,7 +329,12 @@ const controls = stylex.create({
     backgroundColor: ufTokens.surface,
     color: ufTokens.accentInk,
     cursor: "pointer",
-    transitionProperty: "background-color, border-color",
+    // Colours, and the focus ring drawing outward; only the colours stay
+    // under reduced motion.
+    transitionProperty: {
+      default: "background-color, border-color, outline-width",
+      "@media (prefers-reduced-motion: reduce)": "background-color, border-color",
+    },
     transitionDuration: ufTokens.durationFast,
     transitionTimingFunction: ufTokens.easing,
     outlineWidth: { default: "0", ":focus-visible": "2px" },
@@ -325,7 +345,7 @@ const controls = stylex.create({
   box: {
     width: ufTokens.sizeControl,
     height: ufTokens.sizeControl,
-    borderRadius: "5px",
+    borderRadius: ufTokens.radiusSm,
   },
   // 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

package/theme.js

@@ -62,25 +62,23 @@ import { ufTokens } from "./tokens.stylex.js";
  * 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)" },
+  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)" },
 });
 
 /**
@@ -90,23 +88,21 @@ export const ufAutoTheme = stylex.createTheme(ufTokens, {
  * 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)",
+  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)",
 });

package/tokens.stylex.js

@@ -11,18 +11,37 @@
 // # 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 colour a primary action wears; it is a quiet cobalt today and a theme
+// can make it anything, and no rule in `preset.js` has to change when it does.
+// A token named `blue600` 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.
+// # The palette
+//
+// `docs/ui-visual-language.md` explains it; in short: the interface is
+// neutral first — warm greys with no blue cast, near-black ink on off-white
+// paper — and colour is spent in one place, a single accent for what is
+// selected, current or primary. Danger is a brick red rather than a signal
+// red. Dark is designed as its own palette (charcoal, not navy; a lighter,
+// desaturated accent that does not glow), not the light one inverted.
+//
+// The type and spacing steps are `@uniflowed/brand`'s scales. The colours and
+// the corners are not: brand's cyan-to-magenta spectrum and its round corners
+// are uf's logo and marketing identity, and an interface built from them looks
+// like every other generated one, so this module's values are its own. Brand
+// cannot hold the token module itself anyway — a StyleX token's name is
+// computed by the compiler, and `defineVars` takes literals, not an imported
+// array.
+//
+// # No shadows, no gradients
+//
+// The defaults draw depth with a rule and a change of surface, and nothing
+// else. A shadow is the first thing a theme has to fight when the product's
+// look is flat, and a gradient is a decision about a brand this module does
+// not have, so neither is a token and neither appears in a default style.
+// `crates/uf_stylex/src/tests/defaults.rs` compiles every default style —
+// this module, `preset.js`, `theme.js` and every file in `registry/ui/` — and
+// fails on a `box-shadow`, a `text-shadow`, a `drop-shadow()` or a gradient.
 //
 // # What is not a token
 //
@@ -45,31 +64,31 @@ import { stylex } from "@uniflowed/stylex";
 // `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",
+  canvas: "#f6f6f4",
+  sunken: "#eeeeeb",
   surface: "#ffffff",
-  surfaceHover: "#f1f5f9",
-  border: "#dbe3ec",
+  surfaceHover: "#f1f1ee",
+  border: "#d9d9d4",
 
   // Text.
-  ink: "#0f172a",
-  muted: "#475569",
+  ink: "#1b1b19",
+  muted: "#5c5c57",
 
   // The colour a primary action wears, and what is legible on it.
-  accent: "#5c49ff",
-  accentHover: "#4a37f0",
+  accent: "#2b58b5",
+  accentHover: "#234996",
   accentInk: "#ffffff",
-  accentSoft: "#eeecff",
+  accentSoft: "#e8eef9",
 
   // The colour a destructive action wears.
-  danger: "#b42318",
-  dangerHover: "#9a1c12",
+  danger: "#b1271d",
+  dangerHover: "#931f17",
   dangerInk: "#ffffff",
-  dangerSoft: "#fef3f2",
+  dangerSoft: "#fbedeb",
 
   // Focus ring, and the wash behind a modal surface.
-  focus: "#2677ff",
-  scrim: "rgba(15, 23, 42, 0.48)",
+  focus: "#2b58b5",
+  scrim: "rgba(27, 27, 25, 0.45)",
 
   // Type.
   fontSans: "ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif",
@@ -95,20 +114,77 @@ export const ufTokens = stylex.defineVars({
   space8: "32px",
   space12: "48px",
 
-  // Shape.
-  radiusSm: "8px",
-  radiusMd: "12px",
-  radiusLg: "16px",
-  radiusXl: "24px",
+  // Shape. Three small steps and a pill, and nothing rounder: a control is
+  // 2px, a button, field group or popover 4px, and the largest surface — a
+  // card, a dialog — 6px. `radiusPill` is for the few things that are round
+  // by what they are, such as a switch's track or a radio's dot, and not a
+  // way to soften a rectangle.
+  radiusSm: "2px",
+  radiusMd: "4px",
+  radiusLg: "6px",
   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)",
+  // There is no elevation: a surface in front of another is told apart by a
+  // 1px `border` and its own background, never by a shadow.
+
+  // # Motion
+  //
+  // Three durations and three easings, and every default transition is one of
+  // each. `docs/ui-visual-language.md` has the table of what moves how; the
+  // values are argued here, where a theme that wants to change them will look.
+  //
+  // **Durations, by how far the eye has to follow.**
+  //
+  //   * `durationFast`, 120ms: a change *in place* — a colour, a pressed
+  //     button giving way, a focus ring drawing itself, a chevron turning.
+  //     Nothing travels, so anything longer reads as lag between the press
+  //     and the answer; anything under ~100ms is not seen at all, which is
+  //     how #1414's defaults came to look like they had no motion.
+  //   * `durationBase`, 200ms: something small *arriving* or *travelling* — a
+  //     popover, menu or listbox leaving its trigger, a switch's thumb, a
+  //     check being drawn. Long enough to see where it came from, short enough
+  //     that a reader who opens a menu to act in it is never waiting for it.
+  //   * `durationSlow`, 280ms: something *large* — a dialog, a sheet, a
+  //     drawer, a toast, a progress bar's fill. A surface that covers a third
+  //     of the screen and moves as fast as a menu looks thrown. It stops short
+  //     of the ~300ms where an interface starts to feel like it is performing.
+  //
+  // **Easings, by where the motion starts and ends.** All three are
+  // cubic-béziers with both y values inside 0..1, so nothing overshoots its
+  // destination and nothing bounces; `defaults.rs` holds them to that.
+  //
+  //   * `easing`, `cubic-bezier(0.2, 0, 0, 1)`: the standard curve, for
+  //     something moving between two places it rests at — a switch's thumb, a
+  //     progress fill, a drawer between snap points, a colour. It eases out of
+  //     rest a little and settles for a long time, so it never stops abruptly.
+  //   * `easingEnter`, `cubic-bezier(0, 0, 0.2, 1)`: a decelerate, for
+  //     something *arriving*. It leaves at full speed and spends its second
+  //     half settling: half the distance is covered by a fifth of the time,
+  //     so the content is legible almost at once, while the settle is long
+  //     enough to be seen. A stronger curve (Material's emphasised
+  //     `0.05, 0.7, 0.1, 1`) was tried and rejected: it is 78% there by a
+  //     fifth of the time, which on a 200ms popover is the "almost no motion"
+  //     this replaces.
+  //   * `easingExit`, `cubic-bezier(0.4, 0, 1, 1)`: an accelerate, for
+  //     something *leaving*. It starts slowly, so the eye registers that it is
+  //     going, then gets out of the way at full speed. Exits pair it with a
+  //     shorter duration than the matching enter, because nobody watches a
+  //     thing leave. (Exit transitions need the behaviour layer to keep a
+  //     closing part mounted until they finish; until it does, this token is
+  //     declared and not yet read — see `docs/ui-visual-language.md`.)
+  //
+  // A transition names the properties it moves, never `all`. Under
+  // `prefers-reduced-motion: reduce` nothing travels, grows or is drawn:
+  // either the duration is `0s`, or only opacity and colour still transition,
+  // so an overlay still fades rather than cutting. `defaults.rs` checks every
+  // default style for each of these.
   durationFast: "120ms",
   durationBase: "200ms",
+  durationSlow: "280ms",
   easing: "cubic-bezier(0.2, 0, 0, 1)",
+  easingEnter: "cubic-bezier(0, 0, 0.2, 1)",
+  easingExit: "cubic-bezier(0.4, 0, 1, 1)",
 });