@fusion.dev/helix-docs 0.132.0 → 0.133.0

package/content/graphs.mdx

@@ -206,6 +206,25 @@ frame.addEventListener('helix-graph-filter', (event) => {
 The legend is drawn where the notes have two groups or more. On a frame
 narrower than 40rem it is one row, which scrolls.
 
+## Find groups in the links
+
+Notes without a `group` are drawn in one color. Where your data has no groups,
+`groupByCommunity` finds them in the links: notes that link mostly to each other
+become one group, named after its most linked note. Hand its result to the frame,
+and the drawing colors the groups and the legend names them:
+
+```ts
+import { groupByCommunity } from '@fusion.dev/helix-graph'
+
+frame.nodes = groupByCommunity(notes, links)
+frame.links = links
+```
+
+A note that has a `group` keeps it. Communities of fewer than three notes share
+one group, named `Other`. Set `fewest` and `rest` to change either. The same
+notes and links give the same groups every time. On 20,000 notes it takes about
+65 milliseconds.
+
 ## Select a note
 
 Pressing a note selects it, and pressing where no note is clears the selection.

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` | 746,073 | 193,246 | 149,775 | Every headless family. The barrel entry includes all of them. |
+| `@fusion.dev/helix-headless` | 746,304 | 193,314 | 149,776 | 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,284 | 301,883 | 220,711 | Every styled family. |
+| `@fusion.dev/helix` | 1,291,679 | 302,007 | 220,657 | Every styled family. |
 | `lit` | 15,394 | 6,118 | 5,460 | Lit itself, listed so you can subtract it from every row above. |
 
 ## Stylesheets
@@ -84,11 +84,11 @@ 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,883.
+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 302,007.
 
-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.
+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,314 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.
+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,942 bytes gzipped alone.
 
 ## Compared with other systems
 
@@ -100,7 +100,7 @@ The table has no whole-library row. That row would compare how many components e
 
 | Component | System | Raw | Gzip | Brotli |
 |---|---|---|---|---|
-| `button` | **Helix** | 43,806 | 12,554 | 11,023 |
+| `button` | **Helix** | 43,982 | 12,620 | 11,082 |
 | | Carbon | 133,058 | 20,959 | 17,685 |
 | | Material Web | 47,060 | 14,173 | 12,591 |
 | | Shoelace | 62,628 | 18,287 | 15,805 |
@@ -189,7 +189,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | `bar-chart` | 81,076 | 26,555 | 23,488 | 12,644 | 3,701 | 3,035 |
 | `blockquote` | 33,053 | 10,175 | 8,938 | 774 | 176 | 128 |
 | `breadcrumbs` | 88,957 | 28,651 | 23,520 | 1,965 | 451 | 379 |
-| `button` | 37,713 | 11,437 | 10,046 | 3,182 | 812 | 670 |
+| `button` | 37,725 | 11,440 | 10,034 | 3,194 | 814 | 619 |
 | `button-group` | 32,909 | 10,061 | 8,843 | 661 | 137 | 34 |
 | `callout` | 88,077 | 28,508 | 23,396 | 914 | 233 | 168 |
 | `canvas` | 94,126 | 27,730 | 24,309 | 50,034 | 14,930 | 12,613 |
@@ -199,12 +199,12 @@ Structure, accessibility, state, and form participation. It has no presentation
 | `checkbox` | 42,424 | 12,472 | 10,962 | 2,703 | 748 | 514 |
 | `checkbox-group` | 45,548 | 13,159 | 11,549 | 5,307 | 1,316 | 1,017 |
 | `code` | 31,528 | 9,644 | 8,470 | 451 | 77 | -1 |
-| `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 |
+| `code-block` | 133,832 | 43,676 | 36,796 | 17,317 | 4,502 | 3,798 |
+| `color-input` | 151,907 | 47,747 | 40,241 | 25,819 | 6,027 | 5,016 |
+| `color-picker` | 118,278 | 37,129 | 30,542 | 19,642 | 4,706 | 4,026 |
 | `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 |
+| `copy-button` | 128,413 | 42,045 | 35,300 | 11,895 | 2,938 | 2,421 |
 | `data-table` | 186,894 | 56,878 | 48,021 | 57,295 | 14,485 | 11,997 |
 | `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 |
@@ -221,7 +221,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | `graph` | 114,708 | 36,466 | 29,953 | 11,479 | 3,233 | 2,708 |
 | `heatmap` | 78,430 | 25,372 | 22,403 | 10,872 | 2,982 | 2,366 |
 | `icon` | 87,644 | 28,324 | 23,220 | 1,018 | 245 | 126 |
-| `icon-button` | 38,112 | 11,466 | 10,070 | 3,581 | 852 | 646 |
+| `icon-button` | 38,124 | 11,469 | 10,075 | 3,593 | 854 | 670 |
 | `image` | 35,082 | 10,613 | 9,334 | 3,156 | 809 | 657 |
 | `input` | 99,537 | 31,813 | 25,941 | 4,745 | 1,288 | 938 |
 | `kbd` | 34,863 | 10,848 | 9,529 | 2,976 | 922 | 855 |
@@ -238,7 +238,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | `navigation` | 34,843 | 10,709 | 9,395 | 1,361 | 301 | 226 |
 | `notifications` | 104,181 | 33,078 | 26,996 | 11,383 | 2,637 | 2,263 |
 | `number-input` | 102,465 | 32,630 | 26,674 | 7,670 | 2,010 | 1,515 |
-| `object-inspector` | 141,502 | 46,264 | 38,895 | 19,550 | 5,225 | 4,370 |
+| `object-inspector` | 141,531 | 46,276 | 38,905 | 19,579 | 5,236 | 4,304 |
 | `option` | 35,204 | 10,629 | 9,352 | 2,958 | 646 | 543 |
 | `outline` | 38,267 | 11,902 | 10,469 | 4,628 | 1,320 | 1,075 |
 | `pagination` | 150,818 | 47,121 | 39,598 | 27,821 | 6,525 | 5,229 |
@@ -259,7 +259,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | `speed-dial` | 118,638 | 39,539 | 33,189 | 3,743 | 915 | 719 |
 | `splitter` | 42,714 | 12,692 | 11,214 | 10,282 | 2,596 | 2,223 |
 | `stat` | 33,397 | 10,120 | 8,906 | 1,148 | 193 | 173 |
-| `steps` | 97,187 | 31,106 | 25,374 | 6,264 | 1,479 | 1,106 |
+| `steps` | 97,217 | 31,122 | 25,454 | 6,294 | 1,492 | 1,245 |
 | `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 |
@@ -272,7 +272,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | `toggle` | 45,957 | 13,403 | 11,795 | 3,342 | 816 | 583 |
 | `toolbar` | 35,003 | 10,814 | 9,482 | 2,624 | 717 | 552 |
 | `tooltip` | 64,751 | 21,220 | 18,782 | 6,369 | 1,715 | 1,350 |
-| `tour` | 70,570 | 22,635 | 19,952 | 11,032 | 2,719 | 2,232 |
+| `tour` | 70,633 | 22,663 | 19,991 | 11,095 | 2,741 | 2,236 |
 | `tree` | 99,021 | 31,924 | 25,969 | 7,223 | 1,882 | 1,539 |
 | `trend` | 87,684 | 28,370 | 23,291 | 1,056 | 289 | 243 |
 | `video` | 155,346 | 48,784 | 41,231 | 32,520 | 7,642 | 6,463 |
@@ -295,7 +295,7 @@ The headless tier plus presentation. `bun add @fusion.dev/helix` installs this t
 | `bar-chart` | 93,880 | 29,107 | 25,756 | 25,425 | 6,313 | 5,329 |
 | `blockquote` | 34,209 | 10,468 | 9,196 | 1,914 | 467 | 315 |
 | `breadcrumbs` | 92,523 | 29,466 | 24,178 | 5,518 | 1,244 | 1,129 |
-| `button` | 43,806 | 12,554 | 11,023 | 9,257 | 1,937 | 1,505 |
+| `button` | 43,982 | 12,620 | 11,082 | 9,433 | 1,995 | 1,639 |
 | `button-group` | 34,585 | 10,450 | 9,174 | 2,320 | 528 | 375 |
 | `callout` | 90,078 | 29,063 | 23,826 | 2,899 | 756 | 687 |
 | `canvas` | 114,431 | 31,475 | 27,500 | 70,328 | 18,720 | 15,791 |
@@ -305,12 +305,12 @@ The headless tier plus presentation. `bun add @fusion.dev/helix` installs this t
 | `checkbox` | 49,050 | 13,927 | 12,237 | 9,313 | 2,208 | 1,876 |
 | `checkbox-group` | 47,829 | 13,751 | 12,052 | 7,574 | 1,903 | 1,474 |
 | `code` | 32,605 | 9,928 | 8,729 | 1,511 | 377 | 380 |
-| `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 |
+| `code-block` | 150,282 | 46,558 | 39,136 | 33,746 | 7,230 | 6,118 |
+| `color-input` | 185,752 | 52,943 | 44,844 | 59,644 | 11,374 | 9,743 |
+| `color-picker` | 146,420 | 41,723 | 34,558 | 47,778 | 9,346 | 8,013 |
 | `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 |
+| `copy-button` | 138,417 | 43,836 | 36,896 | 21,883 | 4,669 | 3,882 |
 | `data-table` | 225,180 | 63,813 | 53,600 | 95,314 | 21,365 | 17,447 |
 | `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 |
@@ -329,7 +329,7 @@ The headless tier plus presentation. `bun add @fusion.dev/helix` installs this t
 | `grid` | 34,559 | 10,478 | 9,220 | 2,667 | 630 | 522 |
 | `heatmap` | 85,228 | 26,779 | 23,661 | 17,648 | 4,434 | 3,682 |
 | `icon` | 88,350 | 28,509 | 23,354 | 1,707 | 422 | 288 |
-| `icon-button` | 44,127 | 12,484 | 10,977 | 9,582 | 1,854 | 1,563 |
+| `icon-button` | 44,139 | 12,487 | 10,941 | 9,594 | 1,856 | 1,555 |
 | `image` | 36,784 | 11,092 | 9,750 | 4,840 | 1,285 | 1,066 |
 | `input` | 105,902 | 33,263 | 27,153 | 11,104 | 2,685 | 2,139 |
 | `kbd` | 36,275 | 11,305 | 9,919 | 4,373 | 1,361 | 1,190 |
@@ -346,7 +346,7 @@ The headless tier plus presentation. `bun add @fusion.dev/helix` installs this t
 | `navigation` | 36,224 | 11,110 | 9,735 | 2,726 | 713 | 628 |
 | `notifications` | 117,292 | 35,506 | 29,125 | 24,486 | 5,059 | 4,265 |
 | `number-input` | 107,345 | 33,815 | 27,626 | 12,539 | 3,150 | 2,570 |
-| `object-inspector` | 155,139 | 48,519 | 40,992 | 33,167 | 7,563 | 6,311 |
+| `object-inspector` | 155,168 | 48,532 | 40,983 | 33,196 | 7,574 | 6,373 |
 | `option` | 38,458 | 11,533 | 10,163 | 6,201 | 1,574 | 1,257 |
 | `orb` | 43,162 | 13,930 | 12,278 | 8,623 | 3,224 | 2,742 |
 | `outline` | 42,007 | 12,688 | 11,173 | 8,351 | 2,127 | 1,739 |
@@ -369,7 +369,7 @@ The headless tier plus presentation. `bun add @fusion.dev/helix` installs this t
 | `speed-dial` | 126,270 | 41,059 | 34,489 | 11,356 | 2,382 | 1,920 |
 | `splitter` | 48,786 | 13,681 | 12,145 | 16,336 | 3,627 | 3,136 |
 | `stat` | 36,822 | 10,836 | 9,555 | 4,565 | 915 | 730 |
-| `steps` | 110,828 | 33,587 | 27,521 | 19,894 | 3,918 | 3,257 |
+| `steps` | 111,022 | 33,661 | 27,603 | 20,088 | 3,981 | 3,398 |
 | `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 |
@@ -383,7 +383,7 @@ The headless tier plus presentation. `bun add @fusion.dev/helix` installs this t
 | `toggle` | 51,152 | 14,607 | 12,844 | 8,525 | 2,066 | 1,725 |
 | `toolbar` | 36,295 | 11,108 | 9,755 | 3,899 | 1,022 | 824 |
 | `tooltip` | 67,829 | 21,974 | 19,470 | 9,429 | 2,451 | 2,085 |
-| `tour` | 80,121 | 24,220 | 21,448 | 20,565 | 4,378 | 3,738 |
+| `tour` | 80,348 | 24,304 | 21,526 | 20,792 | 4,456 | 3,750 |
 | `tree` | 104,871 | 33,337 | 27,201 | 13,069 | 3,306 | 2,728 |
 | `trend` | 90,903 | 29,129 | 23,898 | 4,271 | 985 | 862 |
 | `video` | 174,764 | 52,259 | 44,284 | 51,918 | 11,165 | 9,570 |
@@ -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,508,620 | 510 | 1,077,666 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
+| `@fusion.dev/helix-headless` | 13,515,038 | 510 | 1,077,677 | `@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` | 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` |
+| `@fusion.dev/helix` | 14,628,121 | 876 | 373,810 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
 
 ## Not measured yet
 

package/content/theme-builder.mdx

@@ -39,6 +39,11 @@ 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.
 
+**Color the figures band** gives one section of the Marketing site layout a
+color of its own, as its own theme. The band is dark or light by whichever text
+reads better on it, and its block follows the page's in the generated
+stylesheet. See [Color one section](./theming#color-one-section).
+
 ## The audit
 
 The audit lists every color pair Helix computed. Each pair shows its ratio,

package/content/theming.mdx

@@ -110,6 +110,39 @@ console.log(css[':root'])
 A value that is not a color and still changes with the mode, such as the edge
 of a floating surface, is set by rules after the block, one for each mode.
 
+## Color one section
+
+A section in a color of its own, such as a deep teal band on a cream page, is a
+theme of its own. Derive it from the same intent, with the section's color as
+its page, under a selector for the section:
+
+```ts
+const band = engine.derive(
+  { ...intent, background: { dark: '#0b2a33' }, scheme: 'dark' },
+  ['[data-band]'],
+)
+```
+
+Choose the scheme the color needs: `dark` for a color light text reads on, and
+`light` for one dark text reads on. A color no text can reach the contrast
+target on is refused, as a page is.
+
+Mark the section so the stylesheet derives its own colors there from the
+section's seeds, in the section's mode, and paint it with its page color:
+
+```html
+<section data-band data-color-mode="dark" data-helix-theme>…</section>
+```
+
+```css
+[data-band] {
+  background-color: var(--helix-color-background);
+  color: var(--helix-color-foreground);
+}
+```
+
+Write the section's block after the page's, so it wins inside the section.
+
 ## Why Helix uses OKLCH
 
 Equal numeric steps in sRGB do not look like equal steps. That makes scales and

package/dist/sources.generated.js

@@ -1790,6 +1790,25 @@ frame.addEventListener('helix-graph-filter', (event) => {
 The legend is drawn where the notes have two groups or more. On a frame
 narrower than 40rem it is one row, which scrolls.
 
+## Find groups in the links
+
+Notes without a \`group\` are drawn in one color. Where your data has no groups,
+\`groupByCommunity\` finds them in the links: notes that link mostly to each other
+become one group, named after its most linked note. Hand its result to the frame,
+and the drawing colors the groups and the legend names them:
+
+\`\`\`ts
+import { groupByCommunity } from '@fusion.dev/helix-graph'
+
+frame.nodes = groupByCommunity(notes, links)
+frame.links = links
+\`\`\`
+
+A note that has a \`group\` keeps it. Communities of fewer than three notes share
+one group, named \`Other\`. Set \`fewest\` and \`rest\` to change either. The same
+notes and links give the same groups every time. On 20,000 notes it takes about
+65 milliseconds.
+
 ## Select a note
 
 Pressing a note selects it, and pressing where no note is clears the selection.
@@ -3346,10 +3365,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\` | 746,073 | 193,246 | 149,775 | Every headless family. The barrel entry includes all of them. |
+| \`@fusion.dev/helix-headless\` | 746,304 | 193,314 | 149,776 | 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,284 | 301,883 | 220,711 | Every styled family. |
+| \`@fusion.dev/helix\` | 1,291,679 | 302,007 | 220,657 | Every styled family. |
 | \`lit\` | 15,394 | 6,118 | 5,460 | Lit itself, listed so you can subtract it from every row above. |
 
 ## Stylesheets
@@ -3372,11 +3391,11 @@ 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,883.
+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 302,007.
 
-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.
+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,314 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.
+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,942 bytes gzipped alone.
 
 ## Compared with other systems
 
@@ -3388,7 +3407,7 @@ The table has no whole-library row. That row would compare how many components e
 
 | Component | System | Raw | Gzip | Brotli |
 |---|---|---|---|---|
-| \`button\` | **Helix** | 43,806 | 12,554 | 11,023 |
+| \`button\` | **Helix** | 43,982 | 12,620 | 11,082 |
 | | Carbon | 133,058 | 20,959 | 17,685 |
 | | Material Web | 47,060 | 14,173 | 12,591 |
 | | Shoelace | 62,628 | 18,287 | 15,805 |
@@ -3477,7 +3496,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | \`bar-chart\` | 81,076 | 26,555 | 23,488 | 12,644 | 3,701 | 3,035 |
 | \`blockquote\` | 33,053 | 10,175 | 8,938 | 774 | 176 | 128 |
 | \`breadcrumbs\` | 88,957 | 28,651 | 23,520 | 1,965 | 451 | 379 |
-| \`button\` | 37,713 | 11,437 | 10,046 | 3,182 | 812 | 670 |
+| \`button\` | 37,725 | 11,440 | 10,034 | 3,194 | 814 | 619 |
 | \`button-group\` | 32,909 | 10,061 | 8,843 | 661 | 137 | 34 |
 | \`callout\` | 88,077 | 28,508 | 23,396 | 914 | 233 | 168 |
 | \`canvas\` | 94,126 | 27,730 | 24,309 | 50,034 | 14,930 | 12,613 |
@@ -3487,12 +3506,12 @@ Structure, accessibility, state, and form participation. It has no presentation
 | \`checkbox\` | 42,424 | 12,472 | 10,962 | 2,703 | 748 | 514 |
 | \`checkbox-group\` | 45,548 | 13,159 | 11,549 | 5,307 | 1,316 | 1,017 |
 | \`code\` | 31,528 | 9,644 | 8,470 | 451 | 77 | -1 |
-| \`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 |
+| \`code-block\` | 133,832 | 43,676 | 36,796 | 17,317 | 4,502 | 3,798 |
+| \`color-input\` | 151,907 | 47,747 | 40,241 | 25,819 | 6,027 | 5,016 |
+| \`color-picker\` | 118,278 | 37,129 | 30,542 | 19,642 | 4,706 | 4,026 |
 | \`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 |
+| \`copy-button\` | 128,413 | 42,045 | 35,300 | 11,895 | 2,938 | 2,421 |
 | \`data-table\` | 186,894 | 56,878 | 48,021 | 57,295 | 14,485 | 11,997 |
 | \`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 |
@@ -3509,7 +3528,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | \`graph\` | 114,708 | 36,466 | 29,953 | 11,479 | 3,233 | 2,708 |
 | \`heatmap\` | 78,430 | 25,372 | 22,403 | 10,872 | 2,982 | 2,366 |
 | \`icon\` | 87,644 | 28,324 | 23,220 | 1,018 | 245 | 126 |
-| \`icon-button\` | 38,112 | 11,466 | 10,070 | 3,581 | 852 | 646 |
+| \`icon-button\` | 38,124 | 11,469 | 10,075 | 3,593 | 854 | 670 |
 | \`image\` | 35,082 | 10,613 | 9,334 | 3,156 | 809 | 657 |
 | \`input\` | 99,537 | 31,813 | 25,941 | 4,745 | 1,288 | 938 |
 | \`kbd\` | 34,863 | 10,848 | 9,529 | 2,976 | 922 | 855 |
@@ -3526,7 +3545,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | \`navigation\` | 34,843 | 10,709 | 9,395 | 1,361 | 301 | 226 |
 | \`notifications\` | 104,181 | 33,078 | 26,996 | 11,383 | 2,637 | 2,263 |
 | \`number-input\` | 102,465 | 32,630 | 26,674 | 7,670 | 2,010 | 1,515 |
-| \`object-inspector\` | 141,502 | 46,264 | 38,895 | 19,550 | 5,225 | 4,370 |
+| \`object-inspector\` | 141,531 | 46,276 | 38,905 | 19,579 | 5,236 | 4,304 |
 | \`option\` | 35,204 | 10,629 | 9,352 | 2,958 | 646 | 543 |
 | \`outline\` | 38,267 | 11,902 | 10,469 | 4,628 | 1,320 | 1,075 |
 | \`pagination\` | 150,818 | 47,121 | 39,598 | 27,821 | 6,525 | 5,229 |
@@ -3547,7 +3566,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | \`speed-dial\` | 118,638 | 39,539 | 33,189 | 3,743 | 915 | 719 |
 | \`splitter\` | 42,714 | 12,692 | 11,214 | 10,282 | 2,596 | 2,223 |
 | \`stat\` | 33,397 | 10,120 | 8,906 | 1,148 | 193 | 173 |
-| \`steps\` | 97,187 | 31,106 | 25,374 | 6,264 | 1,479 | 1,106 |
+| \`steps\` | 97,217 | 31,122 | 25,454 | 6,294 | 1,492 | 1,245 |
 | \`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 |
@@ -3560,7 +3579,7 @@ Structure, accessibility, state, and form participation. It has no presentation
 | \`toggle\` | 45,957 | 13,403 | 11,795 | 3,342 | 816 | 583 |
 | \`toolbar\` | 35,003 | 10,814 | 9,482 | 2,624 | 717 | 552 |
 | \`tooltip\` | 64,751 | 21,220 | 18,782 | 6,369 | 1,715 | 1,350 |
-| \`tour\` | 70,570 | 22,635 | 19,952 | 11,032 | 2,719 | 2,232 |
+| \`tour\` | 70,633 | 22,663 | 19,991 | 11,095 | 2,741 | 2,236 |
 | \`tree\` | 99,021 | 31,924 | 25,969 | 7,223 | 1,882 | 1,539 |
 | \`trend\` | 87,684 | 28,370 | 23,291 | 1,056 | 289 | 243 |
 | \`video\` | 155,346 | 48,784 | 41,231 | 32,520 | 7,642 | 6,463 |
@@ -3583,7 +3602,7 @@ The headless tier plus presentation. \`bun add @fusion.dev/helix\` installs this
 | \`bar-chart\` | 93,880 | 29,107 | 25,756 | 25,425 | 6,313 | 5,329 |
 | \`blockquote\` | 34,209 | 10,468 | 9,196 | 1,914 | 467 | 315 |
 | \`breadcrumbs\` | 92,523 | 29,466 | 24,178 | 5,518 | 1,244 | 1,129 |
-| \`button\` | 43,806 | 12,554 | 11,023 | 9,257 | 1,937 | 1,505 |
+| \`button\` | 43,982 | 12,620 | 11,082 | 9,433 | 1,995 | 1,639 |
 | \`button-group\` | 34,585 | 10,450 | 9,174 | 2,320 | 528 | 375 |
 | \`callout\` | 90,078 | 29,063 | 23,826 | 2,899 | 756 | 687 |
 | \`canvas\` | 114,431 | 31,475 | 27,500 | 70,328 | 18,720 | 15,791 |
@@ -3593,12 +3612,12 @@ The headless tier plus presentation. \`bun add @fusion.dev/helix\` installs this
 | \`checkbox\` | 49,050 | 13,927 | 12,237 | 9,313 | 2,208 | 1,876 |
 | \`checkbox-group\` | 47,829 | 13,751 | 12,052 | 7,574 | 1,903 | 1,474 |
 | \`code\` | 32,605 | 9,928 | 8,729 | 1,511 | 377 | 380 |
-| \`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 |
+| \`code-block\` | 150,282 | 46,558 | 39,136 | 33,746 | 7,230 | 6,118 |
+| \`color-input\` | 185,752 | 52,943 | 44,844 | 59,644 | 11,374 | 9,743 |
+| \`color-picker\` | 146,420 | 41,723 | 34,558 | 47,778 | 9,346 | 8,013 |
 | \`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 |
+| \`copy-button\` | 138,417 | 43,836 | 36,896 | 21,883 | 4,669 | 3,882 |
 | \`data-table\` | 225,180 | 63,813 | 53,600 | 95,314 | 21,365 | 17,447 |
 | \`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 |
@@ -3617,7 +3636,7 @@ The headless tier plus presentation. \`bun add @fusion.dev/helix\` installs this
 | \`grid\` | 34,559 | 10,478 | 9,220 | 2,667 | 630 | 522 |
 | \`heatmap\` | 85,228 | 26,779 | 23,661 | 17,648 | 4,434 | 3,682 |
 | \`icon\` | 88,350 | 28,509 | 23,354 | 1,707 | 422 | 288 |
-| \`icon-button\` | 44,127 | 12,484 | 10,977 | 9,582 | 1,854 | 1,563 |
+| \`icon-button\` | 44,139 | 12,487 | 10,941 | 9,594 | 1,856 | 1,555 |
 | \`image\` | 36,784 | 11,092 | 9,750 | 4,840 | 1,285 | 1,066 |
 | \`input\` | 105,902 | 33,263 | 27,153 | 11,104 | 2,685 | 2,139 |
 | \`kbd\` | 36,275 | 11,305 | 9,919 | 4,373 | 1,361 | 1,190 |
@@ -3634,7 +3653,7 @@ The headless tier plus presentation. \`bun add @fusion.dev/helix\` installs this
 | \`navigation\` | 36,224 | 11,110 | 9,735 | 2,726 | 713 | 628 |
 | \`notifications\` | 117,292 | 35,506 | 29,125 | 24,486 | 5,059 | 4,265 |
 | \`number-input\` | 107,345 | 33,815 | 27,626 | 12,539 | 3,150 | 2,570 |
-| \`object-inspector\` | 155,139 | 48,519 | 40,992 | 33,167 | 7,563 | 6,311 |
+| \`object-inspector\` | 155,168 | 48,532 | 40,983 | 33,196 | 7,574 | 6,373 |
 | \`option\` | 38,458 | 11,533 | 10,163 | 6,201 | 1,574 | 1,257 |
 | \`orb\` | 43,162 | 13,930 | 12,278 | 8,623 | 3,224 | 2,742 |
 | \`outline\` | 42,007 | 12,688 | 11,173 | 8,351 | 2,127 | 1,739 |
@@ -3657,7 +3676,7 @@ The headless tier plus presentation. \`bun add @fusion.dev/helix\` installs this
 | \`speed-dial\` | 126,270 | 41,059 | 34,489 | 11,356 | 2,382 | 1,920 |
 | \`splitter\` | 48,786 | 13,681 | 12,145 | 16,336 | 3,627 | 3,136 |
 | \`stat\` | 36,822 | 10,836 | 9,555 | 4,565 | 915 | 730 |
-| \`steps\` | 110,828 | 33,587 | 27,521 | 19,894 | 3,918 | 3,257 |
+| \`steps\` | 111,022 | 33,661 | 27,603 | 20,088 | 3,981 | 3,398 |
 | \`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 |
@@ -3671,7 +3690,7 @@ The headless tier plus presentation. \`bun add @fusion.dev/helix\` installs this
 | \`toggle\` | 51,152 | 14,607 | 12,844 | 8,525 | 2,066 | 1,725 |
 | \`toolbar\` | 36,295 | 11,108 | 9,755 | 3,899 | 1,022 | 824 |
 | \`tooltip\` | 67,829 | 21,974 | 19,470 | 9,429 | 2,451 | 2,085 |
-| \`tour\` | 80,121 | 24,220 | 21,448 | 20,565 | 4,378 | 3,738 |
+| \`tour\` | 80,348 | 24,304 | 21,526 | 20,792 | 4,456 | 3,750 |
 | \`tree\` | 104,871 | 33,337 | 27,201 | 13,069 | 3,306 | 2,728 |
 | \`trend\` | 90,903 | 29,129 | 23,898 | 4,271 | 985 | 862 |
 | \`video\` | 174,764 | 52,259 | 44,284 | 51,918 | 11,165 | 9,570 |
@@ -3689,11 +3708,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,508,620 | 510 | 1,077,666 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
+| \`@fusion.dev/helix-headless\` | 13,515,038 | 510 | 1,077,677 | \`@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\` | 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\` |
+| \`@fusion.dev/helix\` | 14,628,121 | 876 | 373,810 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
 
 ## Not measured yet
 
@@ -5609,6 +5628,11 @@ 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.
 
+**Color the figures band** gives one section of the Marketing site layout a
+color of its own, as its own theme. The band is dark or light by whichever text
+reads better on it, and its block follows the page's in the generated
+stylesheet. See [Color one section](./theming#color-one-section).
+
 ## The audit
 
 The audit lists every color pair Helix computed. Each pair shows its ratio,
@@ -5765,6 +5789,39 @@ console.log(css[':root'])
 A value that is not a color and still changes with the mode, such as the edge
 of a floating surface, is set by rules after the block, one for each mode.
 
+## Color one section
+
+A section in a color of its own, such as a deep teal band on a cream page, is a
+theme of its own. Derive it from the same intent, with the section's color as
+its page, under a selector for the section:
+
+\`\`\`ts
+const band = engine.derive(
+  { ...intent, background: { dark: '#0b2a33' }, scheme: 'dark' },
+  ['[data-band]'],
+)
+\`\`\`
+
+Choose the scheme the color needs: \`dark\` for a color light text reads on, and
+\`light\` for one dark text reads on. A color no text can reach the contrast
+target on is refused, as a page is.
+
+Mark the section so the stylesheet derives its own colors there from the
+section's seeds, in the section's mode, and paint it with its page color:
+
+\`\`\`html
+<section data-band data-color-mode="dark" data-helix-theme>…</section>
+\`\`\`
+
+\`\`\`css
+[data-band] {
+  background-color: var(--helix-color-background);
+  color: var(--helix-color-foreground);
+}
+\`\`\`
+
+Write the section's block after the page's, so it wins inside the section.
+
 ## Why Helix uses OKLCH
 
 Equal numeric steps in sRGB do not look like equal steps. That makes scales and

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-docs",
   "description": "Versioned documentation content and registry for Helix.",
-  "version": "0.132.0",
+  "version": "0.133.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.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/helix": "0.133.0",
+    "@fusion.dev/helix-cem": "0.133.0",
+    "@fusion.dev/helix-headless": "0.133.0",
+    "@fusion.dev/helix-icons": "0.133.0",
+    "@fusion.dev/helix-map": "0.133.0",
+    "@fusion.dev/helix-styles": "0.133.0",
+    "@fusion.dev/helix-testing": "0.133.0",
+    "@fusion.dev/helix-theme": "0.133.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "lit": "^3.2.1",
     "playwright": "^1.62.1"