htmlboard 0.5.0 → 0.6.0

package/README.md

@@ -93,6 +93,8 @@ Options:
   -h, --help            Display help message
 ```
 
+Running `htmlboard` for a folder it already shows (same folder and root, same version) doesn't start a second canvas on the next port: it prints the running one's URL, and opens it with `--open`.
+
 ### Examples
 
 ```bash
@@ -131,31 +133,39 @@ htmlboard migrate design --write
 
 HtmlBoard is built from the ground up to pair with AI coding agents (Claude, Gemini, Codex, ChatGPT, Antigravity, Cursor).
 
-### Install the agent skill
+### Install the agent skills
+
+HtmlBoard ships [Agent Skills](https://agentskills.io) that teach your agent how to use it. An agent keeps only each skill's one-line description in mind and reads a skill when a task calls for it, so the ones it rarely needs cost almost nothing until then:
+
+| Skill | What it teaches | Read |
+| :--- | :--- | :--- |
+| `htmlboard` | Start the canvas; write, size, name and group designs; shared styles; size and state variants; the catalog and the check | For any design work |
+| `htmlboard-components` | The component file: attributes, slots, scoped CSS, a script, its first-line example | Before writing or changing a component |
+| `htmlboard-designs-json` | Curating the canvas with `designs.json`, and `htmlboard migrate` | When the designs folder has a `designs.json` |
 
-HtmlBoard ships an [Agent Skill](https://agentskills.io) that teaches your agent how to use it: where to put artboards, how to size, name and group them (files describe themselves; `designs.json` is optional) and how to start the canvas. Install it in your project:
+Install them in your project:
 
 ```bash
 npx htmlboard skills install
 ```
 
-This writes `.claude/skills/htmlboard/` (Claude Code) and `.agents/skills/htmlboard/` (Codex and other agents that read `.agents/skills`). Commit them so everyone working on the project gets the skill. Then start a new agent session and just ask for a design.
+This writes them in `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex and other agents that read `.agents/skills`). Commit them so everyone working on the project gets them. Then start a new agent session and just ask for a design.
 
 ```bash
 npx htmlboard skills install --global         # for your user (~/.claude/skills, ~/.agents/skills), all projects
 npx htmlboard skills install --agent claude   # only one agent: claude | agents | all (default)
 npx htmlboard skills install --force          # update a copy you edited locally
-npx htmlboard skills uninstall                # remove it (accepts the same --global / --agent)
+npx htmlboard skills uninstall                # remove them (accepts the same --global / --agent)
 ```
 
-Running `install` again after upgrading HtmlBoard updates the skill; a copy you edited is kept unless you pass `--force`.
+Running `install` again after upgrading HtmlBoard updates the skills; a copy you edited is kept unless you pass `--force`.
 
 ### The workflow
 
 1. **Ask your LLM to generate artboards:**
    > *"Create 3 design explorations for our checkout flow in `designs/03-checkout/`."*
 
-   With the skill, the agent writes `01-one-page.html`, `02-steps.html`, `03-express.html`, each with its size in a `<meta>` tag. They show up as a new "checkout" row, in that order.
+   With the skills, the agent writes `01-one-page.html`, `02-steps.html`, `03-express.html`, each with its size in a `<meta>` tag. They show up as a new "checkout" row, in that order.
 
 2. **Run HtmlBoard in the background:**
    ```bash
@@ -240,6 +250,7 @@ Every `.html` file under the folder is a design (hidden folders, `node_modules`,
 <meta name="htmlboard" content="width=390, height=844">         <!-- its size (and category=…) -->
 <meta name="htmlboard:label" content="light">                   <!-- added to its name: "Checkout · light" -->
 <meta name="htmlboard:variant" content="?theme=dark · dark">    <!-- one more frame: "Checkout · dark" -->
+<meta name="htmlboard:variant" content="width=768, height=1024 · tablet">  <!-- and at a tablet's size -->
 ```
 
 | Tag | What it says |
@@ -248,7 +259,7 @@ Every `.html` file under the folder is a design (hidden folders, `node_modules`,
 | `<meta name="description">` | Its description, shown in the list and found by the search. |
 | `<meta name="htmlboard" content="…">` | `width=…`, `height=…`, `category=…` (`mobile`, `tablet`, `desktop`, `components` or your own word), or `skip` to leave the file out (partials, templates). |
 | `<meta name="htmlboard:label">` | Text added to the name of the file's own frame, when it has variants. |
-| `<meta name="htmlboard:variant">` | One more frame of the same file with that query string, then its label. As many as you like; they follow the file. |
+| `<meta name="htmlboard:variant">` | One more frame of the same file: with a query string (`?theme=dark`), at another size (`width=390, height=844`, so a responsive page shows on a phone too), or both; then its label. As many as you like; they follow the file. |
 
 **Sizes.** The width is the frame's viewport: the page's CSS needs it before it renders. Give the height for designs of a fixed size (a phone screen, a flyer: the frame is that tall and cuts the rest); leave it out and the frame grows with the page. Without a size, words in the path decide (`mobile` → 390 × 844, `tablet` → 768 × 1024, `desktop` → 1280 × 800, `component` → 720 × 600), else 1200 wide.
 
@@ -466,7 +477,9 @@ htmlboard/
 │       ├── 01-screens/   # Dashboard, customers, mobile feed
 │       └── 02-ui-kit/
 ├── skills/
-│   └── htmlboard/        # Agent skill (SKILL.md) copied by `htmlboard skills install`
+│   ├── htmlboard/        # Agent skills (SKILL.md each) copied by `htmlboard skills install`
+│   ├── htmlboard-components/
+│   └── htmlboard-designs-json/
 ├── brand/                # The logo's files (from design/tools/logo.py)
 ├── design/               # htmlboard's own designs, on its own canvas: `npx htmlboard design --root .`
 ├── package.json

package/bin/htmlboard.js

@@ -10,6 +10,7 @@ import { planMigration, checkMigration, applyMigration } from '../src/migrate.js
 import { installComponents, COMPONENTS_FOLDER, COMPONENTS_SCRIPT } from '../src/components.js';
 import { buildCatalog, formatCatalog } from '../src/catalog.js';
 import { runCheck, formatReport, hasProblems, CheckError } from '../src/check.js';
+import { PORTS, findCanvases } from '../src/canvases.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -99,7 +100,7 @@ Examples:
   htmlboard ./designs -p 8080   # Serve ./designs on port 8080
   htmlboard design --root .     # Artboards in ./design that link to ../css/…
   htmlboard --init              # Add sample designs to the current folder
-  htmlboard skills install      # Add the HtmlBoard skill to this project's agents
+  htmlboard skills install      # Add the HtmlBoard skills to this project's agents
   htmlboard components designs  # Let ./designs use components (components/tx-item.html is <tx-item>)
   htmlboard catalog designs     # What ./designs share, in a few lines (for your AI agent)
   htmlboard check designs       # Script errors, missing files, cut-off text in ./designs
@@ -154,8 +155,8 @@ function scaffoldProject(targetDir) {
 function showSkillsHelp() {
   console.log(`
 Usage:
-  htmlboard skills install [options]     Copy the HtmlBoard skill into your agents' skill folders
-  htmlboard skills uninstall [options]   Remove it
+  htmlboard skills install [options]     Copy the HtmlBoard skills into your agents' skill folders
+  htmlboard skills uninstall [options]   Remove them
 
 Options:
   -g, --global          Install for your user (~/.claude/skills, ~/.agents/skills) instead of this project
@@ -211,7 +212,7 @@ function runSkills(args) {
     console.log(`  ${labels[status]}  ${path.relative(process.cwd(), dest) || dest}`);
   }
   if (action === 'install' && results.some((r) => r.status === 'installed' || r.status === 'updated')) {
-    console.log(`\n  Restart your agent session to load the skill, then ask it for a design.`);
+    console.log(`\n  Restart your agent session to load the skills, then ask it for a design.`);
   }
 }
 
@@ -453,6 +454,25 @@ async function main() {
     scaffoldProject(targetDir);
   }
 
+  // A canvas already running for this folder (same root, same version): say where, rather than
+  // starting a second one on the next port
+  const root = options.root ? path.resolve(options.root) : targetDir;
+  const running = (await findCanvases([...PORTS, ...Array.from({ length: 21 }, (_, i) => options.port + i)]))
+    .filter((canvas) => canvas.dir === targetDir && canvas.root === root);
+  const same = running.find((canvas) => canvas.version === pkg.version);
+  if (same) {
+    console.log(`
+  \x1b[90mhtml\x1b[0m\x1b[1mboard\x1b[0m is already running for this folder:
+
+  \x1b[32m➜\x1b[0m  \x1b[1mLocal:\x1b[0m   \x1b[36m${same.url}\x1b[0m
+`);
+    if (options.open) openBrowser(same.url);
+    return;
+  }
+  for (const canvas of running) {
+    console.log(`[htmlboard] v${canvas.version} is running for this folder at ${canvas.url}; starting v${pkg.version} too.`);
+  }
+
   try {
     const { url, rootDir } = await startServer({
       dir: targetDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "htmlboard",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Infinite canvas and design explorer for HTML artboards — designed for humans and LLMs",
   "type": "module",
   "bin": {

package/skills/htmlboard/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: htmlboard
-description: Design UI in plain HTML files and show them side by side on an infinite, live-reloading canvas with the htmlboard CLI. Use when the user asks for mockups, screens, design variants or explorations, components, flyers or any visual proposal, or mentions htmlboard, artboards or designs.json.
+description: Design UI in plain HTML files and show them side by side on an infinite, live-reloading canvas with the htmlboard CLI. Use when the user asks for mockups, screens, design variants or explorations, flyers or any visual proposal, or mentions htmlboard or artboards.
 ---
 
 # HtmlBoard
 
 HtmlBoard serves a folder of HTML files as artboards on a zoomable canvas, like a Figma page. Every design is one ordinary HTML file that says its own name and size, so you design by writing HTML and CSS, and the user sees the result update live while you work.
 
+Two more skills cover the rest when you need it: **htmlboard-components** to write or change a component, **htmlboard-designs-json** when the designs folder has a `designs.json`.
+
 ## Start the canvas
 
 Run it in the background, pointed at the designs folder (it is created if missing):
@@ -19,7 +21,7 @@ npx htmlboard designs --open
 - `-p <port>` picks the port. `--init` adds sample designs; skip it unless the user wants a starter.
 - If the artboards link to files above the designs folder (`../css/theme.css`), serve from the project root: `npx htmlboard design --root .`
 - An empty folder gets the samples automatically, so write your first artboard before starting the server.
-- If a server is already running for this folder, reuse it. `GET /api/health` answers `{"status":"ok","dir":…}`.
+- Running it again for a folder that already has a canvas doesn't start another: it prints that canvas's URL.
 
 ## Write an artboard
 
@@ -48,87 +50,46 @@ One design per file, with its facts in the `<head>`, linking the shared styleshe
 - Always give the `width`: it is the frame's viewport, and the page's CSS needs it. Give the `height` for fixed sizes (a phone screen, a flyer: the frame cuts at it); leave it out for pages that should grow with their content.
 - Design at the real size of the target: phone 390×844, tablet 768×1024, desktop 1280×800 (or 1440×900), and the exact size for print or social formats (e.g. 1080×1350).
 - Use real content in the user's language, not lorem ipsum.
-- Relative links to CSS, images, scripts and fonts work (`assets/logo.svg`; `../css/theme.css` with `--root`).
-- No build step: plain HTML, CSS and browser JavaScript (ES modules and CDN scripts work).
+- Relative links to CSS, images, scripts and fonts work (`assets/logo.svg`; `../css/theme.css` with `--root`). No build step: plain HTML, CSS and browser JavaScript (ES modules and CDN scripts work).
+
+More tags, all optional:
+
+- `<meta name="htmlboard:variant" content="?theme=dark · dark">` shows the same file again with that query string, named "<title> · dark": for states the page builds from its URL (themes, empty or error states, data). A variant can also change the size: `content="width=390, height=844 · mobile"` shows a responsive page at a phone's size too, from the same file (`?theme=dark width=390 · dark mobile` does both). One tag per variant; they follow the file.
+- `<meta name="htmlboard:label" content="light">` adds a label to the name of the file's own frame ("Checkout · light"), to tell it from its variants.
+- `category=…` in the `htmlboard` tag sets the explorer's filter (`mobile`, `components`, your own word) when the path and size don't say it.
+- `<meta name="htmlboard" content="skip">` leaves a file out (partials, templates, a page that isn't a design).
 
 ## Shared styles
 
 Put what the designs share in one stylesheet instead of repeating it in every file: it keeps the designs consistent and spares writing the same CSS again.
 
 - The designs folder has a `styles.css` at its top (sample projects start with one). Before writing a design, see what the designs already share: `npx htmlboard catalog <designs folder>` prints it in a few lines, read from the files (each stylesheet's variables and classes, the scripts, the components with their attributes and an example). Use what fits (`var(--accent)`, `.btn`, `<tx-item>`) and add what's missing; open a file only for what the list doesn't say.
-- If there is none and the project already has a stylesheet or design tokens, link those. Otherwise create `styles.css` with your first design: colors, type and spacing as custom properties, the base styles, and the components you'll repeat.
+- If there is none and the project already has a stylesheet or design tokens, link those. Otherwise create `styles.css` with your first design: colors, type and spacing as custom properties, the base styles, and the classes you'll repeat.
 - Link it with a relative path: `styles.css` from the top of the folder, `../styles.css` from a section folder.
-- A design's own `<style>` holds only what is specific to it. When a second design needs the same thing, move it to `styles.css`.
-- Split it when it grows (`forms.css`, `charts.css`) and link the extra files where they are used.
+- A design's own `<style>` holds only what is specific to it. When a second design needs the same thing, move it to `styles.css`. Split it when it grows (`forms.css`, `charts.css`) and link the extra files where they are used.
 - Editing `styles.css` restyles every design that links it, which is the point for a product's screens. For one-off explorations that should keep their look (a different style, logo options), style them in their own file instead.
 
-More tags, all optional:
-
-- `category=…` in the `htmlboard` tag files the design under the explorer's filters: `mobile`, `tablet`, `desktop`, `components` or your own word. Usually not needed: it comes from words in the path, then from the size when it is a screen's.
-- `<meta name="htmlboard:variant" content="?theme=dark · dark">` shows the same file again with that query string, named "<title> · dark". Use it for states the page builds from its URL (themes, empty or error states, data). Add one tag per variant; they follow the file.
-- `<meta name="htmlboard:label" content="light">` adds a label to the name of the file's own frame ("Checkout · light"), to tell it from its variants.
-- `<meta name="htmlboard" content="skip">` leaves a file out (partials, templates, a page that isn't a design).
-
 ## Components
 
-Markup that designs repeat (a sidebar, a tab bar, a list row, a card with content) goes in a component, so a design writes one tag instead of the block: `<tx-item icon="☕" name="Blue Bottle" amount="-$6.75"></tx-item>`.
-
-- `components/tx-item.html`, at the top of the designs folder, is `<tx-item>`: the file name is the tag, with a hyphen and no number prefix. Designs load `components.js` once (above). If the folder has no `components.js`, run `npx htmlboard components <designs folder>`.
-- The catalog (above) lists them, with their attributes, an example and the designs that use them. Use them; don't copy their markup into designs.
-- Make one when a second design repeats a block (or a design repeats it three times). Not for what a `styles.css` class already does (`<button class="btn btn-primary">` is short), nor in one-off explorations.
-
-A component file is a piece of HTML (no `<!DOCTYPE>`, `<html>`, `<head>` or `<body>`):
-
-```html
-<!-- <tx-item icon="💼" name="Invoice #1042" meta="Yesterday" amount="+$3,450.00" positive></tx-item> -->
-<div class="icon">{{icon}}</div>
-<div class="what"><b>{{name}}</b> <span class="muted">{{meta}}</span></div>
-<div class="amount">{{amount}}</div>
-
-<style>
-  & { display: flex; align-items: center; gap: 14px; }   /* & is the element itself */
-  .icon { width: 40px; height: 40px; border-radius: 12px; background: var(--surface-2); }
-  &[positive] .amount { color: var(--emerald); }
-</style>
-```
+Markup that designs repeat (a sidebar, a tab bar, a list row, a card with content) goes in a component, a file in `components/` that designs use as one tag instead of the block: `<tx-item icon="☕" name="Blue Bottle" amount="-$6.75"></tx-item>`.
 
-- First line: a comment with an example of use, with real values, every attribute and its variants side by side. The catalog shows it, and it is the component's preview on the canvas.
-- `{{name}}` is the element's `name="…"` attribute, as text. Content goes in slots: `<slot></slot>` takes the element's children, `<slot name="actions"></slot>` its children with `slot="actions"`, and what a slot holds shows when nothing fills it.
-- No logic in the markup: variants are attributes styled in CSS (`&[positive]`), and a list is several elements.
-- Its `<style>` only reaches inside the element, which is a block box unless `&` says otherwise. `styles.css` applies inside too: build with its classes (`card`, `btn`, `muted`) and name the component's own parts with names it doesn't use. A design's own `<style>` comes after and can restyle one element, but its selectors reach inside components too, so keep them specific.
-- `<script>` runs for each element once it is built, with `this` as the element. Use it sparingly, a few lines for what markup and CSS can't do, like marking the current link (`<app-sidebar active="Customers">`) or a toggle. No fetching, data or frameworks.
-- Relative links in a component start from its file (`../01-screens/02-customers.html`).
-- Close the tag: `<tx-item …></tx-item>`, never `<tx-item />`. A component can't be a table's row or cell itself (the browser moves it out of the `<table>`), but it works inside a cell: `<td><org-cell …></org-cell></td>`. Where it sits (fixed, margins, the grid around it) belongs to the design.
-- Editing a component changes every design that uses it, like `styles.css`.
+- The catalog lists the project's components with their attributes, an example and the designs that use them. Use them; don't copy their markup into designs.
+- Make one when a second design repeats a block (or a design repeats it three times); not for what a `styles.css` class already does, nor in one-off explorations. To write or change one, use the htmlboard-components skill.
 
 ## Group and order
 
 - **A folder is a section** (a row on the canvas), named after the folder. Put related designs in a folder: `designs/03-checkout/`.
 - **Number prefixes set the order** of files and folders: `01-one-page.html`, `02-steps.html`. They don't show in names or links, so you can renumber freely. Files at the top of the designs folder form a first row without a title.
 - New files and folders show up on the canvas by themselves; you don't register them anywhere.
-
-**`designs.json`** is optional. When a project has one (in the designs folder), it curates: sections with titles (accents, capitals, an order across folders), and values that win over the files'. Designs it doesn't list still show after the ones it lists, in their folder's section, unless it says `"unlisted": "hide"`. If the project's designs.json groups designs by hand, add a new design to the right section there:
-
-```json
-{
-  "sections": [
-    { "title": "Checkout · mobile", "designs": ["03-checkout/01-one-page.html", "03-checkout/02-steps.html"] },
-    { "title": "Launch flyers", "folder": "04-flyers" }
-  ]
-}
-```
-
-An entry is a file name (its variants follow it), or `{ "file", "title", "width", "height", "category", "description" }` to override the file. `"folder"` brings a whole folder. Components aren't on the canvas unless designs.json says `"components": "show"` (or lists `components/<tag>.html`): each shows alone, from its first-line example, 480 wide unless its file has `<meta name="htmlboard" content="width=…">`. `npx htmlboard migrate <folder>` moves an old designs.json's sizes, names and variants into the files (`--write` to apply; without it, it only shows the plan).
+- A `designs.json` in the designs folder, when there is one, curates the canvas (section titles, an order across folders, designs it hides): use the htmlboard-designs-json skill before adding, moving or renaming designs there.
 
 ## Live reload
 
-- Saving an artboard's HTML reloads just that frame; the user's view stays put. A new name or size in its `<head>` updates in place.
-- Saving a file artboards use (a stylesheet, a component, a script, an image, data) reloads the artboards that loaded it.
-- Adding, removing or moving artboards, or saving `designs.json`, rebuilds the canvas.
+Saving a design reloads its frame, saving a file designs use (a stylesheet, a component, an image) reloads the designs that loaded it, and new or removed designs show up by themselves. The user's view stays put: there is nothing to refresh.
 
 ## Working with the user
 
 - Put variants in separate files next to each other (`01-hero-a.html`, `02-hero-b.html`) instead of overwriting the current design, so they can be compared on the canvas. Keep the current one as the reference until the user picks.
-- Say which files you created or changed and what to look at; the user is watching the canvas, not the code. Link straight to an artboard with `http://localhost:3000/#<id>`: the id is the file's path without prefixes and `.html`, other symbols turned into `-` (`03-checkout/02-steps.html` → `checkout-steps`; a variant adds its query: `checkout-steps-theme-dark`).
-- Before reporting back, run `npx htmlboard check <designs folder>` (or a design's file). The canvas open in the user's browser loads each design again and lists, as text, what went wrong: script errors, missing files and components, fonts that didn't load, content cut at the frame's edge, text cut off or spilling out of its box. Fix what it lists and run it again. A note that content goes on below a frame of fixed height is fine for a screen that scrolls, not for a flyer. The check runs in the browser: if it says the canvas isn't open, ask the user to open its URL.
+- Say which files you created or changed and what to look at; the user is watching the canvas, not the code. Link straight to a design with its file after the `#`: `http://localhost:3000/#03-checkout/02-steps.html`.
+- Before reporting back, run `npx htmlboard check <designs folder>` (or a design's file): the canvas open in the user's browser loads each design again and lists what went wrong (script errors, missing files and components, fonts that didn't load, content cut at the frame's edge, text cut off or spilling out). Fix it and run it again. A note about content below a fixed-height frame is fine for a screen that scrolls, not for a flyer. If it says the canvas isn't open, ask the user to open its URL.
 - The check can't judge looks (colors, spacing, alignment). If you can take screenshots, also look at the design at its real size (`http://localhost:3000/<file>`).

package/skills/htmlboard-components/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: htmlboard-components
+description: Write or change an htmlboard component, a file in components/ that designs use as a custom element (components/tx-item.html is <tx-item>). Use when a block repeats across htmlboard designs, or before creating or editing a file in components/.
+---
+
+# HtmlBoard components
+
+A component is markup that designs repeat (a sidebar, a tab bar, a list row, a card with content), written once and used as one tag: `<tx-item icon="☕" name="Blue Bottle" amount="-$6.75"></tx-item>`. The htmlboard skill covers the designs themselves.
+
+- `components/tx-item.html`, at the top of the designs folder, is `<tx-item>`: the file name is the tag, with a hyphen and no number prefix.
+- Designs load `components.js` once, after their stylesheet: `<script type="module" src="../components.js"></script>`. If the designs folder has no `components.js`, run `npx htmlboard components <designs folder>`.
+- See what exists first: `npx htmlboard catalog <designs folder>` lists the components with their attributes, an example and the designs that use them.
+
+A component file is a piece of HTML (no `<!DOCTYPE>`, `<html>`, `<head>` or `<body>`):
+
+```html
+<!-- <tx-item icon="💼" name="Invoice #1042" meta="Yesterday" amount="+$3,450.00" positive></tx-item> -->
+<div class="icon">{{icon}}</div>
+<div class="what"><b>{{name}}</b> <span class="muted">{{meta}}</span></div>
+<div class="amount">{{amount}}</div>
+
+<style>
+  & { display: flex; align-items: center; gap: 14px; }   /* & is the element itself */
+  .icon { width: 40px; height: 40px; border-radius: 12px; background: var(--surface-2); }
+  &[positive] .amount { color: var(--emerald); }
+</style>
+```
+
+- First line: a comment with an example of use, with real values, every attribute and its variants side by side. The catalog shows it, and it is the component's preview on the canvas.
+- `{{name}}` is the element's `name="…"` attribute, as text. Content goes in slots: `<slot></slot>` takes the element's children, `<slot name="actions"></slot>` its children with `slot="actions"`, and what a slot holds shows when nothing fills it.
+- No logic in the markup: variants are attributes styled in CSS (`&[positive]`), and a list is several elements.
+- Its `<style>` only reaches inside the element, which is a block box unless `&` says otherwise. `styles.css` applies inside too: build with its classes (`card`, `btn`, `muted`) and name the component's own parts with names it doesn't use. A design's own `<style>` comes after and can restyle one element, but its selectors reach inside components too, so keep them specific.
+- `<script>` runs for each element once it is built, with `this` as the element. Use it sparingly, a few lines for what markup and CSS can't do, like marking the current link (`<app-sidebar active="Customers">`) or a toggle. No fetching, data or frameworks.
+- Relative links in a component start from its file (`../01-screens/02-customers.html`).
+- Close the tag: `<tx-item …></tx-item>`, never `<tx-item />`. A component can't be a table's row or cell itself (the browser moves it out of the `<table>`), but it works inside a cell: `<td><org-cell …></org-cell></td>`. Where it sits (fixed, margins, the grid around it) belongs to the design.
+- Editing a component changes every design that uses it, like `styles.css`. Afterwards, `npx htmlboard check <designs folder>` lists components that weren't built and errors in their scripts.

package/skills/htmlboard-designs-json/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: htmlboard-designs-json
+description: Curate an htmlboard canvas with designs.json (section titles and order, a design's name or size, hiding unlisted designs, showing components). Use when the designs folder has a designs.json, or the user wants sections named or ordered beyond what folders give.
+---
+
+# HtmlBoard designs.json
+
+Without one, folders are the canvas's sections and number prefixes set the order (the htmlboard skill covers the designs themselves). A `designs.json` in the designs folder curates on top of that: sections with titles (accents, capitals, an order across folders), and values that win over the files'. The files still say the rest: their name, size and variants in their `<head>`.
+
+```json
+{
+  "title": "Wallet app",
+  "sections": [
+    { "title": "Checkout · mobile", "designs": ["03-checkout/01-one-page.html", "03-checkout/02-steps.html"] },
+    { "title": "Launch flyers", "folder": "04-flyers" }
+  ]
+}
+```
+
+- Sections come in their order, designs in theirs. An entry is a file name (its variants follow it; with a query string, it places one variant), or `{ "file", "title", "width", "height", "category", "description" }` to override the file's values.
+- `"folder"` brings a whole folder, in prefix order.
+- Designs it doesn't list still show after the ones it lists, in the section that holds their folder (or a section of their own), unless it says `"unlisted": "hide"`. When it groups designs by hand, add a new design to the right section.
+- Components aren't on the canvas unless it says `"components": "show"` (or lists `components/<tag>.html`): each shows alone, from its first-line example, 480 wide unless its file has `<meta name="htmlboard" content="width=…">`.
+- Saving it rebuilds the canvas.
+- `npx htmlboard migrate <designs folder>` moves an old designs.json's sizes, names and variants into the files and keeps only what they can't say (`--write` to apply; without it, it only shows the plan).

package/src/canvases.js

@@ -0,0 +1,38 @@
+import http from 'node:http';
+
+// The htmlboard canvases running on this machine, found by asking ports for /api/health: for
+// `htmlboard check`, and so that starting htmlboard again for a folder points at the running one.
+
+/** Where htmlboard listens unless told otherwise: 3000, or the next free port */
+export const PORTS = Array.from({ length: 21 }, (_, i) => 3000 + i);
+
+/** GET a URL: its status and body */
+export function get(url, { timeout = 0 } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = http.get(url, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString('utf8') }));
+      res.on('error', reject);
+    });
+    req.on('error', reject);
+    if (timeout) req.setTimeout(timeout, () => req.destroy(new Error('timeout')));
+  });
+}
+
+/**
+ * The htmlboard servers listening on these ports: each its health (dir, root, version) with its
+ * port and url.
+ */
+export async function findCanvases(ports = PORTS) {
+  const found = await Promise.all([...new Set(ports)].map(async (port) => {
+    try {
+      const { status, body } = await get(`http://127.0.0.1:${port}/api/health`, { timeout: 1500 });
+      const health = JSON.parse(body);
+      return status === 200 && health.status === 'ok' && health.dir ? { ...health, port, url: `http://localhost:${port}` } : null;
+    } catch {
+      return null;
+    }
+  }));
+  return found.filter(Boolean);
+}

package/src/check.js

@@ -1,48 +1,18 @@
-import http from 'node:http';
 import path from 'node:path';
+import { PORTS, get, findCanvases } from './canvases.js';
 
 // `htmlboard check`: the canvas running for a folder, open in a browser, loads its designs and says
 // what went wrong in each (see client/check.js); this finds that canvas, asks it, and puts the
 // answer in a few lines of text.
 
-/** Where htmlboard listens unless told otherwise: 3000, or the next free port */
-const PORTS = Array.from({ length: 21 }, (_, i) => 3000 + i);
-
 /** A problem the check couldn't get past (no canvas running, none open in a browser): exit code 2 */
 export class CheckError extends Error {}
 
-function get(url, { timeout = 0 } = {}) {
-  return new Promise((resolve, reject) => {
-    const req = http.get(url, (res) => {
-      const chunks = [];
-      res.on('data', (chunk) => chunks.push(chunk));
-      res.on('end', () => resolve({ status: res.statusCode, body: Buffer.concat(chunks).toString('utf8') }));
-      res.on('error', reject);
-    });
-    req.on('error', reject);
-    if (timeout) req.setTimeout(timeout, () => req.destroy(new Error('timeout')));
-  });
-}
-
 const isInside = (base, target) => {
   const rel = path.relative(base, target);
   return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
 };
 
-/** The htmlboard servers listening on these ports, each with its designs folder (dir) and root */
-async function findCanvases(ports) {
-  const found = await Promise.all(ports.map(async (port) => {
-    try {
-      const { status, body } = await get(`http://127.0.0.1:${port}/api/health`, { timeout: 1500 });
-      const health = JSON.parse(body);
-      return status === 200 && health.status === 'ok' && health.dir ? { ...health, port, url: `http://localhost:${port}` } : null;
-    } catch {
-      return null;
-    }
-  }));
-  return found.filter(Boolean);
-}
-
 /**
  * Check designs with the canvas that shows them: a designs folder, a folder in it, or a design's
  * file (default: all the designs of the canvas found). The canvas must be open in a browser, where

package/src/client/explorer.js

@@ -797,7 +797,7 @@ async function takeCheck(request) {
 
 async function runCheck({ id, designs: boards }) {
   const designs = boards.map((board) => {
-    const shown = state.designs.find((d) => d.file === board.file);
+    const shown = state.designs.find((d) => d.id === board.id); // a size variant has its file's URL
     const height = Number(board.height) || 0;
     return {
       file: board.file,

package/src/designs.js

@@ -120,12 +120,36 @@ function parseSettings(content) {
   return settings;
 }
 
-/** <meta name="htmlboard:variant" content="?tema=escuro · escuro">: the query, then a label */
+// A variant's own setting, as the htmlboard tag says it: width=390, height=844, category=mobile
+const VARIANT_SETTING = /^(width|height|category)=[^,;\s]+[,;]?$/i;
+const LABEL_START = /^[·|:,\-–—]+\s*/;
+
+/**
+ * <meta name="htmlboard:variant" content="?tema=escuro · escuro">: the file once more, with a
+ * query string, a size (width=390, height=844) or both, then a label. A query may leave out its "?".
+ */
 function parseVariant(content) {
-  const [, first, rest] = content.match(/^(\S+)\s*(.*)$/s);
-  const query = first.startsWith('?') ? first : `?${first}`;
-  if (query === '?') return null;
-  return { query, label: rest.replace(/^[·|:,\-–—]+\s*/, '').trim() };
+  const tokens = content.trim().split(/\s+/);
+  let query = '';
+  const settings = [];
+  let i = 0;
+  for (; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (VARIANT_SETTING.test(token)) settings.push(token.replace(/[,;]$/, ''));
+    else if (token.startsWith('?') && !query) query = token;
+    else if (i === 0 && !LABEL_START.test(token)) query = `?${token}`;
+    else break;
+  }
+  if (query === '?') query = '';
+  const { width, height, category } = parseSettings(settings.join(','));
+  if (!query && !width && !height) return null;
+  return { query, label: tokens.slice(i).join(' ').replace(LABEL_START, '').trim(), ...compact({ width, height, category }) };
+}
+
+/** A variant as its tag's content says it: "?theme=dark width=390, height=844 · dark mobile" */
+export function formatVariant({ query = '', label = '', width, height, category }) {
+  const size = [width && `width=${width}`, height && `height=${height}`, category && `category=${category}`].filter(Boolean).join(', ');
+  return [query, size].filter(Boolean).join(' ') + (label ? ` · ${label}` : '');
 }
 
 /** What an HTML file says about itself, from its <head> (see the top of this file) */
@@ -196,12 +220,24 @@ function fileDesign(file, folder, meta) {
   });
 }
 
-function variantDesign(base, { query, label }) {
+// A variant of a file's design: another query string (a state the page builds from its URL), another
+// size (the same page at a phone's width), or both. Without a height of its own, a variant that
+// changes the width grows with its page. One that only changes the size loads the same URL as its
+// file, so its id comes from its label.
+function variantDesign(base, { query = '', label, width, height, category }) {
+  const sized = Boolean(width || height);
+  const size = sized ? { width: width ?? base.width, height: height ?? (width ? undefined : base.height) } : {};
+  const sizeName = sized ? `${size.width}${size.height ? ` × ${size.height}` : ''}` : '';
+  const name = label || [query.slice(1), sizeName].filter(Boolean).join(' · ');
   return compact({
     ...base,
-    key: base.file + query,
+    ...size,
+    key: base.file + query + (sized ? `@${size.width}x${size.height ?? ''}` : ''),
     file: base.file + query,
-    title: `${base.baseTitle} · ${label || query.slice(1)}`,
+    title: `${base.baseTitle} · ${name}`,
+    // A new size is a new device: its category comes from its size, unless it says one
+    category: sized ? category : category ?? base.category,
+    id: sized ? `${designId(base.file + query)}-${slugify(name)}` : undefined,
     variantOf: base.file
   });
 }

package/src/migrate.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { loadDesignsManifest, parseDesignMeta, stripPrefix } from './designs.js';
+import { loadDesignsManifest, parseDesignMeta, stripPrefix, formatVariant } from './designs.js';
 
 // `htmlboard migrate`: moves what a designs.json says about each design into the design's own file
 // (its size, category, label, variants and description) and leaves designs.json with what only it
@@ -110,7 +110,7 @@ export function planMigration(designsDir) {
       }
       for (const key of ['description', 'tags', 'id']) if (item.entry[key] !== undefined) item.keep[key] = item.entry[key];
     }
-    for (const v of declared) lines.push(`<meta name="htmlboard:variant" content="${escapeAttr(v.query + (v.label ? SEP + v.label : ''))}">`);
+    for (const v of declared) lines.push(`<meta name="htmlboard:variant" content="${escapeAttr(formatVariant(v))}">`);
 
     const next = rewriteHead(html, lines);
     if (next !== html) files.push({ file: base, lines, html: next });

package/src/server.js

@@ -224,7 +224,7 @@ export function createServer(options = {}) {
     const wanted = only.map((item) => item.replace(/\\/g, '/').replace(/^\.?\/+|\/+$/g, ''));
     const designs = loadDesignsManifest(targetDir, rootDir).sections
       .flatMap((section) => section.artboards)
-      .map(({ file, title, width, height, fit }) => ({ file, title, width, height, fit }))
+      .map(({ id, file, title, width, height, fit }) => ({ id, file, title, width, height, fit }))
       .filter(({ file }) => {
         const own = (designsPath ? file.slice(designsPath.length + 1) : file).split('?')[0];
         return !wanted.length || wanted.some((item) => !item || own === item || own.startsWith(`${item}/`));

package/src/skills.js

@@ -21,7 +21,8 @@ export const SKILL_TARGETS = {
 function bundledSkills() {
   return fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
     .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, entry.name, 'SKILL.md')))
-    .map((entry) => entry.name);
+    .map((entry) => entry.name)
+    .sort();
 }
 
 function resolveTargets(agent = 'all') {