@fusion.dev/helix-docs 0.0.0-dev → 0.0.3

package/content/browser-support.mdx

@@ -28,11 +28,11 @@ report we want, and it is not one we would have caught.
 | Custom elements and shadow DOM | Everything |
 | `ElementInternals` | Form participation, and ARIA that has to cross a shadow boundary |
 | Popover API | Every overlay: menu, tooltip, select, combobox, dialog |
-| `light-dark()` | 761 declarations, 135 of them in the token layer |
+| `light-dark()` | 156 declarations in the shipped stylesheets, 71 of them in the token layer |
 | `oklch()` | Every color in the system |
 | `:has()` | 11 rules, mostly relational styling of slotted content |
 | `@starting-style` | Entry transitions on overlays |
-| `:state()` | Every boolean state the library publishes: `open`, `checked`, `selected`, `invalid`, `read`, `has-label`, `settled`, `empty` |
+| `:state()` | Every boolean state the library publishes: `open`, `checked`, `selected`, `invalid`, `read`, `has-label`, `settled`, `empty`, `controls` |
 | `CSS.highlights` | Filter-match highlighting, in `Command` and `Combobox` |
 
 Positioning is `@floating-ui/dom` rather than CSS anchor positioning, which is a

package/content/charting.mdx

@@ -52,18 +52,14 @@ Hide the table visually if it should not be seen, and the data is still there:
 The caption becomes the chart's accessible name unless you set `label`, which is
 usually the right words and is already written.
 
-## Series colours
+## Series colors
 
 Twenty-four `--helix-color-series-*` tokens, in order. A chart with three series
 uses the first three. They are ordered to stay distinguishable in that order
 rather than to look good as a full set of twenty-four.
 
-The palette wraps, and where it wraps is one number in one place. It used to be
-four: four families held the same `const PALETTE = 24` and the legend held a
-fifth, so when the palette went from eight to twenty-four one of them was missed
-and drew every ninth series in the first color while the legend beside it named
-the ninth correctly. A number two files have to agree on is a number that will
-stop agreeing.
+The palette wraps, and where it wraps is one number in one place, so a chart and
+the legend beside it can never disagree about which color a series is.
 
 **A chart's mark carries its own series color as a custom property**, because a
 chart knows which series a bar belongs to and CSS cannot count it. That is what
@@ -76,7 +72,7 @@ lets you restyle a series from outside without knowing the drawing order.
 <helix-bar-chart for="revenue"></helix-bar-chart>
 ```
 
-The legend reads the same table, so the names and the colours cannot disagree
+The legend reads the same table, so the names and the colors cannot disagree
 with the chart's. Pointing them at two different tables is the only way to make
 them disagree, and it is not something to do by accident.
 

package/content/coding-agents.mdx

@@ -18,13 +18,9 @@ https://fusion.dev/helix/custom-elements.json
 @fusion.dev/helix/custom-elements.json
 ```
 
-A URL and a package path, the same file either way. **The URL exists because this
-page's own argument required it**: an agent that found the library through
-`llms.txt` has this site and no checkout, and a specifier is reachable from a
-`node_modules` and from nowhere else. It was only the specifier until 24 Aug 2026,
-and the specifier did not resolve either: `exports` carried a `./*` pattern
-pointing at `./dist/*/index.js`, so the path two pages recommended was one
-`require.resolve` refused.
+A URL and a package path, the same file either way. **Both exist because a
+specifier is reachable from a `node_modules` and from nowhere else**, and an
+agent that found the library through `llms.txt` has this site and no checkout.
 
 Every element, every property with its literal type union, every event with its
 class, every slot, every part, every custom property. It is what the framework
@@ -62,13 +58,13 @@ These are the difference between code that looks right and code that passes:
 
 | Rule | Check |
 |---|---|
-| A dispatched event must be declared | `check:events` |
-| A documented part must be rendered | `check:parts` |
-| A documented CSS hook must be read | `check:hooks` |
-| A visual property draws from its axis | `check:axes` |
-| A form control styles with `:disabled` | `check:disabled` |
-| A component that animates answers reduced motion | `check:motion` |
-| No component reads a primitive token | `check:tokens` |
+| A dispatched event must be declared | `helix component --only events` |
+| A documented part must be rendered | `helix component`'s `parts` |
+| A documented CSS hook must be read | `helix component --only hooks` |
+| A visual property draws from its axis | `helix component`'s `axes` |
+| A form control styles with `:disabled` | `helix component --only disabled` |
+| A component that animates answers reduced motion | `helix component --only motion` |
+| No component reads a primitive token | `helix component`'s `tokens` |
 
 If you are generating Helix code, the first two are the ones that produce
 working-looking output that is wrong.
@@ -86,8 +82,7 @@ existing.
 
 Start there rather than crawling: one request, and it names every page on the
 site plus the two machine-readable surfaces above. No count here, because a
-number typed into prose is a number that goes stale, which the read of these pages
-on 24 Aug 2026 found five of.
+number typed into prose is a number that goes stale.
 
 ## From a component's page
 
@@ -127,12 +122,9 @@ of a binary you installed, talking to a client you chose, with no network in it.
 page into one file is out of date the moment anything changes, where the links
 in `llms.txt` are individually cacheable and individually current.
 
-This page used to offer one anyway, a repository path to a generated document
-holding every family at once, which contradicted the paragraph above it and was
-not a thing a consumer could open: an agent reading the published package has
-this site and no checkout. What it was for is covered better by the two surfaces
-already here. `llms.txt` is the index, one request, and each family's `.md` is
-the document. Fetch the families you are using.
+What such a file would be for is covered better by the two surfaces already
+here. `llms.txt` is the index, one request, and each family's `.md` is the
+document. Fetch the families you are using.
 
 **A search index.** The site has one for humans; there is nothing an agent can
 query yet, and `llms.txt` plus the documents it names is a smaller thing to read

package/content/color-modes.mdx

@@ -20,9 +20,9 @@ stylesheet, no `.dark` class to toggle, and nothing to remember to update twice.
 
 Every token is written once, with both halves in a `light-dark()`. Which half
 resolves is decided by `color-scheme` and nothing else, so the mode is a single
-inherited property and no token is restated to honor it. That is 761
-declarations across the library, 135 of them in the token layer, expressing two
-modes without a second copy of anything.
+inherited property and no token is restated to honor it. That is 156
+declarations across the shipped stylesheets, 71 of them in the token layer,
+expressing two modes without a second copy of anything.
 
 ## Setting the mode
 
@@ -72,7 +72,7 @@ told.
 
 ## What this means for your own CSS
 
-Write `light-dark()` for your own colours and set nothing else:
+Write `light-dark()` for your own colors and set nothing else:
 
 ```css
 .callout {

package/content/color.mdx

@@ -6,7 +6,7 @@ title: Color
 
 # Color
 
-Seventy-four of the library's 177 tokens are color, which is most of what a
+Seventy-four of the library's 185 tokens are color, which is most of what a
 theme is. They are roles rather than values: nothing in Helix is named after
 what it looks like, because a name like `--brand-blue-500` stops being true the
 moment anybody rethemes.
@@ -81,7 +81,7 @@ pairing a reader has to be able to read.
 /* Yours to read. */
 color: var(--helix-color-foreground-muted);
 
-/* Not yours to read, and `check:tokens` fails the build on it. */
+/* Not yours to read, and the `tokens` rule fails the build on it. */
 color: var(--_helix-neutral-500);
 ```
 

package/content/elevation-and-material.mdx

@@ -70,8 +70,8 @@ Eight tokens describing translucency rather than color:
 | `--helix-material-blur-sm` | `8px` | The lightest backdrop blur. |
 | `--helix-material-blur-md` | `16px` | The backdrop blur a modal takes. |
 | `--helix-material-blur-lg` | `32px` | The heaviest backdrop blur. |
-| `--helix-material-translucent` | `color-mix(in oklab, light-dark(oklch(1 0 0), oklch(0.21 var(--helix-seed-neutral-chroma, 0) var(--helix-seed-neutral-hue, 258))) 30%, transparent)` | The translucent ground, for a surface that admits what is behind it. |
-| `--helix-material-translucent-strong` | `color-mix(in oklab, light-dark(oklch(1 0 0), oklch(0.21 var(--helix-seed-neutral-chroma, 0) var(--helix-seed-neutral-hue, 258))) 88%, transparent)` | The heavier translucent ground, for one that admits less. |
+| `--helix-material-translucent` | `color-mix(in oklab, light-dark(oklch(1 0 0), oklch(0.182 var(--helix-seed-neutral-chroma, 0) var(--helix-seed-neutral-hue, 258))) 30%, transparent)` | The translucent ground, for a surface that admits what is behind it. |
+| `--helix-material-translucent-strong` | `color-mix(in oklab, light-dark(oklch(1 0 0), oklch(0.182 var(--helix-seed-neutral-chroma, 0) var(--helix-seed-neutral-hue, 258))) 88%, transparent)` | The heavier translucent ground, for one that admits less. |
 | `--helix-material-border` | `light-dark(color-mix(in oklab, oklch(0.15 var(--helix-seed-neutral-chroma, 0) var(--helix-seed-neutral-hue, 258)) 14%, transparent), color-mix(in oklab, oklch(1 0 0) 12%, transparent))` | The edge a translucent surface needs to have any at all. |
 
 [//]: # (/tokens)

package/content/events.mdx

@@ -103,7 +103,7 @@ dispatch, so an event you can listen for is an event that is documented.
 | `helix-navigate` | A component is about to navigate |
 | `helix-copy` | Something was copied |
 | `helix-caret` | The cursor moved in a text control |
-| `helix-load`, `helix-error`, `helix-complete` | Media and async lifecycle |
+| `helix-complete` | A control that fills up has filled |
 | `helix-create` | A new item was made from a query |
 | `helix-console` | The sandbox relaying a log |
 | `helix-tour-ask`, `helix-sample-start`, `helix-sample-end` | Tour and color sampling |

package/content/forms.mdx

@@ -94,7 +94,7 @@ Submitting an empty form blocks and points at the control. `checkValidity()`,
 `reportValidity()` and `:invalid` behave.
 
 **`feedback` overrides the message.** Left empty, the browser's own is shown,
-which is localised and familiar; set, it says what you want in the words your
+which is localized and familiar; set, it says what you want in the words your
 product uses:
 
 ```html
@@ -123,12 +123,10 @@ deliberately reports no value of its own.
 </fieldset>
 ```
 
-That works, and it did not always. The platform tells a form-associated element
-through `formDisabledCallback`, which nothing implemented, so a control inside a
-disabled fieldset stayed fully typeable and announced itself as enabled.
-Measured: a `helix-input` in one accepted text, reported `disabled` as false,
-and carried no `aria-disabled`, while the form's entry list correctly left it
-out. Interactive and unsubmittable is the worst of both.
+That works. The platform tells a form-associated element it has been disabled by
+an ancestor through `formDisabledCallback`, and every Helix control implements
+it, so a control inside a disabled fieldset refuses input and announces itself
+as off rather than staying typeable and unsubmittable.
 
 **For your own CSS this means one rule.** Style disabled controls with
 `:disabled`, never `[disabled]`:

package/content/iconography.mdx

@@ -1,5 +1,5 @@
 ---
-description: 103 glyphs, one geometry, and how to draw one that is not in the set.
+description: 105 glyphs, one geometry, and how to draw one that is not in the set.
 section: Foundations
 title: Iconography
 ---
@@ -10,10 +10,12 @@ title: Iconography
 <helix-icon name="trash"></helix-icon>
 ```
 
-103 glyphs, from Phosphor, drawn on a 256 box at stroke-width 16. That is
+105 glyphs, from Phosphor, drawn on a 256 box at Phosphor's bold weight. That is
 Phosphor's own geometry and it is kept rather than rescaled: normalizing to a 24
 box would change the optical weight of every glyph and stop the set matching
-anything upstream.
+anything upstream. Bold rather than regular, because Phosphor's regular is a
+hairline beside the medium weight this library sets its text in, and an icon
+that reads lighter than the words next to it is the opposite of a mark.
 
 ## Size and color come from the context
 
@@ -63,18 +65,19 @@ failure rather than an empty box.
 
 ## Adding one
 
-Drop the SVG into `helix/icons/raw` and run `bun run icons`. The set is
-generated from those files, so adding a glyph is adding a file rather than
-hand-transcribing a path into a TypeScript object.
+Add the name to `helix/icons/icons.txt` and run `turbo run icons`. Phosphor names
+resolve from `@phosphor-icons/core` at build time, so adding a glyph is adding a
+line rather than hand-transcribing a path into a TypeScript object.
 
-Keep to the same geometry: 256 box, stroke-width 16, no fill. A glyph drawn at a
-different weight is visible immediately when it sits beside one that was not.
+A mark Phosphor does not draw goes into `helix/icons/raw` as an SVG under the
+same name, and is read from there when the package has no match. Keep it to the
+same geometry, a 256 box at the bold weight: a glyph drawn at a different weight
+is visible immediately when it sits beside one that was not.
 
 ## Icons this set does not have
 
 Product marks. Helix and Cortex have marks and they live in the icon package,
 but a mark is not an icon: it identifies a product and does not mean an action.
-Three earlier attempts at product marks were removed for being pictograms of a
-metaphor standing beside a parent that is a geometric monogram, and the rule
-that replaced them is that **a mark is one rounded body with material removed**.
-If you are reaching for the icon set to draw a logo, that is the wrong drawer.
+**A mark is one rounded body with material removed**, never a pictogram of a
+metaphor, because the parent it stands beside is a geometric monogram. If you
+are reaching for the icon set to draw a logo, that is the wrong drawer.

package/content/installation.mdx

@@ -24,8 +24,7 @@ import '@fusion.dev/helix/helix.css'
 
 One import, and it is four files in the order they have to be in:
 `primitives.css`, `tokens.css`, `base.css`, `elements.css`. The order is
-load-bearing and the failure is silent, which these instructions demonstrated
-for longer than anyone would like, so it is stated once inside the package
+load-bearing and the failure is silent, so it is stated once inside the package
 rather than by every consumer.
 
 It resolves `@fusion.dev/helix-styles` through this package's own dependency, so
@@ -41,13 +40,12 @@ own ramp imports the two they want and skips the bundle.
 - **`primitives.css`** is the raw ramp the semantic layer is derived from, and
   it is where the seven `--helix-seed-*` knobs are read. Nothing in your own
   code should name a primitive, and leaving the file out is not a way to
-  enforce that: `tokens.css` refers to one 235 times, so without it every
+  enforce that: `tokens.css` refers to one 297 times, so without it every
   semantic token resolves to nothing at all. Measured on a page missing it,
   `--helix-color-background` computes to `rgba(0, 0, 0, 0)`, and so does every
   other color. It is also the file [theming](theming.mdx) depends on, since a
-  `--helix-seed-brand` nobody reads moves nothing. **This is the one that was
-  missing from this page**, which is why the bundle exists.
-- **`tokens.css`** declares the semantic layer, 177 custom properties in 15
+  `--helix-seed-brand` nobody reads moves nothing.
+- **`tokens.css`** declares the semantic layer, 185 custom properties in 15
   categories, plus `color-scheme: light dark` on `:root`. Everything below reads
   from it, and it reads primitives.
 - **`base.css`** is the element reset, the type scale on bare `h1` through

package/content/introduction.mdx

@@ -30,7 +30,7 @@ analysis time rather than left to review.
 bun add @fusion.dev/helix @fusion.dev/helix-styles
 ```
 
-Three imports at your app root, in this order, then the elements are usable
+Two imports at your app root, in this order, then the elements are usable
 anywhere:
 
 ```ts