@fusion.dev/helix-docs 0.0.0-dev

package/content/color-modes.mdx

@@ -0,0 +1,87 @@
+---
+description: One attribute, two modes, and no token restated to honor it.
+section: Foundations
+title: Color modes
+---
+
+# Color modes
+
+Light and dark are one attribute and no duplicated tokens. There is no second
+stylesheet, no `.dark` class to toggle, and nothing to remember to update twice.
+
+## How it works
+
+```css
+:root {
+  color-scheme: light dark;
+  --helix-color-background: light-dark(#fff, #0b0b0d);
+}
+```
+
+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.
+
+## Setting the mode
+
+```html
+<html data-color-mode="dark">
+```
+
+`[data-color-mode="light"]` and `[data-color-mode="dark"]` set `color-scheme`,
+and `color-scheme` inherits, so the attribute works **on any element** rather
+than only on the root:
+
+```html
+<div data-color-mode="light">
+  <!-- A light preview inside a dark page. One attribute. -->
+</div>
+```
+
+That is the whole mechanism, and it is why the theme builder can show you a
+light and a dark rendering of the same component side by side without rendering
+two documents.
+
+## Following the system
+
+Unset, `:root` declares `color-scheme: light dark`, which means the operating
+system decides. That is the default and it is usually right.
+
+A `prefers-color-scheme` media query still exists in the token layer for one
+narrow case rather than being the mechanism: a value that has to be *derived*
+from the mode, rather than chosen between two, cannot be expressed as
+`light-dark()` and has to ask which mode is current.
+
+## The one component that inverts
+
+`Toast` renders in the opposite mode to the page it is on, which is why it is
+the exception written into the base layer:
+
+```css
+helix-toast:not([data-color-mode]) {
+  color-scheme: var(--_helix-mode-inverted);
+}
+```
+
+A toast is chrome over the page rather than part of it, and inverting is how it
+reads as separate without a border. Opt out by putting `data-color-mode` on it,
+which then wins, because the rule only applies to a toast that has not been
+told.
+
+## What this means for your own CSS
+
+Write `light-dark()` for your own colours and set nothing else:
+
+```css
+.callout {
+  background: light-dark(#eef, #223);
+}
+```
+
+It will follow the page, follow a subtree that was told otherwise, and follow
+the system when nothing has said. Do not write a `prefers-color-scheme` query
+for it, and do not key off the `data-color-mode` attribute: both stop working
+the moment a subtree overrides the mode, which is the case this design exists to
+make cheap.

package/content/color.mdx

@@ -0,0 +1,92 @@
+---
+description: The roles, the ramps, and why the palette is solved rather than picked.
+section: Foundations
+title: Color
+---
+
+# Color
+
+Seventy-four of the library's 177 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.
+
+## The roles
+
+**Grounds**, which things sit on. `background` is the page itself, and the
+surfaces above it are a ladder rather than a set:
+
+[//]: # (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)
+
+Which one to reach for is a question about the geometry rather than about the
+shade, and it is the thing people most often get wrong. See [Surfaces and
+separation](./surfaces-and-separation).
+
+**Inks**, which go on grounds. `foreground`, then `foreground-muted` and
+`foreground-subtle` for text that recedes, and `foreground-on-accent` for text
+that sits on a filled accent rather than on a surface.
+
+**Intent**, which says what something means. `primary` and `accent` for
+emphasis, each with `-hover`, `-active` and `-subtle`; `info`, `success`,
+`warning` and `danger` for status, each with a `-surface` and a `-surface-hover`
+for the tinted box the message sits in.
+
+**Series**, twenty-four of them, for charts. Ordered rather than arbitrary: a
+chart with three lines uses the first three, and they are chosen to stay
+distinguishable in that order rather than to look good as a full set.
+
+**Syntax**, eight roles for code: `callable`, `comment`, `constant`, `invalid`,
+`keyword`, `name`, `string`, `tag`. Deliberately fewer than a full editor theme,
+because a code block in documentation is read rather than edited.
+
+## OKLCH
+
+Every color is authored in OKLCH. Equal numeric steps in sRGB are not equal
+perceptual steps, which makes both ramp generation and contrast arithmetic
+unreliable: a ramp that is even by the numbers looks uneven, and a contrast
+solver working in the wrong space cannot converge on a target it can measure.
+
+Concretely, this is what lets the theme engine take a brand color and *solve*
+for a palette rather than have someone pick one. See [Deriving a
+theme](./theming).
+
+## Contrast is a guarantee
+
+The engine measures every ink against the ground it will really be painted on
+and searches for the lightness that meets the target, rather than proposing a
+value and checking it afterwards. Every pairing it produces meets the target by
+construction.
+
+That guarantee is only as good as the list of pairs somebody thought of, so two
+things are checked rather than one. The engine's declared surface model is held
+against what components actually paint, and then every pairing is measured on a
+laid-out page, which is the only way to see the ones no stylesheet states: just
+eleven rules in the library set an ink and a ground together, where 165 set only
+an ink and 112 only a ground, and a pairing the cascade assembled is still a
+pairing a reader has to be able to read.
+
+## Do not reach past the semantic layer
+
+```css
+/* Yours to read. */
+color: var(--helix-color-foreground-muted);
+
+/* Not yours to read, and `check:tokens` fails the build on it. */
+color: var(--_helix-neutral-500);
+```
+
+The primitive layer underneath, `--_helix-neutral-500` and its kind, is
+`helix/styles`'s own business. The underscore marks it private and the
+indirection is the whole point: it is what lets a theme change what
+`--helix-color-primary` resolves to without every component knowing which step
+of which ramp it happened to be.

package/content/composition.mdx

@@ -0,0 +1,171 @@
+---
+description: Families, parts and groups, and which to reach for.
+section: Essentials
+title: Composition
+---
+
+# Composition
+
+Helix has families, parts and groups, and they are not stylistic choices. Each
+answers a different question, and knowing which you are looking at tells you
+what to import and what to write.
+
+## Namespaces mean composition
+
+`Tabs.Root` contains `Tabs.Tab`. The namespace says *this goes inside that*.
+
+It never says *this is a version of that*. An icon-only button is not a part of
+`Button`, so `IconButton` is top-level. The rule falls out of one line:
+
+> Variants are props. Alternatives are separate components.
+
+A button that is filled instead of outlined is the same component with a
+different `emphasis`. A button that holds only an icon has a different
+accessible-name requirement and a different shape, so it is its own component.
+
+## When a region becomes an element
+
+When it has behavior, state or API. Otherwise it is a slot.
+
+`Card`'s header, body and footer carried none of the three, so five elements
+became one and a title became a real `<h2>` the consumer writes. `Tabs.Tab`,
+`Select.Option` and `Accordion.Item` do carry state, so they stay elements.
+
+**An empty region still costs layout.** A `<slot>` is `display: contents`, so an unassigned one generates no
+box: no grid row, no flex item, no gap. A wrapper generates one either way.
+Measured on Card with identical content: wrappers present but empty rendered
+85px against an ideal of 53px. Bare slots rendered 53px with no hiding logic at
+all.
+
+## When a group is a part
+
+The test is whether the group reports a form value.
+
+**`Radio.Group` and `Toggle.Group` do.** They own the `name`, the `value` and
+the validity, and a lone radio is not a control at all: it is an answer to one.
+The group is what the family is *about*, so it is a part of it, and the member
+has nowhere else to be.
+
+**`Checkbox Group` and `Button Group` do not.** Neither calls `setFormValue`.
+Each checkbox is form-associated and submits itself; the group adds
+`role="group"`, a shared name, and one place to read the set. A button needs no
+group at all. Both are their own families, because their members are complete
+controls that the family does not need the group to explain.
+
+A container holding mixed content is a family for the same reason. `Toolbar`
+holds buttons, dropdowns and inputs, and is about none of them.
+
+## A content property is its slot's fallback
+
+Where a property carries content rather than configuration, it is the fallback
+content of a slot of the same name, never a second thing rendered beside it.
+
+```html
+<!-- The property -->
+<helix-tooltip content="Save"></helix-tooltip>
+
+<!-- The slot, which replaces it -->
+<helix-tooltip>
+  <strong>Save</strong>, or press <helix-kbd>⌘S</helix-kbd>
+</helix-tooltip>
+```
+
+Text stays an attribute, because that is what most tooltips and most avatars
+hold. Anything richer replaces it by being slotted. Both can never show at once,
+and no component has to detect which you did.
+
+One trap: **a whitespace-only text node is assigned to the default slot and
+defeats its fallback.** A newline between the tags is enough. That is
+why some examples close on the same line they open.
+
+## Width comes from the layout
+
+There is no `width` or `fill` property on a button, for the same reason there is
+no `size` one: how wide a control is says something about the region it is in.
+
+A button already stretches in a column flex or a grid, because that is what a
+stretch-aligned parent does to its children:
+
+```html
+<helix-flex direction="column">
+  <helix-button
+    emphasis="solid"
+    tone="primary"
+  >Fills its column</helix-button>
+</helix-flex>
+```
+
+To make one hug its label instead, tell the layout:
+
+```css
+.hug {
+  align-self: start;
+}
+```
+
+```html
+<helix-button class="hug">Hugs its label</helix-button>
+```
+
+The default surprises people: dropping a button into a column makes it full
+width, and the instinct is to look for a property that turns that off.
+
+**A fixed width is a different question, and it belongs to your site.** A
+marketing page whose hero buttons are all the same width is a real and reusable
+practice, but the number is a fact about that page's design, not about buttons.
+Name it once where your other page constants live:
+
+```css
+:root {
+  --site-cta-inline-size: 13rem;
+}
+
+.heroActions helix-button {
+  min-inline-size: var(--site-cta-inline-size);
+}
+```
+
+The same reasoning puts a hero's type size outside the component scale: a
+marketing hero is not a component, so its measurements are the site's own.
+
+## One property per intent
+
+Every field control names itself the same way, and there are exactly two cases.
+
+```html
+<helix-input label="Files"></helix-input>       <!-- a visible label -->
+<helix-input aria-label="Files"></helix-input>  <!-- named, nothing drawn -->
+<helix-input></helix-input>                     <!-- unnamed. avoid -->
+```
+
+`label` means a label. `aria-label` means a name. Neither means a control a
+screen reader announces as "edit text", which is almost never what you want.
+If the page already makes the purpose plain, that is the `aria-label` case, not
+the empty case.
+
+**`aria-label` works here because the component forwards it**, which is not true
+of custom elements in general. A custom element
+cannot delegate a label to the control inside its shadow root: an `aria-label`
+you write on the host sits on a wrapper and never reaches the `<input>` that
+actually takes focus. Measured on this library before it was fixed, the inner
+input came back with no label and no name at all.
+
+So the field renders the label and clips it, and the name arrives through the
+same `<label for>` a visible one does.
+
+There used to be a `hide-label` boolean beside `label`. It is gone: one
+attribute supplying a label and a second saying not to show it is the absence of
+the first, spelled twice.
+
+## Shared behavior becomes its own family
+
+`Option`, `Listbox` and `Select` are three families rather than one because the
+keyboard, the filtering, the multi-select rules and the active-item tracking
+should be written once. `Select` renders a `Listbox` internally; a future
+combobox will; a command palette would.
+
+The same reasoning made `DrilldownController`: `Menu` had held a page stack and
+derived its rows since it was written, and none of that was about menus. `Menu`
+and `Drilldown` share it now.
+
+If you are about to write the second copy of something, that is the signal.

package/content/elevation-and-material.mdx

@@ -0,0 +1,93 @@
+---
+description: Five layers, four shadows, and the glass the material tokens make possible.
+section: Foundations
+title: Elevation and material
+---
+
+# Elevation and material
+
+## Layers
+
+[//]: # (tokens:layer)
+
+| Token | Value |
+| --- | --- |
+| `--helix-layer-beneath` | `-1` |
+| `--helix-layer-base` | `0` |
+| `--helix-layer-raised` | `10` |
+| `--helix-layer-sticky` | `100` |
+| `--helix-layer-overlay` | `1000` |
+| `--helix-layer-toast` | `1200` |
+
+[//]: # (/tokens)
+
+Five, named after what lives at each rather than numbered. A numbered scale
+invites `z-index: 1001`, and the number nobody can justify is how stacking
+context bugs start.
+
+| Layer | What is at it |
+|---|---|
+| `base` | The document |
+| `raised` | Something lifted but still in the flow: a hovered row, a dragged card |
+| `sticky` | A header or a column that stays while content scrolls under it |
+| `overlay` | Menus, dialogs, popovers, tooltips |
+| `toast` | Above everything, including a modal |
+
+**Most overlays do not need these**, because they use the popover API and render
+in the browser's top layer, which is above every z-index by construction. The
+tokens are for the cases the top layer does not cover: your own sticky header,
+your own dragged element, and anything that has to sit between two of ours.
+
+## Shadows
+
+[//]: # (tokens:shadow)
+
+| Token | Value |
+| --- | --- |
+| `--helix-shadow-none` | `none` |
+| `--helix-shadow-sm` | `0 1px 2px var(--_helix-shadow-ink-sm)` |
+| `--helix-shadow-md` | `0 4px 12px var(--_helix-shadow-ink-md)` |
+| `--helix-shadow-lg` | `0 12px 32px var(--_helix-shadow-ink-lg)` |
+| `--helix-shadow-surface` | `var(--helix-shadow-none)` |
+| `--helix-shadow-floating` | `var(--helix-shadow-lg)` |
+
+[//]: # (/tokens)
+
+The first four are the values. The last two are the *decision*, and they are
+what a theme sets to make the system shadow-first or border-first. See [Surfaces
+and separation](./surfaces-and-separation).
+
+## Material
+
+Eight tokens describing translucency rather than color:
+
+[//]: # (tokens:material)
+
+| Token | Value | For |
+| --- | --- | --- |
+| `--helix-material-backdrop` | `blur(var(--helix-material-blur-md)) saturate(1.5)` | The wash behind a modal. |
+| `--helix-material-opacity` | `1` | How opaque a translucent surface is. |
+| `--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-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)
+
+These are what the `material` axis renders: `frosted`, `glass` and `transparent`
+are three points of one optical language, and they are an axis of their own
+rather than values of `emphasis`, because a panel can be glass *and* outlined
+and two things that can be true at once are two axes. See [Visual
+axes](./visual-axes).
+
+**Blur is expensive and is the one thing here worth being deliberate about.** A
+`backdrop-filter` forces the compositor to re-read what is behind the element on
+every frame it moves. A frosted header that is always on screen pays that
+continuously. Reach for `translucent` without the blur when the effect is about
+depth rather than about the texture.
+
+**`material-border` is not decoration.** A translucent surface takes its color
+from what is behind it, so on a busy background it has no edge at all. The
+border token is what keeps it a shape.

package/content/events.mdx

@@ -0,0 +1,125 @@
+---
+description: The request and the notification, why one name is prefixed and the other is not.
+section: Essentials
+title: Events
+---
+
+# Events
+
+**Every state change is announced twice, and the two are for different people.**
+
+```ts
+// The request. Cancelable, carries what is being proposed, and fires before
+// anything moves. This is how you take the decision.
+element.addEventListener('helix-before-change', (event) => {
+  if (locked) {
+    event.preventDefault()
+  }
+})
+
+// The notification, under the platform's own name. Fires after the value moved,
+// so it is on the target where every handler ever written expects it.
+element.addEventListener('change', (event) => {
+  save(event.target.value)
+})
+```
+
+Most consumers want the second. Bind `onChange` in React or `onchange=` in HTML
+and read the target, exactly as you would from an `<input>`. Reach for the
+prefixed one when you mean to refuse.
+
+The class exists rather than a bare `CustomEvent` for three reasons, all about
+the type reaching you: the class name is in the manifest, which is what lets the
+framework typings emit a typed callback instead of `(detail: unknown)`; the
+package augments `HTMLElementEventMap`, which types `addEventListener` for
+people writing plain HTML; and the name lives on the class, so a dispatch and a
+listener cannot disagree about the string.
+
+## Why the request is prefixed and the notification is not
+
+**Retargeting.** An event dispatched inside a shadow root is retargeted to look
+like it came from the host, so a bare `input` from a `<helix-input>` is
+indistinguishable from the inner control's own. Prefixed, it cannot be mistaken
+for either.
+
+**React's claimed verbs.** React's synthetic system owns `change`, `input`,
+`submit`, `copy`, `focus` and the rest, and a prop matching one of those is
+wired to the native event instead. `onhelix-before-change` matches none of them
+and reaches us, which is exactly what a request needs.
+
+**And the notification wants the opposite.** It is not prefixed precisely
+because React claims the verb: `onChange` on a Helix element goes through the
+synthetic system to the native `change` the element sends, which is why the
+ordinary path costs a consumer nothing to learn.
+
+**The type map is global.** `HTMLElementEventMap` is shared with every element
+in your application. Our classes extend `Event`, so an entry named `select`
+would not fail to compile: it would silently retype
+`textarea.addEventListener('select', …)` as carrying our detail, which at
+runtime is `undefined`. Measured. An unprefixed name is not a collision we would
+notice, it is one you would.
+
+## Propagation follows the event's role
+
+**Lifecycle does not bubble and is not composed.** `helix-before-open` and
+`helix-before-close`. Overlays nest, and an inner one's lifecycle must never reach the
+outer one that contains it: a menu closing inside a dialog is not the dialog
+closing.
+
+**Coordination bubbles and is composed.** `helix-select`, `helix-dismiss`,
+`helix-before-change`. A parent, or a router, can intercept one across a shadow
+boundary, which is what makes a `Tree` usable as navigation.
+
+If you are listening on a container and hearing nothing, the event is probably a
+lifecycle one and the listener belongs on the element itself.
+
+## Canceling
+
+The events that precede a state change are cancelable, and that is the only way
+to refuse one:
+
+```ts
+dialog.addEventListener('helix-before-close', (event) => {
+  if (unsaved) {
+    event.preventDefault()
+  }
+})
+```
+
+Every dispatched event is held to a declaration and every declaration to a
+dispatch, so an event you can listen for is an event that is documented.
+
+## The set
+
+| Event | Roughly |
+|---|---|
+| `helix-before-change` | A value about to move, refusable |
+| `helix-before-toggle` | A checked state about to flip, refusable |
+| `helix-before-open`, `helix-before-close` | An open state about to move, refusable |
+| `helix-select` | An item chosen from a set |
+| `helix-dismiss` | The reader asked for something to go away |
+| `helix-next`, `helix-previous` | Movement through a sequence |
+| `helix-filter` | A query changed in a filtering control |
+| `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-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 |
+
+And the native ones every stateful component sends once the change has landed:
+`input` and `change` on a value control, `toggle` on anything that opens,
+carrying `newState` and `oldState` the way `<details>` does, `close` on a dialog,
+and `load` and `error` on an image.
+
+Each component's page lists the events it actually dispatches, with the class
+and the detail.
+
+## In a framework
+
+A native event is `onChange`, `onInput` or `onToggle`, which is what React and
+every framework already understand. A prefixed one is `on` and the name,
+verbatim: `onhelix-before-change`. Nothing strips the prefix and nothing
+camel-cases it, which is React's own behavior rather than a convention here. See [React](./react), [Vue](./vue) and
+[Svelte](./svelte).