htmlboard 0.1.0 → 0.3.0

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, self-contained so it renders on its own, with its facts in the `<head>`:
 
 ```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 -->
   <style>
     body { margin: 0; }
-    .screen { width: 390px; min-height: 844px; /* … */ }
+    .screen { width: 390px; height: 844px; /* … */ }
   </style>
 </head>
 <body>
@@ -42,54 +44,46 @@ 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.
 - No build step: plain HTML, CSS and browser JavaScript (ES modules and CDN scripts work).
 
-## How the canvas lays out files
+More tags, all optional:
 
-**Without `designs.json`** (zero config), every `.html` under the folder is an artboard:
+- `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).
 
-- 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.
+## Group and order
 
-**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:
+- **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` and `tags` (searchable); `category` for the toolbar filters (`desktop`, `mobile`, `tablet`, `components`; guessed from the path, then the width, when left out); `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 pan and zoom stay put.
-- Saving `designs.json`, or creating a new HTML file, rebuilds the canvas.
-- Saving a shared file (CSS, script, image) reloads every frame.
+- 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.
+- 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.