@fusion.dev/helix-docs 0.193.0 → 0.194.0

package/content/using-helix-with-an-agent.mdx

@@ -1,5 +1,5 @@
 ---
-description: Five mistakes that look like Helix bugs, and the files an agent should read.
+description: The rules an agent follows to write Helix code, and the five mistakes that look like Helix bugs.
 parent: coding-agents
 section: Getting started
 title: Using Helix with an agent
@@ -8,41 +8,52 @@ title: Using Helix with an agent
 
 # Using Helix with an agent
 
-This guide is in two places, and both say the same thing:
+This guide is what an agent reads before writing Helix code. It is also the
+`helix` skill: `skills/helix/SKILL.md` in `@fusion.dev/helix`, which matches the
+version installed, and the skill in Helix's plugin for coding agents. [Coding
+agents](./coding-agents) says how to install the plugin or link the skill.
 
-- this page, which [llms.txt](https://fusion.dev/llms.txt) indexes
-- `skills/helix/SKILL.md` inside `@fusion.dev/helix`, which matches the version
-  you installed and works offline
+## Use a Helix family wherever one exists
 
-[Link your tool to this guide](#link-your-tool-to-this-guide) says how to point
-each tool at one of them. [The MCP server](./coding-agents) works with any
-vendor and runs code, and Claude, Cursor, Windsurf, and Zed all support it.
+Write a Helix element for everything Helix has a family for, and a native
+element only for page structure. Before you write a native element, ask whether
+a family stands in for it:
 
-## Read the family before writing its tags
+- `helix api find <tag>`, or the MCP tool `helix_find`, answers a native tag
+  with its family: `button` finds Button, and `h1` finds Text.
+- Each family's file lists the native elements it replaces under `replaces`.
 
-```
-https://fusion.dev/helix/components/<family>.md
-https://fusion.dev/helix/components/<family>.json
-```
+These native elements have families:
 
-Each family's file lists:
+- controls: `button`, `input` of every visible type, `select`, and `textarea`
+- overlays and disclosure: `dialog` and `details`
+- text: `h1` to `h6` and `p`, which `helix-text` writes with `as="h1"` and the
+  rest
+- content: `img`, `picture`, `hr`, `ul`, `ol`, `table`, `code`, `pre`, `kbd`,
+  `blockquote`, `q`, `video`, `progress`, and `meter`
 
-- the import lines for the family
-- every tag
-- every property, with its literal union
-- every event, with its class and its React prop
-- every slot, part, and custom property
-- the examples, each with the import lines it needs
+Page structure stays native: `main`, `section`, `article`, `header`, `footer`,
+`nav`, `form`, `label`, `div`, `span`, and `a`. So does markup a CMS writes
+inside `data-prose`.
 
-**If a tag is not in a family's file, it does not exist.** A property value
-outside a declared union is invalid. Property types are literal unions for this
-reason. `'ghost' | 'outlined' | 'solid' | 'subtle'` shows you the values, and a
-named type such as `ButtonEmphasis` sends you somewhere else to find them.
+`helix scan` and the MCP tool `helix_check` report each native element a page
+writes where an installed family stands in for it, as `native-element`.
+
+## Look up a family before writing its tags
+
+Each family's API is in the packages you installed, and on this site:
+
+- `helix api family <family>`, or the MCP tool `helix_family`
+- `node_modules/@fusion.dev/helix/api.json`
+- `https://fusion.dev/helix/components/<family>.md` and `.json`
 
-The manifest at `https://fusion.dev/helix/custom-elements.json` holds every
-family in one file, which is several megabytes. Read the families you use.
-Start from `https://fusion.dev/llms.txt`. In one request, it names every
-document and the machine-readable sources.
+Each lists the import lines, every tag, every property with its literal union,
+every event with its React prop, every slot, part, and custom property, and the
+examples with the imports each one needs.
+
+**If a tag is not in a family's file, it does not exist.** A property value
+outside a declared union is invalid. Find a family by name, alias, or purpose
+with `helix api find`, or the MCP tool `helix_find`.
 
 ## Five mistakes that look like Helix bugs
 
@@ -147,12 +158,9 @@ Each missing layer has its own symptom:
 - Unstyled headings mean `base.css` is missing.
 - No color anywhere means `primitives.css` or `tokens.css` is missing.
 
-To tell the last two apart, look at the stylesheet. The screen looks the same.
-Without `tokens.css`, nothing declares `--helix-color-*`. Without
-`primitives.css`, all 185 semantic tokens are declared and every color resolves
-to `rgba(0, 0, 0, 0)`, because `tokens.css` refers to a primitive 297 times and
-to nothing else. A missing `primitives.css` looks like a working install, and
-`helix.css` exists to prevent it.
+To tell the last two apart, look at the stylesheet. Without `tokens.css`,
+nothing declares `--helix-color-*`. Without `primitives.css`, every token is
+declared and every color resolves to transparent.
 
 ## Choosing a component family
 
@@ -192,73 +200,25 @@ You can style a component in three ways. Try them in this order:
 belong to `@fusion.dev/helix-styles`. The underscore marks them as internal.
 Read the semantic tokens that refer to them.
 
-## Styling HTML without custom elements
-
-`@fusion.dev/helix-styles` is plain CSS with no JavaScript. It includes recipes
-for markup that Helix does not render:
-
-```html
-<button
-  data-button="solid"
-  data-button-tone="primary"
->Save</button>
-<article data-prose><h2>From a CMS</h2></article>
-<div data-density="sm">…</div>
-```
-
-A recipe sets appearance only. It has none of these:
-
-- state
-- form participation
-- focus trapping
-- keyboard handling
-
-If you are adding a script to a recipe, use the component.
-
-## Link your tool to this guide
-
-**Point your tool at the guide, and do not copy it.** A copy starts to go stale
-as soon as you paste it, and the guide changes with the library.
-
-The skill in the package matches the Helix you installed. In Claude Code, link
-it into your project's skills folder:
+## Markup Helix does not render
 
-```sh
-mkdir -p .claude/skills
-ln -s ../../node_modules/@fusion.dev/helix/skills/helix .claude/skills/helix
-```
-
-Other tools read a file in your repository. Add a line to it that names the
-skill, or this page:
-
-```md
-Helix: read node_modules/@fusion.dev/helix/skills/helix/SKILL.md before
-writing components, and node_modules/@fusion.dev/helix/api.json for the API.
-```
-
-| Tool | Where it goes |
-|---|---|
-| Claude Code | `.claude/skills/helix`, or a line in `AGENTS.md` or `CLAUDE.md` |
-| Cursor | `.cursor/rules/` |
-| GitHub Copilot | `.github/copilot-instructions.md` |
-| Anything else | Whatever it reads. The line is the same |
+HTML that a CMS or a Markdown library writes, inside an element with
+`data-prose`, takes Helix's typography from `@fusion.dev/helix-styles` and needs
+no Helix elements. Everywhere else, write the Helix element.
 
-We do not write those files for you, and we chose this on purpose. You would
-have to maintain a file we generated in your repository against our changes. A
-tool that rewrote it on install would be a dependency you did not ask for, in a
-directory you own. You add the link or the line, and you can delete it.
+## Check the code you wrote
 
-## Install the Helix MCP server
+Run these after you write Helix code, and fix every finding at `error` and
+`warn` before you finish. Each prints JSON with `--json`.
 
-```sh
-helix mcp init --client claude
-```
+| Command | MCP tool | What it finds |
+|---|---|---|
+| `helix scan` | `helix_check` | Unknown tags, attributes, values, slots, parts, hooks, events, and tokens, a native element a Helix family replaces, a missing import, and the rest, each with its file and line |
+| `helix diagnostics --once <url>` | `helix_check_page` | The same on the running page, and what the library logged as it ran |
+| `helix theme audit` | `helix_audit_theme` | Every foreground and background pair in your theme that misses its contrast target |
 
-`helix mcp` answers from the Helix packages your project installs: families,
-examples, import lines, tokens, and the theme a brand color produces. `--client`
-takes `claude`, `cursor`, or `vscode`, and writes the server into the file that
-client reads. [Coding agents](./coding-agents) lists the tools. It runs on your
-machine, talks to a client you chose, and makes no network requests.
+`helix scan --file <path>` reports one file's findings and still reads the whole
+project, so an import in another file counts.
 
 ## What this guide does not cover
 

package/dist/pages.generated.js

@@ -38,7 +38,7 @@ export const docPages = [
         title: 'Charting',
     },
     {
-        description: 'The files an AI agent can read to write Helix code, and where to find each one.',
+        description: 'Install Helix for a coding agent, and the files an agent can read to write Helix code.',
         order: 4,
         section: 'Getting started',
         slug: 'coding-agents',
@@ -264,7 +264,7 @@ export const docPages = [
         title: 'Typography',
     },
     {
-        description: 'Five mistakes that look like Helix bugs, and the files an agent should read.',
+        description: 'The rules an agent follows to write Helix code, and the five mistakes that look like Helix bugs.',
         parent: 'coding-agents',
         section: 'Getting started',
         slug: 'using-helix-with-an-agent',