@fusion.dev/helix-docs 0.104.1 → 0.105.0

package/content/installation.mdx

@@ -1,5 +1,5 @@
 ---
-description: What to install, the order the stylesheets go in, and how to check it worked.
+description: What to install, the order of the stylesheets, and how to check that the elements registered.
 order: 3
 section: Getting started
 title: Installation
@@ -11,55 +11,59 @@ title: Installation
 bun add @fusion.dev/helix
 ```
 
-`@fusion.dev/helix-styles` is not optional and not a peer dependency by accident. The
-components reference semantic tokens and paint nothing without them: a Helix
-page with the elements installed and the tokens missing renders unstyled boxes
-rather than an unthemed version of itself.
+`@fusion.dev/helix-styles` is a required dependency, on purpose. The components
+use its semantic tokens and draw nothing without them. If the elements are
+installed and the tokens are missing, your page shows unstyled boxes. There is
+no fallback theme.
 
-## The stylesheets go in this order
+## Import the stylesheets
 
 ```ts
 import '@fusion.dev/helix-styles/helix.css'
 ```
 
-One import, and it is four files in the order they have to be in:
-`primitives.css`, `tokens.css`, `base.css`, `elements.css`. The order is
-load-bearing and the failure is silent, so it is stated once inside the package
-rather than by every consumer.
+This one import loads four files in the order they must load:
 
-It resolves `@fusion.dev/helix-styles` through this package's own dependency, so
-installing `@fusion.dev/helix` is enough. A bare specifier in an `@import` is
-resolved by a bundler and never by a browser, so a page serving CSS through a
-`<link>` takes the four by path instead.
+1. `primitives.css`
+2. `tokens.css`
+3. `base.css`
+4. `elements.css`
 
-### The four, for anyone substituting a layer
+The order matters, and a wrong order fails without an error. We set the order
+once, inside the package, so you do not have to.
 
-Each file keeps its own export, so a consumer bringing their own reset or their
-own ramp imports the two they want and skips the bundle.
+The import resolves `@fusion.dev/helix-styles` through the dependency in
+`@fusion.dev/helix`, so installing `@fusion.dev/helix` is enough. Only a bundler
+resolves a bare specifier like this one. If you serve CSS through a `<link>`,
+link `helix.css` by its path, as [Without a bundler](./without-a-bundler)
+shows.
 
-- **`primitives.css`** is the raw ramp the semantic layer is derived from, and
-  it is where the seven `--helix-seed-*` knobs are read. Nothing in your own
-  code should name a primitive, and leaving the file out is not a way to
-  enforce that: `tokens.css` refers to one 297 times, so without it every
-  semantic token resolves to nothing at all. Measured on a page missing it,
+### Import the files one at a time
+
+Each file has its own export. If you bring your own reset or your own ramp,
+import the two files you want and skip `helix.css`.
+
+- **`primitives.css`** holds the raw ramp that the semantic layer is derived
+  from. The seven `--helix-seed-*` properties are read here. Your own code
+  should not name a primitive, and leaving the file out does not enforce that.
+  `tokens.css` refers to a primitive 297 times, so without `primitives.css`
+  every semantic token resolves to nothing. We measured a page without it:
   `--helix-color-background` computes to `rgba(0, 0, 0, 0)`, and so does every
-  other color. It is also the file [theming](theming.mdx) depends on, since a
-  `--helix-seed-brand` nobody reads moves nothing.
-- **`tokens.css`** declares the semantic layer, 185 custom properties in 15
-  categories, plus `color-scheme: light dark` on `:root`. Everything below reads
-  from it, and it reads primitives.
-- **`base.css`** is the element reset, the type scale on bare `h1` through
-  `h6`, and the recipes for markup this library does not render. It reads
-  tokens.
-
-**The last one is the one people leave out**, because everything works without
-it right up until the page is server-rendered: an element that has not upgraded
-yet has no shadow root and no styles of its own, so the markup flashes unstyled
-and then snaps into place. `elements.css` is what makes that interval look like
-the finished page.
-
-Put them in a stylesheet you control rather than deep inside a component, so the
-order is visible in one place and stays that way.
+  other color. [Theming](theming.mdx) also depends on this file, because without
+  it, setting `--helix-seed-brand` changes nothing.
+- **`tokens.css`** declares the semantic layer: 185 custom properties in 15
+  categories, plus `color-scheme: light dark` on `:root`. The files below read
+  from it, and it reads from `primitives.css`.
+- **`base.css`** holds the element reset, the type scale on bare `h1` through
+  `h6`, and the recipes for markup that Helix does not render. It reads tokens.
+- **`elements.css`** styles elements before they upgrade. It is the file most
+  often left out, because a page works without it until the page is
+  server-rendered. An element that has not upgraded has no shadow root and no
+  styles of its own, so the markup flashes unstyled and then jumps into place.
+  `elements.css` makes that interval look like the finished page.
+
+Import the files from a stylesheet you control, and keep them out of individual
+components. The order then stays visible in one place.
 
 ## Register the elements
 
@@ -67,57 +71,62 @@ order is visible in one place and stays that way.
 import '@fusion.dev/helix'
 ```
 
-A side-effect import. It calls `customElements.define` for every element, once,
-and is safe to run more than once: the helper behind it checks the registry
-first, because a second `define` for the same tag throws and takes the rest of
-the module with it.
+This import has a side effect: it calls `customElements.define` once for every
+element. You can run it more than once. A second `define` for the same tag
+throws an error and stops the rest of the module, so the helper behind the
+import checks the registry first.
 
-You can register a subset instead, from a subpath:
+To register only some elements, import them from subpaths:
 
 ```ts
 import '@fusion.dev/helix/button'
 import '@fusion.dev/helix/dialog'
 ```
 
-Worth doing when you use a handful of components. Not worth doing in the belief
-that the full import ships everything to the browser: the package is
-side-effectful by design, so a bundler keeps what you import either way, and the
-subpaths are about being explicit rather than about size.
+Import from subpaths when you use a few components. The package has side
+effects by design, so a bundler keeps everything you import. The whole-package
+import registers every element, and a subpath registers only its family.
 
-## Check it worked
+## Check the installation
 
-Render one element and ask the browser whether it upgraded:
+Render one element and check whether it upgraded:
 
 ```ts
 await customElements.whenDefined('helix-button')
 console.log(document.querySelector('helix-button')?.shadowRoot !== null)
 ```
 
-`true` means the definition arrived and the element built its shadow root.
+`true` means the definition loaded and the element built its shadow root.
 `false`, or a promise that never settles, means the registration import did not
-run: usually a `'use client'` boundary the import ended up outside of, or a
-subpath import for a component you did not end up using.
+run. Usually the import is outside a `'use client'` boundary, or you imported
+the subpath of a component you did not end up using.
+
+If the element upgraded and the page still looks wrong, check the stylesheets
+in the order above. The symptom tells you which layer is missing:
+
+- No color at all means `tokens.css` is missing.
+- Unstyled prose and bare headings mean `base.css` is missing.
+- Components that look right once JavaScript runs, but flash unstyled before
+  it, mean `elements.css` is missing.
 
-**A styling problem looks nothing like that.** If the element upgraded and the
-page still looks wrong, the stylesheets are the thing to check, in the order
-above. The tell is which layer is missing: no color at all is `tokens.css`,
-unstyled prose and bare headings is `base.css`, and components that look right
-once JavaScript runs but flash unstyled before it is `elements.css`.
+## Framework setup
 
-## Your framework
+The elements are custom elements, and every framework can render them.
+Frameworks differ in three ways:
 
-The elements are custom elements and every framework can render one. What
-differs is how a framework passes a non-string value, how it binds an event, and
-whether it needs telling that an unknown tag is deliberate.
+- How they pass a value that is not a string.
+- How they bind an event.
+- Whether they need configuration to accept an unknown tag.
 
 | | |
 |---|---|
-| [React](./react) | A runtime bridge ships for it, plus `jsx.d.ts` |
+| [React](./react) | Ships a runtime bridge and `jsx.d.ts` |
 | [Vue](./vue) | Ships `vue.d.ts`, needs `compilerOptions.isCustomElement` |
-| [Svelte](./svelte) | Ships `svelte.d.ts`, and needs nothing else |
+| [Svelte](./svelte) | Ships `svelte.d.ts`, and needs no configuration |
 | [Angular](./angular) | Needs `CUSTOM_ELEMENTS_SCHEMA` |
-| [Other frameworks](./other-frameworks) | Solid, Qwik, Lit, and the three rules they all reduce to |
-| [Without a bundler](./without-a-bundler) | An import map, or the stylesheets alone |
+| [Other frameworks](./other-frameworks) | Solid, Qwik, Lit, and the three rules they all follow |
+| [Without a bundler](./without-a-bundler) | The stylesheets with no build step |
 
-A framework gets its own page when Helix ships typings for it, or when it
-refuses to compile without configuration. Everything else works with no setup.
+A framework has its own page when Helix ships typings for it, or when it does
+not compile Helix tags without configuration. Other frameworks work with no
+setup.

package/content/intent-reference.mdx

@@ -1,13 +1,13 @@
 ---
-description: Every input the theme engine takes, and what each one decides.
+description: Every input the theme engine takes, and what each one changes.
 section: Theming
 title: Intent reference
 ---
 
 # Intent reference
 
-[Deriving a theme](./theming) is the argument. This is the surface: everything
-`ThemeIntent` accepts, and what changes when you set it.
+[Deriving a theme](./theming) explains how the engine works. This page lists
+every field `ThemeIntent` accepts and what changes when you set it.
 
 ```ts
 import { derive } from '@fusion.dev/helix-theme'
@@ -15,93 +15,98 @@ import { derive } from '@fusion.dev/helix-theme'
 const theme = derive({ brand: '#2563eb' })
 ```
 
-**`brand` is the only required input.** Everything else has a default that is
-derived from it or from the design language, and a theme that sets one field is
-a valid theme.
+**`brand` is the only required input.** Every other field has a default,
+computed from `brand` or from the Helix design language. A theme that sets only
+`brand` is a valid theme.
 
 ## Color
 
-| Field | Decides |
+| Field | What it controls |
 |---|---|
-| `brand` | The one color most consumers care about. Required |
-| `accent` | The second emphasis. Unnamed, it is the brand; `{ from: 'brand', rotate: 180 }` asks for the complement |
+| `brand` | Your main brand color. Required |
+| `accent` | The second emphasis color. Defaults to the brand color. `{ from: 'brand', rotate: 180 }` gives the complementary color |
 | `neutral` | The gray ramp, which can be tinted toward the brand |
-| `status` | `info`, `success`, `warning`, `danger`. A color pins one; an object nudges its hue within the meaning it already carries |
+| `status` | `info`, `success`, `warning`, and `danger`. A color pins one. An object adjusts its hue while it keeps its meaning |
 | `chroma` | How saturated the palette is, independent of hue |
-| `scheme` | `'light'` or `'dark'`, for a theme that is only one |
-| `tokens` | Literal overrides, by token name, for the cases nothing else reaches |
+| `scheme` | `'light'` or `'dark'`, for a theme that has only one mode |
+| `tokens` | Literal overrides by token name, for values no other field sets |
 
-**`accent` may be a relation and `status` may not**, and the asymmetry is
-deliberate: a `danger` that rotates with the brand is a warning a reader has to
-re-learn per product.
+`accent` can be defined relative to the brand. `status` colors cannot. If
+`danger` rotated with the brand, your users would have to learn a new warning
+color for each product.
 
-**`chroma` is the axis a brand's feel lives on.** Monotone, muted, restrained
-and vivid are all chroma statements and none of them is a hue. `ceiling` clamps,
-so 0 is monotone and roughly 0.10 is muted; `scale` multiplies what the brand
-supplies. Both apply to every derived color including the brand itself, because
-a monotone theme is one where the brand is gray too. Never applied to a value
-you pinned: a pinned color is a fact.
+`chroma` sets how saturated the theme feels. Monotone, muted, restrained, and
+vivid all describe chroma, and none of them describes a hue. `chroma` has two
+settings:
 
-## The guarantee
+- `ceiling` caps chroma. 0 is monotone, and about 0.10 is muted.
+- `scale` multiplies the chroma the brand color supplies.
 
-| Field | Decides |
+Both apply to every derived color, including the brand color, because in a
+monotone theme the brand is gray too. Neither applies to a color you pinned. A
+pinned color is used exactly as you set it.
+
+## Contrast
+
+| Field | What it controls |
 |---|---|
-| `contrastTarget` | Target contrast for body text. 4.5 is WCAG AA, 7 is AAA |
-| `pairings` | Extra foreground and background pairs to solve for, beyond the model's own |
+| `contrastTarget` | Target contrast for body text. 4.5 is WCAG AA, and 7 is AAA |
+| `pairings` | Extra foreground and background pairs to solve, in addition to the pairs in the engine's surface model |
 
-4.5 is the default because the European Accessibility Act points at WCAG 2.1 AA,
-so it is the figure with legal weight.
+The default is 4.5, the WCAG 2.1 AA figure. The European Accessibility Act
+refers to WCAG 2.1 AA, so 4.5 is the figure with legal weight.
 
 ## Shape and space
 
-| Field | Decides |
+| Field | What it controls |
 |---|---|
 | `radius` | Corner rounding across the system |
-| `density` | Scales spacing and control heights. 1 is default, 0.875 is compact |
-| `separation` | Whether a surface is told apart by an edge or by a lift |
+| `density` | Scales spacing and control heights. 1 is the default, and 0.875 is compact |
+| `separation` | Whether a surface is set apart by an edge or by a lift |
 
-`separation` is the policy pair described in [Surfaces and
+`separation` chooses between the two policies described in [Surfaces and
 separation](./surfaces-and-separation).
 
 ## Type and motion
 
-| Field | Decides |
+| Field | What it controls |
 |---|---|
-| `font` | The families, and the half of the type system that is a scale |
+| `font` | The font families and the type scale |
 | `motion` | `character` and `scale` |
 
-**`motion.character` sets the curve every component reaches for and carries a
-duration multiplier with it**, because the two are one decision: a spring over
-120ms is a twitch, and a soft curve over 120ms is a fade. `scale` multiplies on
-top for a theme that wants the character and not the pace.
+`motion.character` sets the easing curve that every component uses, along with
+a duration multiplier. The curve and the duration are set together because they
+depend on each other. A spring over 120ms looks like a twitch, and a soft curve
+over 120ms looks like a fade. `scale` multiplies the durations again, so you can
+keep a character and change its speed.
 
-`instant` is not scaled. It is 0 and means "do not animate", which is a
-statement rather than a duration, and it emits no curves at all: three easings
-for transitions of zero length is a contradiction.
+The `instant` character is 0, which means "do not animate". `scale` does not
+change it. It outputs none of the three easing curves, because a transition of
+zero length has no curve to follow.
 
-`precise` is the one character that is not physical. The other three accelerate,
-settle or overshoot; linear reads as moved by a mechanism, and it is the only
-curve legible on a short travel, because constancy shows in the timing where an
-overshoot shows in the distance.
+`precise` is the only character that does not imitate physical motion. The
+other three accelerate, settle, or overshoot. `precise` is linear, so movement
+looks driven by a mechanism. It is also the only curve that is easy to see over
+a short distance. Constant speed shows in the timing, and an overshoot needs
+distance to show.
 
 ## Material
 
-| Field | Decides |
+| Field | What it controls |
 |---|---|
 | `material` | `blur` in pixels and `opacity` from 0 to 1 |
 
-**This is the one choice that can invalidate the contrast guarantee.** Contrast
-is measured against a known ground, and a translucent surface does not have one,
-so a pair over it comes back `unverifiable` rather than measured. That is
-reported rather than hidden: a theme with heavy material is making a trade and
-should be able to see it.
+**`material` is the one field that can break the contrast guarantee.** The
+engine measures contrast against a known ground. A translucent surface has no
+known ground, so a pair over it is reported as `unverifiable`. The report shows
+you the trade-off that a theme with heavy material makes.
 
 ## Output
 
-| Field | Decides |
+| Field | What it controls |
 |---|---|
 | `namespace` | The token prefix. Defaults to `helix` |
 
-`namespace` is for a product shipping its own token layer built on this engine.
-Everything else in the library reads `--helix-*`, so changing it is a decision
-about your own surface rather than about Helix's.
+Use `namespace` when your product ships its own token layer built on the
+engine. The rest of the library still reads `--helix-*`, so a new namespace
+changes only your own tokens.

package/content/introduction.mdx

@@ -1,5 +1,5 @@
 ---
-description: What Helix is, and the four packages it stacks into.
+description: What Helix is, and the packages it includes.
 order: 1
 section: Getting started
 title: Introduction
@@ -7,22 +7,25 @@ title: Introduction
 
 # Helix
 
-A design system of web components: tokens, a headless component tier, a styled
-tier, and the framework typings generated from both. It works in any framework,
-or none, because the components are custom elements.
+Helix is a design system of web components. It includes:
 
-Two things make it different from a component library.
+- color, space, and type tokens
+- a headless tier with the structure and behavior of each component
+- a styled tier that adds the visual design
+- typings for each framework, generated from both tiers
 
-**Theming is derivation, not override.** You supply a handful of intent inputs
-and the system computes a complete token set whose every foreground and
-background pair meets its contrast target by construction. See
-[Theming](./theming).
+The components are custom elements, so you can use them in any framework or
+without one.
 
-**AI is a first-class consumer.** Components are described by a custom elements
-manifest with typed enums, documented parts, and generated React prop names. An
-agent can write correct Helix code by reading types alone. That is why
-conventions like inline literal unions and documented CSS parts are enforced at
-analysis time rather than left to review.
+**Helix computes your theme.** You enter a few inputs, such as your brand color,
+and Helix computes every token from them. Every text and background pair meets
+its contrast target. See [Theming](./theming).
+
+**AI agents can read it.** A custom elements manifest describes every component,
+with typed options, documented parts, and generated React prop names, so an
+agent can write correct Helix code from the types alone. The build checks
+conventions such as inline literal unions and documented CSS parts for that
+reason.
 
 ## Install
 
@@ -30,7 +33,7 @@ analysis time rather than left to review.
 bun add @fusion.dev/helix @fusion.dev/helix-styles
 ```
 
-Two imports at your app root, in this order, then the elements are usable
+Add two imports at your app root, in this order. Then you can use the elements
 anywhere:
 
 ```ts
@@ -42,13 +45,13 @@ import '@fusion.dev/helix'
 <helix-accordion separation="outlined">
   <helix-accordion-item default-open>
     <span slot="summary">What is Helix?</span>
-    <p>A design system that derives its own accessible palette.</p>
+    <p>A design system of web components, themed from your brand color.</p>
   </helix-accordion-item>
 </helix-accordion>
 ```
 
-[Installation](./installation) has the order those imports are in and why, and a
-page for each framework.
+[Installation](./installation) explains the import order and links to a page for
+each framework.
 
 ## Packages
 
@@ -61,9 +64,8 @@ page for each framework.
 | `@fusion.dev/helix-icons` | You are drawing an icon outside a component |
 | `@fusion.dev/helix-core` | You are building a new Helix component |
 
-**There is no React package.** The elements are custom elements and React
-renders them directly; what ships for React is a `jsx.d.ts` that types every tag
-and a runtime bridge in `@fusion.dev/helix-core` that repairs React's hydration of
-custom events. [React](./react) has both.
+React uses the elements directly. Helix ships a `jsx.d.ts` that types every
+tag. `@fusion.dev/helix-core` has a runtime bridge that fixes how React hydrates
+custom events. [React](./react) covers both.
 
-See [Tiers](./tiers) for how the packages relate and which one to reach for.
+See [Tiers](./tiers) for how the packages relate and which one to use.