@fusion.dev/helix-docs 0.104.1 → 0.105.0

package/content/state-and-control.mdx

@@ -1,14 +1,15 @@
 ---
-description: Why a declared property is a seed, and how to take a decision when you want it.
+description: How a property you set becomes a starting value, and how to cancel or take over a change.
 section: Essentials
 title: State and control
 ---
 
 # State and control
 
-**A declared property is a seed and a correction.** Write `value`, `open`,
-`checked` or `active` on a Helix element and it starts there and goes on
-managing itself, exactly as `<input value="Ada">` does.
+A property you set is a starting value, and you can assign it again later to
+correct it. Set `value`, `open`, `checked`, or `active` on a Helix element. The
+element starts there and then manages its own state, as `<input value="Ada">`
+does.
 
 ```html
 <helix-input
@@ -17,20 +18,20 @@ managing itself, exactly as `<input value="Ada">` does.
 ></helix-input>
 ```
 
-That works. Type in it and the value moves. Assign to it later and the value
-moves to what you assigned. There is no mode to be in and nothing to wire before
-the control responds.
+When you type in the input, the value changes. When you assign a new value
+later, the value changes to what you assigned. The control has no modes, and you
+do not need to connect anything before it responds.
 
-*This page said the opposite until 26 Aug 2026: writing a property was a claim
-of ownership, so the element announced its changes and applied none of them
-until it was told. The mode is deleted. If you were refusing a change by
-withholding a state update rather than by calling `preventDefault()`, that is
-the one thing that has to be rewritten.*
+*Until August 26, 2026, this page said the opposite. Setting a property claimed
+ownership of the state, so the element announced its changes and applied none
+of them until you set the new value. That mode is removed. If you canceled
+changes by withholding a state update, rewrite that code to call
+`preventDefault()`. Nothing else has to change.*
 
-## Taking a decision
+## Cancel or take over a change
 
-Control is an action rather than a mode. Every change announces before it acts,
-and the announcement is cancelable:
+You take control one change at a time. Each change sends a cancelable event
+before it is applied:
 
 ```ts
 input.addEventListener('helix-before-change', (event) => {
@@ -40,8 +41,8 @@ input.addEventListener('helix-before-change', (event) => {
 })
 ```
 
-`preventDefault()` refuses that one change and nothing moves. To own the state
-outright, refuse and assign your own:
+`preventDefault()` cancels that one change, and nothing moves. To manage the
+state yourself, cancel the change and assign your own value:
 
 ```tsx
 <helix-input
@@ -54,22 +55,27 @@ outright, refuse and assign your own:
 />
 ```
 
-This is the same shape the platform uses everywhere else: `preventDefault()` on
-a form submit, on a link click, on `beforeinput`. Nothing is declared in advance
-and nothing is inferred from which properties you happened to set.
+The platform uses the same pattern. You call `preventDefault()` to cancel:
 
-The imperative form reports the same thing:
+- a form submit
+- a link click
+- a `beforeinput` event
+
+You do not declare anything in advance, and Helix does not infer anything from
+which properties you set.
+
+The imperative method reports the same result:
 
 ```ts
 const applied = item.requestOpen(true)
 ```
 
-`false` means something refused it.
+`false` means something canceled the change.
 
-## Mirroring the state instead
+## Follow the state with the change event
 
-Most consumers want neither of the above. Bind the notification and let the
-element apply:
+Most of the time you do not need to cancel anything. Listen for the change
+event and let the element apply the change:
 
 ```tsx
 <helix-input label="Name" onChange={(event) => setName(event.currentTarget.value)} />
@@ -82,11 +88,11 @@ element apply:
 ></helix-input>
 ```
 
-The native event carries no detail because it does not need one: the element has
-already applied the change by the time it fires, so the value is on the target
-where every handler ever written expects to find it.
+The native event carries no detail. The element has already applied the change
+when the event fires, so the value is on the target, where handlers expect to
+find it.
 
-## `default-` still means something
+## `default-value` sets the value a reset returns to
 
 ```html
 <helix-input
@@ -95,38 +101,44 @@ where every handler ever written expects to find it.
 ></helix-input>
 ```
 
-`default-value` is what a reset returns to. `value` is where the control is now.
-The pair is the platform's, where a native input reflects its `value` *content
-attribute* to `defaultValue` and carries a dirty flag that stops the attribute
-affecting the value once a reader has typed.
+`default-value` is the value a reset returns to. `value` is the control's
+current value. The pair comes from the platform. A native input reflects its
+`value` *content attribute* to `defaultValue`, and it keeps a dirty flag. Once a
+user has typed, the flag stops the attribute from changing the value.
 
-## State is a custom state, not an attribute
+## State is published as a custom state
 
 ```css
 helix-accordion-item:state(open) { … }
 ```
 
-`open` is not reflected, and neither is `value`. A payload written back as an
-attribute leaks whatever the last reader typed into the markup, so a serialized
-host comes back holding their text rather than the author's seed, with no way to
-tell the two apart. `helix-input` takes `type="password"`, which a reflected
-`value` would carry straight past every session-replay masker that knows to mask
-`.value` and `input[value]`.
+`open` is not reflected to an attribute, and neither is `value`. A value written
+back as an attribute would put whatever the last user typed into the markup. A
+serialized element would then hold the user's text, and you could not tell it
+apart from the starting value you wrote. `helix-input` takes `type="password"`.
+A reflected `value` would carry the password past every session-replay masker
+that masks `.value` and `input[value]`.
+
+Helix publishes the resolved boolean as a custom state, and the attribute keeps
+the value you wrote. There are four custom states:
+
+- `:state(open)`
+- `:state(checked)`
+- `:state(invalid)`
+- `:state(read)`
 
-So the resolved boolean is published as a custom state and the plain attribute
-stays what you wrote. `:state(open)`, `:state(checked)`, `:state(invalid)` and
-`:state(read)` are the four, and they work from your own stylesheet exactly as
-an attribute selector did:
+They work in your own stylesheet as an attribute selector did:
 
 ```css
 helix-checkbox:state(checked)::part(control) { … }
 helix-input:state(invalid)::part(field) { … }
 ```
 
-**These were `data-open` and `data-checked` until 27 Aug 2026.** An attribute is
-in the DOM, and the element writes it on its first update, so a framework that
-server-renders your markup and then hydrates it finds attributes its own render
-never produced. React reports that as a hydration mismatch and does not patch it
-up. A custom state is not in the DOM: it reaches your stylesheet and leaves the
-markup alone, so the two renders agree by construction. If you were selecting on
-the old names, the change is mechanical.
+Until August 27, 2026, these states were the `data-open` and `data-checked`
+attributes. An attribute is in the DOM, and the element writes it on its first
+update. A framework that renders your markup on the server and then hydrates it
+finds attributes that its own render never produced. React reports that as a
+hydration mismatch and does not fix it. A custom state is not in the DOM. It
+reaches your stylesheet and leaves the markup alone, so the server render and
+the client render always match. If you selected on the old names, replace each
+one with its custom state.

package/content/surfaces-and-separation.mdx

@@ -1,99 +1,101 @@
 ---
-description: The four ways a surface is told apart, and the ground a component is not.
+description: The four ways to separate a surface from what is behind it, and the tokens that choose between them.
 section: Foundations
 title: Surfaces and separation
 ---
 
 # Surfaces and separation
 
-**A surface is told apart from what is behind it by exactly one of four things:
-a fill, an edge, a lift, or space.** A design language leads with one of them.
-Helix leads with the edge on the page and with the lift above it: a card takes a
-hairline and no shadow, a menu takes a shadow and no hairline. The ladder below
-decides what a surface sits on.
+**Separate each surface from what is behind it with exactly one of four
+things.** The four are a fill, an edge, a lift, and space. A design language
+leads with one of them. Helix uses an edge for surfaces on the page and a lift
+for surfaces above it. A card has a hairline border and no shadow. A menu has a
+shadow and no hairline border. The surface ladder below sets the ground color
+for each place a surface can sit.
 
-## The four mechanisms
+## The four ways to separate a surface
 
 | | |
 |---|---|
-| **Fill** | A different ground color to what is behind it |
+| **Fill** | A ground color different from what is behind it |
 | **Edge** | A border |
 | **Lift** | A shadow |
-| **Space** | Nothing at all, and the gap does the work |
+| **Space** | Nothing at all. The gap separates it |
 
-Most systems use two or three without deciding, which is how you end up with a
-card that has a border, a shadow *and* a tint, each added by someone solving the
-same problem again.
+When a design system uses two or three of these without a plan, a card can end
+up with a border, a shadow, and a tint, each added by someone solving the same
+problem again.
 
-Helix expresses the choice in two pairs of policy tokens:
+Helix sets the choice with two pairs of policy tokens:
 
 [//]: # (tokens:separation-policy)
 
 | Token | Value | For |
 | --- | --- | --- |
-| `--helix-border-surface` | `var(--helix-border-thin)` | The edge a surface in the flow takes. Zero to go shadow-first. |
-| `--helix-shadow-surface` | `var(--helix-shadow-none)` | The lift a surface in the flow takes. None to go border-first. |
-| `--helix-border-floating` | `0` | The edge a surface over content takes. |
-| `--helix-shadow-floating` | `var(--helix-shadow-lg)` | The lift a surface over content takes. |
+| `--helix-border-surface` | `var(--helix-border-thin)` | The border of a surface in the page flow. Set it to zero to separate surfaces with shadows. |
+| `--helix-shadow-surface` | `var(--helix-shadow-none)` | The shadow of a surface in the page flow. Set it to none to separate surfaces with borders. |
+| `--helix-border-floating` | `0` | The border of a surface that floats over content. |
+| `--helix-shadow-floating` | `var(--helix-shadow-lg)` | The shadow of a surface that floats over content. |
 
 [//]: # (/tokens)
 
-Set the border pair to zero and the shadow pair to something, and the whole
-library goes shadow-first. Reverse them and it goes border-first. Every surface
-in the library is themeable in both directions, and checked, because a
-half-converted one reads as done: hook the shadow and hardcode `border: none`
-and it themes perfectly in one direction and cannot be moved in the other.
+To make every component shadow-first, set the border pair to zero and give the
+shadow pair a value. Reverse them to go border-first. Every Helix surface reads
+both pairs, and this is checked. A surface that reads only one pair is easy to
+miss. If it reads the shadow token and sets `border: none` directly, a theme can
+change it in one direction and not in the other.
 
-## The ladder
+## The surface ladder
 
-A surface's ground says where it is, not what shade it is:
+A surface's ground color token names where the surface sits:
 
 [//]: # (tokens:surface-ladder)
 
 | Token | Sample | For |
 | --- | --- | --- |
-| `--helix-color-background` | <span data-token-swatch style={{ background: 'var(--helix-color-background)' }} /> | The page. Told apart by nothing, because it is the ground. |
-| `--helix-color-surface` | <span data-token-swatch style={{ background: 'var(--helix-color-surface)' }} /> | A plane on the page: a card, or a panel you own. Told apart by a fill, an edge or a lift, whichever the policy leads with. |
-| `--helix-color-surface-raised` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-raised)' }} /> | Lifted while still lying on the page: a selected tab, a hovered row. Told apart by its fill, which goes down the ramp rather than up. |
-| `--helix-color-surface-overlay` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-overlay)' }} /> | Over the page rather than on it: a menu, a popover, a dialog. Told apart by its shadow and by what it covers. |
-| `--helix-color-surface-sunken` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-sunken)' }} /> | A well a value goes into: an input, a track, a groove. Told apart by its fill, inward. |
+| `--helix-color-background` | <span data-token-swatch style={{ background: 'var(--helix-color-background)' }} /> | The page background. Every other surface sits on it. |
+| `--helix-color-surface` | <span data-token-swatch style={{ background: 'var(--helix-color-surface)' }} /> | A surface on the page, such as a card or a panel. The separation policy sets it apart with a fill, a border, or a shadow. |
+| `--helix-color-surface-raised` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-raised)' }} /> | A raised surface on the page, such as a selected tab or a hovered row. Its fill is one step down the ramp. |
+| `--helix-color-surface-overlay` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-overlay)' }} /> | A surface over the page, such as a menu, a popover, or a dialog. Its shadow sets it apart. |
+| `--helix-color-surface-sunken` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-sunken)' }} /> | A recessed surface that holds a value, such as an input, a track, or a groove. Its fill sets it apart. |
 
 [//]: # (/tokens)
 
-**`raised` goes down the ramp, not up**, which is the counterintuitive one. A
-selected tab's pill, a hovered row and an option under the pointer all have the
-page on every side, so they are told apart by their fill, and on a white page a
-fill has to be a step *darker* to be seen. `overlay` is the opposite: it is told
-apart by its shadow and by covering something, so on white it is white.
+**`raised` goes one step down the ramp.** A selected tab's pill, a hovered row,
+and an option under the pointer all have the page on every side. Only their
+fill separates them, and on a white page a fill has to be a step darker to be
+seen. `overlay` works the other way. Its shadow and what it covers separate it,
+so on a white page it is white.
 
-## The common mistake
+## Using the page color inside a component
 
-**`--helix-color-background` is the page, and your component is not the page.**
+**`--helix-color-background` is the page color. Do not use it inside a
+component.**
 
 ```css
 /* Wrong. Claims the component is sitting on the page. */
 .marker { background: var(--helix-color-background); }
 ```
 
-Every use of the page's color inside a component is a claim about what that
-component is sitting on, and the claim is right exactly as often as the
-component is put on the page and no other ground. `Timeline`'s marker made it,
-painting itself the page color to knock the rail out behind it, and came out
-darker than any surface that was not the page: on a card it showed as a black
-disc. The sparkline's ring terminus made the same mistake and looked identical.
+Using the page color inside a component assumes the component sits on the page.
+That is right only when the component is placed directly on the page.
 
-The trap is that both of those *worked*, for months, because the page is what
-anybody building a component puts it on. It fails on a card, a drawer, a toast,
-a panel or a photograph, and none of those is where a component gets built.
+`Timeline`'s marker had this mistake. It was painted the page color to hide the
+rail behind it, so it came out darker than any surface other than the page. On a
+card, it showed as a black disc. The sparkline's ring terminus had the same
+mistake and looked the same.
 
-**What to do instead:** put the color behind a hook that defaults to the page,
-so a consumer whose component is not on the page can correct it. That is what
-the library requires of itself, and the same reasoning applies to anything you
-build on top.
+Both looked correct for months, because components are usually built on the
+page. The mistake shows on a card, a drawer, a toast, a panel, or a photograph,
+and components are not built on any of those.
+
+Put the color behind a hook that defaults to the page color. When the component
+sits on another surface, the hook can be set to match. Helix requires this of
+its own components, and the same applies to anything you build with it.
 
 ## Contrast
 
-The theme engine measures an ink against the ground it is *really* painted on,
-which is why the ladder is a model rather than a naming convention: the engine
-has to know that `foreground` on `surface-overlay` is a real pair and
-`foreground-on-accent` on `surface` is not. See [Color](./color).
+The theme engine measures each ink against the ground it is actually painted
+on. The ladder records which pairs occur. For example, `foreground` on
+`surface-overlay` is a real pair, and `foreground-on-accent` on `surface` is
+not. See [Color](./color).

package/content/svelte.mdx

@@ -1,5 +1,5 @@
 ---
-description: Typed tags, and the framework that needs the least said about it.
+description: The Svelte typings, and how Svelte passes props and binds events.
 parent: installation
 section: Getting started
 title: Svelte
@@ -11,35 +11,36 @@ title: Svelte
 import '@fusion.dev/helix/svelte'
 ```
 
-A types-only import, once. It augments `SvelteHTMLElements` so every Helix tag
-is typed in a component, and it does so by re-exporting the JSX types rather
-than emitting a second copy: Svelte binds a handler as `onhelix-before-change={…}`,
-which is the shape those types already describe, and two generated copies of one
-thing are two things that can disagree.
+Add this types-only import once. It augments `SvelteHTMLElements`, so every
+Helix tag is typed in a component. The import re-exports the JSX types. Svelte
+binds a handler as `onhelix-before-change={…}`, which is the shape those types
+already describe. With one shared copy of the types, the Svelte and JSX typings
+cannot disagree.
 
-## Nothing else to configure
+## Pass props and bind events
 
 ```svelte
 <helix-input label="Name" onchange={(event) => (name = event.target.value)} value={name} />
 ```
 
-Svelte sets a property when the element has one and an attribute otherwise, and
-binds `on*` with `addEventListener`. There is no unknown-element warning to
-silence and no compiler flag to set. That is the whole page, and it is short
-because Svelte was already right about custom elements.
+Svelte sets a property when the element has one, and an attribute otherwise. It
+binds `on*` with `addEventListener`. Svelte shows no unknown-element warning,
+and you do not need a compiler flag.
 
-**Pass objects and arrays as properties**, which Svelte does on its own:
+Svelte passes objects and arrays as properties on its own:
 
 ```svelte
 <helix-tabs items={tabs} />
 ```
 
-## Two things that are not framework-specific
+## Read values and refuse changes
 
-`bind:` does not work on a Helix control, because there is no two-way binding
-convention a custom element can opt into. Read the value off the event.
+These two rules apply in every framework.
 
-And a declared `value`, `open`, `checked` or `active` is a seed: the element
-starts there and goes on applying its own changes. To refuse one, cancel the
-matching `helix-before-*` event; withholding a state update refuses nothing.
-See [State and control](./state-and-control).
+`bind:` does not work on a Helix control, because custom elements have no
+two-way binding convention to opt into. Read the value from the event.
+
+A declared `value`, `open`, `checked`, or `active` is a seed. The element starts
+with that value and then applies its own changes. To refuse a change, cancel the
+matching `helix-before-*` event. Skipping a state update does not refuse it. See
+[State and control](./state-and-control).

package/content/theme-builder.mdx

@@ -1,5 +1,5 @@
 ---
-description: The tool that turns intent inputs into a token set you can see.
+description: Enter your theme inputs and see every token Helix computes from them.
 section: Tooling
 title: Theme builder
 ---
@@ -8,37 +8,47 @@ title: Theme builder
 
 [Open the theme builder](/helix/theme).
 
-Move a slider and every surface in the library resolves around it. A theme here
-is derived rather than picked, and this is where you see that happen.
+When you move a slider, every component in the preview updates. Helix computes
+a theme from a few inputs, and the theme builder shows you the result.
 
-## What it does
+## What the theme builder shows
 
-You give it the intent inputs, the same ones `derive()` takes: a brand color, a
-chroma ceiling, a radius, a density, a contrast target, a motion character. It
-runs the real derivation, not an approximation of it, and shows you the complete
-token set plus the library rendered in it.
+You enter the same inputs that `derive()` takes:
 
-Light and dark at once, because `[data-color-mode]` works on any element and the
-two previews are two subtrees of one document. See [Color modes](./color-modes).
+- 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
 
-Every pairing the engine solved is listed with its measured ratio against the
-ground it is actually painted on. Three states:
+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 ground is translucent, so there is no known color to
-  measure against. Not a failure, and not a pass either: it is what a material
-  choice costs you, reported rather than hidden.
-- **Pinned.** You supplied the color outright, so the engine did not solve for
-  it and cannot promise anything about it.
+- **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 theme with a column of `unverifiable` is a theme making a trade. It should be
-possible to see that you made it.
+A column of `unverifiable` pairs means your theme makes a trade. The column lets
+you see that you made it.
 
-## What comes out
+## What the theme builder exports
 
-The token block, as CSS, to paste into your own stylesheet:
+The theme builder gives you the token block as CSS, to paste into your own
+stylesheet:
 
 ```css
 :root {
@@ -47,20 +57,21 @@ The token block, as CSS, to paste into your own stylesheet:
 }
 ```
 
-Or the intent object, to keep in your repository and re-derive from:
+It also gives you the intent object, to keep in your repository and derive the
+theme from again:
 
 ```ts
 export const theme = { brand: '#2563eb', chroma: { ceiling: 0.1 }, radius: 2 }
 ```
 
-**Keep the intent, not the tokens.** The tokens are the output of a solver, and
-the solver improves: a theme stored as its inputs picks up a better derivation,
-and a theme stored as literal values is frozen at the version that produced
-it. The tokens are for pasting into a system that cannot run the engine.
+**Keep the intent object in your repository.** The tokens are the output of a
+solver, and the solver improves. A theme stored as its inputs gets each
+improvement. A theme stored as token values stays at the version that produced
+it. Use the tokens only in a system that cannot run the engine.
 
-## What it does not do
+## Limits of the theme builder
 
-It shows you numbers and swatches, not components in your product. A contrast
-matrix is a grid with three states, which a terminal or a table renders better
-than a picture does, and the components beside it are there to sanity-check the
-result rather than to be a design surface.
+The theme builder shows numbers and swatches. It does not show components in
+your product. The contrast results are a grid with three states, and a terminal
+or a table shows that grid more clearly than a picture. The components beside
+it are for checking the result. They are not a design tool.