@forte-ui/react 1.0.0-alpha.1

package/dist/styles/patterns.css

@@ -0,0 +1,236 @@
+/**
+ * Reusable pattern classes.
+ *
+ * These are plain global class names (not CSS Modules) because components and
+ * consumers both need to apply them, and because the forced-colors rules below
+ * have to reach every surface the library renders.
+ */
+@layer forte.patterns {
+  /* ------------------------------------------------------------------------
+   * Focus ring
+   *
+   * `outline` carries the ring rather than `box-shadow` because outline
+   * follows border-radius, honours outline-offset, is not clipped by an
+   * ancestor's overflow:hidden, and — decisively — survives forced-colors
+   * mode, where box-shadow is forced to `none`. The box-shadow here only
+   * fills the offset gap with the contrasting second tone.
+   * --------------------------------------------------------------------- */
+  .forte-focus-ring:focus-visible,
+  .forte-focus-ring-within:has(:focus-visible) {
+    outline: var(--forte-focus-ring-width) solid var(--forte-focus-ring-inner);
+    outline-offset: var(--forte-focus-ring-offset);
+    box-shadow: 0 0 0 var(--forte-focus-ring-offset) var(--forte-focus-ring-outer);
+  }
+
+  /* `.forte-focus-ring-within` is a statement that the WRAPPER rings on behalf of
+   * whatever inside it holds focus — Slider's and ColorPicker's thumbs over
+   * their hidden inputs, NumberField's group over its text field. So that inner
+   * element must not draw the UA's own ring on top, or the control wears two.
+   *
+   * The `:not()` is what keeps this from also silencing a nested part that
+   * legitimately rings ITSELF (NumberField's steppers sit inside its group and
+   * carry `.forte-focus-ring`). Written as an exclusion rather than left to
+   * document order because this rule and `.forte-focus-ring:focus-visible` below
+   * are both (0,2,0): disjoint sets settle it, a tie would not. `:where()`
+   * keeps the exclusion itself out of the specificity.
+   *
+   * This replaces the `outline: none` each such component used to restate. */
+  .forte-focus-ring-within
+    :where(:not(.forte-focus-ring, .forte-focus-ring-within)):focus-visible {
+    outline: none;
+  }
+
+  /* Inside a clipping context — list rows, tab strips, select items — an
+   * outward ring would be cut off. Invert it. */
+  .forte-focus-ring[data-focus-inset]:focus-visible {
+    outline-offset: calc(-1 * var(--forte-focus-ring-width) - 1px);
+    box-shadow: inset 0 0 0
+      calc(var(--forte-focus-ring-width) + var(--forte-focus-ring-offset))
+      var(--forte-focus-ring-outer);
+  }
+
+  /* SC 2.4.11 Focus Not Obscured: keep a focused control from scrolling to
+   * rest underneath sticky chrome. Apps should also set scroll-padding-block
+   * on their scroll container to match their header height. */
+  :where(.forte-focus-ring, .forte-focus-ring-within) {
+    scroll-margin: var(--forte-space-5, 1.5rem);
+  }
+
+  /* ------------------------------------------------------------------------
+   * Hit target — SC 2.5.8 (24x24 minimum)
+   * Grows the interactive area without changing the visual box.
+   * --------------------------------------------------------------------- */
+  .forte-target {
+    position: relative;
+  }
+
+  .forte-target::after {
+    content: "";
+    position: absolute;
+    inset: 50% auto auto 50%;
+    translate: -50% -50%;
+    width: max(100%, var(--forte-target-min));
+    height: max(100%, var(--forte-target-min));
+  }
+
+  /* ------------------------------------------------------------------------
+   * Scrim
+   * --------------------------------------------------------------------- */
+  .forte-scrim {
+    position: fixed;
+    inset: 0;
+    background-color: var(--forte-scrim-color);
+    transition: opacity var(--forte-duration-fast) var(--forte-ease-standard);
+  }
+
+  .forte-scrim[data-starting-style],
+  .forte-scrim[data-ending-style] {
+    opacity: 0;
+  }
+
+  @supports (backdrop-filter: blur(1px)) {
+    @media (prefers-reduced-transparency: no-preference) and (prefers-contrast: no-preference) {
+      .forte-scrim {
+        backdrop-filter: blur(var(--forte-scrim-blur));
+      }
+    }
+  }
+
+  /* ------------------------------------------------------------------------
+   * Floating surface
+   *
+   * The transparent border is deliberate and load-bearing. `transparent` is
+   * NOT preserved in forced-colors mode — it is replaced with a system colour.
+   * So a border that is invisible normally becomes the visible boundary that
+   * keeps a popup from dissolving into the page once shadows are stripped.
+   * --------------------------------------------------------------------- */
+  .forte-hc-surface {
+    border: 1px solid transparent;
+  }
+
+  .forte-icon {
+    fill: currentColor;
+    stroke: currentColor;
+  }
+
+  /* ------------------------------------------------------------------------
+   * Visually hidden, still announced.
+   *
+   * `display: none` and `visibility: hidden` remove content from the
+   * accessibility tree as well as from paint, which is the opposite of what
+   * is wanted here. The clip-path + 1px box technique keeps the text in the
+   * tree. `white-space: nowrap` prevents a long string collapsing to one
+   * character per line, which some screen readers then read letter by letter.
+   * --------------------------------------------------------------------- */
+  .forte-visually-hidden:not(:focus-within) {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  /* Opt out only where colour IS the information — a swatch, a chart key.
+   * This also disables the automatic text backplate, so anything inside must
+   * supply its own contrast and its own boundary. */
+  .forte-preserve-color {
+    forced-color-adjust: none;
+    border: 1px solid CanvasText;
+  }
+}
+
+/**
+ * Accessibility overrides.
+ *
+ * These live in `forte.a11y`, which is ordered AFTER `forte.components`,
+ * so they beat component CSS by layer order alone — no specificity games, and
+ * no `!important`. See layers.css for why that ordering is load-bearing.
+ */
+@layer forte.a11y {
+  /* ------------------------------------------------------------------------
+   * Forced colors (Windows High Contrast)
+   *
+   * The UA assigns system colours from NATIVE element semantics, not ARIA — a
+   * <div role="button"> gets no ButtonText. Base UI builds most parts from
+   * div/span, so the library has to assign the keywords itself.
+   * --------------------------------------------------------------------- */
+  @media (forced-colors: active) {
+    .forte-hc-surface {
+      border-color: CanvasText;
+      background-color: Canvas;
+      color: CanvasText;
+    }
+
+    /* The :not() is load-bearing. Without it, an element that is BOTH selected
+     * and disabled — a disabled Select item that happens to be the current
+     * value, a disabled active Tab — matches this rule at (0,1,0) and beats the
+     * zero-specificity disabled remedy below, so it paints as fully selected
+     * and never turns GrayText. Excluding disabled here makes the two rules
+     * cover disjoint sets instead of competing. */
+    :is(
+      .forte-hc-selected,
+      [data-selected],
+      [data-checked],
+      [data-highlighted],
+      [aria-selected="true"],
+      [aria-checked="true"]
+    ):not([data-disabled], [aria-disabled="true"], :disabled) {
+      background-color: Highlight;
+      color: HighlightText;
+    }
+
+    :is(.forte-hc-selected, [data-checked], [data-highlighted], [aria-selected="true"]):not(
+      [data-disabled], [aria-disabled="true"], :disabled
+    ) :where(svg, .forte-icon) {
+      fill: HighlightText;
+      stroke: HighlightText;
+    }
+
+    /* `opacity` is NOT overridden by forced-colors, so a 55%-opacity disabled
+     * control keeps full system-colour contrast and still reads as enabled.
+     * GrayText at full opacity is the only reliable disabled signal. */
+    :where([data-disabled], [aria-disabled="true"], :disabled) {
+      color: GrayText;
+      border-color: GrayText;
+      opacity: 1;
+    }
+
+    :where([data-disabled], [aria-disabled="true"], :disabled) :where(svg, .forte-icon) {
+      fill: GrayText;
+      stroke: GrayText;
+    }
+
+    .forte-focus-ring:focus-visible,
+    .forte-focus-ring-within:has(:focus-visible) {
+      outline: 3px solid Highlight;
+      outline-offset: 2px;
+      box-shadow: none;
+    }
+
+    /* Purely decorative and gradient-dependent — hide rather than show a
+     * meaningless system-coloured block. */
+    .forte-hc-decorative {
+      display: none;
+    }
+
+    .forte-scrim {
+      background-color: Canvas;
+      backdrop-filter: none;
+      opacity: 1;
+    }
+
+    .forte-link {
+      color: LinkText;
+      text-decoration: underline;
+    }
+
+    /* The invisible hit-target expander would otherwise paint. */
+    .forte-target::after {
+      display: none;
+    }
+  }
+}

package/dist/styles/properties.css

@@ -0,0 +1,62 @@
+/**
+ * Registered custom properties
+ * ---------------------------------------------------------------------------
+ * `@property` must live at the top level of the stylesheet — it is NOT affected
+ * by (and cannot be nested inside) `@layer`.
+ *
+ * Registering `--forte-accent-seed` is the single highest-value declaration in
+ * this file. An *unregistered* custom property holding a malformed colour makes
+ * every token derived from it "invalid at computed-value time": the whole ramp
+ * silently falls back to inheriting `color`, with no console error and no
+ * visual clue beyond a page that has quietly lost its palette. Registering the
+ * seed with a typed syntax and an initial value contains that failure to the
+ * one bad declaration — the other eleven steps keep working.
+ *
+ * Registration also makes these properties animatable, which is what lets the
+ * theme picker cross-fade between palettes instead of snapping.
+ */
+
+@property --forte-accent-seed {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: oklch(0.55 0.14 247);
+}
+
+@property --forte-secondary-seed {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: oklch(0.58 0.15 305);
+}
+
+/* 0 = pure grey, 1 = a hue-matched sliver of the brand in every neutral. */
+@property --forte-neutral-tint {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 1;
+}
+
+/* 1 = geometry (travel, scale, spin) allowed. 0 = suppressed. */
+@property --forte-motion-ok {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 1;
+}
+
+/* Always (1 - motion-ok). Lets a rule fade *in* a non-motion cue. */
+@property --forte-motion-off {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 0;
+}
+
+/* The sign of the inline axis: 1 in LTR, -1 in RTL. It exists because
+ * `translate` and `transform` have no logical form — a component that has to
+ * move something along the inline axis multiplies its (always positive)
+ * distance by this. Set in tokens.css from the `dir` attribute; registering it
+ * here gives every component a working default even when a rule for the
+ * current direction never matched. */
+@property --forte-direction {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 1;
+}

package/dist/styles/reset.css

@@ -0,0 +1,11 @@
+/**
+ * Optional minimal reset for forte-ui primitives.
+ * Scoped into the `forte-ui` cascade layer so it never overrides consumer
+ * styles. Import is optional:
+ *   import "@forte-ui/react/styles/reset.css";
+ */
+@layer forte {
+  :where(.forte-reset *, .forte-reset) {
+    box-sizing: border-box;
+  }
+}

package/dist/styles/tailwind.css

@@ -0,0 +1,281 @@
+/**
+ * forte-ui × Tailwind v4 — the token bridge.
+ * ---------------------------------------------------------------------------
+ * Import it in the stylesheet that imports Tailwind, BEFORE Tailwind itself:
+ *
+ *   @import "@forte-ui/react/tailwind.css";
+ *   @import "tailwindcss";
+ *
+ * (`theme.css` is still required, once, anywhere in the app — this file only
+ * teaches Tailwind the token names; it does not define the tokens.)
+ *
+ * It re-points Tailwind's theme at the forte-ui tokens, so utilities and
+ * components stay one system: `bg-primary` is `--forte-color-primary`, `gap-5`
+ * is `--forte-space-5`, `rounded-control` follows the `data-forte-radius` preset,
+ * and everything responds to a seed change, dark mode, and theme scopes.
+ *
+ * ---------------------------------------------------------------------------
+ * Why the import order is load-bearing
+ * ---------------------------------------------------------------------------
+ * The `@layer` statement below fixes the cascade-layer order at its first
+ * appearance, and both halves of it matter:
+ *
+ *   - `forte-ui` sits AFTER `base`, or Tailwind's Preflight — which lives in
+ *     `base` and sets `button { background: transparent }` and friends — would
+ *     beat every component's own styles by layer order alone.
+ *   - `forte-ui` sits BEFORE `utilities`, or `p-4` on a Button would lose to
+ *     the button's own padding, and the library's "your CSS always wins"
+ *     contract would silently break for utility classes specifically.
+ *
+ * Import Tailwind first and its own `theme, base, components, utilities`
+ * statement wins the race instead — `forte-ui` then lands after `utilities`,
+ * which is the second failure above. Keeping this import first costs nothing
+ * and settles the order for every stylesheet loaded later, including the
+ * per-component CSS the library's JS injects.
+ *
+ * ---------------------------------------------------------------------------
+ * Why `@theme inline` and not plain `@theme`
+ * ---------------------------------------------------------------------------
+ * A plain `@theme` emits `--color-primary: var(--forte-color-primary)` on
+ * `:root` and points utilities at *that*. But a `var()` inside an unregistered
+ * custom property is substituted where the property is DECLARED, so the value
+ * would freeze to whatever `:root` resolved — and every `.forte-theme` scope,
+ * `data-theme` island and `data-forte-density` / `data-forte-radius` preset would
+ * stop reaching the utility. `inline` substitutes the token reference into
+ * the utility itself (`background-color: var(--forte-color-panel)`), which
+ * resolves at the element. Do not drop the keyword.
+ *
+ * ---------------------------------------------------------------------------
+ * Why Tailwind's own scales are deleted, not extended
+ * ---------------------------------------------------------------------------
+ * Two reasons, one per failure mode:
+ *
+ *   - Philosophy with teeth: with the default palette present, `bg-slate-800`
+ *     compiles, survives review, and then ignores the seed, dark mode and
+ *     every theme scope. Deleting the namespace turns that into a build-time
+ *     "unknown utility" instead of a shipped bug.
+ *   - Arithmetic: Tailwind's spacing is a multiplier (`p-13` is as valid as
+ *     `p-4`), while forte-ui's scale is eight designed steps that go
+ *     non-linear past 4 (5 = 1.5rem … 8 = 3rem). Mapping the eight steps while
+ *     keeping the multiplier would leave `p-8` (3rem) LARGER than `p-9`
+ *     (2.25rem) — replacing the scale wholesale is what keeps it monotonic.
+ *
+ * To opt back into a stock scale anyway, re-declare it in your own `@theme`
+ * after this import; later definitions win. The `--container-*` scale is left
+ * untouched on purpose — `max-w-lg` is how you say `min(32rem, 100%)`.
+ */
+
+@layer theme, base, forte, components, utilities;
+
+@theme {
+  --color-*: initial;
+  --spacing-*: initial;
+  --text-*: initial;
+  --font-*: initial;
+  --font-weight-*: initial;
+  --leading-*: initial;
+  --tracking-*: initial;
+  --radius-*: initial;
+  --shadow-*: initial;
+  --ease-*: initial;
+  --animate-*: initial;
+}
+
+@theme inline {
+  /* ------------------------------------------------------------------------
+   * Colour — semantic slots first. These are the names the components
+   * themselves consume, so anything built out of them re-themes with the
+   * library rather than beside it.
+   * --------------------------------------------------------------------- */
+  --color-background: var(--forte-color-background);
+  --color-foreground: var(--forte-color-foreground);
+  --color-foreground-muted: var(--forte-color-foreground-muted);
+  --color-foreground-subtle: var(--forte-color-foreground-subtle);
+
+  --color-panel: var(--forte-color-panel);
+  --color-panel-hover: var(--forte-color-panel-hover);
+  --color-panel-active: var(--forte-color-panel-active);
+  --color-overlay: var(--forte-color-overlay);
+
+  --color-border: var(--forte-color-border);
+  --color-border-muted: var(--forte-color-border-muted);
+  --color-border-strong: var(--forte-color-border-strong);
+
+  --color-primary: var(--forte-color-primary);
+  --color-primary-hover: var(--forte-color-primary-hover);
+  --color-primary-active: var(--forte-color-primary-active);
+  --color-primary-soft: var(--forte-color-primary-soft);
+  --color-primary-soft-hover: var(--forte-color-primary-soft-hover);
+  --color-primary-soft-active: var(--forte-color-primary-soft-active);
+  --color-primary-border: var(--forte-color-primary-border);
+  --color-primary-text: var(--forte-color-primary-text);
+
+  --color-secondary: var(--forte-color-secondary);
+  --color-secondary-hover: var(--forte-color-secondary-hover);
+  --color-secondary-active: var(--forte-color-secondary-active);
+  --color-secondary-soft: var(--forte-color-secondary-soft);
+  --color-secondary-soft-hover: var(--forte-color-secondary-soft-hover);
+  --color-secondary-soft-active: var(--forte-color-secondary-soft-active);
+  --color-secondary-border: var(--forte-color-secondary-border);
+  --color-secondary-text: var(--forte-color-secondary-text);
+
+  --color-danger: var(--forte-color-danger);
+  --color-danger-hover: var(--forte-color-danger-hover);
+  --color-danger-soft: var(--forte-color-danger-soft);
+  --color-danger-border: var(--forte-color-danger-border);
+  --color-danger-text: var(--forte-color-danger-text);
+
+  --color-success: var(--forte-color-success);
+  --color-success-text: var(--forte-color-success-text);
+  --color-warning: var(--forte-color-warning);
+  --color-warning-text: var(--forte-color-warning-text);
+
+  /* Auto-contrast text for a solid fill. `text-white` is deliberately gone;
+   * this is the token that stays readable when the seed moves. */
+  --color-on-primary: var(--forte-color-on-primary);
+  --color-on-secondary: var(--forte-color-on-secondary);
+  --color-on-danger: var(--forte-color-on-danger);
+
+  /* The raw ramps. Prefer a semantic slot above unless the step number IS the
+   * subject — a palette display, a bespoke chart scale. */
+  --color-accent-1: var(--forte-accent-1);
+  --color-accent-2: var(--forte-accent-2);
+  --color-accent-3: var(--forte-accent-3);
+  --color-accent-4: var(--forte-accent-4);
+  --color-accent-5: var(--forte-accent-5);
+  --color-accent-6: var(--forte-accent-6);
+  --color-accent-7: var(--forte-accent-7);
+  --color-accent-8: var(--forte-accent-8);
+  --color-accent-9: var(--forte-accent-9);
+  --color-accent-10: var(--forte-accent-10);
+  --color-accent-11: var(--forte-accent-11);
+  --color-accent-12: var(--forte-accent-12);
+
+  --color-secondary-1: var(--forte-secondary-1);
+  --color-secondary-2: var(--forte-secondary-2);
+  --color-secondary-3: var(--forte-secondary-3);
+  --color-secondary-4: var(--forte-secondary-4);
+  --color-secondary-5: var(--forte-secondary-5);
+  --color-secondary-6: var(--forte-secondary-6);
+  --color-secondary-7: var(--forte-secondary-7);
+  --color-secondary-8: var(--forte-secondary-8);
+  --color-secondary-9: var(--forte-secondary-9);
+  --color-secondary-10: var(--forte-secondary-10);
+  --color-secondary-11: var(--forte-secondary-11);
+  --color-secondary-12: var(--forte-secondary-12);
+
+  --color-gray-1: var(--forte-gray-1);
+  --color-gray-2: var(--forte-gray-2);
+  --color-gray-3: var(--forte-gray-3);
+  --color-gray-4: var(--forte-gray-4);
+  --color-gray-5: var(--forte-gray-5);
+  --color-gray-6: var(--forte-gray-6);
+  --color-gray-7: var(--forte-gray-7);
+  --color-gray-8: var(--forte-gray-8);
+  --color-gray-9: var(--forte-gray-9);
+  --color-gray-10: var(--forte-gray-10);
+  --color-gray-11: var(--forte-gray-11);
+  --color-gray-12: var(--forte-gray-12);
+
+  /* ------------------------------------------------------------------------
+   * Spacing — the eight steps, 1:1. `gap-5` IS `--forte-space-5` (1.5rem, not
+   * Tailwind's stock 1.25rem). Sizing beyond 3rem is what the untouched
+   * `--container-*` scale is for: `w-full max-w-lg`.
+   * --------------------------------------------------------------------- */
+  /* Zero is not a token, but `p-0` / `inset-0` / `m-0` all route through the
+   * spacing scale — without this key they compile to
+   * `calc(var(--spacing) * 0)`, which is invalid once the multiplier is gone
+   * and so drops the declaration entirely. It fails silently, which is the
+   * worst way for it to fail. */
+  --spacing-0: 0;
+
+  --spacing-1: var(--forte-space-1);
+  --spacing-2: var(--forte-space-2);
+  --spacing-3: var(--forte-space-3);
+  --spacing-4: var(--forte-space-4);
+  --spacing-5: var(--forte-space-5);
+  --spacing-6: var(--forte-space-6);
+  --spacing-7: var(--forte-space-7);
+  --spacing-8: var(--forte-space-8);
+
+  /* Surface padding is density-aware — a `data-forte-density` preset rewrites
+   * it — which is exactly the case `inline` exists for. The rest of the
+   * density family (`--forte-control-h-*`, `--forte-target-*`) has no natural
+   * utility name; reach for it as `h-(--forte-control-h-md)`, which resolves at
+   * the element for the same reason. */
+  --spacing-surface: var(--forte-surface-p);
+
+  /* ------------------------------------------------------------------------
+   * Typography.
+   * --------------------------------------------------------------------- */
+  --font-sans: var(--forte-font-sans);
+  --font-mono: var(--forte-font-mono);
+
+  --text-1: var(--forte-font-size-1);
+  --text-2: var(--forte-font-size-2);
+  --text-3: var(--forte-font-size-3);
+  --text-4: var(--forte-font-size-4);
+  --text-5: var(--forte-font-size-5);
+  --text-6: var(--forte-font-size-6);
+
+  --font-weight-normal: var(--forte-font-weight-normal);
+  --font-weight-medium: var(--forte-font-weight-medium);
+  --font-weight-semibold: var(--forte-font-weight-semibold);
+  --font-weight-bold: var(--forte-font-weight-bold);
+
+  --leading-tight: var(--forte-line-height-tight);
+  --leading-normal: var(--forte-line-height-normal);
+
+  --tracking-tight: var(--forte-letter-spacing-tight);
+  --tracking-normal: var(--forte-letter-spacing-normal);
+
+  /* ------------------------------------------------------------------------
+   * Geometry and elevation. `rounded-control` / `rounded-surface` are the
+   * semantic pair the `data-forte-radius` presets retarget; the numbered steps
+   * are the raw scale behind them.
+   * --------------------------------------------------------------------- */
+  --radius-1: var(--forte-radius-1);
+  --radius-2: var(--forte-radius-2);
+  --radius-3: var(--forte-radius-3);
+  --radius-4: var(--forte-radius-4);
+  --radius-5: var(--forte-radius-5);
+  --radius-6: var(--forte-radius-6);
+  --radius-control: var(--forte-radius-control);
+  --radius-surface: var(--forte-radius-surface);
+  --radius-pill: var(--forte-radius-pill);
+
+  --shadow-1: var(--forte-shadow-1);
+  --shadow-2: var(--forte-shadow-2);
+  --shadow-3: var(--forte-shadow-3);
+  --shadow-4: var(--forte-shadow-4);
+
+  /* ------------------------------------------------------------------------
+   * Motion. Durations and easings only — travel, scale and `--forte-motion-ok`
+   * stay out on purpose. Those are the tokens that collapse under reduced
+   * motion, and a `translate-y-*` utility built from one would need the
+   * `calc(... * var(--forte-motion-ok))` gate that a utility cannot carry.
+   * Anything that has to move writes CSS, the way a component does.
+   *
+   * Pair a spring easing with its matching duration — a shorter duration
+   * truncates the spring mid-bounce.
+   * --------------------------------------------------------------------- */
+  /* The namespace behind `duration-*` is `--transition-duration-*`, not
+   * `--duration-*` — a name that silently generates no utility at all. */
+  --transition-duration-instant: var(--forte-duration-instant);
+  --transition-duration-fast: var(--forte-duration-fast);
+  --transition-duration-normal: var(--forte-duration-normal);
+  --transition-duration-slow: var(--forte-duration-slow);
+  --transition-duration-move: var(--forte-duration-move);
+  --transition-duration-spring-gentle: var(--forte-duration-spring-gentle);
+  --transition-duration-spring-snappy: var(--forte-duration-spring-snappy);
+  --transition-duration-spring-precise: var(--forte-duration-spring-precise);
+  --transition-duration-spring-bouncy: var(--forte-duration-spring-bouncy);
+
+  --ease-standard: var(--forte-ease-standard);
+  --ease-emphasized: var(--forte-ease-emphasized);
+  --ease-exit: var(--forte-ease-exit);
+  --ease-spring-gentle: var(--forte-ease-spring-gentle);
+  --ease-spring-snappy: var(--forte-ease-spring-snappy);
+  --ease-spring-precise: var(--forte-ease-spring-precise);
+  --ease-spring-bouncy: var(--forte-ease-spring-bouncy);
+}

package/dist/styles/theme.css

@@ -0,0 +1,57 @@
+/**
+ * forte-ui — the one stylesheet a consumer needs.
+ *
+ *   import "@forte-ui/react/theme.css";
+ *
+ * Import it ONCE, at the root of your app, before any component. It brings in
+ * the cascade-layer declaration, the registered custom properties, the colour
+ * ramps, the semantic tokens, the motion system, the accessibility responses,
+ * and the shared pattern classes.
+ *
+ * ---------------------------------------------------------------------------
+ * Theming
+ * ---------------------------------------------------------------------------
+ * One variable re-skins everything:
+ *
+ *   :root { --forte-accent-seed: #7c3aed; }
+ *
+ * All twelve accent steps, the brand-tinted neutrals, and a readable text
+ * colour for solid fills are derived from it, in both light and dark mode,
+ * with no JavaScript. Also available:
+ *
+ *   --forte-secondary-seed   second brand colour, same treatment
+ *   --forte-neutral-tint     0 = pure grey ... 1 = brand-tinted greys
+ *   data-forte-radius        "none" | "soft" | "pill"
+ *   data-forte-density       "compact" | "spacious"
+ *   data-forte-motion        "reduce" | "off" | "full"
+ *   data-theme             "light" | "dark"   (otherwise follows the OS)
+ *
+ * Supported seed envelope: lightness 0.45-0.90, chroma 0.02-0.30, and inside
+ * the sRGB gamut. Outside it the ramp still renders but the derived contrast
+ * guarantees no longer hold — scripts/check-contrast.mjs enforces the envelope.
+ *
+ * Scoping: apply `.forte-theme` or `data-forte-theme` to any element to re-theme
+ * just that subtree. The ramps are re-declared on those selectors precisely so
+ * this works; overriding the seed on an arbitrary element does not. The
+ * `data-forte-*` switches need no such hook — put one on any element and it
+ * applies to that element and everything under it, including nested
+ * `.forte-theme` scopes, until a descendant sets its own.
+ *
+ * ---------------------------------------------------------------------------
+ * Overriding
+ * ---------------------------------------------------------------------------
+ * Everything ships inside `@layer forte.*`, which loses to unlayered CSS.
+ * Your own rules and utility classes win without `!important`. The flip side
+ * is a documented opt-out: an unlayered `transition` or `--forte-motion-ok: 1`
+ * in your app will also defeat the library's reduced-motion handling.
+ */
+
+/* Order matters: layers.css establishes the layer order, and properties.css
+ * registers custom properties that later files depend on for typed fallback. */
+@import "./layers.css";
+@import "./properties.css";
+@import "./tokens.color.css";
+@import "./tokens.css";
+@import "./motion.css";
+@import "./a11y.css";
+@import "./patterns.css";