@rowkit/tokens 0.4.0 → 1.0.0-beta.1

package/dist/css.d.ts

@@ -5,10 +5,22 @@
  * the stylesheet from them, so the two cannot drift. `css.test.ts` asserts that
  * every token in every scale reaches the output.
  *
- * Dark mode works by repointing *semantic* tokens under `.dark`. Primitives are
- * emitted once and never change — `--color-primary-600` is the same colour in
- * both themes; what changes is which primitive `--color-primary-solid` points
- * at. That is why the theme can flip without a single hardcoded colour moving.
+ * Two themes. Windows 98 is the default, carried by `:root`; the modern theme
+ * is switched on by `data-theme="modern"` on any element, and its dark scheme
+ * by the system or by `data-color-scheme="dark"` on that same element. A theme
+ * is a set of custom property values and nothing else, so themes nest: a
+ * region marked `data-theme="win98"` inside a modern page is Windows 98.
+ *
+ * One thing makes that work, and it is easy to break. A custom property whose
+ * value contains `var()` is resolved on the element that declares it, and
+ * descendants inherit the result. A theme therefore re-declares every token it
+ * changes on its own element; repointing a primitive at `:root` would not reach
+ * a semantic token that has already been resolved there.
+ *
+ * Shadows take one more step. Tailwind copies a `--shadow-*` value into each
+ * `shadow-*` utility rather than referencing it, so a theme could never change
+ * one. The `@theme` entry is therefore `var(--rk-shadow-*)`, and the value
+ * lives in that variable.
  *
  * @returns The complete stylesheet, ready to write to disk.
  */