htmlboard 0.4.0 → 0.5.0

package/README.md

@@ -31,8 +31,11 @@ Modern AI agents and developers generate dozens of HTML mockups, layout variatio
 
 - 🛸 **Infinite Canvas**: Drag or scroll to move, <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + scroll or pinch to zoom (2% to 800%), with a mouse, a trackpad or a touch screen. Names and section titles stay sharp at any zoom, and the dot grid keeps its spacing.
 - ⚡ **Zero Dependencies**: Pure native Node.js ES modules, fonts included. Runs instantly with `npx htmlboard`, offline too.
-- 🔄 **State-Preserving Live Reload**: The server watches the project and pushes every save (Server-Sent Events). Saving a design reloads its frame; saving a file designs use (a stylesheet, a script, an image, data) reloads just the designs that loaded it; new, removed and renamed designs show up by themselves. Your view never moves.
+- 🔄 **State-Preserving Live Reload**: The server watches the project and pushes every save (Server-Sent Events). Saving a design reloads its frame; saving a file designs use (a stylesheet, a component, a script, an image, data) reloads just the designs that loaded it; new, removed and renamed designs show up by themselves. Your view never moves.
 - 📂 **Designs That Describe Themselves**: Every HTML file is a design, each folder a section, number prefixes the order. A file says its own size, category and variants in a `<meta>` tag or two, so adding a design means writing one file — nothing to keep in sync.
+- 🧩 **Components**: Each file in `components/` is a custom element named after it (`tx-item.html` is `<tx-item>`), so the sidebar every screen shares is written once and used as one tag: attributes, slots and scoped CSS, built in the light DOM with your `styles.css`, no build step.
+- 🗂️ **A Catalog for Agents**: `htmlboard catalog` reads the project and prints what the designs share in a few lines: each stylesheet's variables and classes, the scripts, every component with its attributes, an example and where it's used. An agent learns your styles and components without reading every file, and since it's read from the files, it is never out of date.
+- 🩺 **Checks for Agents**: `htmlboard check` has the canvas open in your browser load each design again and report, 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. An agent checks its work without screenshots.
 - 📐 **Optional `designs.json`**: Curates when you want it (section titles, order, overrides); designs it doesn't list still show at the end, or don't (`"unlisted": "hide"`). `htmlboard migrate` moves an existing one into the files.
 - 📱 **Device Filters**: **Mobile**, **Tablet** and **Desktop** (and **Components**, or your own categories) lay out just those designs, side by side, to compare them.
 - 🔎 **Search**: Find designs by name, file, tags or section (case and accents don't matter); the others fade out in place.
@@ -59,7 +62,7 @@ htmlboard
 
 ### Scaffold a Starter Project
 
-To start with sample designs (a folder of screens and a folder of components, each file describing itself, all sharing one `styles.css`):
+To start with sample designs (a folder of screens and a UI kit, each file describing itself, all sharing one `styles.css` and four components):
 
 ```bash
 npx htmlboard --init
@@ -75,6 +78,9 @@ Usage:
   npx htmlboard [directory] [options]
   htmlboard skills <install|uninstall> [options]   Teach your AI agent to use HtmlBoard
   htmlboard migrate [directory] [--write]          Move designs.json's sizes, titles and variants into the files
+  htmlboard components [directory] [--force]       Add components.js: files in components/ become custom elements
+  htmlboard catalog [directory]                    What the designs share: stylesheets, scripts, components
+  htmlboard check [directory or file] [-p <port>]  What went wrong in the designs, from the canvas open in a browser
 
 Options:
   -p, --port <number>   Port to listen on (default: 3000)
@@ -105,6 +111,15 @@ htmlboard design --root .
 # Start a new folder with sample designs
 htmlboard ./my-new-ui --init --open
 
+# Let the designs in ./design use components
+htmlboard components design
+
+# What the designs in ./design share, in a few lines (what the agent skill reads)
+htmlboard catalog design
+
+# What went wrong in them: script errors, missing files, cut-off text (the canvas must be open)
+htmlboard check design
+
 # See what moving ./design/designs.json into its files would do, then do it
 htmlboard migrate design
 htmlboard migrate design --write
@@ -150,11 +165,70 @@ Running `install` again after upgrading HtmlBoard updates the skill; a copy you
 3. **Watch the canvas update live:**
    As the LLM writes or refines each HTML file, HtmlBoard detects the file change and reloads the iframe on the canvas immediately. You never have to refresh your browser or hunt for file URLs.
 
+### What the designs share: `htmlboard catalog`
+
+Before an agent writes a new design, it needs to know what the others use: the stylesheet's variables and classes, the components and how to write them. Reading every file for that costs tokens in every session. `htmlboard catalog` reads them instead and prints a summary (the skill runs it). On the samples, shortened:
+
+```text
+$ npx htmlboard catalog designs
+designs: 4 designs. Paths below are from this folder.
+
+Stylesheets
+  styles.css · all 4 designs
+    :root { --bg: #0b0d13; --surface: #141724; --surface-2: #1c2030; --border: #23283c;
+      --text: #f1f5f9; --text-muted: #94a3b8; --text-subtle: #64748b; --accent: #6366f1; … }
+    classes .muted .label .row .page-title .page-sub .app .app-main .app-content .card .btn
+      .btn-primary .btn-secondary .btn-outline .btn-danger .badge .badge-dot .badge-emerald …
+
+Scripts
+  components.js · all 4 designs
+
+Components (components/)
+  <stat-card label value trend [warn]> · 2 designs: 01-screens/01-dashboard.html, 02-ui-kit/01-overview.html
+    e.g. <stat-card label="Monthly Recurring Revenue" value="$184,290" trend="▲ +12.4% vs last mo"></stat-card> …
+  <tx-item icon name meta amount [positive]> · 2 designs: 01-screens/03-mobile.html, 02-ui-kit/01-overview.html
+    e.g. <tx-item icon="💼" name="Client Invoice #1042" meta="Yesterday • Wire Transfer" amount="+$3,450.00" positive></tx-item> …
+```
+
+It describes whatever the project has and asks for nothing:
+- **Stylesheets** with any name, in any folder: the ones the designs link or `@import` (CDN ones by their URL), and the ones at the top of the folder that no design links yet.
+- **Variables** under the selector that declares them, so a dark theme's values show too.
+- **Components**: their attributes come from their markup (`{{name}}`), their script and their CSS (`&[warn]` is a flag, `&[size="lg"]` a value).
+
+On the samples it is 2 KB instead of the 9 KB of `styles.css` and `components/`, and the gap grows with the project: a stylesheet's rules don't show, only what they define.
+
+### Checking the designs: `htmlboard check`
+
+An agent can't see the canvas, and a screenshot costs it many tokens, when it can take one at all. `htmlboard check` asks the canvas open in your browser to look instead: each design loads again, out of sight, in a frame of its size, and what went wrong comes back as text:
+
+```text
+$ npx htmlboard check designs
+Checked 6 designs in designs (the canvas at http://localhost:3000): 2 with problems, 1 with notes.
+
+01-screens/02-customers.html · Customers
+  error  TypeError: Cannot read properties of null (reading 'append') (01-screens/02-customers.html:88)
+  error  <org-cel> isn't built: there is no components/org-cel.html
+  error  missing file: img/acme.svg (<img>)
+  layout cut at the right edge (the frame is 1280 px wide): table.table reaches 1342
+  layout text cut off by p.plan (overflow: hidden): "Enterprise annual plan"
+
+01-screens/03-mobile.html · Mobile
+  layout text spills out of .btn: "Confirm and continue"
+
+02-print/01-flyer.html · Flyer
+  note   content goes on below the frame, down to 1460 px (the frame is 1350 px tall)
+```
+
+- **What it finds:** script errors and `console.error`; files that aren't there (a stylesheet's fonts and images, a fetch's data too); components that weren't built; fonts that didn't load; a page that shows nothing; content cut at the frame's right edge; text cut off by a box that hides its overflow, or spilling out of its box. A note says when content goes on below a frame of fixed height: fine for a screen that scrolls, not for a flyer.
+- **What it leaves alone:** what a design means to do, such as text that ends in an ellipsis or is clamped, boxes that scroll, and content hidden or moved off the page on purpose. It doesn't judge looks (colors, spacing, alignment).
+- **It runs in your browser**, so the canvas must be open there. Each check loads the files as they are on disk, so it can run right after a save. Pages shown in frames get a small script first in their `<head>` (`/__explorer/probe.js`) to hear what goes wrong from the start; it only listens in the frames the check loads, and a design opened on its own doesn't get it.
+- A file or a folder checks just those designs: `htmlboard check designs/01-screens/02-customers.html`. It finds the canvas on ports 3000 to 3020 (`-p` for another) and exits with 1 when there are problems, 2 when it can't check. `--json` gives the report as data.
+
 ---
 
 ## 📂 How Designs Are Found
 
-Every `.html` file under the folder is a design (hidden folders, `node_modules`, `dist` and `build` aside):
+Every `.html` file under the folder is a design (hidden folders, `node_modules`, `dist`, `build` and the [components](#-components) in `components/` aside):
 
 - **Sections are folders.** Each folder is a row on the canvas, named after the folder; the files at the top of the folder make a first row without a title.
 - **Number prefixes set the order** of files and folders: `01-…`, `02-…`, `10-…` (up to three digits; `2` comes before `10`). They don't show in names or in links, so reordering breaks nothing.
@@ -180,7 +254,55 @@ Every `.html` file under the folder is a design (hidden folders, `node_modules`,
 
 **Categories** drive the filters. Left out, they come from words in the path, then from the size when it is a screen's (a phone's width, a tablet's 3:4, a desktop's landscape); flyers, boards and other formats get none and show under **All**.
 
-**Shared styles.** Designs link one stylesheet for what they share (tokens, base styles, components) and keep only their own CSS in their `<style>`, so they stay consistent and each new design is shorter to write. The samples use a `styles.css` at the top of the folder (`<link rel="stylesheet" href="../styles.css">`), and the agent skill tells LLMs to read it, use it and grow it. Editing it reloads every design that links it.
+**Shared styles.** Designs link one stylesheet for what they share (tokens, base styles, classes like `.btn` and `.card`) and keep only their own CSS in their `<style>`, so they stay consistent and each new design is shorter to write. The samples use a `styles.css` at the top of the folder (`<link rel="stylesheet" href="../styles.css">`), and the agent skill tells LLMs to look it up (`htmlboard catalog`), use it and grow it. Editing it reloads every design that links it.
+
+---
+
+## 🧩 Components
+
+Designs repeat markup too: the same sidebar on every screen, a dozen rows of a list. Written as a component, it is one tag in each design, and one file to change. Every file in `components/` (at the top of the designs folder) is a custom element named after it, built by `components.js`, which designs load once next to their stylesheet:
+
+```html
+<link rel="stylesheet" href="../styles.css">
+<script type="module" src="../components.js"></script>
+…
+<app-sidebar active="Customers"></app-sidebar>
+<tx-item icon="☕" name="Blue Bottle Coffee" meta="Oct 26 • Food & Beverage" amount="-$6.75"></tx-item>
+```
+
+A component is a piece of HTML, `components/tx-item.html`:
+
+```html
+<!-- <tx-item icon="💼" name="Client Invoice #1042" meta="Yesterday" amount="+$3,450.00" positive></tx-item> -->
+<div class="icon">{{icon}}</div>
+<div class="what">
+  <div class="name">{{name}}</div>
+  <div class="muted">{{meta}}</div>
+</div>
+<div class="amount">{{amount}}</div>
+
+<style>
+  & { display: flex; align-items: center; gap: 14px; }
+  .icon { width: 40px; height: 40px; border-radius: 12px; background: var(--surface-2); }
+  &[positive] .amount { color: var(--emerald); }
+</style>
+```
+
+| In the file | What it does |
+| :--- | :--- |
+| A comment first | An example of use: the component's documentation, for people and agents, and its preview on the canvas. |
+| `{{name}}` | The element's `name="…"` attribute, as text. |
+| `<slot>`, `<slot name="x">` | The element's content; its children with `slot="x"`. What a slot holds shows when nothing fills it. |
+| `<style>` | CSS for this element only (`&` is the element, a block box by default), added once to the pages that use it. |
+| `<script>` | Runs for each element once it is built, with `this` as the element: for the little that markup and CSS can't do, like marking the current link. |
+
+- **They work with your stylesheet.** Components are built in the light DOM, with no shadow root in the way, so `styles.css` reaches inside: they use the same classes as the designs (`card`, `btn`, `muted`). A component's CSS comes after `styles.css` and before the design's own `<style>`, so a design can still adjust one element.
+- **Variants are attributes styled in CSS** (`&[positive]`). There is no template logic to learn; a list is several elements.
+- **Relative links start from the component's file**, so they work from every design.
+- **`components.js` is a file in your project**, so designs work on any static server. `--init` adds it; `htmlboard components [dir]` adds it to a designs folder. After upgrading htmlboard, `htmlboard components [dir] --force` replaces an older copy (and any edits you made to it).
+- **Saving a component reloads the designs that use it.** Component files aren't designs; `designs.json` can show them on the canvas (below).
+- **`htmlboard catalog` lists them** with their attributes, the example each one starts with and the designs that use them.
+- HTML has no self-closing custom elements: write `<tx-item …></tx-item>`, not `<tx-item />`. And 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>`.
 
 ---
 
@@ -206,6 +328,7 @@ A `designs.json` in the folder curates the canvas when folders aren't enough: se
 - Sections come in their order, designs in theirs. An entry is a file name, or `{ "file", … }` with values that win over the file's (`title`, `description`, `width`, `height`, `category`, `tags`, `id`). A `file` may carry a query string to place a variant itself.
 - A file's variants follow it unless designs.json lists them. `"folder"` brings a whole folder (in prefix order).
 - **Designs it doesn't list still show**, after the ones it does: in the section that holds their folder, else in their folder's own section (the files at the top in "Unlisted"). `"unlisted": "hide"` shows only what it lists.
+- **Components show on the canvas with `"components": "show"`**, each alone in its frame, from the example its file starts with, in a "components" section after the designs. They are 480 wide, unless the component's file says `<meta name="htmlboard" content="width=1040">`. A section can also list them (`"components/tx-item.html"`) or bring them all (`"folder": "components"`). A `designs.json` that only says `{ "components": "show" }` leaves the rest of the canvas as the files make it.
 - `name` and `artboards` are synonyms of `title` and `designs`.
 
 ### Moving an existing `designs.json` into the files
@@ -279,6 +402,38 @@ installSkills({ dir: process.cwd(), agent: 'all' });
 // → [{ skill: 'htmlboard', path: '…/.claude/skills/htmlboard', status: 'installed' }, …]
 ```
 
+And so is the components installer:
+
+```javascript
+import { installComponents } from 'htmlboard';
+
+installComponents({ dir: './designs' });
+// → { path: '…/designs/components.js', status: 'installed' }
+```
+
+And the catalog, as data or as the text `htmlboard catalog` prints:
+
+```javascript
+import { buildCatalog, formatCatalog } from 'htmlboard';
+
+const catalog = buildCatalog('./designs'); // { root } for links that start with "/", like --root
+// → { designs: ['01-screens/01-dashboard.html', …],
+//     stylesheets: [{ path: 'styles.css', users: [{ design: '01-screens/01-dashboard.html' }, …], variables, classes, keyframes, fonts }, …],
+//     scripts: [{ path: 'components.js', users }],
+//     components: [{ tag: 'tx-item', attributes: [{ name: 'icon' }, …, { name: 'positive', flag: true }], slots, example, users }, …] }
+console.log(formatCatalog(catalog));
+```
+
+And the check, which needs the canvas open in a browser (the server answers it at `GET /api/check`, `?only=<file or folder>` for some of the designs):
+
+```javascript
+import { runCheck, formatReport } from 'htmlboard';
+
+const { canvas, report } = await runCheck('./designs'); // { port } when it isn't on 3000 to 3020
+// → report: { dir, root, designs: [{ file, title, width, height, problems: [{ level: 'error', kind: 'missing', path: '/img/logo.png', tag: 'img' }, …] }, …] }
+console.log(formatReport(report, { url: canvas.url }));
+```
+
 ---
 
 ## 📂 Project Structure
@@ -291,18 +446,25 @@ htmlboard/
 │   ├── index.js          # Library entry point & API exports
 │   ├── server.js         # HTTP server, SSE live reload
 │   ├── designs.js        # Which designs a folder holds: files, their tags, designs.json
+│   ├── components.js     # Components: their previews, `htmlboard components`
+│   ├── catalog.js        # What the designs share: `htmlboard catalog`
+│   ├── check.js          # `htmlboard check`: asks the canvas, prints its report
 │   ├── migrate.js        # `htmlboard migrate`
 │   ├── skills.js         # `htmlboard skills` installer
 │   ├── client/           # The canvas
 │   │   ├── index.html    # Explorer shell: list, canvas, toolbar, shortcuts
 │   │   ├── explorer.css  # Dark chrome, dot grid
 │   │   ├── explorer.js   # Layout, pan/zoom, search, live reload
+│   │   ├── check.js      # Checks the designs in frames out of sight, for `htmlboard check`
+│   │   ├── probe.js      # Notes script errors and failed loads in the frames the check loads
 │   │   ├── favicon.svg, logo.svg, mark.svg
 │   │   └── fonts/        # Inter and Bricolage Grotesque (OFL)
 │   └── templates/        # The sample designs `--init` adds
-│       ├── styles.css    # Their shared tokens and components
-│       ├── 01-screens/   # Desktop dashboard, mobile feed
-│       └── 02-components/
+│       ├── styles.css    # Their shared tokens and classes
+│       ├── components.js # Turns components/*.html into custom elements (copied into projects)
+│       ├── components/   # Sidebar, top bar, stat card, transaction row
+│       ├── 01-screens/   # Dashboard, customers, mobile feed
+│       └── 02-ui-kit/
 ├── skills/
 │   └── htmlboard/        # Agent skill (SKILL.md) copied by `htmlboard skills install`
 ├── brand/                # The logo's files (from design/tools/logo.py)

package/bin/htmlboard.js

@@ -7,6 +7,9 @@ import { fileURLToPath } from 'node:url';
 import { startServer } from '../src/server.js';
 import { installSkills, uninstallSkills } from '../src/skills.js';
 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';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -76,6 +79,9 @@ Usage:
   npx htmlboard [directory] [options]
   htmlboard skills <install|uninstall> [options]   Teach your AI agent to use HtmlBoard
   htmlboard migrate [directory] [--write]          Move designs.json's sizes, titles and variants into the files
+  htmlboard components [directory] [--force]       Add components.js: files in components/ become custom elements
+  htmlboard catalog [directory]                    What the designs share: stylesheets, scripts, components
+  htmlboard check [directory or file] [-p <port>]  What went wrong in the designs, from the canvas open in a browser
 
 Options:
   -p, --port <number>   Port to listen on (default: 3000)
@@ -94,6 +100,9 @@ Examples:
   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 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
 
 On the canvas:
   Drag, scroll          Move around
@@ -206,6 +215,134 @@ function runSkills(args) {
   }
 }
 
+function runComponents(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Usage:
+  htmlboard components [directory] [--force]
+
+Adds ${COMPONENTS_SCRIPT} and a ${COMPONENTS_FOLDER}/ folder to the designs folder (default: the current one).
+Each file in ${COMPONENTS_FOLDER}/ is then a custom element named after it (${COMPONENTS_FOLDER}/tx-item.html is
+<tx-item>) in the designs that load ${COMPONENTS_SCRIPT}, once, beside their stylesheet:
+
+  <script type="module" src="../${COMPONENTS_SCRIPT}"></script>
+
+A ${COMPONENTS_SCRIPT} that differs from this version's (an older one, or one you edited) is kept;
+--force replaces it.
+`);
+    return;
+  }
+  const unknown = args.find((arg) => arg.startsWith('-') && arg !== '--force' && arg !== '-f');
+  if (unknown) {
+    console.error(`[htmlboard] Unknown option: ${unknown} (see htmlboard components --help)`);
+    process.exit(1);
+  }
+  const dirArg = args.find((arg) => !arg.startsWith('-'));
+  const { path: dest, status } = installComponents({
+    dir: dirArg || process.cwd(),
+    force: args.includes('--force') || args.includes('-f')
+  });
+  const labels = {
+    installed: '\x1b[32m✓ added\x1b[0m',
+    updated: '\x1b[32m✓ updated\x1b[0m',
+    unchanged: '\x1b[90m= up to date\x1b[0m',
+    skipped: '\x1b[33m! differs from this version, kept (use --force to replace)\x1b[0m'
+  };
+  console.log(`  ${labels[status]}  ${path.relative(process.cwd(), dest) || dest}`);
+  if (status === 'installed') {
+    const folder = path.relative(process.cwd(), path.join(path.dirname(dest), COMPONENTS_FOLDER)) || COMPONENTS_FOLDER;
+    console.log(`\n  Write components in ${folder}/ (tx-item.html is <tx-item>) and load ${COMPONENTS_SCRIPT} in the designs.`);
+  }
+}
+
+// A folder as the user would type it: from the current folder, unless that means going up
+function shownPath(dir) {
+  const rel = path.relative(process.cwd(), dir);
+  return !rel ? '.' : rel.startsWith('..') ? dir : rel;
+}
+
+function runCatalog(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Usage:
+  htmlboard catalog [directory] [--root <path>]
+
+Prints what the designs in the folder (default: the current one) share, read from the files: the
+stylesheets and scripts they load, each local stylesheet's variables, classes, @keyframes and
+fonts, and the components in ${COMPONENTS_FOLDER}/ with their attributes, slots, example and where
+they are used. A few lines instead of every file, for the AI agent that writes the designs.
+
+Options:
+  -r, --root <path>   The folder the canvas serves (htmlboard … --root), for links that start
+                      with "/" (default: the designs folder)
+`);
+    return;
+  }
+  let root;
+  const dirs = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--root' || arg === '-r') root = args[++i];
+    else if (arg.startsWith('--root=')) root = arg.slice('--root='.length);
+    else if (arg.startsWith('-')) {
+      console.error(`[htmlboard] Unknown option: ${arg} (see htmlboard catalog --help)`);
+      process.exit(1);
+    } else dirs.push(arg);
+  }
+  let catalog;
+  try {
+    catalog = buildCatalog(dirs[0] || process.cwd(), { root });
+  } catch (err) {
+    console.error(`[htmlboard] ${err.message}`);
+    process.exit(1);
+  }
+  process.stdout.write(formatCatalog(catalog, { name: shownPath(catalog.dir) }));
+}
+
+async function runCheckCommand(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Usage:
+  htmlboard check [directory or file] [-p <port>] [--json]
+
+Has the canvas running for the designs (open in a browser: the check runs there) load each one
+afresh and prints what went wrong, in a few lines of text: script errors and console.error, files
+that aren't there, components that weren't built, fonts that didn't load, content cut at the
+frame's edge, text cut off or spilling out of its box. A directory checks the designs in it, a
+file just that design (default: the current directory).
+
+Exits with 1 when it finds problems, 2 when it can't check (no canvas running, or none open).
+
+Options:
+  -p, --port <number>   The canvas's port (default: found on 3000 to 3020)
+      --json            The report as JSON
+`);
+    return;
+  }
+  let port;
+  let asJson = false;
+  const targets = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--port' || arg === '-p') port = parseInt(args[++i], 10);
+    else if (arg.startsWith('--port=')) port = parseInt(arg.slice('--port='.length), 10);
+    else if (arg === '--json') asJson = true;
+    else if (arg.startsWith('-')) {
+      console.error(`[htmlboard] Unknown option: ${arg} (see htmlboard check --help)`);
+      process.exit(2);
+    } else targets.push(arg);
+  }
+  try {
+    const { canvas, report } = await runCheck(targets[0], { port });
+    if (asJson) console.log(JSON.stringify(report, null, 2));
+    else process.stdout.write(formatReport(report, { name: shownPath(report.dir), url: canvas.url }));
+    process.exitCode = hasProblems(report) ? 1 : 0;
+  } catch (err) {
+    console.error(err instanceof CheckError ? err.message : `[htmlboard] ${err.message}`);
+    process.exitCode = 2;
+  }
+}
+
 function runMigrate(args) {
   const write = args.includes('--write');
   const dirArg = args.find((arg) => !arg.startsWith('-'));
@@ -266,11 +403,26 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'components') {
+    runComponents(args.slice(1));
+    return;
+  }
+
   if (args[0] === 'migrate') {
     runMigrate(args.slice(1));
     return;
   }
 
+  if (args[0] === 'catalog') {
+    runCatalog(args.slice(1));
+    return;
+  }
+
+  if (args[0] === 'check') {
+    await runCheckCommand(args.slice(1));
+    return;
+  }
+
   const options = parseArgs(args);
 
   if (options.help) {

package/package.json

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

package/skills/htmlboard/SKILL.md

@@ -23,7 +23,7 @@ npx htmlboard designs --open
 
 ## Write an artboard
 
-One design per file, with its facts in the `<head>`, linking the shared stylesheet (see below):
+One design per file, with its facts in the `<head>`, linking the shared stylesheet and components (see below):
 
 ```html
 <!DOCTYPE html>
@@ -33,7 +33,8 @@ One design per file, with its facts in the `<head>`, linking the shared styleshe
   <title>Checkout · one page</title>                         <!-- its name on the canvas -->
   <meta name="description" content="Address and payment on one screen">
   <meta name="htmlboard" content="width=390, height=844">   <!-- its size -->
-  <link rel="stylesheet" href="../styles.css">              <!-- shared tokens and components -->
+  <link rel="stylesheet" href="../styles.css">              <!-- shared tokens and classes -->
+  <script type="module" src="../components.js"></script>    <!-- shared components -->
   <style>
     .screen { height: 844px; /* only what this design needs */ }
   </style>
@@ -54,11 +55,11 @@ One design per file, with its facts in the `<head>`, linking the shared styleshe
 
 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). Read it before writing a design and use its tokens (`var(--accent)`) and classes (`.btn`, `.card`, …).
+- 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.
 - 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 (`components/forms.css`, `charts.css`) and link the extra files where they are used.
+- 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:
@@ -68,6 +69,38 @@ More tags, all optional:
 - `<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>
+```
+
+- 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`.
+
 ## 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/`.
@@ -85,16 +118,17 @@ More tags, all optional:
 }
 ```
 
-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. `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).
+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).
 
 ## 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 script, an image, data) reloads the artboards that loaded it.
+- 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.
 
 ## 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`).
-- If you can browse or take screenshots, open the artboard directly (`http://localhost:3000/<file>`) to check it at its real size before reporting back. Fix overflow, clipped text and broken images first.
+- 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.
+- 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>`).