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

package/content/overriding-a-component.mdx

@@ -17,12 +17,14 @@ Three doors are open, and they are in the order you should try them.
 
 ```css
 :root {
-  --helix-radii-md: 2px;
+  --helix-seed-radii: 2px;
 }
 ```
 
 If every card, dialog and button should be squarer, that is a token change and
-you are done. Tokens cross shadow boundaries on their own, because custom
+you are done. The seed rather than `--helix-radii-md`, because the four rungs
+are derived from it: `md` on its own is one step of four, and the buttons and
+dialogs are on a different one. See [Shape and borders](./shape-and-borders). Tokens cross shadow boundaries on their own, because custom
 properties inherit, so one declaration reaches every component at once.
 
 Reach for this first. Most requests that arrive as "can I restyle the button"
@@ -51,10 +53,7 @@ changes that component and nothing else.
 after the component (`--card-padding`, `--drawer-radius`) and a token is named
 `--helix-*`. Every documented hook is held to a rule that actually reads it, in
 both directions: declared and never read is a promise with nothing behind it,
-and read and never declared is a working feature nobody is told about. Three of
-`Button`'s four hooks were inert for a refactor's worth of time while the
-reference went on listing them, which is how that check came
-to exist.
+and read and never declared is a working feature nobody is told about.
 
 Each component's page lists its hooks under Custom properties.
 
@@ -77,10 +76,8 @@ internal structure.
 
 **A published part is a promise**, held both ways:
 a documented part that nothing renders, and a rendered part nobody was told
-about. The second is the worse of the two, because a `::part()` that resolves to
-nothing is valid CSS that matches nothing and reports nothing. `Breadcrumbs`
-published a `nav` part the family does not render; `Checkbox` renders the
-`field` part the whole styled appearance is built on and never declared it.
+about. The first is the worse of the two for you, because a `::part()` that
+resolves to nothing is valid CSS that matches nothing and reports nothing.
 
 Each component's page lists its parts.
 
@@ -105,12 +102,11 @@ its arrow is `tooltip-arrow`.
 `Command` forwarded the listbox's `search-field` under a name it also rendered
 itself, so `::part(search-field)` matched two elements at once.
 
-This is checked in both directions. `check:parts` holds a published part and a
-rendered one to each other, and `check:exportparts` holds a composition to
+This is checked in both directions. `helix component`'s `parts` holds a published part and a
+rendered one to each other, and `helix component`'s `exportparts` holds a composition to
 forwarding everything its child publishes, under one prefix, colliding with
-nothing. Before it existed, 148 published child parts were unreachable: all
-sixteen of the color picker's from inside a color input, all thirteen of the
-date picker's from inside a date input.
+nothing. So every part the color picker publishes is reachable from inside a
+color input, and every part the date picker publishes from inside a date input.
 
 If you still find a part you cannot reach, that is worth reporting rather than
 working around: the missing part is the bug.

package/content/routing.mdx

@@ -34,9 +34,9 @@ amount of JavaScript reproduces:
 - right-click offers Copy Link Address
 - a crawler follows it
 
-Before `href` existed, the docs sidebar put a `<Link>` inside each row. The
-anchor was 57px of a 240px row, so five sixths of every row did nothing, and
-Enter did nothing at all: the tree announced a selection and no anchor heard it.
+A `<Link>` inside each row buys none of it. In the docs sidebar the anchor was
+57px of a 240px row, so five sixths of every row did nothing, and Enter did
+nothing at all: the tree announced a selection and no anchor heard it.
 
 ## `href` and a framework's `<Link>`
 
@@ -195,7 +195,7 @@ host is the only element the listbox can point at.
 same browser, the accessibility tree for `<div role="option"><a href>Open
 settings</a></div>` inside a listbox is an option with *no accessible name*, and
 the link exposed as a child of it. The sibling option with plain text is named
-correctly. So the manoeuvre that works for `treeitem` and `menuitem`, moving the
+correctly. So the maneuver that works for `treeitem` and `menuitem`, moving the
 role onto the anchor, is exactly the one thing that cannot be done here.
 
 Two constraints pointing opposite ways, and no arrangement satisfies both.

package/content/server-rendering.mdx

@@ -39,7 +39,7 @@ has a tree.
 **Anything that inspects the tree runs in `firstUpdated` or later**, and is
 therefore a client-side enhancement by definition.
 
-## Never initialise state in `connectedCallback`
+## Never initialize state in `connectedCallback`
 
 SSR does not call it. Derive from properties, or seed in `willUpdate`, which SSR
 does call.

package/content/shape-and-borders.mdx

@@ -25,18 +25,30 @@ square: a percentage radius on a wide element gives an ellipse, and a pill is
 what you wanted.
 
 Rounding is the fastest single change to how a system feels, and it is one
-token:
+token, but it is the **seed** rather than one of the four above:
 
 ```css
 :root {
-  --helix-radii-md: 2px;
+  --helix-seed-radii: 2px;
 }
 ```
 
-That makes every card, dialog, input and button squarer at once. The theme
+That makes every card, dialog, input and button squarer at once, because `sm`,
+`md` and `lg` are all derived from it: they become 1px, 2px and 3px. The theme
 engine takes a `radius` intent input for exactly this reason. See [Deriving a
 theme](./theming).
 
+**Setting `--helix-radii-md` instead moves only what reads `md`**, which is
+neither the buttons, the inputs and the dialogs (`sm`) nor the cards (`lg`).
+The four rungs are siblings derived from the seed, not a chain, so overriding
+one is how you change a single step on purpose rather than how you reshape a
+system.
+
+**Every floating panel takes `sm`.** A dialog, a drawer, a menu, a popover, a
+tooltip, a toast, and the panel any field opens under itself: all the same
+corner, whatever the panel's size. A radius is read against the corner beside it
+rather than against the area behind it.
+
 **A shape that is round rather than softened does not use these.** An avatar, a
 loader and a radio are circles because of what they are, so they say `50%`
 directly and are unaffected by a theme that squares everything else off.
@@ -59,11 +71,10 @@ belong to [Surfaces and separation](./surfaces-and-separation): they are what a
 theme sets to zero to go shadow-first, or to a width to go border-first.
 
 This distinction is why a component's border width sits behind a per-component
-hook rather than being written inline. Of 68 border declarations reaching for
-`--helix-color-border` before this was fixed, eight put the *color* behind a
-hook and none put the width behind one, so a border could be recoloured and
-never removed, and the floating surfaces wrote `border: none` outright so one
-could never be added either.
+hook rather than being written inline. A width written inline can be recolored
+by a theme and never removed, and a hardcoded `border: none` can never have one
+added back, so a surface themes perfectly in one direction and not at all in the
+other.
 
 ## Corner radius on a group
 

package/content/space-and-size.mdx

@@ -49,7 +49,7 @@ Use them for gap, padding and margin:
 
 ## Size
 
-Thirty-four tokens, and almost all of them name a specific thing:
+Forty-one tokens, and almost all of them name a specific thing:
 `--helix-size-control`, `--helix-size-checkbox`, `--helix-size-switch`,
 `--helix-size-avatar`, `--helix-size-icon`, `--helix-size-tag`,
 `--helix-size-header`, `--helix-size-progress`, `--helix-size-meter`.

package/content/state-and-control.mdx

@@ -21,11 +21,11 @@ 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.
 
-*This page said the opposite until 26 Aug 2026, and the sample above was printed
-as plain text with an instruction not to paste it. Writing a property was a
-claim of ownership, so the element announced its changes and applied none of
-them until it was told, and that markup produced a field that ignored every
-keystroke with nothing logged and nothing visibly wrong.*
+*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.*
 
 ## Taking a decision
 

package/content/svelte.mdx

@@ -39,7 +39,7 @@ because Svelte was already right about custom elements.
 `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.
 
-And a declared `value`, `open`, `checked` or `active` is a claim of ownership:
-the element announces and waits rather than applying the change itself. Use
-`default-value` and its siblings when you want the element to own its own state.
+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).

package/content/theme-builder.mdx

@@ -55,7 +55,7 @@ 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 176 literal values is frozen at the version that produced
+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.
 
 ## What it does not do

package/content/theming.mdx

@@ -63,7 +63,7 @@ console.log(toCss(theme))
 ```
 
 The emitted block carries the seeds as well as the tokens, so the halves the
-engine does not compute, the twenty-four series colours a chart reads, the
+engine does not compute, the twenty-four series colors a chart reads, the
 spacing scale and the corner radii, re-derive from the same values the solver
 used. That is what stops the two paths disagreeing on the same page.
 

package/content/tiers.mdx

@@ -15,7 +15,7 @@ direction never reverses.
 | `@fusion.dev/helix-styles` | Tokens and the base layer. Pure CSS | nothing |
 | `@fusion.dev/helix-core` | Element base class, mixins, decorators | Lit |
 | `@fusion.dev/helix-headless` | Structure, accessibility, state, form participation | `core` |
-| `@fusion.dev/helix` | Presentation: tokens, parts, and the visual axes | `headless`, `styles` |
+| `@fusion.dev/helix` | Presentation: tokens, parts, and the visual axes | `headless`, `turbo run styles` |
 
 `@fusion.dev/helix-theme` and `@fusion.dev/helix-icons` ship beside the stack rather than in it:
 neither is a tier, and neither is needed to render a component. **There is no
@@ -25,7 +25,7 @@ the bridge that repairs React's hydration of custom events is in
 
 ## Why the split
 
-**`headless` must never depend on `styles`.**
+**`headless` must never depend on `turbo run styles`.**
 
 That single constraint is what makes the headless tier independently
 consumable. Consume it and bring your own

package/content/tokens.mdx

@@ -42,10 +42,10 @@ be lifted into: a raised surface goes *down* the ramp, not up.
   groove.
 
 **`raised` and `overlay` are the pair worth learning.** They land on the same
-step in dark mode, which is why one token tried to do both jobs for a while. In
-light they want opposite fills: a hovered row must be darker than a white page,
-and a thumb must be lighter than the groove it sits in. If something looks
-almost right in dark and wrong in light, this is usually why.
+step in dark mode, so one token looks like it would do both jobs. In light they
+want opposite fills: a hovered row must be darker than a white page, and a thumb
+must be lighter than the groove it sits in. If something looks almost right in
+dark and wrong in light, this is usually why.
 
 ## Per-component hooks
 

package/content/using-helix-with-an-agent.mdx

@@ -48,37 +48,37 @@ request and names every document plus these two surfaces.
 
 These are in order of how often they look like a library bug and are not.
 
-### 1. A declared `value` hands you the control
+### 1. Refusing a change by not answering
 
-```text
-<!-- Ignores every keystroke. Nothing is logged. Nothing looks wrong. -->
-<helix-input label="Name" value="Ada"></helix-input>
-```
-
-Do not paste it. Plain text rather than a live example, the same way
-[State and control](./state-and-control) shows this one: a reader copies what is
-in front of them, and these are the two pages that have to show the mistake in
-order to name it.
-
-**Writing `value`, `open`, `checked` or `active` is a claim of ownership.** From
-then on the element announces changes and applies none of them, waiting to be
-told. Which mode it is in is read once, at its first update.
-
-Seed with the `default-` twin, or answer the event:
+**Writing `value`, `open`, `checked` or `active` is a seed and a correction.**
+The element starts there and goes on applying its own changes, exactly as
+`<input value="Ada">` does, so this works and needs no handler beside it:
 
 ```html
 <helix-input
-  default-value="Ada"
   label="Name"
+  value="Ada"
 ></helix-input>
 ```
 
+The trap is on the other side. React force-restores a native `<input>` whose
+state did not move and does not do this for a custom element, so a handler that
+declines to call `setState` leaves the element holding the new value. Refusal is
+`preventDefault()` on the matching `helix-before-*` event:
+
 ```tsx
-<helix-input label="Name" onChange={(e) => setName(e.currentTarget.value)} value={name} />
+<helix-input
+  label="Name"
+  onhelix-before-change={(event) => {
+    event.preventDefault()
+    setName(clean(event.detail.value))
+  }}
+  value={name}
+/>
 ```
 
-In TypeScript this is a compile error rather than a surprise. Everywhere else the
-element warns on its second unanswered request.
+`default-value` and its twins are what a reset returns to. See
+[State and control](./state-and-control).
 
 ### 2. The event name is the event's own
 
@@ -120,10 +120,11 @@ The tell for a missing layer is which. A flash before hydration is
 `elements.css`; bare headings are `base.css`. **No color anywhere means the
 ramp or the semantic layer, and the two are told apart by what is in the
 stylesheet rather than by what is on screen**: without `tokens.css` nothing
-declares `--helix-color-*` at all, while without `primitives.css` all 177 are
-declared and every one resolves to `rgba(0, 0, 0, 0)`, since `tokens.css` refers
-to a primitive 235 times and to nothing else. The second is the one that looks
-like a working install, and it is the reason `all.css` exists.
+declares `--helix-color-*` at all, while without `primitives.css` all 185
+semantic tokens are declared and every color resolves to `rgba(0, 0, 0, 0)`,
+since `tokens.css` refers to a primitive 297 times and to nothing else. The
+second is the one that looks like a working install, and it is the reason
+`all.css` exists.
 
 ## Choosing a family
 
@@ -145,9 +146,11 @@ Two distinctions worth knowing before searching:
 
 Three doors, in the order to try them.
 
-1. **A token.** `--helix-radii-md: 2px` at `:root` reaches every component,
+1. **A token.** `--helix-seed-radii: 2px` at `:root` reaches every component,
    because custom properties inherit. Most "can I restyle the button" is really
-   "our brand has less rounding".
+   "our brand has less rounding". The seed and not `--helix-radii-md`: the four
+   radii are siblings derived from it, so `md` alone moves neither the buttons
+   nor the cards.
 2. **A per-component hook.** `--card-padding` on `helix-card`. Named after the
    component, documented on its page, defaults to a semantic token.
 3. **A part.** `helix-select::part(trigger)`. The most powerful and the one that
@@ -189,7 +192,7 @@ for the API.
 
 | Tool | Where it goes |
 |---|---|
-| Claude Code | `CLAUDE.md`, or a skill in `.claude/skills/` |
+| Claude Code | `AGENTS.md` or `CLAUDE.md`, or a skill in `.claude/skills/` |
 | Cursor | `.cursor/rules/` |
 | GitHub Copilot | `.github/copilot-instructions.md` |
 | Anything else | Whatever it reads. The line is the same |

package/content/using-the-elements.mdx

@@ -63,8 +63,6 @@ inspecting it.
 - `onHelixOpen` binds an event called `HelixOpen`, which nobody dispatches. ❌
 
 The number of hyphens does not matter, measured in Chrome against React 19.2.8.
-An earlier version of this page said two were a hard stop; that was the
-hydration bug above, read as a fact about names.
 
 ## Register once, in a client component
 

package/content/visual-axes.mdx

@@ -29,8 +29,7 @@ vocabularies. You cannot invent a value, and a component may take a subset.
 ## Why two axes
 
 **The library had four axes and one word for all of them.** Counted across both
-tiers, `appearance` held 21 declarations describing at least four different
-questions: where a surface ends (`outlined` against `plain` on a Card), how much
+tiers, `appearance` described at least four different questions: where a surface ends (`outlined` against `plain` on a Card), how much
 ink a control claims (`ghost` against `solid` on a Button), which widget gets
 rendered (`segmented` against `underlined` on Tabs), and in one case a plain
 misfiled tone.
@@ -45,10 +44,9 @@ and a component reintroducing it fails the build.
 
 ## Two axes, not one
 
-This is the test, and the library found it before the registry existed.
-`megamenu-root.css` reads: a consumer can make the panel glass, which is not an
-appearance, because `full` already occupies that axis with a layout. A panel can
-be glass *and* outlined. Two axes.
+This is the test. `Megamenu` is the worked example: a consumer can make the panel
+glass, which is not an appearance, because `full` already occupies that axis with
+a layout. A panel can be glass *and* outlined. Two axes.
 
 If you are adding a property and cannot decide which axis it belongs to, that is
 usually the answer: it is two properties.
@@ -66,7 +64,7 @@ choice between two widgets, which is structural wherever it is made, so it lives
 on either tier.
 
 **What it may not be is a place to put something that is on an axis.** That is
-the failure mode `appearance` demonstrated for 21 components.
+the failure mode `appearance` demonstrated.
 
 ## `tone` is the one axis both tiers carry
 

package/content/without-a-bundler.mdx

@@ -107,11 +107,10 @@ against the stylesheet's own URL with no bundler involved. Copy the whole
 four requests and both layers resolve.
 
 *This page listed `tokens.css` and `base.css` and no `primitives.css` until 24
-Aug 2026, which is the same omission `installation.mdx`, `introduction.mdx` and
-the agent page carried. `tokens.css` refers to a primitive 235 times and imports
-nothing, so a reader who followed this got all 178 semantic tokens declared and
-every one resolving to `rgba(0, 0, 0, 0)`. Linking `all.css` is the fix that
-cannot be got wrong again.*
+Aug 2026. `tokens.css` refers to a primitive 297 times and imports nothing, so a
+reader who followed that got all 185 semantic tokens declared and every color
+resolving to `rgba(0, 0, 0, 0)`. If your page looks unstyled in exactly that
+way, link `all.css` instead.*
 
 `elements.css` stays its own link, being `@fusion.dev/helix`'s rather than this
 package's, and it matters more here than anywhere: with no bundler the module

package/dist/catalog.d.ts

@@ -2,13 +2,10 @@
  * The component catalog: manifests and example markup, as one shape a reader
  * can render.
  *
- * **Pure, and it lives here for the same reason `reference()` does.** This is
- * Helix knowledge, and it used to sit in a marketing app: once both an HTML
- * page and a `.md` route need it, leaving it there means one of them imports
- * across a domain boundary to get at it. Reading the manifests and the
- * `.examples/*.html` files off disk is the caller's job, because a content
- * package that touched the filesystem would trace itself into every consumer's
- * server bundle.
+ * **Pure, and it lives here for the same reason `reference()` does.** Reading
+ * the manifests and the `.examples/*.html` files off disk is the caller's job,
+ * because a content package that touched the filesystem would trace itself
+ * into every consumer's server bundle.
  *
  * Two sources and no third: the manifests describe the API, and the example
  * files hold the markup. Nothing about a component is written down here, which
@@ -105,30 +102,24 @@ export interface Example {
     /**
      * The same example authored in TSX, which is a file and never a conversion.
      *
-     * **Both syntaxes are authored, neither derived.** The sandbox used to run
-     * the HTML through `htmlToJsx` when a reader asked for TSX, which is the
-     * mistake `build-headless-examples.mjs` made one axis over and this package
-     * already rejected once: a derived example is a function of its twin rather
-     * than a thing anybody wrote. It also did not work. Every example carrying a
-     * `<script>` converted to a JSX fragment with a `<script>` in it, which is a
-     * syntax error rather than a bad example, and three separate faults hit the
-     * script-free ones as well.
+     * **Both syntaxes are authored, neither derived.** A derived example is a
+     * function of its twin rather than a thing anybody wrote, and converting the
+     * HTML mechanically does not work: an example carrying a `<script>` becomes
+     * a JSX fragment with a `<script>` in it, which is a syntax error rather
+     * than a bad example.
      *
-     * `check:examples-paired` holds the two files to each other and
-     * `check:visual` holds the two pictures to each other.
+     * `helix component`'s `examples-paired` holds the two files to each other and
+     * `check:spec:visual-parity` holds the two pictures to each other.
      */
     tsx: string;
     /**
      * Which tier the example shows, read from what it renders.
      *
-     * Off the markup rather than off the filename, the same test `check:tokens`
+     * Off the markup rather than off the filename, the same test `helix component`'s `tokens`
      * uses to know a headless example's stylesheet may write raw values: an
      * example is a headless one when it renders a `helix-headless-` element.
-     * When this was written the file was called `headless.html` and the name
-     * could have answered, which is why the comment argued against relying on
-     * it. Both tiers call theirs `preview.html` now, the package directory
-     * carrying the tier, so the name cannot answer and this is the only fact
-     * available. The word `base` was the tier's old name and is gone with it.
+     * Both tiers call theirs `preview.html`, the package directory carrying the
+     * tier, so the name cannot answer and this is the only fact available.
      */
     tier: 'headless' | 'styled';
 }
@@ -152,22 +143,21 @@ export interface Family {
  *
  * An example is up to two files, `<slug>.html` and an optional `<slug>.css`.
  * The HTML is the list: a stylesheet on its own is not an example, and
- * `check:examples` fails on one whose markup is missing rather than showing a
+ * `helix component`'s `examples` fails on one whose markup is missing rather than showing a
  * sandbox with a stylesheet and nothing to style.
  *
  * The pair is what the sandbox already shows, `index.html` beside `styles.css`,
  * so the second file is the one the reader is looking at rather than a build
- * step. It is also what replaced the `style` attributes these examples used to
- * carry: an inline style is unreachable from a stylesheet, cannot express a
- * hover or a media query, and teaches a reader to write the one thing the
- * library exists to avoid.
+ * step. Never an inline `style` attribute instead: it is unreachable from a
+ * stylesheet, cannot express a hover or a media query, and teaches a reader to
+ * write the one thing the library exists to avoid.
  */
 export interface ExampleSource {
     css: string;
     /** Family folder the example was found in. */
     family: string;
     html: string;
-    /** File name without its extension: `default`, `base`, `cards.base`. */
+    /** File name without its extension: `preview`, `headless`, `cards.headless`. */
     slug: string;
     /** The authored TSX beside the HTML, never a conversion of it. */
     tsx: string;