@fusion.dev/helix-docs 0.104.0 → 0.105.0

package/content/theming.mdx

@@ -1,28 +1,26 @@
 ---
-description: Deriving an accessible token set from intent inputs.
+description: Compute a complete token set from your brand color and a few other inputs.
 section: Theming
 title: Deriving a theme
 ---
 
 # Theming
 
-**Tokens are a function, not a table.**
+Helix computes your color tokens from a few inputs, such as your brand color.
 
-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.
+When a design system ships two hundred fixed color values, you theme it by
+changing them one at a time. A change to one value can break the contrast of a
+component elsewhere, and nothing tells you.
 
-`@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.
+`@fusion.dev/helix-theme` computes a complete token set from a few intent
+inputs, and every text and background pair meets its contrast target.
 
 ## Two ways to theme
 
-They are both real and they are not the same thing, so they have different
-names.
+Helix has two ways to theme, and they give different guarantees.
 
-**Tuned** is the CSS path. Write a seed, the stylesheet re-derives, and nothing
-has to be installed or run:
+**Tuned** uses CSS only. Set a seed and the stylesheet recomputes the colors,
+with nothing to install or run:
 
 ```css
 :root {
@@ -32,19 +30,19 @@ has to be installed or run:
 }
 ```
 
-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.
+Set seeds at `:root` or on an element with `[data-helix-theme]`. A seed on any
+other element has no effect. A `var()` inside a custom property is substituted
+on the element where the property is *declared*, so the ramp has already
+resolved at the root. The stylesheet declares the ramp again on each
+`[data-helix-theme]` element, so the ramp there reads the seeds you set on it.
 
-**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.
+Tuned does not guarantee contrast. CSS has no contrast function.
+`oklch(from …)` can step and rotate a color, but it cannot search for the
+lightness that meets a target. The contrast figures built into the ramp are
+exact for the default seed and approximate for any other.
 
-**Verified** is the engine. It solves rather than steps, measures every pair it
-emits, and hands back an artifact:
+**Verified** uses the theme engine. It searches for each color that meets its
+target, measures every pair, and returns the theme with any violations:
 
 ```ts
 import { deriveTheme, toCss } from '@fusion.dev/helix-theme'
@@ -62,42 +60,50 @@ if (theme.violations.length > 0) {
 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 colors 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.
+The CSS from `toCss` includes the seeds as well as the tokens. The stylesheet
+computes the values the engine does not, from the same seeds the engine used:
 
-Reach for tuned to try a color. Reach for verified to ship one.
+- The twenty-four series colors for charts
+- The spacing scale
+- The corner radii
 
-## Why OKLCH
+This keeps both ways of theming in agreement on the same page.
 
-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.
+Use tuned to try a color. Use verified for the theme you ship.
 
-The brand color keeps its hue and chroma; only lightness moves to meet the
-target. That is what preserves brand identity while guaranteeing contrast.
+## Why Helix uses OKLCH
 
-## What it protects against
+Equal numeric steps in sRGB do not look like equal steps. That makes scales and
+contrast math in sRGB unreliable. Helix computes themes in OKLCH for this
+reason. Colors are written in OKLCH and converted to other formats on output.
 
-Both of these produce a palette that passes review and fails in production.
-Both are covered by regression tests.
+The engine keeps your brand color's hue and chroma and changes only its
+lightness to meet the target. Your brand color stays recognizable, and its
+contrast is guaranteed.
 
-**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.
+## Errors the engine prevents
 
-**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.
+The engine prevents two errors. Each one produces a palette that passes review
+and fails in production. Regression tests cover both.
 
-## Inspecting a theme
+### Colors outside the sRGB gamut
 
-Every derived token carries the check that produced it:
+A near-white surface with a brand tint can fall outside the sRGB gamut.
+Converting it to hex then clips it, which changes its hue and breaks the
+contrast the engine solved for. The engine fits every color into the gamut
+before it solves against that color. When fitting changes a token, the token
+reports `chromaReduced`.
+
+### Text on more than one surface
+
+Text appears on `surface` as often as on `background`, for example in cards,
+dialogs, and menus. In a dark theme, `surface` is *lighter* than `background`.
+Light text that passes on the page can lose contrast inside every card. The
+engine solves each foreground color against the hardest surface it appears on.
+
+## Inspect a theme
+
+Each derived token includes the result of its contrast check:
 
 ```ts
 const theme = deriveTheme({ brand })
@@ -107,5 +113,6 @@ for (const token of theme.tokens) {
 }
 ```
 
-`violations` is empty when the theme passes. Anything that could not reach its
-target at the requested chroma is reported there rather than shipped.
+`violations` is empty when the theme passes. A color that cannot reach its
+target at the requested chroma is reported in `violations`, so you can fix it
+before you ship.

package/content/tiers.mdx

@@ -7,39 +7,47 @@ title: Tiers
 
 # Tiers
 
-Helix ships as four stacked packages. Each has one job, and the dependency
-direction never reverses.
+Helix is four packages stacked on each other. Each package has one job, and each
+depends only on the packages below it.
 
 | 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`, `turbo run styles` |
+| `@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).
+`@fusion.dev/helix-theme` and `@fusion.dev/helix-icons` ship beside the stack.
+Neither is a tier, and you do not need either one to render a component.
 
-## Why the split
+There is no React package. We generate the framework typings into
+`@fusion.dev/helix`, and the bridge that repairs React's hydration of custom
+events is in `@fusion.dev/helix-core`. See [React](./react).
 
-**`headless` must never depend on `turbo run styles`.**
+## Why the tiers are separate packages
 
-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.
+**`headless` must never depend on `styles`.**
 
-## What belongs where
+This rule lets you use the headless tier on its own. You install it and write
+all of the styling yourself. Nothing about how Helix looks comes with it. If
+styling moved down into the headless tier, the four packages would be one
+package split across four files.
 
-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.
+## What each tier contains
 
-The styled tier extends it and adds only presentation. Token references live
-here.
+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 the headless tier and adds only presentation. Token
+references live in the styled tier.
 
 ```ts
 // headless/src/accordion/item/accordion-item.ts
@@ -77,10 +85,11 @@ export class HelixAccordion extends HelixHeadlessAccordion {
 }
 ```
 
-## Styling from the outside
+## Style a component from your stylesheet
 
-Shadow DOM markup uses CSS Shadow Parts, not class names. Every structural
-element carries a `part`, which doubles as the public override API:
+Elements inside the shadow DOM carry no class names for you to select. Each
+structural element carries a `part`, and parts are the public API for overriding
+styles:
 
 ```css
 helix-accordion-item::part(trigger) {
@@ -88,9 +97,9 @@ helix-accordion-item::part(trigger) {
 }
 ```
 
-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:
+To change one value, set the component's own custom property. It defaults to a
+system token. Setting it restyles that one component and leaves `--helix-*` and
+every other component unchanged:
 
 ```css
 helix-accordion {
@@ -98,16 +107,16 @@ helix-accordion {
 }
 ```
 
-## The window before an element upgrades
+## Hide elements until they upgrade
 
-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.
+A custom element is an inline, unstyled box until its definition loads. Its
+light-DOM children render immediately, in document order. A card first appears
+as unstyled text and then changes into a card. The delay is short. It is most
+visible on a server-rendered page, where the markup arrives long before the
+JavaScript.
 
-`@fusion.dev/helix` closes it with `elements.css`, which hides every one of its
-tags until the definition lands:
+`@fusion.dev/helix` includes `elements.css`, which hides each of its tags until
+the tag's definition loads:
 
 ```css
 helix-card:not(:defined) {
@@ -115,22 +124,22 @@ helix-card:not(:defined) {
 }
 ```
 
-**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.
+**The base tier ships no such file on purpose.** There are three reasons, and
+the third one affects you most.
 
-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.
+First, hiding an element is a design choice. Below the styled tier, we ship only
+the rules a component cannot work without. For example, `overflow` creates a
+scrollport, and `[hidden]` is the platform's own semantics. Hiding an element
+that has not upgraded is a choice between two imperfect first frames. The
+content is in the markup either way, so a crawler reads it in both cases.
 
-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.
+Second, the rule belongs to the document. A component cannot apply it from
+inside, because there is no shadow root before the upgrade. The rule has to
+live in your stylesheet, so the choice is yours.
 
-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:
+Third, one file for every tag would not fit your project. You import only the
+base elements you use, so a generated list would include tags you never ship.
+Write the rule for the elements you have:
 
 ```css
 helix-base-accordion:not(:defined),
@@ -139,21 +148,20 @@ helix-base-dialog:not(:defined) {
 }
 ```
 
-`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.
+Use `visibility` 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. That replaces a flash of unstyled text
+with a shift of everything below 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.
+You may want to hide nothing. If your first paint matters more than the final
+layout, or your page has to be readable with JavaScript turned off, let the
+unstyled markup show. Because of that choice, we do not write the file 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.
+`open` and `defaultOpen` come from `MixinControllerOpen` in
+`@fusion.dev/helix-core`. The manifest analyzer cannot follow a mixin into
+another package. Document any API that a component gets from a mixin on the
+component itself, with `@event`, `@property`, or a similar tag. Mixin API
+without that documentation is missing from IDE tooltips, from the React wrapper
+generator, and from the manifest that agents read.

package/content/tokens.mdx

@@ -1,5 +1,5 @@
 ---
-description: The two layers, the surface ladder, and what is enforced.
+description: The two token layers, the surface tokens, and the rules the build enforces.
 pinned: true
 section: Theming
 title: Tokens
@@ -7,45 +7,59 @@ title: Tokens
 
 # Tokens
 
-Two layers. You see the second.
+Helix has two layers of tokens. You use the second layer, the semantic tokens.
 
 | 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.
+| Semantic | `--helix-color-primary` | Any code, including yours |
+
+Each semantic token is named for its purpose. The name does not describe its
+value. Every token belongs to exactly one of fifteen categories:
+
+- `color`
+- `space`
+- `radii`
+- `font`
+- `text`
+- `weight`
+- `leading`
+- `tracking`
+- `border`
+- `shadow`
+- `material`
+- `duration`
+- `easing`
+- `size`
+- `layer`
+
+The leading underscore marks a token as private. We may rename or re-space any
+`--_helix-` token without notice. Code that uses a primitive token can break
+when you update Helix, so use the semantic tokens.
+
+## Surface tokens
+
+A surface's depth is its distance from the page, in whichever direction has
+room. The page is white in light mode and black in dark mode. In light mode
+nothing is lighter than white, so a raised surface is *darker* than the page.
 
 - **`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, so one token looks like it would do both jobs. 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.
+- **`surface`**: a plane on the page, such as a card or a panel you own.
+- **`surface-raised`**: something lifted that still *lies on* the page, such as
+  a selected tab's pill, a hovered row, or an option under the pointer. The page
+  surrounds it on all sides, so its fill sets it apart. On a white page, that
+  fill is one step darker.
+- **`surface-overlay`**: something *over* the page, such as a menu, a popover, a
+  dialog, or the thumb of a switch or a segmented control. Its shadow and the
+  content it covers set it apart, so on a white page it is white.
+- **`surface-sunken`**: a well that holds a value, such as an input's fill, a
+  track, or a groove.
+
+**Use `raised` and `overlay` for different jobs.** They are the same color in
+dark mode, so one token can seem to do both jobs. In light mode they need
+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 a surface looks almost right in dark
+mode and wrong in light mode, it usually uses the wrong one of these two tokens.
 
 ## Per-component hooks
 
@@ -55,34 +69,39 @@ helix-card {
 }
 ```
 
-`--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.
+`--card-padding` is a hook that the card component exposes. Hooks are separate
+from the Helix tokens. Each component documents its own hooks, and each hook
+defaults to a semantic token. Use a hook to adjust one component. Use the
+semantic tokens to change every component.
 
-## What is enforced
+## What fails the build
 
-Four things fail the build:
+The build fails on four kinds of error:
 
-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.
+1. A raw value where a token exists, such as `#e5e5e5` where a neutral token
+   fits.
+2. A primitive token used outside `@fusion.dev/helix-styles`.
+3. A reference to a token that does not exist.
+4. A component hook that nothing reads, or a primitive token that nothing
+   resolves to.
 
-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.
+The third check would be worth running on its own. When a token is renamed, a
+reference to the old name resolves to nothing. The property falls back to a
+browser default without a warning. The code looks correct, and the component
+loses its styles.
 
-## Theming
+## Color modes
 
-Both modes live in one declaration:
+Each token declares its light and dark values 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.
+The `color-scheme` property alone decides which value applies. You set the
+color mode with one attribute, and no token is declared twice. Set
+`data-color-mode="light"` or `"dark"` on any element to set the mode for that
+element and everything inside it. `color-scheme` inherits, so one attribute
+shows a light preview inside a dark page.
 
-Absent, it follows the operating system.
+Without the attribute, the mode follows the operating system.