@fusion.dev/helix-docs 0.0.0-dev

package/content/forms.mdx

@@ -0,0 +1,170 @@
+---
+description: Real form participation, labels that resolve across a shadow root, and the disabled trap.
+section: Essentials
+title: Forms and validation
+---
+
+# Forms and validation
+
+Twenty-two families are form-associated custom elements, so a `<form>` collects
+them, resets them, restores them on back-navigation and validates them the way it
+does a native control. Nothing about that is simulated.
+
+```html
+<form>
+  <helix-input
+    label="Name"
+    name="name"
+    required
+  ></helix-input>
+  <helix-select
+    label="Plan"
+    name="plan"
+  >
+    <helix-option value="free">Free</helix-option>
+    <helix-option value="pro">Pro</helix-option>
+  </helix-select>
+  <helix-button type="submit">Save</helix-button>
+</form>
+```
+
+`new FormData(form)` has `name` and `plan` in it. So does a server reading the
+POST body.
+
+## Every control carries its own label
+
+```html
+<helix-input
+  hint="We only use this to sign you in."
+  label="Email"
+  name="email"
+  required
+></helix-input>
+```
+
+There is no wrapping `Field` component, and that is not a style preference. **A
+wrapper cannot name what it wraps.** Its label would live in one shadow root and
+the control in another, and measured in Chrome 148: an `aria-labelledby` IDREF
+cannot see across a shadow boundary, and `control.ariaLabelledByElements =
+[labelInTheWrapper]` reads back as zero elements, the reference silently
+dropped. The same assignment with a label in the control's own tree is kept.
+
+That pattern works in React component libraries because they have no shadow
+boundary. Bringing it here brings the ergonomics and none of the conditions that
+made it work.
+
+So every control that wants a label has the same three properties and renders
+its own nodes:
+
+| Property | For |
+|---|---|
+| `label` | The accessible name, and the fallback for the `label` slot |
+| `hint` | Help under the control, while there is nothing wrong |
+| `feedback` | What is wrong, in your words rather than the browser's |
+
+Each is a slot fallback, so anything richer than a string replaces it:
+
+```html
+<helix-input name="email">
+  <span slot="label">Email <helix-badge>required</helix-badge></span>
+</helix-input>
+```
+
+**A whitespace-only text node defeats a default slot's fallback**, which costs a
+label and gives no warning. Measured in Chrome 148: a newline between the tags
+is enough, so `<helix-checkbox label="Accept">` closed on the next line renders
+no label at all. Named slots do not have this problem, because `slot="label"` is
+an attribute and a text node has none. It is the platform's behavior rather
+than ours, and it is true of every slot fallback in the library.
+
+## Validation
+
+The platform's own validation works, because these are real form participants:
+
+```html
+<helix-input
+  label="Email"
+  name="email"
+  required
+  type="email"
+></helix-input>
+```
+
+Submitting an empty form blocks and points at the control. `checkValidity()`,
+`reportValidity()` and `:invalid` behave.
+
+**`feedback` overrides the message.** Left empty, the browser's own is shown,
+which is localised and familiar; set, it says what you want in the words your
+product uses:
+
+```html
+<helix-input
+  feedback="We need this to send your receipt."
+  label="Email"
+  name="email"
+  required
+></helix-input>
+```
+
+**A group is the participant, not its members.** `Radio.Group` and
+`Toggle.Group` own the `name`, the `value` and the validity: a lone radio is not
+a control at all, it is an answer to one. `Checkbox.Group` is the exception in
+the other direction, since each box in it submits itself already, so the group
+deliberately reports no value of its own.
+
+## The disabled trap
+
+```html
+<fieldset disabled>
+  <helix-input
+    label="Name"
+    name="name"
+  ></helix-input>
+</fieldset>
+```
+
+That works, and it did not always. The platform tells a form-associated element
+through `formDisabledCallback`, which nothing implemented, so a control inside a
+disabled fieldset stayed fully typeable and announced itself as enabled.
+Measured: a `helix-input` in one accepted text, reported `disabled` as false,
+and carried no `aria-disabled`, while the form's entry list correctly left it
+out. Interactive and unsubmittable is the worst of both.
+
+**For your own CSS this means one rule.** Style disabled controls with
+`:disabled`, never `[disabled]`:
+
+```css
+/* Right: matches the attribute and the ancestor fieldset. */
+helix-input:disabled { … }
+
+/* Wrong: misses every control inside a disabled fieldset. */
+helix-input[disabled] { … }
+```
+
+The pseudo-class is true for a control carrying the attribute *and* for one
+inside a disabled fieldset, which sets no attribute on anything. A component
+styled with the attribute selector refuses interaction from the fieldset,
+because the platform disables it either way, and paints itself as live. That
+reads as a control that is simply broken, and it is invisible in every example
+that does not happen to use a fieldset. The library holds itself to this, and
+the same reasoning applies to yours.
+
+`disabled` is mirrored to `aria-disabled` rather than removing the control from
+the accessibility tree, so a screen reader can still announce that the control
+exists and is currently off.
+
+## Seeding a form
+
+A declared `value` or `checked` is a seed and the control goes on managing
+itself, so a form needs nothing wired to work. `default-value` is what a reset
+returns to, which is usually what a seed in a form means:
+
+```html
+<helix-input
+  default-value="Ada"
+  label="Name"
+  name="name"
+></helix-input>
+```
+
+See [State and control](./state-and-control).

package/content/iconography.mdx

@@ -0,0 +1,80 @@
+---
+description: 103 glyphs, one geometry, and how to draw one that is not in the set.
+section: Foundations
+title: Iconography
+---
+
+# Iconography
+
+```html
+<helix-icon name="trash"></helix-icon>
+```
+
+103 glyphs, from Phosphor, drawn on a 256 box at stroke-width 16. That is
+Phosphor's own geometry and it is kept rather than rescaled: normalizing to a 24
+box would change the optical weight of every glyph and stop the set matching
+anything upstream.
+
+## Size and color come from the context
+
+An icon has no `size` and no `color` property. It is `1em` square and
+`currentColor`, so it takes the size and color of the text it sits in:
+
+```html
+<span data-tone="danger">
+  <helix-icon name="warning"></helix-icon> Careful
+</span>
+```
+
+Inside a control, `--helix-size-icon` is what decides, and it follows the
+region's density along with everything else. That is why an icon in a small
+button is smaller without anybody saying so.
+
+## Decorative or named
+
+```html
+<!-- Decorative: the text beside it already says what this is. -->
+<helix-button>
+  <helix-icon name="trash"></helix-icon>
+  Delete
+</helix-button>
+
+<!-- Named: there is no text, so the icon has to carry the name. -->
+<helix-icon-button
+  label="Delete"
+  name="trash"
+></helix-icon-button>
+```
+
+An icon with no `label` is hidden from assistive technology, which is right when
+the words are beside it and wrong when they are not. `Icon.Button` takes a
+`label` because it never has words beside it.
+
+## Importing a glyph directly
+
+```ts
+import { trash } from '@fusion.dev/helix-icons'
+```
+
+Each glyph is an exported string, so you can put one in your own markup, in a
+canvas, or anywhere an element is not what you want. Every `name` the library
+uses is held to the set of glyphs that actually exist, so a typo is a build
+failure rather than an empty box.
+
+## Adding one
+
+Drop the SVG into `helix/icons/raw` and run `bun run icons`. The set is
+generated from those files, so adding a glyph is adding a file rather than
+hand-transcribing a path into a TypeScript object.
+
+Keep to the same geometry: 256 box, stroke-width 16, no fill. A glyph drawn at a
+different weight is visible immediately when it sits beside one that was not.
+
+## Icons this set does not have
+
+Product marks. Helix and Cortex have marks and they live in the icon package,
+but a mark is not an icon: it identifies a product and does not mean an action.
+Three earlier attempts at product marks were removed for being pictograms of a
+metaphor standing beside a parent that is a geometric monogram, and the rule
+that replaced them is that **a mark is one rounded body with material removed**.
+If you are reaching for the icon set to draw a logo, that is the wrong drawer.

package/content/installation.mdx

@@ -0,0 +1,125 @@
+---
+description: What to install, the order the stylesheets go in, and how to check it worked.
+order: 3
+section: Getting started
+title: Installation
+---
+
+# Installation
+
+```sh
+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.
+
+## The stylesheets go in this order
+
+```ts
+import '@fusion.dev/helix/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, which these instructions demonstrated
+for longer than anyone would like, so it is stated once inside the package
+rather than by every consumer.
+
+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.
+
+### The four, for anyone substituting a layer
+
+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.
+
+- **`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 235 times, so without it every
+  semantic token resolves to nothing at all. Measured on a page missing 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. **This is the one that was
+  missing from this page**, which is why the bundle exists.
+- **`tokens.css`** declares the semantic layer, 177 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.
+
+## Register the elements
+
+```ts
+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.
+
+You can register a subset instead, from a subpath:
+
+```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.
+
+## Check it worked
+
+Render one element and ask the browser 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.
+`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.
+
+**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`.
+
+## Your framework
+
+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.
+
+| | |
+|---|---|
+| [React](./react) | A runtime bridge ships for it, plus `jsx.d.ts` |
+| [Vue](./vue) | Ships `vue.d.ts`, needs `compilerOptions.isCustomElement` |
+| [Svelte](./svelte) | Ships `svelte.d.ts`, and needs nothing else |
+| [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 |
+
+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.

package/content/intent-reference.mdx

@@ -0,0 +1,107 @@
+---
+description: Every input the theme engine takes, and what each one decides.
+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.
+
+```ts
+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.
+
+## Color
+
+| Field | Decides |
+|---|---|
+| `brand` | The one color most consumers care about. Required |
+| `accent` | The second emphasis. Defaults to the complement, `{ from: 'brand', rotate: 180 }` |
+| `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 |
+| `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 |
+
+**`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.
+
+**`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.
+
+## The guarantee
+
+| Field | Decides |
+|---|---|
+| `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 |
+
+4.5 is the default because the European Accessibility Act points at WCAG 2.1 AA,
+so it is the figure with legal weight.
+
+## Shape and space
+
+| Field | Decides |
+|---|---|
+| `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 |
+
+`separation` is the policy pair described in [Surfaces and
+separation](./surfaces-and-separation).
+
+## Type and motion
+
+| Field | Decides |
+|---|---|
+| `font` | The families, and the half of the type system that is a 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.
+
+`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.
+
+`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.
+
+## Material
+
+| Field | Decides |
+|---|---|
+| `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.
+
+## Output
+
+| Field | Decides |
+|---|---|
+| `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.

package/content/introduction.mdx

@@ -0,0 +1,69 @@
+---
+description: What Helix is, and the four packages it stacks into.
+order: 1
+section: Getting started
+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.
+
+Two things make it different from a component library.
+
+**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).
+
+**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.
+
+## Install
+
+```sh
+bun add @fusion.dev/helix @fusion.dev/helix-styles
+```
+
+Three imports at your app root, in this order, then the elements are usable
+anywhere:
+
+```ts
+import '@fusion.dev/helix/helix.css'
+import '@fusion.dev/helix'
+```
+
+```html
+<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>
+  </helix-accordion-item>
+</helix-accordion>
+```
+
+[Installation](./installation) has the order those imports are in and why, and a
+page for each framework.
+
+## Packages
+
+| Package | Use when |
+| --- | --- |
+| `@fusion.dev/helix-styles` | Always. Tokens and the base layer |
+| `@fusion.dev/helix` | You want Helix components as-is |
+| `@fusion.dev/helix-headless` | You want the behavior and none of the styling |
+| `@fusion.dev/helix-theme` | You are generating or validating a theme |
+| `@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.
+
+See [Tiers](./tiers) for how the packages relate and which one to reach for.

package/content/localization.mdx

@@ -0,0 +1,95 @@
+---
+description: Locale-aware controls, translatable strings, and a layout that already flips.
+section: Essentials
+title: Localization and RTL
+---
+
+# Localization and RTL
+
+## Right-to-left already works
+
+Set `dir` and the layout flips:
+
+```html
+<html
+  dir="rtl"
+  lang="ar"
+>
+```
+
+Every component is written in logical properties, `inline-start` rather than
+`left`, `margin-block` rather than `margin-top`. Sixty-seven stylesheets name a
+direction, and **not one of them names a physical side**: there is no
+`margin-left`, no `padding-right` and no `inset-top` anywhere in the library.
+Nothing infers the direction for you and nothing needs to: the document says it
+and the components follow.
+
+The same is true of anything you write on top. Use logical properties and your
+layout flips with ours; use `left` and `right` and it will not.
+
+## Locale-aware controls
+
+Six families format numbers or dates and take a `locale`:
+
+| | |
+|---|---|
+| `Date Input`, `Date Picker` | Date formats and first day of week |
+| `Time Input`, `Time Picker` | 12 or 24 hour, and separators |
+| `Pagination` | Grouped thousands in page numbers |
+| `File Input` | File sizes |
+
+```html
+<helix-pagination
+  locale="de-DE"
+  pages="1200"
+></helix-pagination>
+```
+
+Left unset, they use the browser's own locale, which is usually right. Set it
+when your application's language is a choice the reader made rather than the one
+their operating system is in.
+
+Formatting goes through `Intl`, so there is no locale data bundled and nothing
+to keep up to date.
+
+## Translatable strings
+
+Seventy properties across the headless tier are strings a reader sees, and every
+one is a property rather than a hardcoded word. The ones that combine
+values are format templates:
+
+```html
+<helix-pagination-summary
+  format="{from} bis {to} von {total}"
+  locale="de-DE"
+  page="2"
+  page-size="10"
+  total="1500"
+></helix-pagination-summary>
+```
+
+The placeholders are named rather than positional, so a translation can reorder
+them, which some languages require and a positional format cannot express.
+
+**Pass these from your own translation system.** Helix ships English defaults
+and no translation machinery: a design system that owned the string catalog
+would be a second one to keep in step with yours.
+
+## What to check when adding a language
+
+- **Long strings.** German and Finnish will find every control that assumed a
+  short label. Controls take their width from the layout rather than carrying
+  one, which helps, but a toolbar that fitted six buttons may now fit four.
+- **The `lang` attribute, not just the strings.** Hyphenation, quotation marks
+  and font fallback all key off it.
+- **Numerals.** `Intl` handles the digits; a hardcoded `%` or a currency symbol
+  in your own markup will not move to the right side.
+- **Icons that point.** A chevron meaning "forward" is mirrored by the logical
+  properties; one baked into an SVG path is not.
+
+## What is not covered
+
+There is no message catalog, no pluralization helper and no date-range
+formatter beyond what the controls do for themselves. Those belong to your
+application's i18n layer, and every one of these properties is designed to be
+fed from it.