@fusion.dev/helix-docs 0.0.0-dev

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

@@ -0,0 +1,231 @@
+---
+description: The four things that look like a library bug and are not, and where an agent should read from.
+parent: coding-agents
+section: Getting started
+title: Using Helix with an agent
+---
+
+
+# Using Helix with an agent
+
+**A page rather than a skill file, and the format is the point.** This started as
+`.claude/skills/using-helix/SKILL.md`, which is one vendor's format sitting in a
+repository, and every other vendor has its own: Cursor reads `.cursor/rules`,
+Copilot reads `.github/copilot-instructions.md`, and a consumer of the published
+packages has none of them because they have this site and no checkout.
+
+So the content lives once, here, at a URL that [llms.txt](https://fusion.dev/llms.txt) indexes and
+that every one of those formats can point at. Paste the link into whichever file
+your tool reads. What is vendor-neutral and executable is [the MCP
+server](./coding-agents), which Claude, Cursor, Windsurf and Zed all speak.
+
+## Read the manifest before writing a tag
+
+```
+https://fusion.dev/helix/custom-elements.json
+@fusion.dev/helix/custom-elements.json
+```
+
+Every tag, every property with its literal union, every event with its class,
+every slot, part and custom property. **The vocabulary is the file**: a tag that
+is not in it does not exist, and a property value outside a declared union is one
+the component rejects. Unions are literal rather than named for exactly this
+reason, so `'ghost' | 'outlined' | 'solid' | 'subtle'` answers the question where
+`ButtonEmphasis` sends you somewhere else.
+
+One family as data, when the whole manifest is more than the question needs:
+
+```
+https://fusion.dev/helix/components/<family>.json
+https://fusion.dev/helix/components/<family>.md
+```
+
+The `.md` carries the API tables **and the examples**, which the HTML page
+deliberately does not. Start from `https://fusion.dev/llms.txt`, which is one
+request and names every document plus these two surfaces.
+
+## The four things that go wrong
+
+These are in order of how often they look like a library bug and are not.
+
+### 1. A declared `value` hands you the control
+
+```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:
+
+```html
+<helix-input
+  default-value="Ada"
+  label="Name"
+></helix-input>
+```
+
+```tsx
+<helix-input label="Name" onChange={(e) => setName(e.currentTarget.value)} value={name} />
+```
+
+In TypeScript this is a compile error rather than a surprise. Everywhere else the
+element warns on its second unanswered request.
+
+### 2. The event name is the event's own
+
+`onhelix-before-open`, not `onHelixOpen` and not `onOpen`. React slices `on` off the
+prop and listens for exactly what is left, so the casing is not negotiable. From
+anything that is not React, `addEventListener('helix-before-open', …)`.
+
+**Lifecycle does not bubble and coordination does.** `helix-before-open` and
+`helix-before-close` reach the element and stop, so a menu closing inside a dialog is
+not the dialog closing; `helix-select`, `helix-before-change` and `helix-dismiss` cross
+shadow boundaries and can be caught on a container. If a listener on a wrapper
+hears nothing, it is a lifecycle event and belongs on the element.
+
+### 3. `:disabled`, never `[disabled]`
+
+```css
+helix-input:disabled { … }   /* right: matches a disabled fieldset too */
+helix-input[disabled] { … }  /* wrong: a fieldset sets no attribute */
+```
+
+A control inside `<fieldset disabled>` is disabled by the platform and carries no
+attribute, so the attribute selector paints it as live while it refuses input.
+
+### 4. Two stylesheets, then the elements
+
+```ts
+import '@fusion.dev/helix/helix.css'
+import '@fusion.dev/helix'
+```
+
+`helix.css` is `primitives.css`, `tokens.css`, `base.css` and `elements.css` in
+the order they have to be in. Write them out yourself only to substitute one.
+
+`elements.css` is the one people leave out, and everything works without it
+until the page is server-rendered: an element that has not upgraded has no
+styles of its own, so the markup flashes unstyled and then snaps into place.
+
+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.
+
+## Choosing a family
+
+Ask the manifest, not your memory. Each family's `helix.aliases` lists the other
+names it goes by, which is usually how a request arrives: `Segment` and `NavItem`
+are `Toggle`, `Key` is `Legend`, `Hint` is `Tooltip`.
+
+Two distinctions worth knowing before searching:
+
+- **A group is a part when it reports a form value** and its own family when it
+  does not. `Radio.Group` and `Toggle.Group` are parts; `Checkbox Group` and
+  `Button Group` are families whose members submit themselves.
+- **A control has no `size`.** Height comes from `data-density` on the region,
+  `sm` / `md` / `lg`, which crosses shadow boundaries through custom properties.
+  If two controls in a row must differ in height, the layout is wrong rather than
+  the API.
+
+## Styling from the outside
+
+Three doors, in the order to try them.
+
+1. **A token.** `--helix-radii-md: 2px` at `:root` reaches every component,
+   because custom properties inherit. Most "can I restyle the button" is really
+   "our brand has less rounding".
+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
+   couples you to internal structure.
+
+**Never read a primitive.** `--_helix-neutral-500` and its kind belong to
+`@fusion.dev/helix-styles`; the underscore says so and the indirection is the point.
+
+## No custom elements at all
+
+`@fusion.dev/helix-styles` is plain CSS with no JavaScript, and it carries recipes for
+markup Helix does not render:
+
+```html
+<button
+  data-button="solid"
+  data-button-tone="primary"
+>Save</button>
+<article data-prose><h2>From a CMS</h2></article>
+<div data-density="sm">…</div>
+```
+
+A recipe has appearance and no behavior: no state, no form participation, no
+focus trapping, no keyboard handling. If you are adding script to one, the
+component is what you wanted.
+
+## Pointing your tool at this page
+
+**A line, not a copy.** Every tool that reads project instructions reads a file
+in your repository, and they all read a different one. What goes in it is a
+pointer to this URL rather than its contents: a copy starts going stale the
+moment it is pasted, and this page changes with the library.
+
+```md
+Helix: read https://fusion.dev/helix/docs/using-helix-with-an-agent
+before writing components, and https://fusion.dev/helix/custom-elements.json
+for the API.
+```
+
+| Tool | Where it goes |
+|---|---|
+| Claude Code | `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 |
+
+**We do not write those files for you**, and that is the Sovereignty Constraint
+rather than laziness: a file we generate into your repository is one you then
+maintain against our changes, and a tool that rewrites it on install is a
+dependency you did not ask for in a directory you own. The line above is yours to
+paste and yours to delete.
+
+## The one thing worth installing
+
+```json
+{
+  "mcpServers": {
+    "helix": { "command": "helix", "args": ["mcp"] }
+  }
+}
+```
+
+`helix mcp` is a subcommand of the CLI, speaking MCP over stdio, which Claude,
+Cursor, Windsurf and Zed all read. It answers the question no document can,
+which is what a given brand color derives to. It runs on your machine, talks to
+a client you chose, and has no network in it.
+
+## What this page will not tell you
+
+**Anything the manifest answers.** Property names, unions, part names, event
+names and hooks change with the library and are in a file you can fetch; a list
+of them here would be a second copy going stale. Fetch the family.
+
+**What a brand color derives to.** That is computation rather than a document,
+and `helix mcp` is where it lives: an MCP server over stdio with
+`helix_audit_theme` and `helix_derive_theme`, both taking the JSON a
+`helix.theme.json` holds. It runs on your machine and nobody hosts it.
+
+**Whether a component is good for your case.** The examples are the honest
+answer to that and they are text: every family's `.md` carries them, and
+`https://fusion.dev/helix/sandbox?e=<family>.<slug>` opens one editable.

package/content/using-the-elements.mdx

@@ -0,0 +1,125 @@
+---
+description: Binding events, registering elements, and the traps in both.
+pinned: true
+section: Essentials
+title: Using the elements
+---
+
+# Using the elements
+
+Write `<helix-card>` in your JSX. They are plain custom elements: no wrapper, no
+patched React, and no React package: there is not one.
+
+```tsx
+export default function Page() {
+  return (
+    <helix-card>
+      <h2 slot="header">Deployments</h2>
+      <helix-button emphasis="solid" tone="primary">Ship it</helix-button>
+    </helix-card>
+  )
+}
+```
+
+Everything below is a trap that has actually cost time, rather than general
+advice.
+
+## Bind Helix events with `onhelix-*`
+
+```tsx
+<helix-tabs onhelix-before-activate={(event) => setPane(event.detail.value)} />
+```
+
+There is a real bug underneath this, and the elements work around it for you.
+**React attaches no custom element listener while hydrating**, so on a
+server-rendered page every one of these props is dead until React commits an
+update for some other reason, at which point it silently starts working. Nothing
+is logged. It is
+[facebook/react#35446](https://github.com/facebook/react/issues/35446), open and
+unfixed.
+
+Every Helix element binds the handler itself, immediately before it announces
+anything, using the function React is already holding for it. Measured in Chrome
+against React 19.2.8: on a hydrated page the first event reaches the handler,
+and it is never delivered twice once React binds its own listener.
+
+Nothing is required of you, and nothing changes once React fixes it.
+
+React's own events are unaffected where they bubble. `onClick` on a
+`<helix-button>` goes through the synthetic system, which hydration does set up.
+
+A few of ours are native events relayed from inside the component, and the ones
+that do not bubble (`load` and `error` on Avatar, `ended`, `play` and `pause` on
+Video) reach nothing React sets up. The elements bind those for you, so
+`onError` on a `<helix-avatar>` works like the rest.
+
+## The prop is `on` plus the event name
+
+React slices `on` off the prop and listens for exactly what is left, without
+inspecting it.
+
+- `onhelix-before-open` reaches `helix-before-open`. ✅
+- `onhelix-sample-start` reaches `helix-sample-start`. ✅
+- `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
+
+A custom element registers as a side effect of importing its module, and that
+import has to be in the client graph to ever run. A server component's imports
+do not ship to the browser. So one client component holds every element import
+and renders `null`:
+
+```tsx
+'use client'
+import '@fusion.dev/helix/card'
+import '@fusion.dev/helix/button'
+
+export function HelixElements(): null {
+  return null
+}
+```
+
+Render it once in your layout. **Your pages stay server components.** An
+unregistered tag is just an unknown element in the HTML that upgrades when the
+definition lands. Asking you to mark every page `'use client'` to use a button
+would not be a design system.
+
+## Import `elements.css` beside the base layer
+
+```ts
+import '@fusion.dev/helix-styles/base.css'
+import '@fusion.dev/helix/elements.css'
+```
+
+It hides each tag with `:not(:defined)` until it upgrades, using `visibility` so
+the page does not reflow. Without it a card arrives as a run of unstyled text
+and then snaps into a card.
+
+It is generated from the element sources and enumerates the tags, because CSS
+cannot select "any custom element" and a bare `:not(:defined)` would also catch
+your framework's dev overlay.
+
+## Import from subpaths
+
+```ts
+import '@fusion.dev/helix/card' // ✅ one family
+import '@fusion.dev/helix' // ❌ the barrel
+```
+
+One family per module, so you are not shipping the library to use a button.
+
+## There is no declarative shadow DOM
+
+Components render on the server through Lit SSR in our own tests, but the app
+ships no DSD, and the shadow styles arrive with the definition rather than in
+the markup. You do not need to configure anything for this; it is here so the
+absence is not mistaken for something missing.
+
+The short version of why: DSD cannot activate for script-inserted nodes, a
+server component's output is replayed from the flight payload through DOM APIs
+rather than re-run, and the patch that made it work hooked webpack, which
+Turbopack ignores, silently.

package/content/versioning.mdx

@@ -0,0 +1,72 @@
+---
+description: What a version number means here, and which packages move together.
+order: 6
+section: Getting started
+title: Versioning
+---
+
+# Versioning
+
+**Every Helix package shares one version.** `@fusion.dev/helix@1.4.0` works with
+`@fusion.dev/helix-headless@1.4.0` and with `@fusion.dev/helix-styles@1.4.0`, and that is a
+guarantee rather than a coincidence: they are released together, always, from
+one tag.
+
+```sh
+bun add @fusion.dev/helix@1.4.0 @fusion.dev/helix-styles@1.4.0
+```
+
+Pin them to the same number or pin none of them. A range that lets one drift
+ahead of another is the one configuration this scheme does not defend against.
+
+## Why lockstep
+
+Cortex moves independently. Full-repo lockstep would be wrong here because the
+documentation packages carry the version of what they document: publishing a
+Cortex fix would bump `@fusion.dev/helix-docs` to a version in which nothing about Helix
+changed.
+
+Per-domain lockstep keeps the property that matters, which is that two Helix
+packages of the same version are the pair that was tested together.
+
+## The version lives in the tag
+
+Every manifest in the repository holds `0.0.0-dev`. The real number is stamped
+in CI, seconds before packing.
+
+If you read the source: a manifest saying `0.0.0-dev` is not an unreleased
+package, it is every package. Committing the number back
+would need a bot whose push access outranks branch protection, to record
+something `git tag` already holds.
+
+Two tag shapes, and the second is the useful one:
+
+| Tag | Means |
+|---|---|
+| `helix-v1.4.0` | A release that promoted |
+| `helix-attempt-v1.4.0` | A number that was spent and did not ship |
+
+Version computation reads both, so a failed release burns a number rather than
+poisoning the next one. If you see 1.4.0 skipped, that is what happened.
+
+## Documentation is versioned with the code
+
+`@fusion.dev/helix-docs@1.4.0` documents Helix 1.4.0. There is no version axis inside
+the package and no version switcher in it: the package version *is* the version,
+because every package in the domain moves together.
+
+A site serving several versions installs several versions, which is the
+mechanism npm already provides and the only one that cannot drift.
+
+## Stability
+
+Components carry a `status` in the manifest and on their page: `experimental`,
+`stable`, or `deprecated`. Most of the library is experimental today and says
+so. That label is the honest one and it will not be softened to make the set
+look more finished than it is.
+
+## Release notes
+
+On GitHub, generated from the tags. There is no changelog file in this package,
+because a second copy of the release notes is a second thing to keep in step and
+the one that goes stale is the one nobody is reading that week.

package/content/visual-axes.mdx

@@ -0,0 +1,75 @@
+---
+description: Four words with fixed vocabularies, one escape hatch, and the word that is refused.
+section: Theming
+title: Visual axes
+---
+
+# Visual axes
+
+A component's visual choices come from four registered axes with fixed
+vocabularies. You cannot invent a value, and a component may take a subset.
+
+| Axis | Values |
+|---|---|
+| `emphasis` | `ghost`, `outlined`, `solid`, `subtle` |
+| `material` | `frosted`, `glass`, `transparent` |
+| `separation` | `elevated`, `filled`, `outlined`, `plain` |
+| `tone` | The status and intent words: `primary`, `accent`, `neutral`, `danger`, and so on |
+| `width` | `auto`, `full`, `standard` |
+
+```html
+<helix-button
+  emphasis="solid"
+  tone="primary"
+>Save</helix-button>
+<helix-card separation="outlined">…</helix-card>
+<helix-megamenu material="glass">…</helix-megamenu>
+```
+
+## 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
+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.
+
+The tell is that `outlined` appeared in two of those groups meaning different
+things. On a Card it says where the surface ends. On a Button it says how much
+ink. Same word, two questions, and no way to ask one without answering the
+other.
+
+**`appearance` is refused outright now.** It is not a word this library uses,
+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.
+
+If you are adding a property and cannot decide which axis it belongs to, that is
+usually the answer: it is two properties.
+
+## `variant` is the escape hatch
+
+```html
+<helix-tabs variant="segmented">…</helix-tabs>
+<helix-time-picker variant="wheels">…</helix-time-picker>
+```
+
+`variant` takes no registry, being component-specific by definition: `segmented`
+against `underlined`, `list` against `wheels`, `dots` against `marks`. It is a
+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.
+
+## `tone` is the one axis both tiers carry
+
+A styled axis never appears on the headless tier, which has nothing to paint and
+no box to size. `tone` is the exception and a principled one: it says what a
+thing *means*, and meaning survives having no stylesheet.

package/content/vue.mdx

@@ -0,0 +1,80 @@
+---
+description: The one compiler setting Vue needs, and why props and events already work.
+parent: installation
+section: Getting started
+title: Vue
+---
+
+# Vue
+
+```ts
+import '@fusion.dev/helix/vue'
+```
+
+A types-only import, once. It augments Vue's `GlobalComponents` so every Helix
+tag is typed in an SFC template, with its real props and its real events. The
+generated file declares the augmentation under both `vue` and
+`@vue/runtime-core`, because tooling disagrees about which one to read.
+
+## Tell the compiler the tags are deliberate
+
+Without this, Vue resolves `<helix-button>` as a component it cannot find and
+warns on every render.
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    vue({
+      template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith('helix-') } },
+    }),
+  ],
+})
+```
+
+The prefix test is the whole rule. Every element in the library is `helix-`
+something, in both tiers, and nothing else is.
+
+## Props and events need no ceremony
+
+Vue sets a property when the element has one and falls back to an attribute
+otherwise, which is exactly right for these: a string goes through either path
+and an array or an object goes through the property.
+
+```vue
+<helix-tabs :items="items" @helix-before-activate="onActivate" />
+```
+
+`@helix-before-activate` binds with `addEventListener`, so the name is the event's own.
+Vue is the framework this works most quietly in, which is why this page is
+short: there is no bridge and no wrapper, only the compiler setting above.
+
+**Force the property with `.prop` if you ever need to**, for instance where a
+string would be ambiguous:
+
+```vue
+<helix-input :value.prop="'42'" />
+```
+
+Rarely necessary, and it exists so you do not go looking for it.
+
+## Seeding, mirroring and refusing
+
+`value`, `open`, `checked` and `active` are seeds. The element applies its own
+changes from there, so all three of these work. See [State and
+control](./state-and-control).
+
+```vue
+<!-- Seeded: the element owns it from there. -->
+<helix-input default-value="Ada" label="Name" />
+
+<!-- Mirrored: bind the notification and let the element apply. -->
+<helix-input label="Name" @change="name = $event.target.value" />
+
+<!-- Refused: you take the decision for this one change. -->
+<helix-input
+  :value="name"
+  label="Name"
+  @helix-before-change="$event.preventDefault(); name = clean($event.detail.value)"
+/>
+```