@fusion.dev/helix-docs 0.0.0-dev

package/content/svelte.mdx

@@ -0,0 +1,45 @@
+---
+description: Typed tags, and the framework that needs the least said about it.
+parent: installation
+section: Getting started
+title: Svelte
+---
+
+# Svelte
+
+```ts
+import '@fusion.dev/helix/svelte'
+```
+
+A types-only import, once. It augments `SvelteHTMLElements` so every Helix tag
+is typed in a component, and it does so by re-exporting the JSX types rather
+than emitting a second copy: Svelte binds a handler as `onhelix-before-change={…}`,
+which is the shape those types already describe, and two generated copies of one
+thing are two things that can disagree.
+
+## Nothing else to configure
+
+```svelte
+<helix-input label="Name" onchange={(event) => (name = event.target.value)} value={name} />
+```
+
+Svelte sets a property when the element has one and an attribute otherwise, and
+binds `on*` with `addEventListener`. There is no unknown-element warning to
+silence and no compiler flag to set. That is the whole page, and it is short
+because Svelte was already right about custom elements.
+
+**Pass objects and arrays as properties**, which Svelte does on its own:
+
+```svelte
+<helix-tabs items={tabs} />
+```
+
+## Two things that are not framework-specific
+
+`bind:` does not work on a Helix control, because there is no two-way binding
+convention a custom element can opt into. Read the value off the event.
+
+And a declared `value`, `open`, `checked` or `active` is a claim of ownership:
+the element announces and waits rather than applying the change itself. Use
+`default-value` and its siblings when you want the element to own its own state.
+See [State and control](./state-and-control).

package/content/theme-builder.mdx

@@ -0,0 +1,66 @@
+---
+description: The tool that turns intent inputs into a token set you can see.
+section: Tooling
+title: Theme builder
+---
+
+# Theme builder
+
+[Open the theme builder](/helix/theme).
+
+Move a slider and every surface in the library resolves around it. A theme here
+is derived rather than picked, and this is where you see that happen.
+
+## What it does
+
+You give it the intent inputs, the same ones `derive()` takes: a brand color, a
+chroma ceiling, a radius, a density, a contrast target, a motion character. It
+runs the real derivation, not an approximation of it, and shows you the complete
+token set plus the library rendered in it.
+
+Light and dark at once, because `[data-color-mode]` works on any element and the
+two previews are two subtrees of one document. See [Color modes](./color-modes).
+
+## The contrast column
+
+Every pairing the engine solved is listed with its measured ratio against the
+ground it is actually painted on. Three states:
+
+- **Met.** The pair reaches the target.
+- **Unverifiable.** The ground is translucent, so there is no known color to
+  measure against. Not a failure, and not a pass either: it is what a material
+  choice costs you, reported rather than hidden.
+- **Pinned.** You supplied the color outright, so the engine did not solve for
+  it and cannot promise anything about it.
+
+A theme with a column of `unverifiable` is a theme making a trade. It should be
+possible to see that you made it.
+
+## What comes out
+
+The token block, as CSS, to paste into your own stylesheet:
+
+```css
+:root {
+  --helix-color-primary: oklch(…);
+  …
+}
+```
+
+Or the intent object, to keep in your repository and re-derive from:
+
+```ts
+export const theme = { brand: '#2563eb', chroma: { ceiling: 0.1 }, radius: 2 }
+```
+
+**Keep the intent, not the tokens.** The tokens are the output of a solver, and
+the solver improves: a theme stored as its inputs picks up a better derivation,
+and a theme stored as 176 literal values is frozen at the version that produced
+it. The tokens are for pasting into a system that cannot run the engine.
+
+## What it does not do
+
+It shows you numbers and swatches, not components in your product. A contrast
+matrix is a grid with three states, which a terminal or a table renders better
+than a picture does, and the components beside it are there to sanity-check the
+result rather than to be a design surface.

package/content/theming.mdx

@@ -0,0 +1,111 @@
+---
+description: Deriving an accessible token set from intent inputs.
+section: Theming
+title: Deriving a theme
+---
+
+# Theming
+
+**Tokens are a function, not a table.**
+
+A design system that ships two hundred hand-picked hex values can only offer
+override. You change one, break contrast somewhere three components away, and
+never find out. That is a config file, not a theming system.
+
+`@fusion.dev/helix-theme` computes a complete token set from a handful of intent
+inputs, and every foreground and background pair meets its contrast target **by
+construction** rather than by audit.
+
+## Two ways to theme
+
+They are both real and they are not the same thing, so they have different
+names.
+
+**Tuned** is the CSS path. Write a seed, the stylesheet re-derives, and nothing
+has to be installed or run:
+
+```css
+:root {
+  --helix-seed-brand: oklch(0.58 0.19 20);
+  --helix-seed-accent-hue: 140;
+  --helix-seed-chroma-scale: 0.4;
+}
+```
+
+It works at `:root` and on any `[data-helix-theme]` subtree, and nowhere else.
+A `var()` inside a custom property is substituted on the element the property is
+*declared* on, so the ramp has already resolved at the root and a seed written
+on a plain element is read by nothing. Naming the scope is what re-runs those
+declarations.
+
+**Tuned makes no contrast promise**, and cannot. CSS has no contrast function:
+`oklch(from …)` can step and rotate, and it cannot search for the lightness that
+clears a target. The figures baked into the ramp are exact for the seed that
+ships and approximate for any other.
+
+**Verified** is the engine. It solves rather than steps, measures every pair it
+emits, and hands back an artifact:
+
+```ts
+import { deriveTheme, toCss } from '@fusion.dev/helix-theme'
+
+const theme = deriveTheme({
+  brand: '#0b3d91',
+  contrastTarget: 4.5, // 4.5 is WCAG AA, 7 is AAA
+  scheme: 'light',
+})
+
+if (theme.violations.length > 0) {
+  throw new Error(theme.violations.join('\n'))
+}
+
+console.log(toCss(theme))
+```
+
+The emitted block carries the seeds as well as the tokens, so the halves the
+engine does not compute, the twenty-four series colours a chart reads, the
+spacing scale and the corner radii, re-derive from the same values the solver
+used. That is what stops the two paths disagreeing on the same page.
+
+Reach for tuned to try a color. Reach for verified to ship one.
+
+## Why OKLCH
+
+Equal numeric steps in sRGB are not equal perceptual steps, which makes both
+scale generation and contrast math unreliable. OKLCH is what makes derivation
+possible at all. Colors are authored in it and converted at the edge.
+
+The brand color keeps its hue and chroma; only lightness moves to meet the
+target. That is what preserves brand identity while guaranteeing contrast.
+
+## What it protects against
+
+Both of these produce a palette that passes review and fails in production.
+Both are covered by regression tests.
+
+**Solving against colors that cannot be rendered.** A near-white surface
+carrying brand tint falls outside the sRGB gamut and gets truncated on the way
+to hex, breaking both the intended hue and the contrast just solved for. Every
+color is gamut-fitted before it is solved against, and a token reports
+`chromaReduced` when fitting changed it rather than clipping silently.
+
+**Verifying against only one surface.** Text lands on `surface` as often as on
+`background`: cards, dialogs, menus. In a dark theme `surface` is *lighter*
+than `background`, so light text loses contrast inside every card while the
+page itself passes. Foregrounds are solved against the hardest surface they
+land on, not just the page background.
+
+## Inspecting a theme
+
+Every derived token carries the check that produced it:
+
+```ts
+const theme = deriveTheme({ brand })
+
+for (const token of theme.tokens) {
+  console.log(token.name, token.hex, token.contrast, token.chromaReduced)
+}
+```
+
+`violations` is empty when the theme passes. Anything that could not reach its
+target at the requested chroma is reported there rather than shipped.

package/content/tiers.mdx

@@ -0,0 +1,159 @@
+---
+description: Why the headless and styled tiers are separate packages.
+order: 2
+section: Getting started
+title: Tiers
+---
+
+# Tiers
+
+Helix ships as four stacked packages. Each has one job, and the dependency
+direction never reverses.
+
+| Package | Owns | Depends on |
+| --- | --- | --- |
+| `@fusion.dev/helix-styles` | Tokens and the base layer. Pure CSS | nothing |
+| `@fusion.dev/helix-core` | Element base class, mixins, decorators | Lit |
+| `@fusion.dev/helix-headless` | Structure, accessibility, state, form participation | `core` |
+| `@fusion.dev/helix` | Presentation: tokens, parts, and the visual axes | `headless`, `styles` |
+
+`@fusion.dev/helix-theme` and `@fusion.dev/helix-icons` ship beside the stack rather than in it:
+neither is a tier, and neither is needed to render a component. **There is no
+React package.** The framework typings are generated into `@fusion.dev/helix`, and
+the bridge that repairs React's hydration of custom events is in
+`@fusion.dev/helix-core`. See [React](./react).
+
+## Why the split
+
+**`headless` must never depend on `styles`.**
+
+That single constraint is what makes the headless tier independently
+consumable. Consume it and bring your own
+styling entirely; nothing about how Helix looks comes with it. If styling leaks
+downward, the four are one package in four files.
+
+## What belongs where
+
+The headless tier owns what a component **is and does**: markup structure, ARIA
+wiring, slots, events, internal state, form participation. It ships no CSS, no
+token references, and none of the visual axes.
+
+The styled tier extends it and adds only presentation. Token references live
+here.
+
+```ts
+// headless/src/accordion/item/accordion-item.ts
+// no CSS, no tokens
+export class HelixHeadlessAccordionItem extends MixinControllerOpen(HelixElement) {
+  protected override render() {
+    return html`
+      <div part="container">
+        <button aria-expanded=${this.open} part="trigger" @click=${this.handleToggle}>
+          <slot name="summary"></slot>
+        </button>
+      </div>
+    `
+  }
+}
+
+// web/src/accordion/root/accordion-root.ts
+// extends the headless one, adds presentation only
+import { styles } from './accordion-root.css.js'
+
+@customElement('helix-accordion')
+export class HelixAccordion extends HelixHeadlessAccordion {
+  @property({ reflect: true })
+  separation?: 'outlined' | 'plain'
+
+  static override styles: CSSResultGroup = styles
+}
+```
+
+```css
+/* web/src/accordion/item/accordion-item.css */
+[part='trigger'] {
+  min-block-size: var(--helix-size-control);
+  padding: var(--helix-space-sm);
+}
+```
+
+## Styling from the outside
+
+Shadow DOM markup uses CSS Shadow Parts, not class names. Every structural
+element carries a `part`, which doubles as the public override API:
+
+```css
+helix-accordion-item::part(trigger) {
+  font-weight: 600;
+}
+```
+
+For single-knob changes, prefer the per-component custom property. It defaults
+to a system token, so overriding it restyles one component without touching
+`--helix-*` and affecting everything else:
+
+```css
+helix-accordion {
+  --accordion-radius: 1rem;
+}
+```
+
+## The window before an element upgrades
+
+A custom element is an inline, unstyled box until its definition loads, and its
+light-DOM children render immediately in document order. So a card arrives as a
+run of unstyled text and then snaps into a card. The window is short and it is
+most visible on a server-rendered page, where the markup is there long before
+the JavaScript is.
+
+`@fusion.dev/helix` closes it with `elements.css`, which hides every one of its
+tags until the definition lands:
+
+```css
+helix-card:not(:defined) {
+  visibility: hidden;
+}
+```
+
+**The base tier ships no such file, and that is deliberate rather than
+missing.** Three reasons, and the third is the one that matters to you.
+
+It is a decision rather than a mechanism. The rules the library ships below the
+styled tier are the ones a component cannot work without: `overflow` is what
+creates a scrollport, `[hidden]` is the platform's own semantics. Hiding an
+element that has not upgraded is a preference between two imperfect frames, and
+the content is in the markup either way, so a crawler reads it regardless.
+
+It is a document rule, not a component one. Nothing can help from inside,
+because before the upgrade there is no shadow root to put a rule in. It has to
+live in your stylesheet, which makes it yours to decide.
+
+And a blanket file would be wrong for you anyway. You import the handful of
+base elements you use, not all of them, so a generated list would hide tags you
+never ship. Write the ones you have:
+
+```css
+helix-base-accordion:not(:defined),
+helix-base-dialog:not(:defined) {
+  visibility: hidden;
+}
+```
+
+`visibility` rather than `display`, so the element keeps its place in the
+layout and the page does not reflow when it upgrades. `display: none` collapses
+the box and the content jumps in when the definition arrives, which trades a
+flash of unstyled text for a shift of everything under it.
+
+You may want neither. A page whose first paint matters more than its last
+inch, or one that has to be readable with JavaScript disabled, is better off
+letting the unstyled markup show. That choice is the reason this file is not
+made for you.
+
+## Mixins and tooling
+
+`open` and `defaultOpen` come from `MixinControllerOpen` in `@fusion.dev/helix-core`.
+The manifest analyzer cannot follow a mixin into another package, so any
+mixin-provided API a component exposes has to be documented on the component
+itself with `@event`, `@property`, or similar. Undocumented mixin API is
+invisible to IDE tooltips, the React wrapper generator, and any agent reading
+the manifest.

package/content/tokens.mdx

@@ -0,0 +1,88 @@
+---
+description: The two layers, the surface ladder, and what is enforced.
+pinned: true
+section: Theming
+title: Tokens
+---
+
+# Tokens
+
+Two layers. You see the second.
+
+| Layer | Shape | Who may use it |
+|---|---|---|
+| Primitive | `--_helix-neutral-500` | `@fusion.dev/helix-styles` only |
+| Semantic | `--helix-color-primary` | everything, including you |
+
+Every semantic token answers *what is this for*, never *what value is it*. There
+are fifteen categories and every token is in exactly one: `color` `space`
+`radii` `font` `text` `weight` `leading` `tracking` `border` `shadow`
+`material` `duration` `easing` `size` `layer`.
+
+The leading underscore is the whole convention: `--_helix-` is private and may
+be renamed or re-spaced without notice. Reaching past the semantic layer is the
+one thing that will break under you.
+
+## The surfaces
+
+Depth is distance from the page, in whichever direction there is room. The page
+is white in light and black in dark, so in light there is nothing above white to
+be lifted into: a raised surface goes *down* the ramp, not up.
+
+- **`background`**: the page.
+- **`surface`**: a plane on the page. A card, a panel you own.
+- **`surface-raised`**: something lifted while still *lying on* the page: a
+  selected tab's pill, a hovered row, an option under the pointer. It has the
+  page on all sides, so it is told apart by its fill, which on white has to be a
+  step darker.
+- **`surface-overlay`**: something *over* the page rather than on it: a menu, a
+  popover, a dialog, and the thumb of a switch or a segmented control. It is
+  told apart by its shadow and by what it covers, so on white it is white.
+- **`surface-sunken`**: a well you put a value into, an input's fill, a track, a
+  groove.
+
+**`raised` and `overlay` are the pair worth learning.** They land on the same
+step in dark mode, which is why one token tried to do both jobs for a while. In
+light they want opposite fills: a hovered row must be darker than a white page,
+and a thumb must be lighter than the groove it sits in. If something looks
+almost right in dark and wrong in light, this is usually why.
+
+## Per-component hooks
+
+```css
+helix-card {
+  --card-padding: var(--helix-space-lg);
+}
+```
+
+`--card-padding` is not a Helix token. It is a hook that particular component
+exposes, documented on the component, and it defaults to a semantic token. Use
+them to nudge one component; use the semantic tokens to move everything.
+
+## What is enforced
+
+Four things fail the build:
+
+1. **A raw value where a token exists.** `#e5e5e5` when a neutral is right there.
+2. **A primitive referenced from outside `@fusion.dev/helix-styles`.**
+3. **A reference to a token that does not exist.**
+4. **A component hook nothing reads**, and a primitive nothing resolves into.
+
+The third earns its keep on its own: a renamed token resolves to nothing, the
+property silently falls back to a browser default, and the code looks correct
+while the component is quietly unstyled.
+
+## Theming
+
+Both modes live in one declaration:
+
+```css
+--helix-color-surface: light-dark(var(--_helix-neutral-50), var(--_helix-neutral-900));
+```
+
+Which half resolves is decided by `color-scheme` and nothing else, so the color
+mode is a single attribute and no token is restated to honor it. Set
+`data-color-mode="light"` or `"dark"` on any element to theme that subtree.
+`color-scheme` inherits, so a light preview inside a dark page is one attribute.
+
+Absent, it follows the operating system.

package/content/typography.mdx

@@ -0,0 +1,117 @@
+---
+description: Three families, one scale, and a heading that is a real heading.
+section: Foundations
+title: Typography
+---
+
+# Typography
+
+## The families
+
+[//]: # (tokens:font)
+
+| Token | Value | For |
+| --- | --- | --- |
+| `--helix-font-sans` | `ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif` | Everything, unless it is one of the two below. |
+| `--helix-font-mono` | `ui-monospace, SFMono-Regular, "SF Mono", Menlo, monospace` | Code, and anything that has to line up in a column. |
+| `--helix-font-display` | `ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif` | Headings meant to be looked at rather than read. Falls back to the sans face. |
+
+[//]: # (/tokens)
+
+Three, not a scale of weights and widths, because a design system with more type
+families than a product has uses ends up with two that mean the same thing.
+
+## The scale
+
+`--helix-text-xs` through `--helix-text-3xl`, plus `--helix-text-control`, which
+is the size a control's own text takes and follows the region's density rather
+than the type scale.
+
+**The scale is applied to real headings by the base layer, not by a component.**
+
+```css
+:where([data-prose] h1) { font-size: var(--helix-text-3xl); }
+:where([data-prose] h2) { font-size: var(--helix-text-2xl); }
+```
+
+Styling the element rather than a component means the markup and the appearance
+cannot disagree by default, and it reaches prose the design system never renders:
+anything out of a CMS, a markdown file, or a rich-text field lands inside
+`[data-prose]` and comes out right without being rewritten.
+
+**`Text` exists for the case where they genuinely have to come apart.** A
+section's second heading sometimes has to look smaller without lying about the
+outline, and a `<p>` sometimes has to read as a caption, so `as` chooses the
+element and `variant` chooses the ramp:
+
+```html
+<helix-text
+  as="h3"
+  variant="body"
+>Reads as body, outlines as a heading</helix-text>
+```
+
+They default to matching, so `as="h2"` and nothing else is the common case, and
+the pairing is resolved in CSS rather than by writing an attribute onto the host,
+because that would be a hydration mismatch in every React consumer. Size, weight
+and leading are not properties: a ramp is a decision the system already made, and
+exposing the parts offers a few hundred combinations of which a handful are
+right. There is no separate `Heading` component, because that is `as`.
+
+## Applying it to your own text
+
+```html
+<article data-prose>
+  <h2>A real heading</h2>
+  <p>Body text, at the right measure and leading.</p>
+</article>
+```
+
+`[data-prose]` is the container. Inside it, headings, paragraphs, lists, links
+and code are all styled from the token layer.
+
+For one-off text outside prose, `[data-text]` carries the ramp:
+
+```html
+<span data-text="sm">Fine print</span>
+```
+
+## The vertical metrics
+
+[//]: # (tokens:leading)
+
+| Token | Value | For |
+| --- | --- | --- |
+| `--helix-leading-tight` | `1.2` | Body text set close, for a short measure. |
+| `--helix-leading-normal` | `1.5` | Body text, and the default a paragraph takes. |
+| `--helix-leading-loose` | `1.7` | Body text set open, for a long measure or a small size. |
+| `--helix-leading-heading` | `calc(0.99em + 0.5rem)` | Headings, which want less than a paragraph. Written as a length plus an em so it tightens as the type grows. |
+
+[//]: # (/tokens)
+
+[//]: # (tokens:tracking)
+
+| Token | Value | For |
+| --- | --- | --- |
+| `--helix-tracking-tight` | `-0.01em` | Large type, which needs the letters closer than a paragraph does. |
+| `--helix-tracking-normal` | `0` | Body text, and the default. |
+| `--helix-tracking-wide` | `0.02em` | Small capitals and labels, which need the room. |
+| `--helix-tracking-wider` | `0.12em` | An uppercase eyebrow, which needs more room than a label. |
+
+[//]: # (/tokens)
+
+[//]: # (tokens:weight)
+
+| Token | Value | For |
+| --- | --- | --- |
+| `--helix-weight-regular` | `400` | Body text, and the weight most of a page is set in. |
+| `--helix-weight-medium` | `500` | A label, or a heading that should not shout. |
+| `--helix-weight-semibold` | `600` | A heading, and the heaviest this system goes. |
+
+[//]: # (/tokens)
+
+**Headings have their own leading token rather than a smaller number of the body
+one.** A heading set at the paragraph's line height reads as loose at every
+size, and the correction is not proportional: the larger the type, the less
+leading it wants. One token expresses that once instead of a magic multiplier at
+every heading level.