@cube-dev/ui-kit 0.205.0 → 0.206.1

package/docs/tasty/ai-agents.md

@@ -10,7 +10,7 @@ Notation: ❌ wrong → ✅ correct.
 
 Color tokens (`#name`), custom properties (`$name`), `preset` names, `recipe` names, state aliases (`@mobile`) and extra units are **project-defined** in `tasty.config.ts` or a `configure({ … })` call. Look them up before writing styles. Never invent a name — reuse an existing one, or add it to the config.
 
-Only Tasty's built-ins exist without config: `#white`, `#black`, `#border`, `#outline`, `#current`, `#clear`, and `$gap`, `$radius`, `$border-width`, `$outline-width`, `$transition`, `$sharp-radius`, `$bold-font-weight`, `$font-sans-fallback`, `$font-mono-fallback`.
+Only Tasty's built-ins exist without config: `#white`, `#black`, `#border`, `#outline`, `#current`, `#clear`, and `$gap`, `$radius`, `$border-width`, `$outline-width`, `$transition`, `$sharp-radius`, `$bold-font-weight`, `$icon-size` (only where a `preset` applies), `$font-sans-fallback`, `$font-mono-fallback`.
 
 ## 1. Where styles go
 
@@ -72,6 +72,7 @@ The last row goes the other way — longhands over the shorthand — because `fl
 | `#name.50`            | token at 50% opacity — digits are a decimal fraction: `.5` = `.50` = 50%, `.05` = 5%, `.100` = 10% |
 | `#name.$opacity`      | opacity from a custom property                                                                     |
 | `#clear` / `#current` | `transparent` / `currentcolor`                                                                     |
+| `#a+#b.04`            | `#b` at 4% opacity over `#a`, as one color; layers stack left to right (`#a+#b.1+#c.04`)           |
 | `$name`               | custom property → `var(--name)`                                                                    |
 | `(#a, #b)`            | fallback chain                                                                                     |
 | `$$name` / `##name`   | the custom property _name_ (not its value) — inside `transition`                                   |
@@ -134,7 +135,7 @@ Directional modifiers beat placeholder zeros:
 - ❌ `padding: '2x 4x top right'` — a directional group takes one value, so `4x` is dropped → ✅ `padding: '2x top, 4x right'`
 - ❌ `fade: '3x 1x top bottom'` → ✅ `fade: '3x top, 1x bottom'`
 
-Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, and `tabSize`. Logical axis category styles accept one or two values in start/end order and the `start`, `end`, and `longhand` modifiers. `fill`, `color`, `caretColor`, and `accentColor` take a color only (use `#clear` for transparent). `fill` also mixes two colors with a comma, the weight as a percentage: ❌ `fill: '#surface #dark.04'` (deprecated overlay layer) · ❌ `fill: '#dark.04, #surface'` (half-transparent mix) → ✅ `fill: '#dark 4%, #surface'`.
+Value-only properties reject both colors and modifiers: `gap`, `columnGap`, `rowGap`, `opacity`, `zIndex`, `order`, `flexGrow`, `flexShrink`, `flexBasis`, `aspectRatio`, `lineClamp`, and `tabSize`. Logical axis category styles accept one or two values in start/end order and the `start`, `end`, and `longhand` modifiers. `fill`, `color`, `caretColor`, and `accentColor` take a color only (use `#clear` for transparent). An overlay is a compound color, in any color slot: ❌ `fill: '#surface #dark.04'` (deprecated overlay layer) · ❌ `fill: '#dark.04, #surface'` (half-transparent mix) → ✅ `fill: '#surface+#dark.04'`. Write it as one word, with no spaces around `+`. Every layer after the first needs an opacity suffix, and its token must be opaque: a translucent layer token, or one that is `#clear` in some state, leaves the result see-through, so vary the suffix (`#surface+#dark.$hover`) or the whole compound per state instead. A comma mix in `fill` is deprecated too: ❌ `fill: '#dark 4%, #surface'` → ✅ `fill: '#surface+#dark.04'`. For any other mix, write `color-mix()` itself: ✅ `fill: 'color-mix(in srgb, #dark $weight, #surface)'`.
 
 ### `transition`
 

package/docs/tasty/dsl.md

@@ -168,6 +168,7 @@ color: '#purple.5',         // 50% opacity
 color: '#purple.05',        // 5% opacity
 color: '#purple.$fade',     // Opacity from a custom property
 fill: '#current',           // → currentcolor
+fill: '#surface+#dark.04',  // #dark at 4% opacity over #surface, as one color
 color: '(#primary, #secondary)',  // Fallback syntax
 ```
 
@@ -255,6 +256,57 @@ clamped, and rectangular, so there is no hue to interpolate against
 `transparent`. Nothing configures it — see
 [Color space](configuration.md#color-space).
 
+### Compound colors
+
+Join color tokens with `+` to paint each one, at its own opacity, over the
+colors before it. The result is one color, so it works anywhere a token does:
+
+```jsx
+fill: '#surface+#dark.04',
+// → color-mix(in srgb, var(--dark-color) 4%, var(--surface-color))
+
+border: '1bw #border+#dark.1',
+color: 'light-dark(#primary+#black.2, #primary+#white.2)',
+'#hover-surface': '#surface-2+#surface-text.03',
+```
+
+Read it left to right, bottom layer first: `#surface+#accent.1+#dark.04` paints
+`#accent` at 10% over `#surface`, then `#dark` at 4% over that. Every operand is
+an ordinary token — `#current`, `#clear`, a hex color, a replace token — and
+takes its opacity suffix as it does anywhere: `#surface+#dark.$hover` reads the
+opacity from `$hover`, and a faded base such as `#surface.5+#dark.04` is layered
+as it is.
+
+The layers mix in sRGB, the space browsers composite in, so the color is exactly
+what stacking them as layers would show — but it is one color, which contrast
+checkers can read and transitions interpolate. A faded base is exact too:
+`#surface.5+#dark.04` is as translucent as the two layers would be.
+
+Every layer's token has to be opaque. The mix counts a layer's own alpha as well
+as its opacity suffix, and lowers the alpha of the whole color, so a layer token
+that holds a translucent color, or turns transparent in some state, leaves the
+result see-through: with `'#overlay': { '': '#clear', hovered: '#dark' }`,
+`'#surface+#overlay.04'` is 96% opaque at rest. Vary the opacity instead
+(`'#surface+#dark.$hover'`), or give each state its own color
+(`fill: { '': '#surface', hovered: '#surface+#dark.04' }`).
+
+- Write it as one word: `#surface + #dark.04` is three separate values, and
+  Tasty warns in development.
+- A layer without an opacity covers everything before it: `#surface+#dark` is
+  `#dark`, with a development warning.
+- A layer Tasty can see is transparent — `#clear`, a fade to `.0`, a color with
+  a zero alpha — is left out: `#surface+#clear` is `#surface`.
+- Over a transparent base, a layer is just its fade: `#clear+#dark.04` compiles
+  to `#dark.04`.
+- A `+` joining anything but color tokens (`#surface+1x`) is not a compound: the
+  token is dropped, with a development warning, and the style renders as if
+  that color were not there.
+
+A `+` joins tokens only. To fade a whole compound, give it a token
+(`'#hover-surface': '#surface+#dark.04'`) and fade that (`#hover-surface.5`). For
+a mix that is not a layer over another color, such as an even blend in OKLCH,
+write `color-mix()` itself.
+
 ---
 
 ## CSS Color Functions

package/docs/tasty/styles.md

@@ -303,52 +303,64 @@ Avoid setting physical and logical declarations that resolve to the same edge in
 
 Background color with design token support. Preferred over `backgroundColor` and `background`.
 
-**Syntax:** `[color]`, or two colors mixed with a comma: `[color] [weight%], [color]`
+**Syntax:** `[color]`
 
 | Value | Effect |
 |-------|--------|
 | `"#purple"` | Token-based background color |
 | `"#purple.10"` | Token color at 10% opacity |
-| `"#dark 4%, #surface"` | `#dark` mixed into `#surface` at 4% — the color `#dark` at 4% opacity over `#surface` would show |
+| `"#surface+#dark.04"` | `#dark` at 4% opacity over `#surface`, as one color — see [Compound colors](dsl.md#compound-colors) |
 | `"rgb(255 128 0)"` | CSS color value |
 | `"color-mix(in oklab, #primary 50%, #surface)"` | CSS color function — see [CSS Color Functions](dsl.md#css-color-functions) |
 
-#### Mixing two colors
+#### Overlays
 
-A comma between two colors mixes them into one:
+An overlay over a base color is a [compound color](dsl.md#compound-colors):
 
 ```jsx
-fill: '#dark 4%, #surface'
-// → background-color: color-mix(in srgb, var(--dark-color) 4%, var(--surface-color));
+fill: { '': '#surface', hovered: '#surface+#dark.04', pressed: '#surface+#dark.08' }
+// hovered → background-color: color-mix(in srgb, var(--dark-color) 4%, var(--surface-color));
 ```
 
-The comma-separated parts are the arguments of `color-mix()`, as written, mixed in sRGB: the space browsers composite layers in. When the weighted color is opaque, the mix is exactly what drawing it at that opacity over the other color shows. And because it is one `background-color`:
+The overlay token has to be opaque, with its opacity in the suffix: a translucent
+token, or one that turns `#clear` in some state, leaves the background
+see-through. Because the result is one `background-color`:
 
 - contrast checkers such as axe-core and Lighthouse can read it;
 - it transitions and animates between states like any other color;
 - an `image` on the same element stays the only `background-image` layer.
 
-The weight can come from a token or an expression: `'#dark $hover-weight, #surface'`, `'#dark ($hover * 100%), #surface'`.
-
-Give the weight as a percentage, not as an opacity. A color without a percentage takes half the weight, and its own alpha weighs it down again, so the mix comes out see-through: `'#dark.04, #surface'` is 52% opaque, not `#dark` at 4% over `#surface`. In development Tasty warns about a `#name.N` or `#clear` part without a percentage. It can't see into a token, though, so a token holding a translucent color mixes the same way with no warning: keep the token opaque and put its weight in the percentage.
-
-A mix takes two colors. Any more are ignored, with a development warning.
-
 #### Two colors separated by a space (deprecated)
 
 `fill: '#surface #dark.04'` paints the first color as `background-color` and the second as a `linear-gradient()` layer over it, through the `--tasty-second-fill-color` custom property. It still works, with a development warning, and is going away in the next major version: contrast checkers can't see through a `background-image`, so axe-core reports every text node over the layer as *incomplete*.
 
+Put a `+` where the space is:
+
 | Before | After |
 |--------|-------|
-| `'#surface #dark.04'` | `'#dark 4%, #surface'` |
+| `'#surface #dark.04'` | `'#surface+#dark.04'` |
 | `'#surface #clear'` | `'#surface'` |
 | `'#surface #accent'` (an opaque overlay) | `'#accent'` |
-| `'#base #overlay'` (a token holding a translucent color) | `'#overlay $overlay-weight, #base'`, with `#overlay` opaque and `$overlay-weight` a percentage |
+| `'#base #overlay'` (a token holding a translucent color) | `'#base+#overlay.$overlay-alpha'`, with `#overlay` opaque and `$overlay-alpha` its opacity as a number |
 
 The rewrites are exact when the overlay token is opaque. A state map no longer needs the same two-color shape in every state to transition smoothly: every state is now a plain background color.
 
 If an overlay has to stay a translucent token, draw the layer yourself with `fill: '#base', image: 'linear-gradient(#overlay, #overlay)'`. Contrast checkers can't read that either.
 
+#### Two colors mixed with a comma (deprecated)
+
+`fill: '#dark 4%, #surface'` mixes the two colors in sRGB, as the arguments of `color-mix()`: `color-mix(in srgb, var(--dark-color) 4%, var(--surface-color))`. It still works, with a development warning, and is going away in the next major version. A compound color is the same mix, in every color slot, and `color-mix()` itself covers what a compound can't write. `tasty/prefer-fill-mix` in [`@tenphi/eslint-plugin-tasty`](https://github.com/tenphi/eslint-plugin-tasty) rewrites each mix to the same color.
+
+| Before | After |
+|--------|-------|
+| `'#dark 4%, #surface'`, `'#surface, #dark 4%'` | `'#surface+#dark.04'` |
+| `'#accent 10%, #surface+#dark.04'` | `'#surface+#dark.04+#accent.1'` |
+| `'#dark $hover-weight, #surface'` (a percentage) | `'#surface+#dark.$hover-alpha'`, with `$hover-alpha` the opacity as a number — or `'color-mix(in srgb, #dark $hover-weight, #surface)'` |
+| `'#dark, #surface'`, `'rgb(0 0 0) 4%, #surface'`, and any other mix | `'color-mix(in srgb, #dark, #surface)'` — the same parts, in `color-mix()` |
+| `'#dark.04, #surface'` (a translucent part without a percentage) | `'#surface+#dark.04'` |
+
+Every rewrite but the last row's is the same color. `'#dark.04, #surface'` mixed a translucent color in by half and came out 52% opaque, so its rewrite paints what it was most likely meant to: `#dark` at 4% over `#surface`.
+
 There is no default fill color, so `fill: true` is ignored with a development warning. Use `false` for no fill.
 
 **Related deprecated props:** `backgroundColor` (use `fill`), `background` (overrides all background props when set — avoid).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.205.0",
+  "version": "0.206.1",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -34,7 +34,8 @@
     "docs/tasty",
     "docs/glaze",
     "docs/*.md",
-    "tasty.config.ts"
+    "tasty.config.ts",
+    "tasty.config.generated.ts"
   ],
   "keywords": [
     "uikit"
@@ -59,7 +60,7 @@
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
     "@tenphi/glaze": "2.0.0",
-    "@tenphi/tasty": "3.15.0",
+    "@tenphi/tasty": "3.17.1",
     "clipboard-copy": "^4.0.1",
     "clsx": "^1.1.1",
     "diff": "^8.0.3",
@@ -198,6 +199,7 @@
     "add-icons": "cd src/icons && node add-new-icon.js && pnpm fix",
     "audit-docs": "node scripts/audit-docs.mjs",
     "audit-defaults": "UPDATE_DEFAULTS=1 vitest run src/eslint-plugin/defaults.test.ts && prettier --write src/eslint-plugin/defaults.generated.ts",
+    "generate:tasty-config": "UPDATE_TASTY_CONFIG=1 vitest run src/tokens/tasty-config.test.ts && prettier --write tasty.config.generated.ts",
     "diagnostics:compiler": "node scripts/compiler/report.mjs",
     "diagnostics:form": "node scripts/form-diagnostics.mjs",
     "diagnostics:complexity": "node scripts/complexity-report.mjs",
@@ -207,6 +209,7 @@
     "test:form-compiled": "vitest run --config vitest.form-compiled.config.ts",
     "diagnostics:hooks": "node scripts/hooks-diagnostics.mjs",
     "check:react-package": "node scripts/compiler/check-package.mjs",
+    "check:component-tokens": "node scripts/check-component-tokens.mjs",
     "check:consumer-declarations": "node scripts/check-consumer-declarations.mjs"
   }
 }