@fusion.dev/helix-docs 0.0.0-dev

package/content/sandbox.mdx

@@ -0,0 +1,76 @@
+---
+description: The editor beside the preview, and how to build one of your own.
+section: Tooling
+title: Sandbox
+---
+
+# Sandbox
+
+[Open the sandbox](/helix/sandbox).
+
+Every example on a component's page is editable. Change the markup and the
+preview redraws; change the stylesheet beside it and the preview restyles.
+
+The same elements are what you would reach for to build a playground of your
+own, and the isolation below is what makes running someone else's markup safe.
+
+## The frame is sandboxed
+
+The preview runs in a sandboxed iframe with an opaque origin, and the script
+that drives it is served as a static classic script rather than rendered by a
+route.
+
+**What that buys:** markup typed into the sandbox runs in the frame, and an
+`<img onerror>` in it cannot read the surrounding page's cookies, its
+`localStorage`, or the editor's contents. Before the frame was isolated, it
+could. Measured.
+
+The classic script is the part that looks like packaging and is not: from an
+opaque origin, a module import or a `fetch` back to the site's origin is
+cross-origin and fails without CORS headers. A classic `<script src>` is not
+CORS-checked, so it is the one shape that can carry the component library into a
+document the page cannot reach into and which cannot reach back out.
+
+## Coordination is by event
+
+A source pane dispatches `helix-before-edit`, which bubbles, and the sandbox hands
+the value to whatever preview is slotted into it. Neither child knows the other
+exists, so either can be replaced or used alone.
+
+The event carries the pane's `name`, which is what lets one sandbox hold several
+panes without the root identifying senders by reference: `html` is the preview's
+markup and `css` is its stylesheet. A pane named anything else is showing
+something rather than driving it, and is ignored.
+
+```html
+<helix-sandbox>
+  <helix-sandbox-source
+    name="html"
+    slot="source"
+  >…</helix-sandbox-source>
+  <helix-sandbox-source
+    name="css"
+    slot="source"
+  >…</helix-sandbox-source>
+  <helix-sandbox-preview slot="preview"></helix-sandbox-preview>
+</helix-sandbox>
+```
+
+## The console is patched in the frame
+
+Logs from the example reach the page's console panel; logs from the page around
+it do not. That is deliberate and is the point of doing the patching in the
+frame rather than in the sandbox: it catches what the example itself logs and
+nothing else.
+
+## The package is private
+
+`@fusion.dev/helix-sandbox` does not publish. It is the editor and spec runner for this
+repository, and it is Helix tooling rather than a Helix product: the elements
+assume the frame, the frame assumes the build, and the build assumes this
+repository's layout.
+
+If you want an editable example in your own documentation, the honest answer
+today is that you would build it, and the manifest and the `.examples` files are
+what you would build it from. That is a gap rather than a policy, and worth
+telling us about.

package/content/server-rendering.mdx

@@ -0,0 +1,103 @@
+---
+description: What renders without a DOM, and what has to wait for one.
+section: Essentials
+title: Server rendering
+---
+
+# Server rendering
+
+Every component renders on a server with no DOM. If you are only consuming
+Helix, the practical consequence is small: components work in your server
+components and there is nothing to configure. If you are extending one, the
+rules below are the whole contract.
+
+## There is no DOM
+
+Lit's element shim carries attributes. It does not carry a tree. `querySelector`
+is undefined, `this.children` is undefined, and anything that walks the DOM
+throws while rendering.
+
+Two real examples from this library, both found the first time their component
+was given a server spec:
+
+```ts
+// Select. `display` is read during render and reached the render root.
+private get listbox() {
+  return this.renderRoot?.querySelector('[part="listbox"]') ?? null
+}
+
+// Menu item. `hasSubmenu` is read during render and spread its children.
+get hasSubmenu(): boolean {
+  return [...(this.children ?? [])].some((child) => child.slot === 'submenu')
+}
+```
+
+Before those two guards, neither component could be server-rendered at all. Both
+looked correct in every browser, because the client always has a root and always
+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`
+
+SSR does not call it. Derive from properties, or seed in `willUpdate`, which SSR
+does call.
+
+## Guard generated ids
+
+```ts
+if (!this.id) {
+  this.id = `helix-${crypto.randomUUID()}`
+}
+```
+
+The server writes the id into the HTML; the client sees it present and skips
+generating a new one, so both agree. Without the guard they disagree and the
+association breaks on hydration.
+
+## Semantics on the host, presentation in the shadow root
+
+IDREFs do not cross shadow boundaries, so `aria-labelledby` inside a shadow root
+can never resolve to a light-DOM id. Use `ElementInternals`, which writes no
+attribute at all, so the host stays exactly as you wrote it and hydration has
+nothing to disagree about.
+
+**Labels are the case that catches people.** `<label for>` cannot reach into a
+shadow root either, which is why a field's label is rendered *inside* the
+control rather than by anything wrapping it, and why a wrapping "form field"
+component cannot own the label without handing it down as a property. It is also
+why `aria-label` on a host has to be forwarded rather than left where it was
+written. See [Composition](./composition).
+
+Where an id genuinely cannot reach, **element references can**, and they resolve
+outward: an element in a shadow root may point at one in the light DOM.
+`Listbox` uses that for `aria-activedescendant`, because its options are your
+elements and the element that takes focus is in its shadow root. Feature-test
+them: assigning to a property an engine does not implement is a no-op rather
+than an error.
+
+## A child announces itself to its parent
+
+A parent cannot poll for a child that has not upgraded yet. The child dispatches
+a bubbling ready event and the parent listens.
+
+## Writing a server spec
+
+Every component has a `*.ssr.spec.ts`, and there is one rule about them worth
+repeating, because it has produced a false pass twice:
+
+**Never assert structure against the raw SSR string.** Declarative shadow DOM
+inlines the component's stylesheet into the very markup being asserted, and that
+stylesheet names every part, host attribute and token the component uses. So
+`toContain('part="media"')` passes on a *selector*, and
+`not.toContain('data-scrolled')` fails on a `:host([data-scrolled])` *rule*,
+both saying nothing about what rendered.
+
+Use the helpers: `withoutStyles`, `hasPart`, `partTag`, `hostTag`. And match
+attribute bindings with a pattern, since they render across several lines:
+
+```ts
+expect(markup).toMatch(/<a\s+part="button"/) // ✅
+expect(markup).toContain('<a part="button"') // ❌ never matches
+```

package/content/shape-and-borders.mdx

@@ -0,0 +1,80 @@
+---
+description: Five radii, two widths, and the two tokens that are a policy rather than a value.
+section: Foundations
+title: Shape and borders
+---
+
+# Shape and borders
+
+## Radii
+
+[//]: # (tokens:radii)
+
+| Token | Value |
+| --- | --- |
+| `--helix-radii-none` | `0` |
+| `--helix-radii-sm` | `calc(var(--helix-seed-radii, 0.5rem) * 0.5)` |
+| `--helix-radii-md` | `var(--helix-seed-radii, 0.5rem)` |
+| `--helix-radii-lg` | `calc(var(--helix-seed-radii, 0.5rem) * 1.5)` |
+| `--helix-radii-full` | `9999px` |
+
+[//]: # (/tokens)
+
+`full` is `9999px` rather than `50%`, which matters for anything that is not
+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:
+
+```css
+:root {
+  --helix-radii-md: 2px;
+}
+```
+
+That makes every card, dialog, input and button squarer at once. The theme
+engine takes a `radius` intent input for exactly this reason. See [Deriving a
+theme](./theming).
+
+**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.
+
+## Border widths
+
+[//]: # (tokens:border)
+
+| Token | Value |
+| --- | --- |
+| `--helix-border-thin` | `1px` |
+| `--helix-border-thick` | `2px` |
+| `--helix-border-surface` | `var(--helix-border-thin)` |
+| `--helix-border-floating` | `0` |
+
+[//]: # (/tokens)
+
+The first two are values you pick. **The second two are a decision**, and they
+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.
+
+## Corner radius on a group
+
+Adjacent controls in a group flatten the corners between them, so a button group
+reads as one shape rather than three:
+
+```css
+[data-button]:not(:first-child) { border-start-start-radius: 0; }
+```
+
+The base layer does this for the recipes, and the components do it for
+themselves. If you build your own group: it is the inner corners that go flat,
+not the outer ones, and it is `border-start-start-radius` rather than
+`border-top-left-radius` so it follows the writing direction.

package/content/size-and-density.mdx

@@ -0,0 +1,86 @@
+---
+description: Why no control has a size, and what to write instead.
+section: Theming
+title: Size and density
+---
+
+# Size and density
+
+**A control has no size. It takes its height from the region it is in.**
+
+```html
+<helix-flex data-density="lg">
+  <helix-button
+    emphasis="solid"
+    tone="primary"
+  >See what is shipping</helix-button>
+</helix-flex>
+```
+
+There is no `size` prop on a button, an input, a select or a checkbox. That
+looks like a restriction and is not one.
+
+## Size does three jobs
+
+**Emphasis.** The `emphasis` axis carries it. A filled primary button says "this one
+matters" far louder than eight more pixels ever will.
+
+**Fit.** This is a fact about the region rather than about the control. A
+toolbar is tight, a hero is spacious, a table row is tighter still. The control
+does not know which it is in; the region does.
+
+**Optical role.** Real, and only for things that are not controls. An avatar at
+24 in a list and 96 on a profile is a different graphic, not a taller control.
+That is why `size` survives on `Avatar` and `Spinner` and nowhere else: those
+are pictures.
+
+## The test that settles it
+
+*Can two controls sitting together legitimately differ in height?*
+
+Save and Cancel. An icon button beside a text button. An input and its submit.
+The two halves of a split button. In every case the answer is no.
+
+So a per-instance size is only ever used to say something about the **region**,
+one element at a time, which is exactly how a row ends up with one member the
+wrong height. Said once on the region, a ragged row is not discouraged. It is
+unwritable.
+
+That is also what makes this safe for anything generating code, whether that is
+a person or a model: there is no size to get wrong, and one question to ask per
+region instead of one per element.
+
+## How to use it
+
+Put `data-density` on any container. `sm`, `md` or `lg`. `md` is the default and
+is never written.
+
+```html
+<helix-toolbar>
+  <!-- Nothing here needs a size. The toolbar is already dense. -->
+  <helix-button>Run</helix-button>
+  <helix-select label="Target"><!-- … --></helix-select>
+</helix-toolbar>
+```
+
+**Containers that are dense by nature declare it themselves.** The app header,
+the toolbar and the announcement all do, so a control put in one is already the
+right height without anybody deciding.
+
+It works through custom properties (`--helix-size-control`,
+`--helix-size-checkbox`, `--helix-size-switch`, `--helix-size-tag`), which is
+why it costs no component any API and crosses every shadow boundary on its own.
+
+The `-sm` / `-md` / `-lg` tokens are the scale and never move. The unsuffixed
+ones are the current step, and `data-density` is what moves them.
+
+## What this is not
+
+**`data-link-size` stays.** A text link has no control height: its size is
+typography, and it follows the text around it.
+
+**A control may still declare its own scale.** `--helix-size-switch` is one step
+above `--helix-size-checkbox` at every density, because a switch is a track with
+a thumb inside it and a checkbox is a box with a mark in it. That is the
+component choosing where it sits on the scale, once, for everyone. It is not the
+same thing as a consumer setting a height per instance.

package/content/space-and-size.mdx

@@ -0,0 +1,89 @@
+---
+description: One spacing scale, and why a control's height is not on it.
+section: Foundations
+title: Space and size
+---
+
+# Space and size
+
+Two scales that look similar and answer different questions. Space is the gaps
+between things. Size is how big a control is. Mixing them is how a layout ends
+up with a button that is one step of padding taller than the input beside it.
+
+## Space
+
+[//]: # (tokens:space)
+
+| Token | Value |
+| --- | --- |
+| `--helix-space-none` | `0rem` |
+| `--helix-space-2xs` | `calc(0.25rem * var(--helix-seed-density, 1))` |
+| `--helix-space-xs` | `calc(0.5rem * var(--helix-seed-density, 1))` |
+| `--helix-space-sm` | `calc(0.75rem * var(--helix-seed-density, 1))` |
+| `--helix-space-md` | `calc(1rem * var(--helix-seed-density, 1))` |
+| `--helix-space-lg` | `calc(1.5rem * var(--helix-seed-density, 1))` |
+| `--helix-space-xl` | `calc(2rem * var(--helix-seed-density, 1))` |
+| `--helix-space-2xl` | `calc(3rem * var(--helix-seed-density, 1))` |
+| `--helix-space-3xl` | `calc(4rem * var(--helix-seed-density, 1))` |
+| `--helix-space-control` | `var(--helix-space-md)` |
+
+[//]: # (/tokens)
+
+Nine steps, t-shirt named rather than numbered. A numbered scale invites
+arithmetic (`space-4` is twice `space-2`) which stops being true the moment the
+scale is tuned, and invites a `space-4.5` the first time something does not fit.
+
+`--helix-space-control` is the tenth and is different in kind: it is the inset a
+control uses, and it follows the region's density rather than sitting on the
+scale. See [Size and density](./size-and-density).
+
+Use them for gap, padding and margin:
+
+```css
+.toolbar {
+  display: flex;
+  gap: var(--helix-space-sm);
+  padding: var(--helix-space-md);
+}
+```
+
+## Size
+
+Thirty-four 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`.
+
+Most come in a `-sm`, `-md` and `-lg` set beside the unsuffixed one. **The
+unsuffixed token is the live one** and the suffixed ones are the values the
+density axis picks between. The loader is the exception: it has `-sm`, `-md`
+and `-lg` and no unsuffixed token above them, because nothing reads a loader's
+size off the density. So a component reads `--helix-size-control` and the
+region's `[data-density]` decides which of `-sm`, `-md` or `-lg` that resolves
+to.
+
+That is why a component has no `size` property: the answer is the region's, and
+saying it once there means a ragged row is not merely discouraged, it is
+unwritable.
+
+## The focus ring is three tokens
+
+```
+--helix-size-focus-ring     the ring's own thickness
+--helix-size-focus-offset   the gap between the control and the ring
+--helix-size-focus-reach    ring plus offset, for reserving room
+```
+
+The third exists because a ring drawn outside a control needs room, and every
+component that draws one otherwise recomputes the sum. Reserve with `reach`,
+draw with the other two.
+
+## What not to do
+
+**Do not use a size token for a gap.** `--helix-size-control` is a height, and a
+layout that uses it as a gap changes meaning the day a density changes under it.
+
+**Do not use a raw value because the scale has no step for it.** If a gap is
+genuinely between `sm` and `md`, say so rather than writing `11px`: it is
+usually a sign the two things being separated belong at different levels of the
+layout.

package/content/state-and-control.mdx

@@ -0,0 +1,132 @@
+---
+description: Why a declared property is a seed, and how to take a decision when you want it.
+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.
+
+```html
+<helix-input
+  label="Name"
+  value="Ada"
+></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.
+
+*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.*
+
+## Taking a decision
+
+Control is an action rather than a mode. Every change announces before it acts,
+and the announcement is cancelable:
+
+```ts
+input.addEventListener('helix-before-change', (event) => {
+  if (locked) {
+    event.preventDefault()
+  }
+})
+```
+
+`preventDefault()` refuses that one change and nothing moves. To own the state
+outright, refuse and assign your own:
+
+```tsx
+<helix-input
+  label="Name"
+  onhelix-before-change={(event) => {
+    event.preventDefault()
+    setName(sanitize(event.detail.value))
+  }}
+  value={name}
+/>
+```
+
+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 imperative form reports the same thing:
+
+```ts
+const applied = item.requestOpen(true)
+```
+
+`false` means something refused it.
+
+## Mirroring the state instead
+
+Most consumers want neither of the above. Bind the notification and let the
+element apply:
+
+```tsx
+<helix-input label="Name" onChange={(event) => setName(event.currentTarget.value)} />
+```
+
+```html
+<helix-input
+  label="Name"
+  onchange="save(this.value)"
+></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.
+
+## `default-` still means something
+
+```html
+<helix-input
+  default-value="Ada"
+  label="Name"
+></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.
+
+## State is a custom state, not an attribute
+
+```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]`.
+
+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:
+
+```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.

package/content/surfaces-and-separation.mdx

@@ -0,0 +1,99 @@
+---
+description: The four ways a surface is told apart, and the ground a component is not.
+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.
+
+## The four mechanisms
+
+| | |
+|---|---|
+| **Fill** | A different ground color to what is behind it |
+| **Edge** | A border |
+| **Lift** | A shadow |
+| **Space** | Nothing at all, and the gap does the work |
+
+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.
+
+Helix expresses the choice in 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. |
+
+[//]: # (/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.
+
+## The ladder
+
+A surface's ground says where it is, not what shade it is:
+
+[//]: # (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. |
+
+[//]: # (/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.
+
+## The common mistake
+
+**`--helix-color-background` is the page, and your component is not the page.**
+
+```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.
+
+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.
+
+**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.
+
+## 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).