@fusion.dev/helix-docs 0.186.1 → 0.188.0

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

@@ -1,5 +1,5 @@
 ---
-description: Four mistakes that look like Helix bugs, and the files an agent should read.
+description: Five mistakes that look like Helix bugs, and the files an agent should read.
 parent: coding-agents
 section: Getting started
 title: Using Helix with an agent
@@ -8,58 +8,63 @@ title: Using Helix with an agent
 
 # Using Helix with an agent
 
-**We publish this guide as a web page so that every tool can read it.** It began
-as `.claude/skills/using-helix/SKILL.md`, a file format that one vendor reads in
-a repository. Every other vendor reads its own file:
+This guide is in two places, and both say the same thing:
 
-- Cursor reads `.cursor/rules`.
-- Copilot reads `.github/copilot-instructions.md`.
+- 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
 
-If you install the published packages, you have none of these files. You have
-this site and no checkout of our repository.
+[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.
 
-So the guide lives in one place, here, at a URL that
-[llms.txt](https://fusion.dev/llms.txt) indexes and that each of those files can
-link to. Paste the link into the file your tool reads. [The MCP
-server](./coding-agents) works with any vendor and runs code, and Claude,
-Cursor, Windsurf, and Zed all support it.
-
-## Read the manifest before writing a tag
+## Read the family before writing its tags
 
 ```
-https://fusion.dev/helix/custom-elements.json
-@fusion.dev/helix/custom-elements.json
+https://fusion.dev/helix/components/<family>.md
+https://fusion.dev/helix/components/<family>.json
 ```
 
-The manifest lists:
+Each family's file lists:
 
+- the import lines for the family
 - every tag
 - every property, with its literal union
-- every event, with its class
+- every event, with its class and its React prop
 - every slot, part, and custom property
+- the examples, each with the import lines it needs
 
-**If a tag is not in the manifest, 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.
-
-When you need one family, fetch it as data:
-
-```
-https://fusion.dev/helix/components/<family>.json
-https://fusion.dev/helix/components/<family>.md
-```
+**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.
 
-The `.md` file has the API tables and the examples. The HTML page leaves the
-examples out on purpose. Start from `https://fusion.dev/llms.txt`. In one
-request, it names every document and these two sources.
+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.
 
-## Four mistakes that look like Helix bugs
+## Five mistakes that look like Helix bugs
 
 Each of these looks like a bug in Helix. They are listed from the most common to
 the least common.
 
-### 1. Blocking a change without `preventDefault()`
+### 1. Writing a tag without importing its family
+
+Each tag needs its family's entry imported. A family does not register another
+family's elements that you write inside it, so a Select needs Option imported
+beside it, and a Data Table needs Table:
+
+```js
+import '@fusion.dev/helix/select'
+import '@fusion.dev/helix/option'
+```
+
+Without the second line, the options are unknown elements and the Select offers
+nothing. Each family's Usage block and each example list the lines to import.
+Copy them with the markup.
+
+### 2. Blocking a change without `preventDefault()`
 
 **Setting `value`, `open`, `checked`, or `active` sets the starting state and
 corrects the current state.** The element starts in that state and then applies
@@ -91,7 +96,7 @@ block a change, call `preventDefault()` on the matching `helix-before-*` event:
 A form reset returns the element to `default-value` and the matching attributes
 for the other states. See [State and control](./state-and-control).
 
-### 2. Using the exact event name
+### 3. Using the exact event name
 
 In React, write `onhelix-before-open`. `onHelixOpen` and `onOpen` do not work.
 React removes `on` from the prop name and listens for exactly the rest, so the
@@ -105,7 +110,7 @@ so a menu closing inside a dialog does not close the dialog. `helix-select`,
 listen for them on a container. If a listener on a wrapper receives nothing, the
 event is a lifecycle event. Put the listener on the element.
 
-### 3. Styling a disabled control with `:disabled`
+### 4. Styling a disabled control with `:disabled`
 
 ```css
 helix-input:disabled { … }   /* right: matches a disabled fieldset too */
@@ -116,7 +121,7 @@ The browser disables a control inside `<fieldset disabled>` without adding an
 attribute to it. The `[disabled]` selector does not match it, so the control
 looks enabled while it does not accept input.
 
-### 4. Loading every style layer before the elements
+### 5. Loading every style layer before the elements
 
 ```ts
 import '@fusion.dev/helix-styles/helix.css'
@@ -212,20 +217,28 @@ If you are adding a script to a recipe, use the component.
 
 ## Link your tool to this guide
 
-**Link to this page from your instructions file, and do not copy it.** Each tool
-that reads project instructions reads a file in your repository, and each tool
-reads a different one. A copy starts to go stale as soon as you paste it, and
-this page changes with the library.
+**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:
+
+```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 https://fusion.dev/helix/docs/using-helix-with-an-agent
-before writing components, and https://fusion.dev/helix/custom-elements.json
-for the API.
+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 | `AGENTS.md` or `CLAUDE.md`, or a skill in `.claude/skills/` |
+| 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 |
@@ -233,22 +246,19 @@ for the API.
 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 paste the line above, and you can delete it.
+directory you own. You add the link or the line, and you can delete it.
 
 ## Install the Helix MCP server
 
-```json
-{
-  "mcpServers": {
-    "helix": { "command": "helix", "args": ["mcp"] }
-  }
-}
+```sh
+helix mcp init --client claude
 ```
 
-`helix mcp` is a subcommand of the CLI. It serves MCP over stdio, which Claude,
-Cursor, Windsurf, and Zed all read. It computes the theme a given brand color
-produces, which no document can list. It runs on your machine, talks to a client
-you chose, and makes no network requests.
+`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.
 
 ## What this guide does not cover
 
@@ -256,10 +266,9 @@ you chose, and makes no network requests.
 and hooks change with the library, and they are in a file you can fetch. A list
 of them here would be a second copy that goes stale. Fetch the family.
 
-**The theme a brand color produces.** Helix computes it, so use `helix mcp`, an
-MCP server over stdio with `helix_audit_theme` and `helix_derive_theme`. Both
-take the same JSON that a `helix.theme.json` file holds. It runs on your
-machine, and we do not host it.
+**The theme a brand color produces.** Helix computes it, so call
+`helix_derive_theme`, or run `helix theme build`. Both take the same JSON that a
+`helix.theme.json` file holds.
 
 **Whether a component fits your case.** Read the examples to decide. Every
 family's `.md` file includes them as text, and

package/dist/index.d.ts

@@ -1,7 +1,6 @@
-export type { ApiMember, Element, EventDoc, Example, ExampleSource, Family, PropertyDoc, } from './catalog.js';
-export { catalog, findInCatalog } from './catalog.js';
-export { displayName, startCase, tierOf } from './naming.js';
-export { place, type ReferenceFamily, type ReferenceOptions, reference, referenceFamilies, } from './reference.js';
+export type { ApiMember, Element, EventDoc, Example, ExampleSource, Family, PropertyDoc, } from '@fusion.dev/helix-cem';
+export { catalog, displayName, findInCatalog, place, startCase, tierOf, } from '@fusion.dev/helix-cem';
+export { type ReferenceFamily, type ReferenceOptions, reference, referenceFamilies, } from './reference.js';
 export { contentPath, type DocNavPage, type DocNavSection, type DocPage, type DocSection, findPage, navigation, pages, sections, } from './registry.js';
 export { findSection } from './sections.js';
 export { docSources } from './sources.generated.js';

package/dist/index.js

@@ -1,6 +1,5 @@
-export { catalog, findInCatalog } from './catalog.js';
-export { displayName, startCase, tierOf } from './naming.js';
-export { place, reference, referenceFamilies, } from './reference.js';
+export { catalog, displayName, findInCatalog, place, startCase, tierOf, } from '@fusion.dev/helix-cem';
+export { reference, referenceFamilies, } from './reference.js';
 export { contentPath, findPage, navigation, pages, sections, } from './registry.js';
 export { findSection } from './sections.js';
 export { docSources } from './sources.generated.js';

package/dist/pages.generated.js

@@ -258,7 +258,7 @@ export const docPages = [
         title: 'Typography',
     },
     {
-        description: 'Four mistakes that look like Helix bugs, and the files an agent should read.',
+        description: 'Five mistakes that look like Helix bugs, and the files an agent should read.',
         parent: 'coding-agents',
         section: 'Getting started',
         slug: 'using-helix-with-an-agent',

package/dist/reference.d.ts

@@ -32,7 +32,14 @@ export interface ReferenceExample {
     css: string;
     description: string;
     html: string;
+    /** The import lines that register what the example writes, printed above it. */
+    imports?: string[];
     label: string;
+    /** The baseline pictures, linked under the example beside the family's `.md`. */
+    renders?: {
+        file: string;
+        shot: string;
+    }[];
 }
 /** What to put above the reference, for a caller that generates a file. */
 export interface ReferenceOptions {
@@ -54,8 +61,8 @@ export interface ReferenceOptions {
      * Frontmatter, emitted above the heading.
      *
      * Provenance rather than decoration: a generated document should say what it
-     * was generated from, so a reader who finds one detached from this repository
-     * can still tell where to look. Keys are written in the order given, because
+     * was generated from, so a reader who finds one on its own can still tell
+     * where to look. Keys are written in the order given, because
      * a reader scans the first line and `title` is what they want there.
      */
     frontmatter?: Array<[string, string]>;
@@ -63,18 +70,12 @@ export interface ReferenceOptions {
     lede?: string[];
     /** Top-level heading. */
     title?: string;
+    /**
+     * The import block for each family, keyed by family slug, printed under a
+     * Usage heading before the first element. The catalog's `usage` is it.
+     */
+    usage?: Record<string, string[]>;
 }
-/**
- * The family and part a declaration belongs to, from where its file is.
- *
- * Not from the tag name. A tag is a string the family prefix can only be
- * guessed out of: `helix-button-group` is one family and `helix-tab` is a
- * part of another, and nothing in the name says which. The path says both.
- */
-export declare const place: (path: string | undefined) => {
-    family: string;
-    part: string;
-};
 /** One family's declarations, in the order a reference prints them. */
 export interface ReferenceFamily {
     family: string;

package/dist/reference.js

@@ -1,4 +1,4 @@
-import { startCase } from './naming.js';
+import { place, startCase } from '@fusion.dev/helix-cem';
 const INFRASTRUCTURE = new Set(['HelixElement']);
 const isPublic = (member) => member.privacy !== 'private' &&
     member.privacy !== 'protected' &&
@@ -14,10 +14,6 @@ const table = (depth, heading, columns, rows) => {
     const body = rows.map((row) => `| ${row.join(' | ')} |`).join('\n');
     return `\n${'#'.repeat(depth)} ${heading}\n\n${head}\n${rule}\n${body}\n`;
 };
-export const place = (path) => {
-    const [, family = '', part = ''] = /^src\/([^/]+)\/([^/]+)\//.exec(path ?? '') ?? [];
-    return { family, part };
-};
 export const referenceFamilies = (manifest) => {
     const families = new Map();
     for (const module of manifest.modules ?? []) {
@@ -79,7 +75,7 @@ const element = (depth, declaration, part) => {
     return lines;
 };
 const withoutSummary = (html) => html.replace(/^<!--\s*@summary[\s\S]*?-->\n*/, '');
-const shown = (depth, examples) => {
+const shown = (depth, family, examples) => {
     if (examples.length === 0) {
         return [];
     }
@@ -89,10 +85,16 @@ const shown = (depth, examples) => {
         if (example.description) {
             lines.push(example.description, '');
         }
+        if (example.imports && example.imports.length > 0) {
+            lines.push('```js', ...example.imports, '```', '');
+        }
         lines.push('```html', withoutSummary(example.html), '```', '');
         if (example.css) {
             lines.push('```css', example.css, '```', '');
         }
+        if (example.renders && example.renders.length > 0) {
+            lines.push(`Pictured: ${example.renders.map((render) => `[${render.shot}](${family}/${render.file})`).join(', ')}.`, '');
+        }
     }
     return lines;
 };
@@ -113,10 +115,14 @@ export const reference = (manifest, options = {}) => {
         if (families.length > 1) {
             lines.push(`## ${startCase(family)}`, '');
         }
+        const usage = options.usage?.[family] ?? [];
+        if (usage.length > 0) {
+            lines.push(`${'#'.repeat(depth)} Usage`, '', '```js', ...usage, '```', '');
+        }
         for (const { declaration, part } of parts) {
             lines.push(...element(depth, declaration, part));
         }
-        lines.push(...shown(depth, options.examples?.[family] ?? []));
+        lines.push(...shown(depth, family, options.examples?.[family] ?? []));
     }
     return `${lines
         .join('\n')