@fusion.dev/helix-docs 0.131.0 → 0.132.0

package/content/intent-reference.mdx

@@ -28,7 +28,8 @@ computed from `brand` or from the Helix design language. A theme that sets only
 |---|---|
 | `brand` | Your main brand color. Required |
 | `accent` | The second emphasis color. Defaults to the brand color. `{ from: 'brand', rotate: 180 }` gives the complementary color |
-| `neutral` | The gray ramp, which can be tinted toward the brand |
+| `background` | The page's color, `{ light, dark }`, for a page that is not pure white or pure black. The surfaces keep their contrast with it, and the grays take its tint. A page no text color can reach the contrast target on is refused |
+| `neutral` | The gray ramp, which can be tinted toward the brand. With `background`, it takes the page's tint |
 | `status` | `info`, `success`, `warning`, and `danger`. A color pins one. An object adjusts its hue while it keeps its meaning |
 | `chroma` | How saturated the palette is, independent of hue |
 | `scheme` | `'light'` or `'dark'`, for a theme that has only one mode |

package/content/metrics.mdx

@@ -58,10 +58,10 @@ either barrel. The per-component tables show what your page pays.
 | Package | Raw | Gzip | Brotli | |
 |---|---|---|---|---|
 | `@fusion.dev/helix-core` | 183,735 | 58,230 | 49,473 | The element base class, mixins, decorators, and floating positioning. |
-| `@fusion.dev/helix-headless` | 745,966 | 193,214 | 149,903 | Every headless family. The barrel entry includes all of them. |
+| `@fusion.dev/helix-headless` | 746,073 | 193,246 | 149,775 | Every headless family. The barrel entry includes all of them. |
 | `@fusion.dev/helix-icons` | 55,565 | 17,727 | 14,864 | The whole glyph set. |
 | `@fusion.dev/helix-theme` | 3,626 | 1,597 | 1,384 | The derivation engine. Most sites run it at build time, and a theme switcher runs it in the browser. |
-| `@fusion.dev/helix` | 1,291,029 | 301,797 | 220,733 | Every styled family. |
+| `@fusion.dev/helix` | 1,291,284 | 301,883 | 220,711 | Every styled family. |
 | `lit` | 15,394 | 6,118 | 5,460 | Lit itself, listed so you can subtract it from every row above. |
 
 ## Stylesheets
@@ -84,9 +84,9 @@ shows the whole cost of using the base layer on its own.
 
 **Most of your first component is the shared runtime.** The median styled family is 21,372 bytes gzipped alone, and it adds 2,254 to a page that already has Helix. The shared runtime is 89 percent of the first component, and the component itself is 11 percent. Ten typical components cost the first number once, plus nine of the added number. The two columns in the tables below let you work that out for your own components.
 
-Across the 104 styled components, the smallest is `code` at 9,928 bytes gzipped alone, and the largest is `data-table` at 63,813. Every family together is 301,797.
+Across the 104 styled components, the smallest is `code` at 9,928 bytes gzipped alone, and the largest is `data-table` at 63,813. Every family together is 301,883.
 
-No family imports a barrel. The `barrels` rule in `fusion workspace` enforces that. `@fusion.dev/helix-headless` marks every module in `dist` as having side effects, which is true of a file that calls `customElements.define`. A bundler can remove none of it. One `import { HelixHeadlessButton } from '@fusion.dev/helix-headless'` costs 193,214 bytes gzipped, whatever else the page imports. That is 9 times the median family above. All 104 styled families import the headless family they extend directly. The rule checks the shape of the import, so it applies to any package that sets `sideEffects`, whatever its name.
+No family imports a barrel. The `barrels` rule in `fusion workspace` enforces that. `@fusion.dev/helix-headless` marks every module in `dist` as having side effects, which is true of a file that calls `customElements.define`. A bundler can remove none of it. One `import { HelixHeadlessButton } from '@fusion.dev/helix-headless'` costs 193,246 bytes gzipped, whatever else the page imports. That is 9 times the median family above. All 104 styled families import the headless family they extend directly. The rule checks the shape of the import, so it applies to any package that sets `sideEffects`, whatever its name.
 
 The headless tier never had the problem, so it serves as the control. `@fusion.dev/helix-core` is `sideEffects: false`, and the median headless family is 21,928 bytes gzipped alone.
 
@@ -202,11 +202,11 @@ Structure, accessibility, state, and form participation. It has no presentation
 | `code-block` | 133,803 | 43,664 | 36,792 | 17,288 | 4,490 | 3,847 |
 | `color-input` | 151,779 | 47,718 | 40,233 | 25,691 | 5,998 | 4,976 |
 | `color-picker` | 118,224 | 37,113 | 30,494 | 19,588 | 4,689 | 3,874 |
-| `combobox` | 146,691 | 46,408 | 38,900 | 21,146 | 5,230 | 4,258 |
+| `combobox` | 146,722 | 46,415 | 38,946 | 21,177 | 5,239 | 4,380 |
 | `command` | 116,641 | 36,394 | 29,750 | 18,065 | 4,588 | 3,719 |
 | `copy-button` | 128,401 | 42,039 | 35,305 | 11,883 | 2,933 | 2,322 |
 | `data-table` | 186,894 | 56,878 | 48,021 | 57,295 | 14,485 | 11,997 |
-| `date-input` | 144,949 | 45,900 | 38,587 | 19,177 | 4,830 | 4,067 |
+| `date-input` | 144,981 | 45,912 | 38,562 | 19,209 | 4,845 | 4,000 |
 | `date-picker` | 100,136 | 32,351 | 26,467 | 9,900 | 2,714 | 2,336 |
 | `description-list` | 33,012 | 10,012 | 8,793 | 1,132 | 182 | 155 |
 | `dialog` | 36,561 | 11,114 | 9,752 | 2,717 | 765 | 587 |
@@ -215,7 +215,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | `drawer` | 35,314 | 10,755 | 9,427 | 1,761 | 466 | 446 |
 | `drilldown` | 97,002 | 31,492 | 25,596 | 5,704 | 1,481 | 1,170 |
 | `empty` | 33,506 | 10,310 | 9,098 | 956 | 233 | 140 |
-| `file-input` | 100,449 | 32,330 | 26,417 | 6,215 | 1,787 | 1,429 |
+| `file-input` | 100,500 | 32,345 | 26,387 | 6,266 | 1,803 | 1,479 |
 | `filter-input` | 157,243 | 49,107 | 41,347 | 28,023 | 6,779 | 5,542 |
 | `format-date` | 36,522 | 11,235 | 9,940 | 2,867 | 684 | 532 |
 | `graph` | 114,708 | 36,466 | 29,953 | 11,479 | 3,233 | 2,708 |
@@ -263,9 +263,9 @@ Structure, accessibility, state, and form participation. It has no presentation
 | `switch` | 41,773 | 12,384 | 10,883 | 1,650 | 497 | 338 |
 | `table` | 99,327 | 32,297 | 26,296 | 10,158 | 2,798 | 2,311 |
 | `tabs` | 41,013 | 12,219 | 10,747 | 3,925 | 834 | 594 |
-| `tag` | 88,357 | 28,573 | 23,333 | 895 | 192 | 113 |
+| `tag` | 88,370 | 28,577 | 23,348 | 908 | 197 | 161 |
 | `textarea` | 43,960 | 12,892 | 11,311 | 3,996 | 1,070 | 755 |
-| `time-input` | 158,079 | 49,121 | 41,337 | 29,016 | 7,045 | 5,755 |
+| `time-input` | 158,111 | 49,133 | 41,350 | 29,048 | 7,058 | 5,895 |
 | `time-picker` | 117,196 | 37,094 | 30,330 | 19,136 | 5,104 | 4,148 |
 | `timeline` | 88,806 | 28,574 | 23,446 | 1,809 | 380 | 300 |
 | `toast` | 92,163 | 29,709 | 24,315 | 4,078 | 951 | 820 |
@@ -308,11 +308,11 @@ The headless tier plus presentation. `bun add @fusion.dev/helix` installs this t
 | `code-block` | 150,253 | 46,548 | 39,158 | 33,717 | 7,215 | 6,126 |
 | `color-input` | 185,460 | 52,861 | 44,724 | 59,352 | 11,295 | 9,511 |
 | `color-picker` | 146,202 | 41,656 | 34,488 | 47,560 | 9,284 | 7,867 |
-| `combobox` | 161,799 | 49,039 | 41,252 | 36,231 | 7,906 | 6,471 |
+| `combobox` | 161,978 | 49,085 | 41,270 | 36,410 | 7,955 | 6,615 |
 | `command` | 127,393 | 38,493 | 31,618 | 28,803 | 6,694 | 5,583 |
 | `copy-button` | 138,405 | 43,830 | 36,878 | 21,871 | 4,664 | 3,877 |
 | `data-table` | 225,180 | 63,813 | 53,600 | 95,314 | 21,365 | 17,447 |
-| `date-input` | 160,960 | 48,876 | 41,238 | 35,177 | 7,843 | 6,678 |
+| `date-input` | 161,140 | 48,929 | 41,318 | 35,357 | 7,899 | 6,643 |
 | `date-picker` | 105,753 | 33,518 | 27,415 | 15,499 | 3,859 | 3,238 |
 | `description-list` | 35,390 | 10,586 | 9,287 | 3,502 | 768 | 694 |
 | `dialog` | 40,938 | 12,132 | 10,723 | 7,079 | 1,782 | 1,494 |
@@ -321,7 +321,7 @@ The headless tier plus presentation. `bun add @fusion.dev/helix` installs this t
 | `drawer` | 39,577 | 11,767 | 10,345 | 6,007 | 1,482 | 1,263 |
 | `drilldown` | 101,699 | 32,584 | 26,513 | 10,393 | 2,528 | 2,071 |
 | `empty` | 34,946 | 10,764 | 9,445 | 2,380 | 678 | 489 |
-| `file-input` | 111,827 | 34,613 | 28,369 | 17,594 | 4,020 | 3,366 |
+| `file-input` | 112,026 | 34,672 | 28,381 | 17,793 | 4,076 | 3,392 |
 | `filter-input` | 185,579 | 53,639 | 45,210 | 56,353 | 11,398 | 9,498 |
 | `flex` | 33,966 | 10,295 | 9,062 | 2,078 | 445 | 296 |
 | `format-date` | 37,170 | 11,382 | 10,030 | 3,497 | 860 | 608 |
@@ -373,10 +373,10 @@ The headless tier plus presentation. `bun add @fusion.dev/helix` installs this t
 | `switch` | 46,139 | 13,459 | 11,778 | 6,001 | 1,568 | 1,279 |
 | `table` | 104,921 | 33,482 | 27,341 | 15,746 | 3,981 | 3,421 |
 | `tabs` | 47,249 | 13,492 | 11,867 | 10,154 | 2,155 | 1,927 |
-| `tag` | 91,560 | 29,474 | 24,113 | 4,083 | 1,013 | 827 |
+| `tag` | 91,721 | 29,528 | 24,083 | 4,244 | 1,063 | 870 |
 | `text` | 36,086 | 10,644 | 9,325 | 4,200 | 880 | 692 |
 | `textarea` | 47,395 | 13,733 | 12,034 | 7,418 | 1,928 | 1,528 |
-| `time-input` | 179,569 | 52,698 | 44,403 | 50,488 | 10,697 | 8,990 |
+| `time-input` | 179,749 | 52,754 | 44,471 | 50,668 | 10,753 | 8,930 |
 | `time-picker` | 128,924 | 39,284 | 32,256 | 30,852 | 7,322 | 6,068 |
 | `timeline` | 92,119 | 29,344 | 24,098 | 5,110 | 1,130 | 917 |
 | `toast` | 99,696 | 31,426 | 25,725 | 11,599 | 2,601 | 2,189 |
@@ -401,11 +401,11 @@ stripped column shows the bytes we removed.
 | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
 |---|---|---|---|---|
 | `@fusion.dev/helix-core` | 1,192,742 | 171 | 267,144 | `@floating-ui/dom`, `@fusion.dev/helix-icons` |
-| `@fusion.dev/helix-headless` | 13,506,127 | 510 | 1,077,660 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
+| `@fusion.dev/helix-headless` | 13,508,620 | 510 | 1,077,666 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
 | `@fusion.dev/helix-icons` | 150,162 | 21 | 50,346 | `svgo` |
 | `@fusion.dev/helix-styles` | 102,155 | 6 | 0 | none |
-| `@fusion.dev/helix-theme` | 500,416 | 8 | 5,191 | none |
-| `@fusion.dev/helix` | 14,618,004 | 876 | 373,795 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
+| `@fusion.dev/helix-theme` | 514,288 | 8 | 5,300 | none |
+| `@fusion.dev/helix` | 14,621,013 | 876 | 373,802 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
 
 ## Not measured yet
 

package/content/theme-builder.mdx

@@ -15,53 +15,60 @@ a theme from a few inputs, and the theme builder shows you the result.
 
 You enter the same inputs that `derive()` takes:
 
-- a brand color
-- a chroma ceiling
-- a radius
-- a density
-- a contrast target
-- a motion character
-
-The theme builder runs the full derivation. It shows you every token, and the
-components drawn with them.
-
-It shows light and dark at the same time. `[data-color-mode]` works on any
-element, so the two previews are two subtrees of one document. See
-[Color modes](./color-modes).
-
-## The contrast column
-
-The contrast column lists every color pair Helix computed. Each pair shows its
-ratio, measured against the background it is painted on. A pair has one of
-three states:
-
-- **Met.** The pair reaches the target.
-- **Unverifiable.** The background is translucent, so there is no known color
-  to measure against. The pair neither passes nor fails. This is the cost of a
-  translucent material, and the theme builder reports it.
-- **Pinned.** You set the color yourself. The engine did not compute it, so its
-  contrast is not guaranteed.
-
-A column of `unverifiable` pairs means your theme makes a trade. The column lets
-you see that you made it.
-
-## What the theme builder exports
-
-The theme builder gives you the token block as CSS, to paste into your own
+- **Color:** the brand, the color scheme, the contrast target, the saturation,
+  the accent angle, and the page's color in light and in dark
+- **Shape and type:** the density, the corner radius, the three faces, the body
+  size, and the type scale
+- **Status:** how far the status colors follow the palette, and how far their
+  hues may move
+- **Motion, separation, and material:** the motion character, how surfaces are
+  set apart, and how floating surfaces are blurred and see-through
+
+The theme builder runs the full derivation on every change. It shows a page
+drawn with the theme, and the stylesheet the theme generates beside it.
+
+The Color scheme field picks which half you see: light, dark, or the site's own
+mode. See [Color modes](./color-modes).
+
+## A page of your own color
+
+The Light page and Dark page fields give the page a color, such as a warm cream
+or a deep teal. They start at pure white and pure black, the page Helix draws
+without one. The surfaces keep the contrast with the page they keep with white
+or black, the grays take its tint, and every text color is solved against it. A
+page that no text color can reach the contrast target on is left out of the
+preview, and a caption under the fields says so.
+
+## The audit
+
+The audit lists every color pair Helix computed. Each pair shows its ratio,
+measured against the background it is painted on, and either passes or fails
+its target. Its three tabs are:
+
+- **Contrast.** The pairs that fail, or a line saying that every pair passes.
+- **Collisions.** Colors too close to each other to tell apart, such as the
+  primary color and a status color.
+- **Unverifiable.** Pairs whose background is translucent, so there is no known
+  color to measure against. This is the cost of a translucent material, and
+  the theme builder reports it.
+
+## What the theme builder gives you
+
+The generated stylesheet is the token block as CSS, to paste into your own
 stylesheet:
 
 ```css
-:root {
-  --helix-color-primary: oklch(…);
+[data-theme="preview"] {
+  --helix-color-background: #f7f2eb;
   …
 }
 ```
 
-It also gives you the intent object, to keep in your repository and derive the
-theme from again:
+The page's link holds every input you changed, so a link is the theme. To derive
+the theme in your own build, write the same inputs as an intent object:
 
 ```ts
-export const theme = { brand: '#2563eb', chroma: { ceiling: 0.1 }, radius: 2 }
+export const theme = { background: { light: '#f7f2eb' }, brand: '#ff6200' }
 ```
 
 **Keep the intent object in your repository.** The tokens are the output of a

package/dist/sources.generated.js

@@ -2309,7 +2309,8 @@ computed from \`brand\` or from the Helix design language. A theme that sets onl
 |---|---|
 | \`brand\` | Your main brand color. Required |
 | \`accent\` | The second emphasis color. Defaults to the brand color. \`{ from: 'brand', rotate: 180 }\` gives the complementary color |
-| \`neutral\` | The gray ramp, which can be tinted toward the brand |
+| \`background\` | The page's color, \`{ light, dark }\`, for a page that is not pure white or pure black. The surfaces keep their contrast with it, and the grays take its tint. A page no text color can reach the contrast target on is refused |
+| \`neutral\` | The gray ramp, which can be tinted toward the brand. With \`background\`, it takes the page's tint |
 | \`status\` | \`info\`, \`success\`, \`warning\`, and \`danger\`. A color pins one. An object adjusts its hue while it keeps its meaning |
 | \`chroma\` | How saturated the palette is, independent of hue |
 | \`scheme\` | \`'light'\` or \`'dark'\`, for a theme that has only one mode |
@@ -3345,10 +3346,10 @@ either barrel. The per-component tables show what your page pays.
 | Package | Raw | Gzip | Brotli | |
 |---|---|---|---|---|
 | \`@fusion.dev/helix-core\` | 183,735 | 58,230 | 49,473 | The element base class, mixins, decorators, and floating positioning. |
-| \`@fusion.dev/helix-headless\` | 745,966 | 193,214 | 149,903 | Every headless family. The barrel entry includes all of them. |
+| \`@fusion.dev/helix-headless\` | 746,073 | 193,246 | 149,775 | Every headless family. The barrel entry includes all of them. |
 | \`@fusion.dev/helix-icons\` | 55,565 | 17,727 | 14,864 | The whole glyph set. |
 | \`@fusion.dev/helix-theme\` | 3,626 | 1,597 | 1,384 | The derivation engine. Most sites run it at build time, and a theme switcher runs it in the browser. |
-| \`@fusion.dev/helix\` | 1,291,029 | 301,797 | 220,733 | Every styled family. |
+| \`@fusion.dev/helix\` | 1,291,284 | 301,883 | 220,711 | Every styled family. |
 | \`lit\` | 15,394 | 6,118 | 5,460 | Lit itself, listed so you can subtract it from every row above. |
 
 ## Stylesheets
@@ -3371,9 +3372,9 @@ shows the whole cost of using the base layer on its own.
 
 **Most of your first component is the shared runtime.** The median styled family is 21,372 bytes gzipped alone, and it adds 2,254 to a page that already has Helix. The shared runtime is 89 percent of the first component, and the component itself is 11 percent. Ten typical components cost the first number once, plus nine of the added number. The two columns in the tables below let you work that out for your own components.
 
-Across the 104 styled components, the smallest is \`code\` at 9,928 bytes gzipped alone, and the largest is \`data-table\` at 63,813. Every family together is 301,797.
+Across the 104 styled components, the smallest is \`code\` at 9,928 bytes gzipped alone, and the largest is \`data-table\` at 63,813. Every family together is 301,883.
 
-No family imports a barrel. The \`barrels\` rule in \`fusion workspace\` enforces that. \`@fusion.dev/helix-headless\` marks every module in \`dist\` as having side effects, which is true of a file that calls \`customElements.define\`. A bundler can remove none of it. One \`import { HelixHeadlessButton } from '@fusion.dev/helix-headless'\` costs 193,214 bytes gzipped, whatever else the page imports. That is 9 times the median family above. All 104 styled families import the headless family they extend directly. The rule checks the shape of the import, so it applies to any package that sets \`sideEffects\`, whatever its name.
+No family imports a barrel. The \`barrels\` rule in \`fusion workspace\` enforces that. \`@fusion.dev/helix-headless\` marks every module in \`dist\` as having side effects, which is true of a file that calls \`customElements.define\`. A bundler can remove none of it. One \`import { HelixHeadlessButton } from '@fusion.dev/helix-headless'\` costs 193,246 bytes gzipped, whatever else the page imports. That is 9 times the median family above. All 104 styled families import the headless family they extend directly. The rule checks the shape of the import, so it applies to any package that sets \`sideEffects\`, whatever its name.
 
 The headless tier never had the problem, so it serves as the control. \`@fusion.dev/helix-core\` is \`sideEffects: false\`, and the median headless family is 21,928 bytes gzipped alone.
 
@@ -3489,11 +3490,11 @@ Structure, accessibility, state, and form participation. It has no presentation
 | \`code-block\` | 133,803 | 43,664 | 36,792 | 17,288 | 4,490 | 3,847 |
 | \`color-input\` | 151,779 | 47,718 | 40,233 | 25,691 | 5,998 | 4,976 |
 | \`color-picker\` | 118,224 | 37,113 | 30,494 | 19,588 | 4,689 | 3,874 |
-| \`combobox\` | 146,691 | 46,408 | 38,900 | 21,146 | 5,230 | 4,258 |
+| \`combobox\` | 146,722 | 46,415 | 38,946 | 21,177 | 5,239 | 4,380 |
 | \`command\` | 116,641 | 36,394 | 29,750 | 18,065 | 4,588 | 3,719 |
 | \`copy-button\` | 128,401 | 42,039 | 35,305 | 11,883 | 2,933 | 2,322 |
 | \`data-table\` | 186,894 | 56,878 | 48,021 | 57,295 | 14,485 | 11,997 |
-| \`date-input\` | 144,949 | 45,900 | 38,587 | 19,177 | 4,830 | 4,067 |
+| \`date-input\` | 144,981 | 45,912 | 38,562 | 19,209 | 4,845 | 4,000 |
 | \`date-picker\` | 100,136 | 32,351 | 26,467 | 9,900 | 2,714 | 2,336 |
 | \`description-list\` | 33,012 | 10,012 | 8,793 | 1,132 | 182 | 155 |
 | \`dialog\` | 36,561 | 11,114 | 9,752 | 2,717 | 765 | 587 |
@@ -3502,7 +3503,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | \`drawer\` | 35,314 | 10,755 | 9,427 | 1,761 | 466 | 446 |
 | \`drilldown\` | 97,002 | 31,492 | 25,596 | 5,704 | 1,481 | 1,170 |
 | \`empty\` | 33,506 | 10,310 | 9,098 | 956 | 233 | 140 |
-| \`file-input\` | 100,449 | 32,330 | 26,417 | 6,215 | 1,787 | 1,429 |
+| \`file-input\` | 100,500 | 32,345 | 26,387 | 6,266 | 1,803 | 1,479 |
 | \`filter-input\` | 157,243 | 49,107 | 41,347 | 28,023 | 6,779 | 5,542 |
 | \`format-date\` | 36,522 | 11,235 | 9,940 | 2,867 | 684 | 532 |
 | \`graph\` | 114,708 | 36,466 | 29,953 | 11,479 | 3,233 | 2,708 |
@@ -3550,9 +3551,9 @@ Structure, accessibility, state, and form participation. It has no presentation
 | \`switch\` | 41,773 | 12,384 | 10,883 | 1,650 | 497 | 338 |
 | \`table\` | 99,327 | 32,297 | 26,296 | 10,158 | 2,798 | 2,311 |
 | \`tabs\` | 41,013 | 12,219 | 10,747 | 3,925 | 834 | 594 |
-| \`tag\` | 88,357 | 28,573 | 23,333 | 895 | 192 | 113 |
+| \`tag\` | 88,370 | 28,577 | 23,348 | 908 | 197 | 161 |
 | \`textarea\` | 43,960 | 12,892 | 11,311 | 3,996 | 1,070 | 755 |
-| \`time-input\` | 158,079 | 49,121 | 41,337 | 29,016 | 7,045 | 5,755 |
+| \`time-input\` | 158,111 | 49,133 | 41,350 | 29,048 | 7,058 | 5,895 |
 | \`time-picker\` | 117,196 | 37,094 | 30,330 | 19,136 | 5,104 | 4,148 |
 | \`timeline\` | 88,806 | 28,574 | 23,446 | 1,809 | 380 | 300 |
 | \`toast\` | 92,163 | 29,709 | 24,315 | 4,078 | 951 | 820 |
@@ -3595,11 +3596,11 @@ The headless tier plus presentation. \`bun add @fusion.dev/helix\` installs this
 | \`code-block\` | 150,253 | 46,548 | 39,158 | 33,717 | 7,215 | 6,126 |
 | \`color-input\` | 185,460 | 52,861 | 44,724 | 59,352 | 11,295 | 9,511 |
 | \`color-picker\` | 146,202 | 41,656 | 34,488 | 47,560 | 9,284 | 7,867 |
-| \`combobox\` | 161,799 | 49,039 | 41,252 | 36,231 | 7,906 | 6,471 |
+| \`combobox\` | 161,978 | 49,085 | 41,270 | 36,410 | 7,955 | 6,615 |
 | \`command\` | 127,393 | 38,493 | 31,618 | 28,803 | 6,694 | 5,583 |
 | \`copy-button\` | 138,405 | 43,830 | 36,878 | 21,871 | 4,664 | 3,877 |
 | \`data-table\` | 225,180 | 63,813 | 53,600 | 95,314 | 21,365 | 17,447 |
-| \`date-input\` | 160,960 | 48,876 | 41,238 | 35,177 | 7,843 | 6,678 |
+| \`date-input\` | 161,140 | 48,929 | 41,318 | 35,357 | 7,899 | 6,643 |
 | \`date-picker\` | 105,753 | 33,518 | 27,415 | 15,499 | 3,859 | 3,238 |
 | \`description-list\` | 35,390 | 10,586 | 9,287 | 3,502 | 768 | 694 |
 | \`dialog\` | 40,938 | 12,132 | 10,723 | 7,079 | 1,782 | 1,494 |
@@ -3608,7 +3609,7 @@ The headless tier plus presentation. \`bun add @fusion.dev/helix\` installs this
 | \`drawer\` | 39,577 | 11,767 | 10,345 | 6,007 | 1,482 | 1,263 |
 | \`drilldown\` | 101,699 | 32,584 | 26,513 | 10,393 | 2,528 | 2,071 |
 | \`empty\` | 34,946 | 10,764 | 9,445 | 2,380 | 678 | 489 |
-| \`file-input\` | 111,827 | 34,613 | 28,369 | 17,594 | 4,020 | 3,366 |
+| \`file-input\` | 112,026 | 34,672 | 28,381 | 17,793 | 4,076 | 3,392 |
 | \`filter-input\` | 185,579 | 53,639 | 45,210 | 56,353 | 11,398 | 9,498 |
 | \`flex\` | 33,966 | 10,295 | 9,062 | 2,078 | 445 | 296 |
 | \`format-date\` | 37,170 | 11,382 | 10,030 | 3,497 | 860 | 608 |
@@ -3660,10 +3661,10 @@ The headless tier plus presentation. \`bun add @fusion.dev/helix\` installs this
 | \`switch\` | 46,139 | 13,459 | 11,778 | 6,001 | 1,568 | 1,279 |
 | \`table\` | 104,921 | 33,482 | 27,341 | 15,746 | 3,981 | 3,421 |
 | \`tabs\` | 47,249 | 13,492 | 11,867 | 10,154 | 2,155 | 1,927 |
-| \`tag\` | 91,560 | 29,474 | 24,113 | 4,083 | 1,013 | 827 |
+| \`tag\` | 91,721 | 29,528 | 24,083 | 4,244 | 1,063 | 870 |
 | \`text\` | 36,086 | 10,644 | 9,325 | 4,200 | 880 | 692 |
 | \`textarea\` | 47,395 | 13,733 | 12,034 | 7,418 | 1,928 | 1,528 |
-| \`time-input\` | 179,569 | 52,698 | 44,403 | 50,488 | 10,697 | 8,990 |
+| \`time-input\` | 179,749 | 52,754 | 44,471 | 50,668 | 10,753 | 8,930 |
 | \`time-picker\` | 128,924 | 39,284 | 32,256 | 30,852 | 7,322 | 6,068 |
 | \`timeline\` | 92,119 | 29,344 | 24,098 | 5,110 | 1,130 | 917 |
 | \`toast\` | 99,696 | 31,426 | 25,725 | 11,599 | 2,601 | 2,189 |
@@ -3688,11 +3689,11 @@ stripped column shows the bytes we removed.
 | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
 |---|---|---|---|---|
 | \`@fusion.dev/helix-core\` | 1,192,742 | 171 | 267,144 | \`@floating-ui/dom\`, \`@fusion.dev/helix-icons\` |
-| \`@fusion.dev/helix-headless\` | 13,506,127 | 510 | 1,077,660 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
+| \`@fusion.dev/helix-headless\` | 13,508,620 | 510 | 1,077,666 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
 | \`@fusion.dev/helix-icons\` | 150,162 | 21 | 50,346 | \`svgo\` |
 | \`@fusion.dev/helix-styles\` | 102,155 | 6 | 0 | none |
-| \`@fusion.dev/helix-theme\` | 500,416 | 8 | 5,191 | none |
-| \`@fusion.dev/helix\` | 14,618,004 | 876 | 373,795 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
+| \`@fusion.dev/helix-theme\` | 514,288 | 8 | 5,300 | none |
+| \`@fusion.dev/helix\` | 14,621,013 | 876 | 373,802 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
 
 ## Not measured yet
 
@@ -5584,53 +5585,60 @@ a theme from a few inputs, and the theme builder shows you the result.
 
 You enter the same inputs that \`derive()\` takes:
 
-- a brand color
-- a chroma ceiling
-- a radius
-- a density
-- a contrast target
-- a motion character
+- **Color:** the brand, the color scheme, the contrast target, the saturation,
+  the accent angle, and the page's color in light and in dark
+- **Shape and type:** the density, the corner radius, the three faces, the body
+  size, and the type scale
+- **Status:** how far the status colors follow the palette, and how far their
+  hues may move
+- **Motion, separation, and material:** the motion character, how surfaces are
+  set apart, and how floating surfaces are blurred and see-through
 
-The theme builder runs the full derivation. It shows you every token, and the
-components drawn with them.
+The theme builder runs the full derivation on every change. It shows a page
+drawn with the theme, and the stylesheet the theme generates beside it.
 
-It shows light and dark at the same time. \`[data-color-mode]\` works on any
-element, so the two previews are two subtrees of one document. See
-[Color modes](./color-modes).
+The Color scheme field picks which half you see: light, dark, or the site's own
+mode. See [Color modes](./color-modes).
 
-## The contrast column
+## A page of your own color
 
-The contrast column lists every color pair Helix computed. Each pair shows its
-ratio, measured against the background it is painted on. A pair has one of
-three states:
+The Light page and Dark page fields give the page a color, such as a warm cream
+or a deep teal. They start at pure white and pure black, the page Helix draws
+without one. The surfaces keep the contrast with the page they keep with white
+or black, the grays take its tint, and every text color is solved against it. A
+page that no text color can reach the contrast target on is left out of the
+preview, and a caption under the fields says so.
 
-- **Met.** The pair reaches the target.
-- **Unverifiable.** The background is translucent, so there is no known color
-  to measure against. The pair neither passes nor fails. This is the cost of a
-  translucent material, and the theme builder reports it.
-- **Pinned.** You set the color yourself. The engine did not compute it, so its
-  contrast is not guaranteed.
+## The audit
 
-A column of \`unverifiable\` pairs means your theme makes a trade. The column lets
-you see that you made it.
+The audit lists every color pair Helix computed. Each pair shows its ratio,
+measured against the background it is painted on, and either passes or fails
+its target. Its three tabs are:
 
-## What the theme builder exports
+- **Contrast.** The pairs that fail, or a line saying that every pair passes.
+- **Collisions.** Colors too close to each other to tell apart, such as the
+  primary color and a status color.
+- **Unverifiable.** Pairs whose background is translucent, so there is no known
+  color to measure against. This is the cost of a translucent material, and
+  the theme builder reports it.
 
-The theme builder gives you the token block as CSS, to paste into your own
+## What the theme builder gives you
+
+The generated stylesheet is the token block as CSS, to paste into your own
 stylesheet:
 
 \`\`\`css
-:root {
-  --helix-color-primary: oklch(…);
+[data-theme="preview"] {
+  --helix-color-background: #f7f2eb;
   …
 }
 \`\`\`
 
-It also gives you the intent object, to keep in your repository and derive the
-theme from again:
+The page's link holds every input you changed, so a link is the theme. To derive
+the theme in your own build, write the same inputs as an intent object:
 
 \`\`\`ts
-export const theme = { brand: '#2563eb', chroma: { ceiling: 0.1 }, radius: 2 }
+export const theme = { background: { light: '#f7f2eb' }, brand: '#ff6200' }
 \`\`\`
 
 **Keep the intent object in your repository.** The tokens are the output of a

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-docs",
   "description": "Versioned documentation content and registry for Helix.",
-  "version": "0.131.0",
+  "version": "0.132.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -36,14 +36,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix": "0.131.0",
-    "@fusion.dev/helix-cem": "0.131.0",
-    "@fusion.dev/helix-headless": "0.131.0",
-    "@fusion.dev/helix-icons": "0.131.0",
-    "@fusion.dev/helix-map": "0.131.0",
-    "@fusion.dev/helix-styles": "0.131.0",
-    "@fusion.dev/helix-testing": "0.131.0",
-    "@fusion.dev/helix-theme": "0.131.0",
+    "@fusion.dev/helix": "0.132.0",
+    "@fusion.dev/helix-cem": "0.132.0",
+    "@fusion.dev/helix-headless": "0.132.0",
+    "@fusion.dev/helix-icons": "0.132.0",
+    "@fusion.dev/helix-map": "0.132.0",
+    "@fusion.dev/helix-styles": "0.132.0",
+    "@fusion.dev/helix-testing": "0.132.0",
+    "@fusion.dev/helix-theme": "0.132.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "lit": "^3.2.1",
     "playwright": "^1.62.1"