@fusion.dev/helix-docs 0.186.1 → 0.187.0

package/content/coding-agents.mdx

@@ -45,15 +45,20 @@ type such as `ButtonEmphasis` sends you somewhere else to look.
 ## Markdown and JSON for each component family
 
 ```
-/components/<family>.md
-/components/<family>.json
+https://fusion.dev/helix/components/<family>.md
+https://fusion.dev/helix/components/<family>.json
 ```
 
-These are static files. The `.md` file has:
+These are static files, one pair for each family. Read the family you are
+writing instead of the whole manifest. The manifest holds every family in one
+file, and it is several megabytes.
+
+The `.md` file has:
 
 - the family's metadata
+- a Usage block with the import lines for the family
 - every element's description and API tables
-- the examples
+- the examples, each with the import lines it needs
 
 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
@@ -61,24 +66,49 @@ 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` file has the same family as structured data.
+Each example the visual check pictures links its pictures under it: wide at
+640 pixels, narrow at 390, and dark at 640, taken in the environment that
+`examples.json` records. Compare a render of your own to them.
+
+The `.json` file has the same family as structured data, and three fields an
+agent uses most:
+
+- `usage`, the import block for each tier
+- `imports` on each example, an import line for every element it writes
+- `specifier` and `words` on each element: the line that registers it, and the
+  properties `registerWords` translates
+
+## Import every family you write
+
+Each tag needs its family's entry imported. A family registers its own parts,
+so `@fusion.dev/helix/tabs` registers Tab and Tab Panel. A family does not
+register another family's elements that you write inside it:
+
+```js
+import '@fusion.dev/helix/select'
+import '@fusion.dev/helix/option'
+```
+
+Without the Option import, the options are unknown elements and the Select
+offers nothing. The same is true
+of the layout around an example: a Button inside a Flex needs both imports.
+Copy the import lines above an example together with its markup.
 
-## Rules the build checks
+## Check the code you wrote
 
-Code that looks right can still fail these checks:
+These checks run on your project, and each one prints JSON with `--json`:
 
-| Rule | Check |
+| Command | What it finds |
 |---|---|
-| A dispatched event must be declared | `helix component --only events` |
-| A documented part must be rendered | `helix component`'s `parts` |
-| 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 supports reduced motion | `helix component --only motion` |
-| No component reads a primitive token | `helix component`'s `tokens` |
+| `helix scan` | Unknown tags, attributes, values, slots, parts, hooks, React event props, and tokens, a `--_helix-` primitive read, `[disabled]` on a form control, a selector on an attribute the element never writes back, and a tag whose entry nothing imports, each with its file and line |
+| `helix theme audit` | Every foreground and background pair in your theme that misses its contrast target |
+| `initDiagnostics()` from `@fusion.dev/helix-diagnostics` | The same findings on the running page, and what the library reports as it runs, such as an option nobody imported |
 
-If you generate Helix code, watch the first two rules. Breaking them produces
-output that looks like it works and is wrong.
+`helix scan` and `helix theme audit` exit 1 when they find an error and 0 when
+they find none. Run them after you write Helix code, and fix each finding
+before you finish. `helix scan --file <path>` reports one file's findings, and
+`helix scan --stdin tsx` reads a snippet from stdin. Both still read the whole
+project, so an import in another file counts.
 
 ## The index
 
@@ -106,28 +136,57 @@ Each family page has a menu beside its title with:
 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`
+## The Helix MCP server
 
 ```sh
-helix mcp
+helix mcp init --client claude
 ```
 
-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. It answers from the Helix packages
+your project installs, so every answer is for the version you build with, and
+each one names that package and version. `helix mcp init` adds the server to
+the file your client reads and keeps every other server in it:
 
-`helix mcp` runs an MCP server over stdio with two tools:
+| Client | File |
+|---|---|
+| `claude` | `.mcp.json` |
+| `cursor` | `.cursor/mcp.json` |
+| `vscode` | `.vscode/mcp.json` |
 
-- `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.
+The server runs `npx @fusion.dev/helix-cli mcp`, which is the copy in your
+project. It has eight tools:
 
-Both take the same JSON that a `helix.theme.json` file holds.
+| Tool | What it returns |
+|---|---|
+| `helix_find` | The families that answer a name, an alias, a tag, or a purpose, best first |
+| `helix_family` | One family's tags, properties and their unions, events and their React props, slots, parts, custom properties, words, and import lines |
+| `helix_example` | One example as HTML and TSX, with its stylesheet, the import lines it needs, and links to its pictures |
+| `helix_imports` | The import lines for a list of tags, and the closest tag to any unknown one |
+| `helix_tokens` | The semantic tokens, by a word in the name or description and by category |
+| `helix_check` | The findings `helix scan` reports for the files you name, or for a snippet before you write it |
+| `helix_audit_theme` | Every foreground and background pair a brand color derives to, with its ratio and target |
+| `helix_derive_theme` | The theme's CSS |
+
+Each result is structured, with an output schema, and the same JSON as text.
+A name that matches more than one family, such as `Dropdown`, returns an error
+listing each family. The theme tools take the same JSON that a
+`helix.theme.json` file holds.
+
+Each lookup is also a command, for a script or a person:
 
-**`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.
+```sh
+helix api find dropdown
+helix api family select
+helix api example select
+helix api imports helix-select helix-option
+helix api tokens surface --category color
+```
+
+`--json` prints what the MCP tool returns.
+
+**`helix_derive_theme` 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 `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
@@ -136,14 +195,9 @@ no network requests.
 
 ## What we do not publish for agents
 
-**`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.
-
-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.
+**`llms-full.txt`, or any other whole-library download of the pages.** 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.
 
-**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.
+`llms.txt` is the index, in one request, and each family's `.md` file is its
+document. Fetch the families you use, or ask `helix mcp`.