@pitlane/theme 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,124 @@
 # @pitlane/theme
 
+## 0.3.0
+
+Authoring moves off W3C DTCG. `createTheme` now takes a schema tree and the
+token tree it describes, and token values are the CSS they become. DTCG stays
+as an interchange format behind `@pitlane/theme/dtcg`.
+
+**Breaking.** Every theme written against 0.1.0 or 0.2.0 has to be rewritten.
+There is no compatibility shim, and `createTheme` does not accept a DTCG
+document any more. `fromDTCG` reads one, so an existing document can be moved
+across without being retyped by hand:
+
+```ts
+import { createTheme } from "@pitlane/theme";
+import { fromDTCG } from "@pitlane/theme/dtcg";
+
+export let { token: t, raw, Theme } = createTheme(fromDTCG(existingDocument));
+```
+
+What changes in a hand-written theme:
+
+| 0.2.0                                              | 0.3.0                                    |
+| -------------------------------------------------- | ---------------------------------------- |
+| `createTheme(document, { modes })`                 | `createTheme({ schema, tokens, modes })` |
+| `{ $type: "color" }` on a group                    | `color: s.color()` in the schema tree    |
+| `{ $value: "#fff" }`                               | `"#fff"`                                 |
+| `$value: { value: 2.5, unit: "rem" }`              | `"2.5rem"`                               |
+| `$value: { colorSpace: "oklch", components: […] }` | the `oklch(…)` text                      |
+| A shadow, border, transition, or gradient object   | the CSS shorthand text                   |
+| `$value: [0.25, 0.1, 0.25, 1]` on `cubicBezier`    | the same tuple, under `s.easing()`       |
+| A shadow's `color: "{color.line}"` sub-value       | the reference inside the shorthand text  |
+| `modes: { dark: { … { $value } } }`                | `modes: { dark: { tokens: { … } } }`     |
+| `"{color.white}"`                                  | `base.color.white` in an `extend` layer  |
+
+The accessor shape, `raw`, `<Theme />`, `css`, `tva`, `combine`, and `cx` are
+all unchanged.
+
+References need the most attention. The `"{color.white}"` string syntax is gone,
+and a reference is a property access on the layer below:
+
+```ts
+createTheme({ schema: { color: s.color() }, tokens: { color: { white: "#fff" } } }).extend(
+    base => ({
+        schema: { surface: s.color() },
+        tokens: { surface: { page: base.color.white } },
+    }),
+);
+```
+
+The emitted CSS is the same, `--surface-page: var(--color-white)`, so overrides
+still cascade. What changes is that the reference is now checked: its type has
+to match its position, and renaming the target breaks the reference at build
+time instead of emitting a variable nothing declares.
+
+Three consequences worth planning for. A semantic tier becomes a separate
+`extend` from the primitives it names. A mode override that references another
+token goes in an `extend` layer too, since that is where an accessor is in
+scope. And a DTCG sub-value alias, such as a shadow whose `color` field was
+`{color.line}`, becomes an interpolation:
+``tokens: { shadow: { card: `0 1px 2px ${base.color.line}` } }``.
+
+`fromDTCG` converts a document's aliases for you, including the ones inside a
+composite's sub-values, so an existing document needs no hand-editing.
+
+One side effect worth knowing: a layer's declarations follow the ones it
+references, so moving a semantic tier into an `extend` moves its declarations
+later in the `:root` block. Custom properties in one rule resolve independently
+of order, so nothing about the cascade changes. Declaring the namespace as an
+empty group in the base tree reserves its position if the order matters for
+diffing.
+
+- `createTheme({ schema, tokens, modes })` replaces
+  `createTheme(document, options)`. A leaf is a string, a number, or an array;
+  a plain object is a group. No `$value` wrappers, and no reserved token names.
+- `@pitlane/theme/schema` — one factory per token type, built on
+  `remix/data-schema` and designed for `import * as s`. `s.color()`,
+  `s.dimension()`, `s.duration()`, `s.number()`, `s.easing()`, `s.shadow()`,
+  `s.border()`, `s.transition()`, `s.gradient()`, `s.stroke()`,
+  `s.font.family()`, and `s.font.weight()` name a token type;
+  `s.group(self, children)` types a node and lets its children override it;
+  `s.scale()` declares a base whose accessor leaf multiplies; `s.any()`
+  declines to type a token at all.
+- Composite types (`shadow`, `border`, `transition`, `gradient`) and
+  `cubicBezier` take CSS text. `inset`, `em`, `%`, `clamp()`, `light-dark()`,
+  and `color-mix()` all work, none of which DTCG can express. The structured
+  object forms remain on the DTCG import path.
+- `theme.extend(patch)` deep-merges a patch and returns a new theme.
+  `theme.select(projection)` replaces the theme with a projection of it, which
+  may also reshape and rename. Both take a callback that receives the accessor,
+  so a layer can reference what it builds on.
+- `<Theme />` carries the init it was compiled from as `$theme`, and
+  `createTheme(SomeTheme)` reads it, so a published theme is one import.
+- `@pitlane/theme/default` — `DefaultTheme`, Tailwind v4's primitives with no
+  semantic layer. Pair it with `select` to avoid shipping every one of them.
+- `@pitlane/theme/dtcg` — `fromDTCG` reads a conformant 2025.10 document and
+  derives its schema from each token's resolved `$type`; `toDTCG` writes one
+  out and counts the values the format cannot express.
+- `scale(base)` multiplies any dimension, duration, or number token, keeping
+  its brand. `lightDark(light, dark)` writes a `light-dark()` color, and
+  composes with token references.
+- A mode declares its own condition. `media` defaults to
+  `(prefers-color-scheme: <name>)`; `selector` emits a second block for a
+  user-selectable toggle, which outranks the media block on specificity so an
+  explicit choice beats the OS preference.
+- A `"{a.b.c}"` string left over from the old format raises `ThemeError` naming
+  the `extend` that replaces it. Braces are never valid in a CSS value, so
+  passing one through would put `{color.white}` in the stylesheet where a color
+  belongs.
+- A reference is a property access, so it is type-checked wherever it appears,
+  including interpolated into a composite's CSS text. `select` refuses a
+  projection that drops a token something it kept refers to, and a reference
+  whose type does not match its position raises `ThemeError`.
+- Bad token values raise `ValidationError` from `remix/data-schema`, one issue
+  per bad token with its own path, all reported in one pass. Read `issues`
+  rather than `message`. `ThemeError` covers the structural failures: an
+  unknown or wrongly-typed reference, a reference to an untyped token, a
+  reference cycle, a variable collision, a reserved character in a name, and a
+  mode overriding a token that does not exist.
+- `css()`, `tva()`, `combine()`, and `cx()` are unchanged.
+
 ## 0.2.0
 
 - Raised the `remix` peer dependency to `^3.0.0-beta.10` (from

package/README.md

@@ -1,6 +1,6 @@
 # @pitlane/theme
 
-Type-safe styling with W3C design tokens for [Remix 3](https://remix.run). `createTheme` takes a [DTCG token document](https://www.designtokens.org/tr/drafts/format/) and returns a typed token accessor plus a `<Theme />` component that installs the tokens as CSS custom properties. The `css`, `tva`, `combine`, and `cx` helpers wrap `remix/ui`'s `css()` mixin and enforce your palette at the type level.
+Type-safe styling with design tokens for [Remix 3](https://remix.run). `createTheme` compiles a schema tree and a tree of CSS values into a typed token accessor plus a `<Theme />` component that installs CSS custom properties. The `css`, `tva`, `combine`, and `cx` helpers wrap `remix/ui`'s `css()` mixin and enforce the theme palette at the type level.
 
 ## Install
 
@@ -14,33 +14,40 @@ Requires `remix@^3.0.0-beta.10` as a peer.
 
 ## Quick start
 
+Define the schema beside the tokens it describes. Token values are the CSS they become:
+
 ```ts
 // app/theme.ts
-import { createTheme } from "@pitlane/theme";
+import { createTheme, lightDark } from "@pitlane/theme";
+import * as s from "@pitlane/theme/schema";
 
 export let {
     token: t,
     raw,
     Theme,
-} = createTheme(
-    {
-        color: {
-            $type: "color",
-            white: { $value: "#fff" },
-            gray: { 50: { $value: "#fafafa" }, 900: { $value: "#171717" } },
-            bg: { $value: "{color.white}" },
-        },
-        space: { $type: "dimension", sm: { $value: "8px" }, md: { $value: "16px" } },
+} = createTheme({
+    schema: {
+        color: s.color(),
+        spacing: s.scale(),
+        radius: s.dimension(),
+        shadow: s.shadow(),
+        animate: s.any(),
     },
-    {
-        modes: {
-            dark: { color: { bg: { $value: "{color.gray.900}" } } },
+    tokens: {
+        color: {
+            white: "#fff",
+            gray: { 50: "#fafafa", 900: "#171717" },
+            page: lightDark("#fff", "#171717"),
         },
+        spacing: "0.25rem",
+        radius: { full: "999px", responsive: "clamp(0.25rem, 2vw, 1rem)" },
+        shadow: { card: "0 1px 2px rgb(0 0 0 / 0.07)" },
+        animate: { spin: "spin 1s linear infinite" },
     },
-);
+});
 ```
 
-Render `<Theme />` once near the root. It emits a single `<style data-pitlane-theme>` element containing `:root` plus one `@media (prefers-color-scheme: dark)` block for the override:
+Render `<Theme />` once near the root. It emits one `<style data-pitlane-theme>` element with the custom properties:
 
 ```tsx
 import { Theme } from "./theme.ts";
@@ -57,7 +64,9 @@ function App() {
 }
 ```
 
-Pass tokens to `css()` inline at each element, through the `mix` prop. Token-mapped properties accept only the matching brand, so off-palette literals fail to compile:
+`<Theme />` declares `color-scheme: light dark` on `:root` whenever a token uses `lightDark()`, because `light-dark()` resolves to its light value when `color-scheme` is undeclared. Declare a narrower value yourself to override it.
+
+Pass tokens to `css()` inline at each element through the `mix` prop. Token-mapped properties accept only the matching brand:
 
 ```tsx
 import { css } from "@pitlane/theme";
@@ -65,24 +74,53 @@ import { t } from "./theme.ts";
 
 <article
     mix={css({
-        color: t.color.bg, // ✓ ColorToken
-        padding: [t.space.sm, t.space.md], // ✓ 1–4 token tuple
-        margin: 0, // ✓ literal zero
-        // color: "#ff0000", // ✗ not in the palette
+        color: t.color.page,
+        padding: [t.spacing(2), t.spacing(4)],
+        margin: 0,
+        // color: "#ff0000", // type error: outside the palette
         "&:hover": { color: t.color.gray[900] },
     })}
 />;
 ```
 
+`t.spacing(4)` produces `calc(var(--spacing) * 4)`, and `t.spacing.token` is the unmultiplied `var(--spacing)`. Use module-level `scale(token)` to multiply an ordinary dimension, duration, or number token.
+
+## Reference one token from another
+
+A reference is a property access on the layer below, so it goes in an `extend`. There is no string syntax for one, which is what lets the compiler check every reference and break the build when a target is renamed:
+
+```ts
+export let {
+    token: t,
+    raw,
+    Theme,
+} = createTheme({
+    schema: { palette: s.color() },
+    tokens: { palette: { ink: "#1c1a16", paper: "#f5f1e8" } },
+}).extend(base => ({
+    schema: { color: s.color(), shadow: s.shadow() },
+    tokens: {
+        color: { text: base.palette.ink, surface: base.palette.paper },
+        // A composite is CSS text, so a reference goes in by interpolation.
+        shadow: { card: `0 1px 2px ${base.palette.ink}` },
+    },
+}));
+```
+
+The emitted declarations keep their `var()` indirection, `--color-text: var(--palette-ink)`, so overriding a primitive reaches everything that references it. A mode override that references another token goes in an `extend` layer too, since that is where an accessor is in scope.
+
+A layer's declarations follow the ones they reference, which moves them later in the `:root` block. Custom properties in one rule resolve independently of order. Declare the namespace as an empty group in the base tree to reserve its position.
+
 ## Exports
 
-- `createTheme(document, options?)` — returns `{ token, raw, Theme }`. `token` (conventionally `t`) mirrors the document; each leaf is a branded `var()` string. `raw(ref)` resolves the base-mode value behind a ref. `<Theme />` installs the CSS custom properties and accepts an optional `nonce`.
-- `css(props)` — `remix/ui`'s `css()` with brand enforcement; call it inline at each `mix` callsite.
-- `tva(config)` — a cva-style variant resolver returning a `mix`-ready descriptor.
-- `combine(...fns)` — composes `tva` components into one.
-- `cx(...)` — a clsx-compatible `className` joiner.
-- `ThemeError` — thrown for invalid documents, references, or overrides.
-- Types: `ThemeOptions`, `ThemeProps`, `ThemeResult`, `ThemeComponent`, `ThemedCSSProps`, `ThemedCSSMixin`, `TVAConfig`, `TVAProps`, `TVAFn`, `CombinedTVAFn`, `ClassValue`, `DTCGDocument`, `TokenTree`, `DeepPartialTokens`, and the per-type token brands (`ColorToken`, `DimensionToken`, `DurationToken`, and the rest).
+- `createTheme({ schema, tokens, modes? })` compiles a theme and returns `{ token, raw, Theme, extend, select }`. `token`, conventionally `t`, mirrors the tree with branded `var()` strings. `raw(ref)` resolves a base value. `<Theme />` installs the custom properties.
+- `createTheme(DefaultTheme)` accepts a published theme component and returns a derivable theme. `@pitlane/theme/default` exports `DefaultTheme`, Tailwind v4 primitives without a semantic layer.
+- `css(props)` is `remix/ui`'s `css()` with token-brand enforcement. Call it inline at each `mix` callsite.
+- `tva(config)` creates a cva-style variant resolver. `combine(...fns)` composes tva components. `cx(...)` joins clsx-compatible class values.
+- `lightDark(light, dark)` returns CSS `light-dark()` text. `scale(token)` returns a multiplier for an ordinary dimension, duration, or number token.
+- `ThemeError` reports structural failures: a reference whose type does not match its position, a reference to an untyped token, a variable collision, an undeclared token, a mode overriding an unknown token, and a `"{a.b.c}"` string left over from the pre-0.3.0 format. Invalid values raise `ValidationError` from `remix/data-schema`, whose `issues` array contains the detail.
+- `@pitlane/theme/schema` exports `s.color()`, `s.dimension()`, `s.duration()`, `s.number()`, `s.easing()`, `s.shadow()`, `s.border()`, `s.transition()`, `s.gradient()`, `s.stroke()`, `s.font.family()`, `s.font.weight()`, `s.scale()`, `s.any()`, and `s.group()`.
+- Types include `ThemeInit`, `ThemeMode`, `ThemeResult`, `ThemeComponent`, `ThemeProps`, `TokenTree`, `ScaleFn`, `Tokens`, `TokenValue`, `ThemedCSSProps`, `ThemedCSSMixin`, TVA types, and per-type token brands.
 
 ## Links