htmlboard 0.2.0 → 0.4.0

package/README.md

@@ -32,8 +32,9 @@ 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.
-- 🔍 **Auto-Discovery**: Point HtmlBoard at any folder. It finds every HTML file, names it after its `<title>`, sizes it from words in its path (mobile, tablet, desktop…) and lays the folders out as rows.
-- 📐 **Declarative Manifest (`designs.json`)**: Optional file to choose the sections, the order, the sizes and the names.
+- 📂 **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.
+- 📐 **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.
 - 🎯 **Focus & Zoom-to-Fit**: Click a design in the list or double-click it on the canvas to fit it, <kbd>Shift</kbd> + <kbd>1</kbd> fits everything, <kbd>←</kbd> <kbd>→</kbd> step through the designs.
 - 🔗 **Deep Links**: The URL follows the selected design (`http://localhost:3000/#checkout-b`), so you can share or reload a view of one design.
@@ -58,7 +59,7 @@ htmlboard
 
 ### Scaffold a Starter Project
 
-To create a new workspace with starter templates (mobile screen, desktop dashboard, and component library):
+To start with sample designs (a folder of screens and a folder of components, each file describing itself, all sharing one `styles.css`):
 
 ```bash
 npx htmlboard --init
@@ -73,6 +74,7 @@ Usage:
   htmlboard [directory] [options]
   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
 
 Options:
   -p, --port <number>   Port to listen on (default: 3000)
@@ -80,7 +82,7 @@ Options:
   -r, --root <path>     Serve files from this parent folder, so artboards can link to
                         shared files outside the designs folder (default: the designs folder)
   -o, --open            Open the explorer automatically in default browser
-      --init            Scaffold starter designs.json and sample artboards
+      --init            Add sample designs (two folders of artboards)
   -v, --version         Display HtmlBoard version
   -h, --help            Display help message
 ```
@@ -100,8 +102,12 @@ htmlboard ./src/designs -p 8080
 # Artboards in ./design that link to the site's own ../css and ../js
 htmlboard design --root .
 
-# Initialize sample templates in a new folder
+# Start a new folder with sample designs
 htmlboard ./my-new-ui --init --open
+
+# See what moving ./design/designs.json into its files would do, then do it
+htmlboard migrate design
+htmlboard migrate design --write
 ```
 
 ---
@@ -112,7 +118,7 @@ HtmlBoard is built from the ground up to pair with AI coding agents (Claude, Gem
 
 ### Install the agent skill
 
-HtmlBoard ships an [Agent Skill](https://agentskills.io) that teaches your agent how to use it: where to put artboards, how to size and name them, how `designs.json` works and how to start the canvas. Install it in your project:
+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:
 
 ```bash
 npx htmlboard skills install
@@ -132,7 +138,9 @@ Running `install` again after upgrading HtmlBoard updates the skill; a copy you
 ### The workflow
 
 1. **Ask your LLM to generate artboards:**
-   > *"Create 3 design explorations for our checkout flow in `artboards/checkout-v1.html`, `artboards/checkout-v2.html`, and `artboards/checkout-v3.html`."*
+   > *"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.
 
 2. **Run HtmlBoard in the background:**
    ```bash
@@ -144,78 +152,71 @@ Running `install` again after upgrading HtmlBoard updates the skill; a copy you
 
 ---
 
-## 📋 The `designs.json` Manifest
+## 📂 How Designs Are Found
 
-While HtmlBoard automatically discovers HTML files, you can add a `designs.json` file in your designs folder for custom layout and organization. Only `sections[].designs[].file` is required; the short form is enough:
+Every `.html` file under the folder is a design (hidden folders, `node_modules`, `dist` and `build` aside):
 
-```json
-{
-  "sections": [
-    {
-      "title": "Home",
-      "designs": [
-        { "file": "home-mobile.html", "title": "Home · phone", "width": 390, "height": 844 },
-        { "file": "home-mobile.html?theme=dark", "title": "Home · phone · dark", "width": 390, "height": 844 },
-        { "file": "home-desktop.html", "title": "Home · desktop", "width": 1440 }
-      ]
-    }
-  ]
-}
+- **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.
+- **A file describes itself** in its `<head>`:
+
+```html
+<title>Checkout</title>                                         <!-- its name -->
+<meta name="description" content="One page, address first">    <!-- its description -->
+<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" -->
 ```
 
-Sections are rows (top to bottom) and designs run left to right. A `file` may carry a query string, so one HTML file can show several states. Leave `height` out to let the frame grow with its page. `id` and `category` are derived from the file when left out.
+| Tag | What it says |
+| :--- | :--- |
+| `<title>` | The design's name (without one: the file's name, prefix and extension off). |
+| `<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. |
+
+**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.
 
-The full form adds ids, descriptions (shown in the list), categories and tags (searchable); `name`/`artboards` are synonyms of `title`/`designs`:
+**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.
+
+---
+
+## 📋 `designs.json` (Optional)
+
+A `designs.json` in the folder curates the canvas when folders aren't enough: section titles with accents and capitals, an order across folders, a name or size the file doesn't give. The files still say the rest:
 
 ```json
 {
-  "title": "Fintech Mobile & Web App",
-  "description": "Exploration of screen flows, responsive layouts, and UI components",
+  "title": "Wallet app",
   "sections": [
+    { "title": "Onboarding", "designs": ["01-onboarding/01-welcome.html", "01-onboarding/02-sign-up.html"] },
+    { "title": "Checkout · round 2", "folder": "03-checkout" },
     {
-      "id": "screens",
-      "name": "Screen Layouts",
-      "description": "Full page layouts across mobile and desktop viewports",
-      "artboards": [
-        {
-          "id": "desktop-dashboard",
-          "title": "Desktop Dashboard",
-          "file": "artboards/desktop.html",
-          "width": 1280,
-          "height": 820,
-          "category": "desktop",
-          "tags": ["desktop", "dashboard", "analytics"]
-        },
-        {
-          "id": "mobile-app",
-          "title": "Mobile App Feed",
-          "file": "artboards/mobile.html",
-          "width": 390,
-          "height": 844,
-          "category": "mobile",
-          "tags": ["mobile", "ios", "finance"]
-        }
-      ]
-    },
-    {
-      "id": "components",
-      "name": "Component Library",
-      "artboards": [
-        {
-          "id": "ui-primitives",
-          "title": "UI Kit Elements",
-          "file": "artboards/components.html",
-          "width": 780,
-          "height": 720,
-          "category": "components",
-          "tags": ["design-system", "buttons", "inputs"]
-        }
-      ]
+      "title": "Print",
+      "description": "Flyers for the launch",
+      "designs": [{ "file": "flyer.html", "title": "Launch flyer", "height": 1350 }]
     }
   ]
 }
 ```
 
+- 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.
+- `name` and `artboards` are synonyms of `title` and `designs`.
+
+### Moving an existing `designs.json` into the files
+
+```bash
+npx htmlboard migrate design          # shows what it would do, and checks the canvas stays the same
+npx htmlboard migrate design --write  # does it
+```
+
+It writes each file's size, category, label, variants and description as tags after its `<title>`, and leaves designs.json with the sections, their titles and order, and the values the files can't say (a name that isn't the file's `<title>` plus a label, say).
+
 ---
 
 ## ⌨️ Keyboard Shortcuts
@@ -232,10 +233,11 @@ The full form adds ids, descriptions (shown in the list), categories and tags (s
 | <kbd>←</kbd> / <kbd>→</kbd> | Previous / next design |
 | <kbd>Enter</kbd> | Open the selected design on its own |
 | <kbd>/</kbd> | Search (<kbd>Enter</kbd> fits the first match, <kbd>Esc</kbd> clears) |
+| <kbd>1</kbd> – <kbd>4</kbd> | Show all, mobile, tablet, desktop (<kbd>5</kbd> on: the other categories) |
 | <kbd>R</kbd> | Reload the designs |
 | <kbd>\</kbd> | Show or hide the list |
 | <kbd>?</kbd> | Show the shortcuts |
-| <kbd>Esc</kbd> | Deselect |
+| <kbd>Esc</kbd> | Deselect, then clear the search, then the filter |
 
 On the canvas the designs are pictures: the canvas takes every click and scroll, so <kbd>Ctrl</kbd> + scroll never zooms the page itself. Use **Open** (or <kbd>Enter</kbd>) to try a design's links and hover states on its own.
 
@@ -259,6 +261,15 @@ console.log(`HtmlBoard running at ${instance.url}`);
 // await instance.close();
 ```
 
+The list of designs is there too, as the explorer gets it:
+
+```javascript
+import { loadDesignsManifest } from 'htmlboard';
+
+const { sections } = loadDesignsManifest('./designs');
+// → [{ id: 'screens', name: 'screens', artboards: [{ id, title, file, width, height, category }, …] }, …]
+```
+
 The skill installer is exported too:
 
 ```javascript
@@ -278,7 +289,9 @@ htmlboard/
 │   └── htmlboard.js      # CLI executable
 ├── src/
 │   ├── index.js          # Library entry point & API exports
-│   ├── server.js         # HTTP server, SSE live reload, auto-discovery
+│   ├── server.js         # HTTP server, SSE live reload
+│   ├── designs.js        # Which designs a folder holds: files, their tags, designs.json
+│   ├── migrate.js        # `htmlboard migrate`
 │   ├── skills.js         # `htmlboard skills` installer
 │   ├── client/           # The canvas
 │   │   ├── index.html    # Explorer shell: list, canvas, toolbar, shortcuts
@@ -286,9 +299,10 @@ htmlboard/
 │   │   ├── explorer.js   # Layout, pan/zoom, search, live reload
 │   │   ├── favicon.svg, logo.svg, mark.svg
 │   │   └── fonts/        # Inter and Bricolage Grotesque (OFL)
-│   └── templates/        # Starter scaffold templates
-│       ├── designs.json  # Starter manifest
-│       └── artboards/    # Sample mobile, desktop, & component screens
+│   └── templates/        # The sample designs `--init` adds
+│       ├── styles.css    # Their shared tokens and components
+│       ├── 01-screens/   # Desktop dashboard, mobile feed
+│       └── 02-components/
 ├── 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

@@ -6,6 +6,7 @@ import { exec } from 'node:child_process';
 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';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -74,6 +75,7 @@ Usage:
   htmlboard [directory] [options]
   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
 
 Options:
   -p, --port <number>   Port to listen on (default: 3000)
@@ -81,7 +83,7 @@ Options:
   -r, --root <path>     Serve files from this parent folder, so artboards can link to
                         shared files outside the designs folder (default: the designs folder)
   -o, --open            Open the explorer automatically in your default browser
-      --init            Scaffold starter designs.json and sample artboards in target directory
+      --init            Add sample designs (two folders of artboards) to the directory
   -v, --version         Display the version
   -h, --help            Display this help message
 
@@ -90,7 +92,7 @@ Examples:
   htmlboard --open              # Run and launch browser automatically
   htmlboard ./designs -p 8080   # Serve ./designs on port 8080
   htmlboard design --root .     # Artboards in ./design that link to ../css/…
-  htmlboard --init              # Initialize starter templates in current folder
+  htmlboard --init              # Add sample designs to the current folder
   htmlboard skills install      # Add the HtmlBoard skill to this project's agents
 
 On the canvas:
@@ -98,6 +100,7 @@ On the canvas:
   Ctrl/Cmd + scroll     Zoom (or pinch)
   Double-click          Fit a design (Shift + 1 fits everything)
   /                     Search
+  1 – 4                 Show all, mobile, tablet, desktop
   ?                     All the shortcuts
 `);
 }
@@ -118,42 +121,25 @@ function openBrowser(url) {
 
 function scaffoldProject(targetDir) {
   const templatesDir = path.join(__dirname, '..', 'src', 'templates');
-  const targetConfig = path.join(targetDir, 'designs.json');
-  const targetArtboardsDir = path.join(targetDir, 'artboards');
-
-  console.log(`[htmlboard] Scaffolding starter project in ${targetDir}...`);
-
-  if (!fs.existsSync(targetDir)) {
-    fs.mkdirSync(targetDir, { recursive: true });
-  }
-
-  if (!fs.existsSync(targetArtboardsDir)) {
-    fs.mkdirSync(targetArtboardsDir, { recursive: true });
-  }
-
-  // Copy designs.json if not present
-  if (!fs.existsSync(targetConfig)) {
-    const srcConfig = path.join(templatesDir, 'designs.json');
-    if (fs.existsSync(srcConfig)) {
-      fs.copyFileSync(srcConfig, targetConfig);
-      console.log(`  ✓ Created designs.json`);
-    }
-  } else {
-    console.log(`  ℹ designs.json already exists (skipped)`);
-  }
-
-  // Copy starter artboards
-  const starterFiles = ['mobile.html', 'desktop.html', 'components.html'];
-  for (const file of starterFiles) {
-    const srcFile = path.join(templatesDir, 'artboards', file);
-    const destFile = path.join(targetArtboardsDir, file);
-    if (!fs.existsSync(destFile) && fs.existsSync(srcFile)) {
-      fs.copyFileSync(srcFile, destFile);
-      console.log(`  ✓ Created artboards/${file}`);
+  console.log(`[htmlboard] Adding sample designs to ${targetDir}...`);
+  // Folders are sections and number prefixes the order; each file says its own size
+  const copy = (from, rel) => {
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+      const relPath = path.join(rel, entry.name);
+      const dest = path.join(targetDir, relPath);
+      if (entry.isDirectory()) {
+        fs.mkdirSync(dest, { recursive: true });
+        copy(path.join(from, entry.name), relPath);
+      } else if (fs.existsSync(dest)) {
+        console.log(`  ℹ ${relPath} already exists (skipped)`);
+      } else {
+        fs.copyFileSync(path.join(from, entry.name), dest);
+        console.log(`  ✓ Created ${relPath}`);
+      }
     }
-  }
-
-  console.log(`\n🎉 Starter templates created successfully!`);
+  };
+  fs.mkdirSync(targetDir, { recursive: true });
+  copy(templatesDir, '');
 }
 
 function showSkillsHelp() {
@@ -220,6 +206,58 @@ function runSkills(args) {
   }
 }
 
+function runMigrate(args) {
+  const write = args.includes('--write');
+  const dirArg = args.find((arg) => !arg.startsWith('-'));
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Usage:
+  htmlboard migrate [directory] [--write]
+
+Moves what designs.json says about each design into the design's own file (its size, category,
+label, variants and description, as <meta> tags after its <title>) and leaves designs.json with
+the sections, their titles and order, and the values that differ from the files'.
+
+Without --write it only shows what it would do, and checks that the canvas stays the same.
+`);
+    return;
+  }
+  const dir = path.resolve(dirArg || process.cwd());
+  let plan;
+  try {
+    plan = planMigration(dir);
+  } catch (err) {
+    console.error(`[htmlboard] Can't read ${path.join(dir, 'designs.json')}: ${err.message}`);
+    process.exit(1);
+  }
+  const differences = checkMigration(dir, plan);
+  const [before, after] = plan.entries;
+
+  console.log(`\n  \x1b[1m${path.relative(process.cwd(), dir) || '.'}\x1b[0m`);
+  if (!plan.files.length) console.log('  \x1b[90mNo file to change.\x1b[0m');
+  for (const { file, lines } of plan.files) {
+    console.log(`\n  ${file}`);
+    for (const line of lines) console.log(`    \x1b[32m+\x1b[0m ${line}`);
+  }
+  console.log(`\n  designs.json: ${before} entries → ${after}`);
+  if (differences.length) {
+    console.log(`\n  \x1b[33mThe canvas would change:\x1b[0m`);
+    for (const { before: was, after: will } of differences.slice(0, 20)) {
+      if (was) console.log(`    \x1b[31m-\x1b[0m ${was}`);
+      if (will) console.log(`    \x1b[32m+\x1b[0m ${will}`);
+    }
+  } else {
+    console.log(`  \x1b[32m✓\x1b[0m The canvas stays the same.`);
+  }
+
+  if (!write) {
+    console.log(`\n  Nothing written. Run again with --write to apply.\n`);
+    return;
+  }
+  applyMigration(dir, plan);
+  console.log(`\n  \x1b[32m✓ Written:\x1b[0m ${plan.files.length} file${plan.files.length === 1 ? '' : 's'} and designs.json.\n`);
+}
+
 async function main() {
   const args = process.argv.slice(2);
 
@@ -228,6 +266,11 @@ async function main() {
     return;
   }
 
+  if (args[0] === 'migrate') {
+    runMigrate(args.slice(1));
+    return;
+  }
+
   const options = parseArgs(args);
 
   if (options.help) {
@@ -246,21 +289,15 @@ async function main() {
     scaffoldProject(targetDir);
   }
 
-  // If directory is empty, auto-prompt or auto-scaffold
+  // An empty folder (or a new one) gets the sample designs
   let entries = [];
   try {
     entries = fs.readdirSync(targetDir);
   } catch (_) {
     fs.mkdirSync(targetDir, { recursive: true });
   }
-
-  const hasHtml = entries.some((e) => e.endsWith('.html')) ||
-    (fs.existsSync(path.join(targetDir, 'artboards')) &&
-     fs.readdirSync(path.join(targetDir, 'artboards')).some((e) => e.endsWith('.html')));
-  const hasDesignsJson = fs.existsSync(path.join(targetDir, 'designs.json'));
-
-  if (!hasHtml && !hasDesignsJson && entries.filter((e) => !e.startsWith('.')).length === 0) {
-    console.log(`[htmlboard] Directory is empty. Initializing starter artboards...`);
+  if (!options.init && !entries.some((e) => !e.startsWith('.'))) {
+    console.log(`[htmlboard] Directory is empty. Adding sample designs...`);
     scaffoldProject(targetDir);
   }
 

package/package.json

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

package/skills/htmlboard/SKILL.md

@@ -5,7 +5,7 @@ description: Design UI in plain HTML files and show them side by side on an infi
 
 # 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, so you design by writing HTML and CSS, and the user sees the result update live while you work.
+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.
 
 ## Start the canvas
 
@@ -16,24 +16,26 @@ npx htmlboard designs --open
 ```
 
 - It prints the URL (default `http://localhost:3000`; if the port is busy it takes the next free one). Give the URL to the user.
-- `-p <port>` picks the port. `--init` adds three sample artboards and a `designs.json`; skip it unless the user wants a starter.
+- `-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":…}`.
 
 ## Write an artboard
 
-One design per file. Keep each file self-contained so it renders on its own:
+One design per file, with its facts in the `<head>`, linking the shared stylesheet (see below):
 
 ```html
 <!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
-  <title>Checkout · variant B</title>   <!-- the artboard's title on the canvas -->
+  <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 -->
   <style>
-    body { margin: 0; }
-    .screen { width: 390px; min-height: 844px; /* … */ }
+    .screen { height: 844px; /* only what this design needs */ }
   </style>
 </head>
 <body>
@@ -42,54 +44,57 @@ One design per file. Keep each file self-contained so it renders on its own:
 </html>
 ```
 
+- 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 shared CSS, images, scripts and fonts work (`assets/logo.svg`; `../css/theme.css` with `--root`). Reuse the project's own stylesheet and tokens when there is one.
+- 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).
 
-## How the canvas lays out files
+## Shared styles
 
-**Without `designs.json`** (zero config), every `.html` under the folder is an artboard:
+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.
 
-- Each subfolder is a section (row); files at the top level go to "Root Designs".
-- The size comes from words in the file's path: `mobile`, `phone`, `iphone` → 390×844; `tablet`, `ipad` → 768×1024; `component`, `ui`, `atomic` → 720×600; `desktop`, `laptop`, `screen` → 1280×800; anything else → 1200×800. Name files accordingly, e.g. `checkout/mobile-variant-b.html`.
-- Hidden folders, `node_modules`, `dist` and `build` are skipped.
+- 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`, …).
+- 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.
+- 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.
 
-**With `designs.json`** in the designs folder, the manifest replaces discovery completely: a file not listed in it doesn't show. Use it to choose order, sizes and grouping:
+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).
+
+## 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
 {
-  "title": "Checkout redesign",
   "sections": [
-    {
-      "title": "Checkout · mobile",
-      "description": "Three directions for the payment step",
-      "designs": [
-        { "file": "checkout/a.html", "title": "A · current", "width": 390, "height": 844 },
-        { "file": "checkout/b.html", "title": "B · one page", "width": 390, "tags": ["proposal"] },
-        { "file": "checkout/b.html?theme=dark", "title": "B · dark", "width": 390, "height": 844 }
-      ]
-    }
+    { "title": "Checkout · mobile", "designs": ["03-checkout/01-one-page.html", "03-checkout/02-steps.html"] },
+    { "title": "Launch flyers", "folder": "04-flyers" }
   ]
 }
 ```
 
-- Sections are rows, top to bottom; designs run left to right.
-- `file` is relative to the designs folder and may carry a query string, so one file can show several states.
-- Omit `height` to let the frame grow to the page's full height (long pages, boards, docs).
-- Optional: `description` (shown in the list), `tags` and `category` (searchable), `id` (derived from `file`).
-- `name` and `artboards` are accepted as synonyms of a section's `title` and `designs`.
-
-When the project already has a `designs.json`, add every new file to it.
+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).
 
 ## Live reload
 
-- Saving an artboard's HTML reloads just that frame; the user's view stays put.
+- 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 `designs.json`, or adding or removing artboards, rebuilds the canvas.
+- 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 (`hero-a.html`, `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 `.html`, slashes and other symbols turned into `-`: `checkout/b.html` → `checkout-b`).
+- 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.