@fusion.dev/helix-docs 0.104.1 → 0.105.0

package/content/coding-agents.mdx

@@ -1,5 +1,5 @@
 ---
-description: Every surface here is readable by a machine, and where each one is.
+description: The files an AI agent can read to write Helix code, and where to find each one.
 order: 4
 section: Getting started
 title: Coding agents
@@ -7,9 +7,9 @@ title: Coding agents
 
 # Coding agents
 
-An agent writing Helix code should not have to read a rendered website. Three
-surfaces give it the library as text, all generated from the sources this site
-renders from.
+We publish Helix as text for agents that write Helix code, so an agent does not
+need to read the rendered website. Three sources give it the library as text.
+We generate all three from the same sources as this site.
 
 ## The manifest
 
@@ -18,43 +18,54 @@ https://fusion.dev/helix/custom-elements.json
 @fusion.dev/helix/custom-elements.json
 ```
 
-A URL and a package path, the same file either way. **Both exist because a
-specifier is reachable from a `node_modules` and from nowhere else**, and an
-agent that found the library through `llms.txt` has this site and no checkout.
+The URL and the package path serve the same file. A package path works only
+from a `node_modules` folder. An agent that found Helix through `llms.txt` can
+reach this site and has no checkout, so it needs the URL.
 
-Every element, every property with its literal type union, every event with its
-class, every slot, every part, every custom property. It is what the framework
-typings, the reference documentation and the site's component pages are all
-generated from, so it cannot disagree with them.
+The manifest lists:
 
-**A generated manifest is what makes hallucinating a component impossible to
-sustain.** The vocabulary is the file: a tag that is not in it does not exist,
-and a prop value outside a declared union is a value the component will reject.
+- every element
+- every property, with its literal type union
+- every event, with its class
+- every slot
+- every part
+- every custom property
 
-Literal unions rather than named types are enforced at analysis time for exactly
-this reason: `'ghost' | 'outlined' | 'solid' | 'subtle'` tells a reader what to
-write, where `ButtonEmphasis` tells them to go and look somewhere else.
+We generate the framework typings, the reference documentation, and the site's
+component pages from the manifest, so they always match it.
 
-## Markdown for every family
+**If a tag is not in the manifest, it does not exist.** An agent can check every
+tag and value it writes against the file, so an invented component is caught. A
+prop value outside a declared union is invalid.
+
+For the same reason, the analyzer requires literal unions for property types.
+`'ghost' | 'outlined' | 'solid' | 'subtle'` shows you what to write. A named
+type such as `ButtonEmphasis` sends you somewhere else to look.
+
+## Markdown and JSON for each component family
 
 ```
 /components/<family>.md
 /components/<family>.json
 ```
 
-Static files. The `.md` carries the family's metadata, every element's
-description and API tables, and **the examples**, which the HTML page
-deliberately does not: that page answers what a component can do and the sandbox
-beside it answers what it looks like, and a reference that started collecting
-pictures would stop being the one place you can trust to be complete. An agent
-has no sandbox to be sent to, and to it an example is text rather than a
-picture.
+These are static files. The `.md` file has:
+
+- the family's metadata
+- every element's description and API tables
+- the examples
+
+The HTML page leaves the examples out on purpose. The page lists what a
+component can do, and the sandbox beside it shows what the component looks
+like. Keeping pictures out of the reference keeps it the one place you can trust
+to be complete. An agent cannot use the sandbox, and it reads an example as
+text, so the `.md` file includes the examples.
 
-The `.json` is the same family as structured data.
+The `.json` file has the same family as structured data.
 
-## What is enforced
+## Rules the build checks
 
-These are the difference between code that looks right and code that passes:
+Code that looks right can still fail these checks:
 
 | Rule | Check |
 |---|---|
@@ -63,11 +74,11 @@ These are the difference between code that looks right and code that passes:
 | A documented CSS hook must be read | `helix component --only hooks` |
 | A visual property draws from its axis | `helix component`'s `axes` |
 | A form control styles with `:disabled` | `helix component --only disabled` |
-| A component that animates answers reduced motion | `helix component --only motion` |
+| A component that animates supports reduced motion | `helix component --only motion` |
 | No component reads a primitive token | `helix component`'s `tokens` |
 
-If you are generating Helix code, the first two are the ones that produce
-working-looking output that is wrong.
+If you generate Helix code, watch the first two rules. Breaking them produces
+output that looks like it works and is wrong.
 
 ## The index
 
@@ -75,57 +86,64 @@ working-looking output that is wrong.
 /llms.txt
 ```
 
-Every page on the site, grouped, each one linked at its `.md` and annotated with
-a sentence. Generated from the same route registry the sitemap comes from, so a
-page cannot exist without appearing here and cannot appear here without
-existing.
+`llms.txt` lists every page on the site, in groups. Each entry links to the
+page's `.md` file and has a one-sentence summary. We generate it from the same
+route registry as the sitemap. Every page appears in it, and every entry in it
+is a page that exists.
 
-Start there rather than crawling: one request, and it names every page on the
-site plus the two machine-readable surfaces above. No count here, because a
-number typed into prose is a number that goes stale.
+Start with `llms.txt`. In one request, it names every page on the site and the
+two machine-readable sources above. This guide gives no page count, because a
+number typed into prose goes stale.
 
-## From a component's page
+## Links on each component page
 
-Every family page carries a menu beside its title with **View Markdown**, **Copy
-Markdown**, and links that hand the document's URL to Claude or to Cursor. The
-URL rather than the contents, because the URL stays current and a pasted copy
-starts going stale the moment it is pasted.
+Each family page has a menu beside its title with:
 
-## The one thing a document cannot answer
+- **View Markdown**
+- **Copy Markdown**
+- links that send the document's URL to Claude or to Cursor
+
+The links send the URL, because the URL stays current. A pasted copy starts to
+go stale as soon as you paste it.
+
+## Compute a theme with `helix mcp`
 
 ```sh
 helix mcp
 ```
 
-The three surfaces above are closed sets: every tag, every token, every example,
-all published and all fetchable. What none of them holds is what *your* brand
-color derives to, because the input is a color and the domain is infinite, so the
-answer has to be computed when it is asked.
+The three sources above are fixed sets. Every tag, token, and example is
+published, and an agent can fetch it. None of them has the theme for *your*
+brand color. The input is a color, and there are infinitely many colors, so
+Helix has to compute the theme when an agent requests it.
+
+`helix mcp` runs an MCP server over stdio with two tools:
+
+- `helix_audit_theme` measures every foreground against the background it is
+  painted on. It reports each pair with its ratio and target.
+- `helix_derive_theme` returns the CSS.
 
-`helix mcp` serves that over stdio as an MCP server, with two tools:
-`helix_audit_theme`, which measures every foreground against the ground it is
-really painted on and reports each pair with its ratio and target, and
-`helix_derive_theme`, which returns the CSS. Both take the same JSON a
-`helix.theme.json` holds.
+Both take the same JSON that a `helix.theme.json` file holds.
 
-**It refuses to hand back a palette that fails its own targets**, the way
-`helix theme build` does. Pasting one into a stylesheet is worse than reading a
-warning above it, and an agent does not read warnings.
+**`helix mcp` does not return a palette that fails its own targets**, the same
+as `helix theme build`. A failing palette pasted into a stylesheet is worse than
+a warning above it, and an agent does not read warnings.
 
-**You run it and nobody hosts it.** A server we operated would be one more
-service standing between you and your own tokens; this is a subcommand of a
-binary you installed, talking to a client you chose, with no network in it.
+You run `helix mcp` yourself, and we do not host it. A server we operated would
+be one more service between you and your own tokens. `helix mcp` is a
+subcommand of a binary you installed. It talks to a client you chose and makes
+no network requests.
 
-## What is not here
+## What we do not publish for agents
 
-**`llms-full.txt`, or any other whole-library download.** Concatenating every
-page into one file is out of date the moment anything changes, where the links
-in `llms.txt` are individually cacheable and individually current.
+**`llms-full.txt`, or any other whole-library download.** A single file with
+every page goes out of date as soon as anything changes. Each link in `llms.txt`
+can be cached on its own and stays current on its own.
 
-What such a file would be for is covered better by the two surfaces already
-here. `llms.txt` is the index, one request, and each family's `.md` is the
-document. Fetch the families you are using.
+The two sources already here cover what such a file would be for. `llms.txt` is
+the index, in one request, and each family's `.md` file is its document. Fetch
+the families you use.
 
-**A search index.** The site has one for humans; there is nothing an agent can
-query yet, and `llms.txt` plus the documents it names is a smaller thing to read
-than most search APIs are to learn.
+**A search index.** The site has a search index for people. There is nothing an
+agent can query yet. Reading `llms.txt` and the documents it names takes less
+work than learning most search APIs.

package/content/color-modes.mdx

@@ -1,15 +1,16 @@
 ---
-description: One attribute, two modes, and no token restated to honor it.
+description: Switch between light and dark mode with one attribute. Each token declares both values once.
 section: Foundations
 title: Color modes
 ---
 
 # Color modes
 
-Light and dark are one attribute and no duplicated tokens. There is no second
-stylesheet, no `.dark` class to toggle, and nothing to remember to update twice.
+One attribute switches between light and dark mode. Each token declares its
+light and dark values together. You do not need a second stylesheet, a `.dark`
+class, or a second copy of any value.
 
-## How it works
+## How color modes work
 
 ```css
 :root {
@@ -18,21 +19,20 @@ stylesheet, no `.dark` class to toggle, and nothing to remember to update twice.
 }
 ```
 
-Every token is written once, with both halves in a `light-dark()`. Which half
-resolves is decided by `color-scheme` and nothing else, so the mode is a single
-inherited property and no token is restated to honor it. That is 156
-declarations across the shipped stylesheets, 71 of them in the token layer,
-expressing two modes without a second copy of anything.
+Each token is written once, with its light and dark values in `light-dark()`.
+The `color-scheme` property alone decides which value applies. `color-scheme`
+inherits, so one property sets the mode for an element and everything inside
+it. The shipped stylesheets use `light-dark()` in 156 declarations, 71 of them
+in the token layer.
 
-## Setting the mode
+## Set the mode
 
 ```html
 <html data-color-mode="dark">
 ```
 
-`[data-color-mode="light"]` and `[data-color-mode="dark"]` set `color-scheme`,
-and `color-scheme` inherits, so the attribute works **on any element** rather
-than only on the root:
+`[data-color-mode="light"]` and `[data-color-mode="dark"]` set `color-scheme`.
+Because `color-scheme` inherits, **the attribute works on any element**:
 
 ```html
 <div data-color-mode="light">
@@ -40,24 +40,24 @@ than only on the root:
 </div>
 ```
 
-That is the whole mechanism, and it is why the theme builder can show you a
-light and a dark rendering of the same component side by side without rendering
-two documents.
+The theme builder uses the same attribute to show a component in light and dark
+mode side by side in one document.
 
-## Following the system
+## Follow the operating system
 
-Unset, `:root` declares `color-scheme: light dark`, which means the operating
-system decides. That is the default and it is usually right.
+When you do not set a mode, `:root` declares `color-scheme: light dark`, and the
+operating system decides the mode. This is the default, and it is usually the
+right choice.
 
-A `prefers-color-scheme` media query still exists in the token layer for one
-narrow case rather than being the mechanism: a value that has to be *derived*
-from the mode, rather than chosen between two, cannot be expressed as
-`light-dark()` and has to ask which mode is current.
+The token layer uses a `prefers-color-scheme` media query in one case.
+`light-dark()` chooses between two values. A value that has to be *computed*
+from the mode cannot use `light-dark()`, so a media query checks which mode is
+current.
 
-## The one component that inverts
+## Toast uses the opposite mode
 
-`Toast` renders in the opposite mode to the page it is on, which is why it is
-the exception written into the base layer:
+`Toast` renders in the opposite mode to the page it is on. The base layer sets
+this with one rule:
 
 ```css
 helix-toast:not([data-color-mode]) {
@@ -65,14 +65,13 @@ helix-toast:not([data-color-mode]) {
 }
 ```
 
-A toast is chrome over the page rather than part of it, and inverting is how it
-reads as separate without a border. Opt out by putting `data-color-mode` on it,
-which then wins, because the rule only applies to a toast that has not been
-told.
+A toast sits over the page. The opposite mode sets it apart from the page
+without a border. To choose a toast's mode yourself, set `data-color-mode` on
+it. The rule applies only to a toast without that attribute.
 
-## What this means for your own CSS
+## Colors in your own CSS
 
-Write `light-dark()` for your own colors and set nothing else:
+Write your own colors with `light-dark()`. You do not need anything else:
 
 ```css
 .callout {
@@ -80,8 +79,12 @@ Write `light-dark()` for your own colors and set nothing else:
 }
 ```
 
-It will follow the page, follow a subtree that was told otherwise, and follow
-the system when nothing has said. Do not write a `prefers-color-scheme` query
-for it, and do not key off the `data-color-mode` attribute: both stop working
-the moment a subtree overrides the mode, which is the case this design exists to
-make cheap.
+The color then follows:
+
+- The page's mode
+- The mode of a subtree that sets its own
+- The operating system, when nothing sets a mode
+
+Do not write a `prefers-color-scheme` query for it, and do not select on the
+`data-color-mode` attribute. Both stop working when a subtree sets its own mode,
+and this design exists to make that easy.

package/content/color.mdx

@@ -1,81 +1,95 @@
 ---
-description: The roles, the ramps, and why the palette is solved rather than picked.
+description: The color roles, why Helix uses OKLCH, and how the engine meets contrast targets.
 section: Foundations
 title: Color
 ---
 
 # Color
 
-Seventy-four of the library's 185 tokens are color, which is most of what a
-theme is. They are roles rather than values: nothing in Helix is named after
-what it looks like, because a name like `--brand-blue-500` stops being true the
-moment anybody rethemes.
+Seventy-four of the library's 185 tokens are colors, and they make up most of a
+theme. Each color token is named for its role. No token is named for how it
+looks, because a name like `--brand-blue-500` becomes wrong as soon as you change
+the theme.
 
-## The roles
+## Color roles
 
-**Grounds**, which things sit on. `background` is the page itself, and the
-surfaces above it are a ladder rather than a set:
+### Grounds
+
+Grounds are the colors that content sits on. `background` is the page itself.
+The surfaces above it form an ordered ladder:
 
 [//]: # (tokens:surface-ladder)
 
 | Token | Sample | For |
 | --- | --- | --- |
-| `--helix-color-background` | <span data-token-swatch style={{ background: 'var(--helix-color-background)' }} /> | The page. Told apart by nothing, because it is the ground. |
-| `--helix-color-surface` | <span data-token-swatch style={{ background: 'var(--helix-color-surface)' }} /> | A plane on the page: a card, or a panel you own. Told apart by a fill, an edge or a lift, whichever the policy leads with. |
-| `--helix-color-surface-raised` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-raised)' }} /> | Lifted while still lying on the page: a selected tab, a hovered row. Told apart by its fill, which goes down the ramp rather than up. |
-| `--helix-color-surface-overlay` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-overlay)' }} /> | Over the page rather than on it: a menu, a popover, a dialog. Told apart by its shadow and by what it covers. |
-| `--helix-color-surface-sunken` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-sunken)' }} /> | A well a value goes into: an input, a track, a groove. Told apart by its fill, inward. |
+| `--helix-color-background` | <span data-token-swatch style={{ background: 'var(--helix-color-background)' }} /> | The page background. Every other surface sits on it. |
+| `--helix-color-surface` | <span data-token-swatch style={{ background: 'var(--helix-color-surface)' }} /> | A surface on the page, such as a card or a panel. The separation policy sets it apart with a fill, a border, or a shadow. |
+| `--helix-color-surface-raised` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-raised)' }} /> | A raised surface on the page, such as a selected tab or a hovered row. Its fill is one step down the ramp. |
+| `--helix-color-surface-overlay` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-overlay)' }} /> | A surface over the page, such as a menu, a popover, or a dialog. Its shadow sets it apart. |
+| `--helix-color-surface-sunken` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-sunken)' }} /> | A recessed surface that holds a value, such as an input, a track, or a groove. Its fill sets it apart. |
 
 [//]: # (/tokens)
 
-Which one to reach for is a question about the geometry rather than about the
-shade, and it is the thing people most often get wrong. See [Surfaces and
+Choose a surface by where the element sits relative to the page. This is the
+choice people most often get wrong. See [Surfaces and
 separation](./surfaces-and-separation).
 
-**Inks**, which go on grounds. `foreground`, then `foreground-muted` and
-`foreground-subtle` for text that recedes, and `foreground-on-accent` for text
-that sits on a filled accent rather than on a surface.
+### Inks
+
+Inks are the colors that go on grounds. The base ink is `foreground`.
+
+- `foreground-muted` and `foreground-subtle` are for text that recedes.
+- `foreground-on-accent` is for text on a filled accent color.
+
+### Intent
+
+Intent colors show what something means.
+
+- `primary` and `accent` are for emphasis. Each has `-hover`, `-active`, and
+  `-subtle` variants.
+- `info`, `success`, `warning`, and `danger` are for status. Each has a
+  `-surface` and a `-surface-hover` variant for the tinted box that holds the
+  message.
+
+### Series
+
+Helix has twenty-four series colors for charts. They are ordered, so a chart
+with three lines uses the first three. We chose the colors so that the first
+ones in the list stay easy to tell apart, however many a chart uses.
+
+### Syntax
 
-**Intent**, which says what something means. `primary` and `accent` for
-emphasis, each with `-hover`, `-active` and `-subtle`; `info`, `success`,
-`warning` and `danger` for status, each with a `-surface` and a `-surface-hover`
-for the tinted box the message sits in.
+The eight syntax roles for code are `callable`, `comment`, `constant`,
+`invalid`, `keyword`, `name`, `string`, and `tag`. A full editor theme has more
+roles. Helix has fewer because code in documentation only needs to be read.
 
-**Series**, twenty-four of them, for charts. Ordered rather than arbitrary: a
-chart with three lines uses the first three, and they are chosen to stay
-distinguishable in that order rather than to look good as a full set.
+## Why colors use OKLCH
 
-**Syntax**, eight roles for code: `callable`, `comment`, `constant`, `invalid`,
-`keyword`, `name`, `string`, `tag`. Deliberately fewer than a full editor theme,
-because a code block in documentation is read rather than edited.
+Every Helix color is written in OKLCH. In sRGB, equal numeric steps do not look
+equal, which makes ramps and contrast math unreliable. A ramp with even numeric
+steps looks uneven. A contrast solver that works in sRGB cannot converge on a
+target that it can measure.
 
-## OKLCH
+OKLCH lets the theme engine *solve* for a palette from your brand color. See
+[Deriving a theme](./theming).
 
-Every color is authored in OKLCH. Equal numeric steps in sRGB are not equal
-perceptual steps, which makes both ramp generation and contrast arithmetic
-unreliable: a ramp that is even by the numbers looks uneven, and a contrast
-solver working in the wrong space cannot converge on a target it can measure.
+## How the engine meets contrast targets
 
-Concretely, this is what lets the theme engine take a brand color and *solve*
-for a palette rather than have someone pick one. See [Deriving a
-theme](./theming).
+The engine measures each ink against the ground it will be painted on. It then
+searches for the lightness that meets the target. Every pair it produces meets
+the target.
 
-## Contrast is a guarantee
+The engine can solve only the pairs it knows about, so we check two things:
 
-The engine measures every ink against the ground it will really be painted on
-and searches for the lightness that meets the target, rather than proposing a
-value and checking it afterwards. Every pairing it produces meets the target by
-construction.
+- We compare the engine's surface model with what the components paint.
+- We measure every pair on a rendered page.
 
-That guarantee is only as good as the list of pairs somebody thought of, so two
-things are checked rather than one. The engine's declared surface model is held
-against what components actually paint, and then every pairing is measured on a
-laid-out page, which is the only way to see the ones no stylesheet states: just
-eleven rules in the library set an ink and a ground together, where 165 set only
-an ink and 112 only a ground, and a pairing the cascade assembled is still a
-pairing a reader has to be able to read.
+The second check finds pairs that no single CSS rule states. Only eleven rules
+in the library set an ink and a ground together. Another 165 set only an ink,
+and 112 set only a ground. The cascade combines them into the rest of the
+pairs, and each of those pairs must still be readable.
 
-## Do not reach past the semantic layer
+## Use only semantic tokens
 
 ```css
 /* Yours to read. */
@@ -85,8 +99,7 @@ color: var(--helix-color-foreground-muted);
 color: var(--_helix-neutral-500);
 ```
 
-The primitive layer underneath, `--_helix-neutral-500` and its kind, is
-`helix/styles`'s own business. The underscore marks it private and the
-indirection is the whole point: it is what lets a theme change what
-`--helix-color-primary` resolves to without every component knowing which step
-of which ramp it happened to be.
+Primitive tokens such as `--_helix-neutral-500` belong to `helix/styles`. The
+underscore marks them as private. Components use only semantic tokens, such as
+`--helix-color-primary`. A theme can change what a semantic token resolves to,
+and no component depends on which step of which ramp a color comes from.