cssints 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "cssints",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "CSS in TypeScript: typed css.* calls compiled to atomic CSS at build time (a Vite plugin)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/cssints"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist",
+    "skills",
+    "docs"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "browser": "./dist/runtime.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "default": "./dist/vite.mjs"
+    },
+    "./plugin": {
+      "types": "./dist/plugin-types.d.mts",
+      "default": "./dist/plugin.mjs"
+    },
+    "./frame": {
+      "types": "./dist/frame.d.mts",
+      "default": "./dist/frame.mjs"
+    },
+    "./surface": {
+      "types": "./dist/surface.d.mts",
+      "default": "./dist/surface.mjs"
+    },
+    "./parent-vars": {
+      "types": "./dist/parent-vars.d.mts",
+      "default": "./dist/parent-vars.mjs"
+    },
+    "./derived": {
+      "types": "./dist/derived.d.mts",
+      "default": "./dist/derived.mjs"
+    },
+    "./check": {
+      "types": "./dist/check.d.mts",
+      "default": "./dist/check.mjs"
+    },
+    "./tui": {
+      "types": "./dist/tui-types.d.mts",
+      "default": "./dist/tui.mjs"
+    }
+  },
+  "dependencies": {
+    "@cssints/css-grammar": "^0.1.0",
+    "culori": "^4.0.2",
+    "effect": "4.0.0",
+    "happy-dom": "^20.14.5",
+    "lightningcss": "^1.32.0",
+    "magic-string": "^0.30.0",
+    "mdn-data": "2.27.1",
+    "oxc-parser": "^0.149.0"
+  },
+  "peerDependencies": {
+    "@opencode/client": "^2.0.26",
+    "vite": "^8.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode/client": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/cssints/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: cssints
+description: >-
+  Write, review and fix styles in a project that uses cssints, the CSS-in-TypeScript compiler (a Vite plugin that
+  runs css.* calls at build time and replaces them with atomic class strings). Load it when code imports from
+  "cssints" with { type: "cssints" }, uses cn(), cx(), cv(), css.* members, media()/hover()/container()/within(),
+  createTokens, createGlobalTheme, check.contrast, or an @cssints/* package (layout, motion, fluid, fonts, reset,
+  tokens, icons, ...), and when a build fails with a "cssints:" message such as "must be known at build time",
+  "without the attribute", "unexpected ... expected <...>", "overlap without one containing the other" or
+  "wraps ... the marker of kernel".
+---
+
+# cssints: styles in TypeScript, compiled at build time
+
+Every `css.*` call runs at build time in Vite's Module Runner and is replaced by a class string. The values are
+checked against the CSS grammars (mdn-data) twice: in the types, where the call is, and again by the build, with the
+file and the place of the call. One sheet, `virtual:cssints.css`, holds every rule once, in `@layer`s. The browser
+gets class strings, `cx` and the few lines behind `cv`. The reference is `docs/API.md` of the cssints repository; the
+parts below are what you need most of the time.
+
+If the cssints MCP server is configured, prefer it for checks: `check_declaration` (is this value valid, and the
+message the build would give), `check_support` (browser support for the project's browserslist), `check_contrast`,
+`compile` (a module's classes, CSS, errors and warnings), `search_docs` and `list_plugins`. On a running dev server
+of an app with `cssints({ devtools: true })` (`url`, default `http://localhost:5173`): `explain_class` (a class from
+the DOM → its declarations, conditions, layer, tokens and the call that made it), `module_styles` (a file's calls and
+their CSS) and `dev_errors` (the build errors Vite has now). In a headless Chromium (playwright-core):
+`inspect_element` (a CSS selector → the element's classes by call, the winner per property, what it overrides, ✓/✗
+against the computed style) and `why_property` (why one property has its value), with `hover`, `focus`, `width` and
+`height`. Without it, the build is the check: run the dev server or `vite build` and read the message.
+
+## Setup
+
+```ts
+// vite.config.ts
+import cssints, { cssTarget, targets } from "cssints/vite";
+
+export default {
+  plugins: [cssints()], // any order beside React, Solid, ... plugins
+  css: { transformer: "lightningcss", lightningcss: { targets }, devSourcemap: true },
+  build: { cssMinify: "lightningcss", cssTarget },
+};
+```
+
+- The entry imports `"virtual:cssints.css"` once. `tsconfig.json` needs `"types": ["vite/client"]`.
+- `targets` and `cssTarget` come from the browserslist (`BROWSERSLIST`, else `package.json` / `.browserslistrc`, else
+  `defaults`), read from `process.cwd()`: run Vite from the app's folder. Support warnings read the config of Vite's
+  `root`, and each is said at the `css.*` call that made it, once per file per build (in dev, again after an edit).
+- `devSourcemap: true` maps each class rule in Chrome's Styles pane to the call that made it; in a build,
+  `build: { sourcemap: true }` (or `"hidden"`) maps the sheet asset too (bundle analysers split its bytes by module).
+
+## The import attribute
+
+```ts
+import { cx } from "cssints"; // runtime: the only member without the attribute
+import { cn, cv, hover, media, p } from "cssints" with { type: "cssints" }; // build time
+import * as css from "cssints" with { type: "cssints" }; // the same, as a namespace
+import { stack } from "./stack.ts" with { type: "cssints" }; // your own helper module, run at build time
+```
+
+- A build-time member imported without the attribute is a build error:
+  `imports build-time p from "cssints" without the attribute`.
+- Plugin packages are imported with the attribute too: `import { stack } from "@cssints/layout" with { type: "cssints" }`.
+- `import type { Style } from "cssints"` needs no attribute.
+
+## Arguments are build-time values
+
+`p(n)` with `n` a prop, a parameter or state fails: `css arguments must be known at build time: n is not defined
+where the call is evaluated`. The types do not catch it. Choose at runtime between styles made at build time:
+
+```tsx
+<div className={cx(base, on && p(4))} />          // a condition: cx skips falsy values
+<button className={button({ size })} />            // a cv() variant
+<div style={style(token.set(accent, "#dc2626"))} /> // a token set inline (static values)
+<div style={{ "--accent": value }} />              // a dynamic value: a plain style prop
+```
+
+A helper module imported with the attribute may take parameters (`stack(4)`): each call is a site of its own. A call
+the run does not reach (`false && p(4)`, a branch) still gets its class string.
+
+## Properties and values
+
+- Every property is a camelCase member (`paddingLeft`, `alignItems`); short names `p pt pr pb pl`, `m mt mr mb ml`,
+  `bg`. There is no `items` or `justify`.
+- A bare number is a spacing step of 0.25rem in `padding*`, `margin*`, `gap*`, `inset*`: `p(4)` is `1rem`. Elsewhere
+  it is a `<number>`: `opacity(0.5)`; `width(4)` is a type error, write `width("4rem")`.
+- Parts are joined by a space: `border("1px solid", accent)`, `padding("1rem 2rem")`, `margin("0", "auto")`.
+- Keywords are written in their canonical case: `color("RED")` is an error that says to write `"red"`.
+- `flex()` and `grid()` with no argument set `display` and chain container properties without the prefix:
+  `flex().direction("column").alignItems("center").gap(2)`. With an argument they are the shorthand
+  (`flex("1")`, a plain style that does not chain). Item properties (`flexGrow`, `alignSelf`) are plain members.
+- CSS functions are calls: `calc(t.space.md, "*", 2)`, `clamp("1rem", "2vw", "2rem")`, `colorMix("in oklab", a, "black 15%")`,
+  `linearGradient("to right", [a, "25%"], "blue")`. Clashing names end in `Fn`: `colorFn`, `translateFn`, `attrFn`.
+- `firstThatWorks("100dvh", "100vh")` is a value with fallbacks in one class.
+- `keyframes({ from: opacity(0), to: opacity(1) })` returns a name for `animation(fade, "200ms")`.
+
+## Merging: cn, cx, cv
+
+- `cn(...)` merges at build time into one string; the later of one property wins (`cn(p(4), p(2))` is `p(2)`). A
+  longhand beats its shorthand whatever the order. Two properties that overlap without one containing the other
+  (`borderTop` and `borderColor`, `marginLeft` and `marginInline`) are a build error: set one, or the longhands.
+- `cx(...)` joins strings at runtime (skips falsy values, flattens arrays; no clsx objects). It sees no conflicts.
+- `cv({ base, variants, defaultVariants, compoundVariants })` is the function you call; props are typed. A variant
+  wins over the base, a compound (`{ size: "lg", tone: "loud", class: p(6) }`) over both. Values are `css.*` styles,
+  never CSS strings.
+
+```ts
+const button = cv({
+  base: cn(p(2), fontSize("1rem")),
+  variants: { size: { sm: p(1), lg: p(4) }, disabled: { true: opacity(0.5) } },
+  defaultVariants: { size: "sm" },
+});
+button({ size: "lg", disabled: true });
+```
+
+## Conditions and layers
+
+Conditions are wrappers that nest: `hover(bg("#eee"))`, `media("(width >= 40rem)")(p(4))`, `md(hover(...))`.
+
+- Pseudo-classes: `hover`, `focus`, `focusVisible`, `active`, `disabled` and the other standard ones without arguments.
+- `media(q)`, `container("sidebar (width < 30rem)")`, `supports("(display: grid)")`; queries are checked, and a range
+  needs parentheses: `(width >= 40rem)`, not `min-width > 40rem`. Bind them once: `const md = media("(width >= 40rem)")`.
+- `attr("aria-current", "page")(color("blue"))`; `attr(name)` is presence; `op` is `=`, `~=`, `|=`, `^=`, `$=`, `*=`.
+- Parent state: `group()` (or `group("card")`) marks the ancestor, `within(hover, "card")(...)` reads it.
+- Layer = number of conditions: none `_.a`, one `_.b`, up to four (`_.e`); a fifth is an error. More conditions win.
+  In one layer the sheet orders rules (pseudo-classes by their usual order, queries by min-width, `attr()` after
+  pseudo-classes), not your argument order.
+- `global(selector, ...styles)` is a rule with no class (a reset): in `_.k`, below every class. It takes `media()`,
+  `container()` and `supports()`, not `hover` (put the state in the selector).
+- `layers("app", "author", "viewer")` declares top-level layers after the engine's; `{ before: true }` before them.
+- No pseudo-elements and no `:has()` in 0.1.
+
+A condition wraps declarations. A plugin member that is only a kernel's marker class (`pretty()`, `balance()`,
+`frame()` with no method, `group()`) cannot go under a condition: `:hover wraps _balance-prettyCore, the marker of
+kernel balance.prettyCore, with no declaration of its own`. Put the member outside, and the condition around one of
+its methods (`cn(skeleton(), hover(skeleton().highlight("white")))`) or a plain property.
+
+## Tokens, themes, contrast
+
+```ts
+const t = createTokens({
+  color: { $type: "color", bg: { $value: "#ffffff" }, fg: { $value: "#111827" } },
+  space: { $type: "dimension", md: { $value: "1rem" } },
+});
+createGlobalTheme(t, media("(prefers-color-scheme: dark)"), {
+  color: { bg: "#0b0b0f", fg: "#f3f4f6" },
+});
+createGlobalTheme(t, ".brand", { color: { fg: "#7c2d12" } });
+check.contrast(t.color.fg, t.color.bg, { min: 4.5 }); // every theme too; below min is a build error
+export const card = cn(bg(t.color.bg), color(t.color.fg), p(t.space.md));
+```
+
+A token is its `var(--name)` and fits where a value of its type fits. Pass the token, not `"var(--color-bg)"` (a
+warning). Single tokens: `token.color("#2563eb", "accent")` (named, settable) or `token.color("#6b7280")` (private).
+DTCG JSON, Figma exports, references `{color.accent}`, derived values and layers of themes:
+[references/tokens.md](references/tokens.md).
+
+## Plugin packages: which one
+
+Import them with the attribute, except `@cssints/tokens` and `@cssints/ramp` (plain data for `createTokens`). A
+member returns a class string (or a value) that goes into `cn()`/`cx()`. Details and gotchas:
+[references/plugins.md](references/plugins.md).
+
+| Need                                        | Package                                                      |
+| ------------------------------------------- | ------------------------------------------------------------ |
+| Stacks, clusters, sidebars, auto grids      | `@cssints/layout`: `stack()`, `cluster()`, `sidebar()`, ...  |
+| A length that grows with the viewport       | `@cssints/fluid`: `fontSize(fluid("1rem", "1.5rem"))`        |
+| Web fonts with a metric-matched fallback    | `@cssints/fonts`: `font(family, { provider })`               |
+| A CSS reset below every style               | `@cssints/reset`: `reset({ media?, prose? })`                |
+| Ready-made tokens (Open Props, Radix, ...)  | `@cssints/tokens/<set>`: data for `createTokens`             |
+| A palette with contrast steps               | `@cssints/ramp`: `ramp(base, { mode, ... })` into tokens     |
+| Icons as a mask class                       | `@cssints/icons`: `icons({ provider, ... })`                 |
+| Looks per `data-mode` (app, author, viewer) | `@cssints/mise-en-mode`: `look(t, name, source, overrides)`  |
+| Eased gradients                             | `@cssints/gradient`: `gradient(kind, dir, from, to, ...)`    |
+| Enter and exit animations                   | `@cssints/motion`: `motion().preset("fade-in")`              |
+| Animations on scroll into view              | `@cssints/reveal`: `reveal().preset("slide-in-up")`          |
+| Styles while a sticky header is stuck       | `@cssints/stuck`: `sticky().top("0")`, `stuck(styles)`       |
+| Balanced headings, no orphans               | `@cssints/balance`: `balance()`, `pretty()`                  |
+| Squircle corners                            | `@cssints/squircle`: `squircle().radius("24px")`             |
+| Masonry                                     | `@cssints/masonry`: `masonry().columns("12rem")`             |
+| Image placeholders from the image's colours | `@cssints/placeholder`: `backgroundImage(placeholder(path))` |
+| Loading skeletons in one phase              | `@cssints/skeleton`: `skeleton().radius("50%")`              |
+| Concentric radius, parent-relative colour   | `cssints/frame`: `frame()`; `cssints/surface`: `surface()`   |
+
+A member conflicts with the properties its kernel sets: `cn(stack(), display("grid"))` is a build error. Use the
+member's methods instead.
+
+## Build errors
+
+Read the message: it names the property or the member, the bad value and what the grammar expected, and it points at
+the call. The common ones, with fixes: [references/errors.md](references/errors.md).
+
+## Rules of thumb
+
+- Make every style at module level or in a helper module; choose between them at runtime with `cx`, `cv` or tokens.
+- Prefer `cn()` to `cx()` when the parts are fixed: it is checked for conflicts and leaves nothing at runtime.
+- Prefer a token and a theme to a second style for each colour mode.
+- Write `check.contrast` for each text/background pair you use; it checks every theme.
+- A support warning is not an error: the value works where the targets have it. LightningCSS lowers what it can
+  (`oklch()` gets a fallback) and those values do not warn.
+- Styles of a library on cssints are evaluated by the app's plugin; such a package must be a direct dependency.

package/skills/cssints/references/errors.md

@@ -0,0 +1,85 @@
+# cssints build errors and warnings
+
+A value error is given twice: as a type error on the bad part in the editor, and as a build error with the file and
+the place of the call (the Vite overlay points at it). Some errors only the build sees: runtime arguments, conflicts,
+contrast, ranges in some positions, `supports()` property names. The messages below are the real text, shortened with
+`…`.
+
+## Imports and build-time values
+
+| Message                                                                                                                  | Meaning and fix                                                                                                                                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<file> imports build-time p from "cssints" without the attribute. Import it as: … with { type: "cssints" }`             | Every member but `cx` runs at build time. Add `with { type: "cssints" }` to that import (keep `cx` in a plain import, or in the same one).                                                                     |
+| `css arguments must be known at build time: n is not defined where the call is evaluated (a parameter, a prop or state)` | The call reads a runtime value. Make the styles at build time and choose at runtime: `cx(on && p(4))`, a `cv()` variant, or a token set in `style={...}`. Also when a local shadows a global (`open`, `name`). |
+| `imports _cv from "cssints", which is gone`                                                                              | Old code: `cv({ ... })` is the function now. Drop `_cv(` and its closing bracket.                                                                                                                              |
+
+## Grammar errors
+
+The shape is `<property>: unexpected "<token>" in "<value>", expected <grammar>`.
+
+| Example                                                                                                | Fix                                                                                                 |
+| ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `padding: unexpected "-0.25rem" in "-0.25rem", expected <length-percentage [0,∞]>` (`p(-1)`)           | Out of the range. A negative spacing is not a padding; use `margin` for negative values.            |
+| `color: unexpected "RED" in "RED" ("RED" is red in CSS; write "red"), expected <color>`                | Keywords and function names have one spelling, the canonical lowercase one.                         |
+| `color: unexpected "1px" … ("var(--gap)" is checked as "1px": a token stands for a value of its type)` | A token of the wrong type: a length token in a colour property. Use a token of the property's type. |
+| `width: unexpected "calc(1px" … (cannot add length and time)`                                          | Math on mixed kinds. Check the units and the tokens in the `calc()`.                                |
+| `@media: unexpected "min-width" in "screen and min-width > 40rem", expected <media-query>`             | A range needs parentheses: `media("(width >= 40rem)")`.                                             |
+| `@supports: unexpected "grdi" in "(display: grdi)", expected <supports-in-parens>`                     | A typo in the declaration of `supports()`.                                                          |
+| `selector: unexpected end in "a >", expected <complex-selector-list>`                                  | A selector of `global()` or of a theme is incomplete.                                               |
+| `cv() base must be a css.* value (cn(...), a flex() chain or one property), got "padding: 1rem"`       | CSS strings are gone everywhere: write `cn(p(4), fontSize("1rem"))`.                                |
+
+A type error with no build error usually means the value is valid CSS that the types read too strictly (or the
+reverse); trust the build's message and, with the MCP server, `check_declaration`.
+
+## Chains
+
+| Message                                                                    | Fix                                                                                          |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `flex() has no .padding(); it chains direction, wrap, flow, alignItems, …` | A chain has only its container properties. Merge the rest: `cn(flex().gap(2), p(4))`.        |
+| `plain styles do not chain (.gap); merge them with cn(...) or cx(...)`     | `flex("1")` (with an argument) is the shorthand property, a plain style.                     |
+| `sticky().top() is used twice` (and other members: a method is used once)  | Each method of a chain once. Under a condition, a second chain is fine: `hover(x().y(...))`. |
+
+## Conflicts
+
+| Message                                                                                                             | Fix                                                                                                                                         |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `border-top and border-color overlap without one containing the other, so the sheet cannot order them …`            | In one `cn()`. Set one of them, or the longhands (`borderTopColor`). Same for a physical and a logical side (`marginLeft`, `marginInline`). |
+| `cv() base and variant active.yes: border-bottom and border-color overlap …`                                        | The same rule between base, variants and compounds that can be active together.                                                             |
+| `cv() variants a.x and b.x both set color and can be active together, so nothing says which wins`                   | Set the property in one variant, or in the base.                                                                                            |
+| `layout: kernel stack-core sets display, flex-direction, gap (this style also sets display)`                        | A plugin member and a property its kernel sets, in one `cn()`. Use the member's method (`stack().gap(4)`), or drop the property.            |
+| `frame: frame() sets padding, margin, border-radius and the border: use its methods (this style also sets padding)` | The same, with the plugin's own message.                                                                                                    |
+
+`cx()` joins strings at runtime and checks nothing: a conflict across `cx()` arguments is not reported.
+
+## Conditions
+
+| Message                                                                                                        | Fix                                                                                                                                                                                     |
+| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:hover wraps _balance-prettyCore, the marker of kernel balance.prettyCore, with no declaration of its own: …` | A kernel is global CSS keyed to a class: it cannot be conditional. Put the member outside the condition; wrap one of its methods or a plain property (`hover(css.textWrap("pretty"))`). |
+| `a style takes at most 4 conditions (layers _.a to _.e); this one has 5: …`                                    | Fewer nested wrappers. Bind a combined query (`media("(width >= 40rem) and (hover: hover)")`) instead of two.                                                                           |
+| `global() takes media(), container() and supports() conditions, not :hover: write the state in the selector`   | `global("a:hover", color("red"))`.                                                                                                                                                      |
+| `within(media(...))` is an error                                                                               | `within()` takes a pseudo-class wrapper or `attr(...)`, not a query.                                                                                                                    |
+
+## Tokens, themes, layers
+
+| Message                                                                               | Fix                                                                                                             |
+| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `contrast 2.84 is below 4.5: c.fg #999 on c.bg #fff, in the default values`           | `check.contrast` failed (it names the theme when a theme fails). Change the colour, or the theme that names it. |
+| warning: `padding: "var(--space-sm)" is the token space.sm: pass the token itself, …` | Pass `t.space.sm`; for a fallback, `css.var(t.space.sm, "4px")`.                                                |
+| warning: `… stays at its static default in chrome 109 …`                              | A derived colour the old-browser runtime cannot compute; it keeps its default there. Usually acceptable.        |
+| two tokens with one name, `2xs` and `_2xs` in one group, a cycle of references        | Rename; a digit key `2xs` is `t.space._2xs` in code.                                                            |
+| `$type "fontFamily"` (or `string`, a composite type) has no token type                | Leave it out of the token file; set fonts with `fontFamily(...)` or `@cssints/fonts`.                           |
+| an undeclared layer in `{ layer: "app" }`, the same layers in another order           | Call `layers("app", ...)` first, in this module or one it imports; keep one order everywhere.                   |
+
+## Support warnings
+
+`cursor: "pointer" … is not supported by ios_saf … (css.properties.cursor)`: the value is valid, a browserslist target
+lacks it. It is a warning, not an error. Options: accept it, add a fallback (`firstThatWorks(wanted, fallback)`), or
+narrow the browserslist. The BCD key is in parentheses; `check_support` of the MCP server answers the same question.
+Vite shows the warning at the `css.*` call that made it (file, line, column, a code frame). A build says it once per
+file; a dev server again when that file is edited, not on every update. The targets are the browserslist of Vite's
+`root`.
+
+## When an error has `(trace <id>)`
+
+The build ran with `CSSINTS_TRACE=otlp`; search for the id in the trace backend (Jaeger) to see the hook and the file.

package/skills/cssints/references/plugins.md

@@ -0,0 +1,91 @@
+# The plugin packages
+
+Each package is written on `scope()` of `cssints/plugin` and has a README with its rules and limits
+(`node_modules/@cssints/<name>/README.md`). Import them with `with { type: "cssints" }`, except `@cssints/tokens`
+and `@cssints/ramp`, which are plain data. What the others share:
+
+- A chain member (`stack()`, `motion()`, `skeleton()`) is a kernel class plus one class per method; each method sets a
+  custom property, so a method works under a condition: `media("(width >= 40rem)")(stack().gap(8))`.
+- A member conflicts with what its kernel sets, in one `cn()`: use its methods, not the plain property.
+- A member that is only a kernel class (`balance()`, `pretty()`, `skeleton()` with no method) cannot be inside a
+  condition. Put it outside; put a method inside.
+- Fallbacks for older browsers (CSS under `@supports not`, or a small script) are in the build only when a browserslist
+  target needs them, and are delivered by the engine: nothing to import by hand.
+- Files read at build time (icons, fonts, placeholder images) are not watched in dev: restart, or touch the module.
+
+## Layout and type
+
+**`@cssints/layout`**: `stack().gap(6)`, `cluster().gap(2).justify("space-between").align("center")`,
+`sidebar().side("right").width("20rem").content("50%").gap(4)`, `switcher().threshold("30rem").gap(2)`,
+`cover().minHeight("100vh")`, `autoGrid().min("16rem").gap(4)`. No media queries: they respond to their space.
+`cn(stack(), display("grid"))` is a conflict; padding, sizes and colours are fine.
+
+**`@cssints/masonry`**: `masonry().columns("12rem").gap(4)`. `display: grid-lanes` where the browser has it (Safari
+26.4), CSS columns elsewhere (the order then runs down each column).
+
+**`@cssints/fluid`**: `fontSize(fluid("1rem", "1.5rem", { from: "20rem", to: "80rem" }))`, a `clamp()` computed at
+build time; `fluid.container(...)` against the container's width. px or rem only. A range that fails WCAG 1.4.4
+(text resize) is a build error; `{ zoom: false }` for lengths that are not text.
+
+**`@cssints/fonts`**: in a module of its own, `export const body = font("Inter", { provider: "fontsource", weights:
+[400, 700] })` (or `provider: "fs", files: [...]`); then `body.family()` (the `@font-face` rules, a metric-matched
+fallback face, `font-family`) and `body.trim({ lineHeight: 1.2 })` (cap-height trim: `text-box`, else capsize margins).
+
+**`@cssints/balance`**: `balance()` (`text-wrap: balance`, with a 0.55 kB script for targets without it) and
+`pretty()` (native only). Under a condition write `textWrap("balance")` instead.
+
+## Base and tokens
+
+**`@cssints/reset`**: `reset({ media: true, prose: true })` once, at the top level of a module the entry loads. In
+`@layer reset` before the engine's layers: any style beats it. A layer of yours between:
+`layers("reset", "base", { before: true })`.
+
+**`@cssints/tokens`**: data, not a call. `createTokens({ radix: light })`, themes from `dark`;
+`createTokens({ ...colors, size: sizes })` from `/open-props`. Pass only the scales you use (type cost).
+
+**`@cssints/ramp`**: `ramp("#2563eb", { mode: "contrast", ratios: [1.2, 1.5, 3, 4.5, 7], background: "#fff" })` or
+`{ mode: "lightness", steps: 9 }`, as a group of `createTokens`; `overrides(ramp(...))` for a theme. A contrast step
+meets its ratio on that background only: make a second ramp for a dark background. Imported without the attribute
+(plain data).
+
+**`@cssints/mise-en-mode`**: `look(t, "dark", "app" | "author" | "viewer", overrides, { scope? })`: a theme on
+`[data-mode="dark"]` (and `data-mode="dark/color"` for one aspect, a top-level token group) in the layers
+`app < author < viewer`. Checked like `createGlobalTheme`, read by `check.contrast`.
+
+**`@cssints/icons`**: in a module of its own, `export const mdi = icons<typeof import("@iconify-json/mdi/icons.json")>({
+provider: "iconify-json", collection: "mdi" })` or `icons({ provider: "fs", dir: "src/icons" })`; then
+`cn(mdi("close"), color("crimson"), width("1.5em"))`. One-colour icons take `color`; a wrong name is a build error with
+a suggestion.
+
+## Paint
+
+**`@cssints/gradient`**: `backgroundImage(gradient("linear", "to bottom", "#000", "transparent", "ease-in-out", 5))`:
+eased stops mixed in oklab. Each argument its own string; the direction is one string (`"to bottom"`).
+
+**`@cssints/placeholder`**: `backgroundImage(placeholder("src/hero.jpg"))` (a gradient of the image's colours) or
+`{ mode: "thumbhash" }` (a tiny PNG; pair it with `backgroundSize("cover")`). JPEG and PNG only; the path is relative
+to the working directory.
+
+**`@cssints/squircle`**: `squircle().radius("24px")`: `corner-shape: squircle`, else a mask of the same shape (which
+clips shadows and outlines: put those on a wrapper). Set the radius with `radius()`, not `borderRadius`.
+
+**`@cssints/skeleton`**: `cn(skeleton().radius("50%"), width("3rem"), height("3rem"))`: one clock on `:root`, so every
+skeleton shimmers in phase; still under reduced motion. Do not set `background`, `background-image`, `-size`,
+`-position`, `-attachment` or `border-radius` beside it (`backgroundColor` is fine and shows through).
+
+**`cssints/frame`** (`frame().radius("1.5rem").padding(4).border("1px")`: a nested frame's radius is concentric) and
+**`cssints/surface`** (`surface().color(canvas)`, `.lighten(0.06)`, `.darken()`, `.contrast()`, `.ink()`: a colour
+relative to the parent surface). Both ship in `cssints`; a script fallback for browsers without style queries.
+
+## Motion and scroll
+
+**`@cssints/motion`**: `motion().preset("slide-in-up").duration("500ms").delay("100ms").easing("linear")`. Presets
+`fade-*`, `slide-*-up|down|left|right`, `scale-*`, `blur-*` (in and out). Reduced motion turns movement into a fade.
+No `animation*` property beside it.
+
+**`@cssints/reveal`**: `reveal().preset("blur-in").range("entry 0% entry 100%")`: motion's entrance presets on
+`animation-timeline: view()`; where a target lacks it, a 0.3 kB script plays the animation once on entry.
+
+**`@cssints/stuck`**: `sticky().top("0")` on the sticky element, `stuck(color("red"))` or `stuck("bottom")(...)` on an
+element inside it (a scroll-state query matches descendants only). An IntersectionObserver fallback where the targets
+lack scroll-state queries.

package/skills/cssints/references/tokens.md

@@ -0,0 +1,91 @@
+# Tokens, themes and contrast
+
+## Single tokens
+
+```ts
+import * as css from "cssints" with { type: "cssints" };
+
+const accent = css.token.color("#2563eb", "accent"); // --accent, can be set
+const gap = css.token.length("16px", { var: "gap", inherit: false });
+const muted = css.token.color("#6b7280"); // --_<hash>, private: token.set() rejects it
+
+export const a = css.cn(css.color(accent), css.gap(gap));
+export const b = css.style(css.token.set(accent, "red")); // { "--accent": "red" } for a style prop
+```
+
+Types: `color`, `length`, `percentage`, `lengthPercentage`, `number`, `integer`, `angle`, `time`, `customIdent`,
+`resolution`, `url`, `image`, `transformList`, `easingFunction`, `shadow`. Each gives one `@property` rule. A value in
+`rem`/`em`/`ch` gets a px initial value and the real value on `:root`, so it follows the user's font size.
+
+## Token sets (DTCG)
+
+```ts
+export const t = css.createTokens({
+  color: {
+    $type: "color",
+    accent: { $value: "#2563eb" },
+    hover: { $value: "color-mix(in oklab, {color.accent}, black 15%)" }, // derived: follows accent in themes
+    link: { $value: "{color.accent}" }, // alias
+  },
+  space: {
+    $type: "dimension",
+    "2xs": { $value: "2px" },
+    md: { $value: { value: 1, unit: "rem" } },
+  },
+});
+// t.color.accent, t.space._2xs (a key that starts with a digit gets "_"), variable --space-2xs
+```
+
+- `$type` is inherited through groups and required: `color`, `dimension`, `number`, `duration`, `fontWeight`,
+  `cubicBezier`, `shadow`. `fontFamily`, `string`, `boolean` and the other composite types are errors.
+- Names are the kebab-case path (`--color-accent`). The second argument maps a path to a name or `{ var, inherit }`.
+- JSON works: `import tokens from "./tokens.json" with { type: "json" }; createTokens(tokens)`. The editor then knows
+  the paths but not the types; the build checks the values.
+- Figma's own export (one DTCG file per mode) and TokensBrücke ("Split modes into separate files"): the default mode
+  is `createTokens(json)`, another mode is `createGlobalTheme(t, dark, darkJson)` as it is. Tokens Studio's format goes
+  through Style Dictionary with `@tokens-studio/sd-transforms` first (recipe in docs/API.md, "JSON from Figma").
+- Ready-made sets: `@cssints/tokens/open-props`, `/radix`, `/flexoki`, `/reasonable-colors` (data: put a set under a
+  group, `createTokens({ radix: light })` gives `--radix-blue-11`). Palettes: `@cssints/ramp`.
+
+## Themes
+
+```ts
+const dark = css.media("(prefers-color-scheme: dark)");
+css.createGlobalTheme(t, dark, { color: { accent: "#60a5fa" } }); // :root under the media query
+css.createGlobalTheme(t, ".brand", { color: { accent: "#db2777" } }); // a selector; hover and link follow
+css.createGlobalTheme(t.color, css.container("(width < 30rem)"), { accent: "#000" }); // a group, a container query
+css.createGlobalTheme(t, ".soft", {
+  color: { link: "color-mix(in oklab, {color.accent}, white 20%)" },
+}); // live
+```
+
+- The condition is a `media()`, a `container()` or a selector. Not `hover` or `supports()`.
+- Options: `{ layer: "app" }` (a layer declared with `layers()`), `{ scope: "article.post" }` (an `@scope` around a
+  selector theme).
+- A theme re-declares the aliases and derived tokens that depend on what it overrides.
+- Put themes in a module of their own and import it once from the entry (`import "./theme.ts"`); a module that uses a
+  token gets the theme rules for that token.
+- Sheet order: tokens and themes are in `_.k`, below every class; a selector theme beats a condition theme.
+
+## Contrast
+
+```ts
+css.check.contrast(t.color.fg, t.color.bg, { min: 4.5 }); // WCAG 2.x, 1 to 21
+```
+
+- Checks the defaults and every theme that sets either token (themes of one selector are read together in cascade
+  order). A ratio below `min` is a build error with both colours and the theme.
+- A value it cannot evaluate (`color-mix()` over another token, `currentColor`, `light-dark()`, a translucent colour)
+  is a warning, not a pass.
+- A value set at runtime (a slider on `<html>`) is checked at its default only.
+- `surface().ink()` picks black or white by lightness and is not a contrast guarantee: check the pair with tokens.
+
+## Top-level layers
+
+```ts
+css.layers("app", "author", "viewer"); // after the engine's layers: they beat the engine's :root fallbacks
+css.layers("reset", "base", { before: true }); // before the engine's: every cssints style beats them
+```
+
+The same names in another order, or a layer on both sides, is a build error. `@cssints/reset` uses `reset` before the
+engine's layers; `@cssints/mise-en-mode` uses `app < author < viewer`.