@tenphi/cookbook 0.31.0 → 0.31.1

package/docs/upstream/manifest.json

@@ -1,10 +1,10 @@
 [
   {
     "name": "@tenphi/tasty",
-    "version": "3.14.0",
+    "version": "3.16.0",
     "license": "MIT",
     "repository": "https://github.com/tenphi/tasty",
-    "ref": "v3.14.0",
+    "ref": "v3.16.0",
     "directory": "upstream/tasty"
   },
   {

package/docs/upstream/tasty/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/tenphi/tasty/v3.14.0/assets/tasty.svg" width="128" height="128" alt="Tasty logo" />
+  <img src="https://raw.githubusercontent.com/tenphi/tasty/v3.16.0/assets/tasty.svg" width="128" height="128" alt="Tasty logo" />
 </p>
 
 <h1 align="center">Tasty</h1>
@@ -548,7 +548,7 @@ Covered in [Types and Linting](#eslint-and-oxlint): 40+ rules for ESLint 9+ and
 [Tasty for VS Code](https://github.com/tenphi/tasty-vscode-extension) highlights color tokens, units, state keys, presets, and style properties inside `tasty()`, `tastyStatic()`, `styles` objects, and style functions, and adds snippets for components, state maps, and `configure()`. Install the `.vsix` from the [latest release](https://github.com/tenphi/tasty-vscode-extension/releases/latest).
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/tenphi/tasty/v3.14.0/assets/tasty-vscode-highlight.png" width="512" alt="Tasty VS Code syntax highlighting example" />
+  <img src="https://raw.githubusercontent.com/tenphi/tasty/v3.16.0/assets/tasty-vscode-highlight.png" width="512" alt="Tasty VS Code syntax highlighting example" />
 </p>
 
 ### Glaze

package/docs/upstream/tasty/docs/ai-agents.md

@@ -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).
+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. `fill` also mixes two colors with a comma, the weight as a percentage: `'#dark 4%, #surface'`.
 
 ### `transition`
 

package/docs/upstream/tasty/docs/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/upstream/tasty/docs/react-api.md

@@ -356,7 +356,7 @@ const Badge = tasty({
   variants: {
     primary: {
       border: { '': '#white.2', pressed: '#primary-text', disabled: '#clear' },
-      fill: { '': '#white #primary', hovered: '#white #primary-text' },
+      fill: { '': '#primary', hovered: '#primary-text' },
     },
     secondary: {
       border: { '': '#primary.15', pressed: '#primary.3' },

package/docs/upstream/tasty/docs/styles.md

@@ -303,17 +303,67 @@ 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 `[base-color] [overlay-color]`
+**Syntax:** `[color]`, or two colors mixed with a comma: `[color] [weight%], [color]`
 
 | Value | Effect |
 |-------|--------|
 | `"#purple"` | Token-based background color |
 | `"#purple.10"` | Token color at 10% opacity |
-| `"#surface #primary.10"` | Background `#surface` with `#primary.10` overlay (two colors enable smooth transitions between both) |
+| `"#surface+#dark.04"` | `#dark` at 4% opacity over `#surface`, as one color — see [Compound colors](dsl.md#compound-colors) |
+| `"#dark 4%, #surface"` | `#dark` mixed into `#surface` at 4% — the same color, written as `color-mix()` arguments |
 | `"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) |
 
-When two colors are provided, the first sets the background color and the second is applied as an overlay gradient layer. This enables independent CSS transitions on each color. With `image` or `backgroundImage` on the same element, the image is layered over the overlay color in one `background-image`.
+#### Overlays
+
+An overlay over a base color is a [compound color](dsl.md#compound-colors):
+
+```jsx
+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 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.
+
+#### Mixing two colors
+
+A comma between two colors mixes them into one:
+
+```jsx
+fill: '#dark 4%, #surface'
+// → 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`:
+
+- 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'` | `'#surface+#dark.04'` |
+| `'#surface #clear'` | `'#surface'` |
+| `'#surface #accent'` (an opaque overlay) | `'#accent'` |
+| `'#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.
 
 There is no default fill color, so `fill: true` is ignored with a development warning. Use `false` for no fill.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/cookbook",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "description": "Repository-native static documentation for Astro",
   "type": "module",
   "keywords": [
@@ -68,8 +68,8 @@
   "author": "Andrey Yamanov",
   "license": "MIT",
   "dependencies": {
-    "@tenphi/docs": "0.31.0",
-    "@tenphi/renderer": "0.31.0"
+    "@tenphi/docs": "0.31.1",
+    "@tenphi/renderer": "0.31.1"
   },
   "peerDependencies": {
     "astro": "^7.3.2"