htmlboard 0.0.0-stage → 0.2.0

package/skills/htmlboard/SKILL.md

@@ -0,0 +1,95 @@
+---
+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.
+---
+
+# 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.
+
+## Start the canvas
+
+Run it in the background, pointed at the designs folder (it is created if missing):
+
+```sh
+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.
+- 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:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Checkout · variant B</title>   <!-- the artboard's title on the canvas -->
+  <style>
+    body { margin: 0; }
+    .screen { width: 390px; min-height: 844px; /* … */ }
+  </style>
+</head>
+<body>
+  <main class="screen">…</main>
+</body>
+</html>
+```
+
+- 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
+
+**Without `designs.json`** (zero config), every `.html` under the folder is an artboard:
+
+- 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.
+
+**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:
+
+```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 }
+      ]
+    }
+  ]
+}
+```
+
+- 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.
+
+## Live reload
+
+- Saving an artboard's HTML reloads just that frame; the user's view stays put.
+- 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.
+
+## 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`).
+- 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.

package/src/client/explorer.css

@@ -0,0 +1,372 @@
+/* HtmlBoard explorer. Its own dark chrome, so the designs stand out on the canvas. */
+
+@font-face {
+  font-family: 'Inter';
+  font-style: normal;
+  font-weight: 400 700;
+  font-display: swap;
+  src: url(fonts/inter.woff2) format('woff2');
+}
+
+@font-face {
+  font-family: 'Bricolage Grotesque';
+  font-style: normal;
+  font-weight: 500 800;
+  font-display: swap;
+  src: url(fonts/bricolage-grotesque.woff2) format('woff2');
+}
+
+:root {
+  --x-canvas: #1C1C1E;
+  --x-dot: rgb(255 255 255 / 0.09);
+  --x-panel: #252527;
+  --x-raised: #2E2E31;
+  --x-line: #3A3A3E;
+  --x-text: #EDEDEB;
+  --x-text-soft: #9D9DA3;
+  --x-accent: #3D9DFF;
+  --x-wash: rgb(255 255 255 / 0.07);
+  --x-live: #3DD68C;
+  --font-ui: 'Inter', system-ui, sans-serif;
+  --font-display: 'Bricolage Grotesque', 'Inter', system-ui, sans-serif;
+  color-scheme: dark;
+}
+
+*, ::before, ::after { box-sizing: border-box; }
+
+html, body { height: 100%; margin: 0; overflow: hidden; }
+
+body {
+  font-family: var(--font-ui);
+  font-weight: 500;
+  color: var(--x-text);
+  background: var(--x-canvas);
+}
+
+:focus-visible { outline: 2px solid var(--x-accent); outline-offset: 2px; }
+
+[hidden] { display: none !important; }
+
+kbd {
+  display: inline-block;
+  min-width: 1.6em;
+  padding: 0 4px;
+  border: 1px solid var(--x-line);
+  border-radius: 4px;
+  background: var(--x-raised);
+  font: inherit;
+  font-size: 0.92em;
+  line-height: 1.5;
+  text-align: center;
+}
+
+.app { display: flex; height: 100%; }
+
+/* ---------- The list ---------- */
+
+.sidebar {
+  display: flex;
+  flex-direction: column;
+  flex: none;
+  width: 272px;
+  border-right: 1px solid var(--x-line);
+  background: var(--x-panel);
+}
+
+.app.is-collapsed .sidebar { display: none; }
+
+/* htmlboard's own row: the logo (a link to the project) and the version */
+.brand { display: flex; align-items: center; justify-content: space-between; gap: 8px; padding: 14px 16px 12px; border-bottom: 1px solid var(--x-line); }
+.brand-logo { display: block; border-radius: 4px; }
+.brand-logo img { display: block; width: auto; height: 18px; }
+.version { font-size: 11px; color: var(--x-text-soft); font-variant-numeric: tabular-nums; }
+
+.sidebar-head { display: flex; align-items: baseline; gap: 8px; padding: 16px 16px 10px; }
+.sidebar-head h1 { min-width: 0; margin: 0; font: 800 24px/1.1 var(--font-display); overflow-wrap: anywhere; }
+.count { flex: none; font-size: 13px; color: var(--x-text-soft); font-variant-numeric: tabular-nums; }
+
+.search { position: relative; margin: 0 12px 4px; }
+
+.search svg {
+  position: absolute;
+  left: 9px;
+  top: 50%;
+  width: 15px;
+  height: 15px;
+  fill: none;
+  stroke: var(--x-text-soft);
+  stroke-width: 2;
+  stroke-linecap: round;
+  transform: translateY(-50%);
+  pointer-events: none;
+}
+
+.search input {
+  width: 100%;
+  height: 32px;
+  padding: 0 30px;
+  border: 1px solid var(--x-line);
+  border-radius: 6px;
+  background: var(--x-canvas);
+  color: var(--x-text);
+  font: inherit;
+  font-size: 13px;
+}
+
+.search input::placeholder { color: var(--x-text-soft); opacity: 1; }
+.search input:focus { border-color: var(--x-accent); outline: none; }
+.search input::-webkit-search-cancel-button { appearance: none; }
+
+.search kbd {
+  position: absolute;
+  right: 7px;
+  top: 50%;
+  font-size: 11px;
+  color: var(--x-text-soft);
+  transform: translateY(-50%);
+  pointer-events: none;
+}
+
+.search input:focus ~ kbd, .search input:not(:placeholder-shown) ~ kbd { display: none; }
+
+.list { flex: 1; overflow-y: auto; padding: 0 8px 16px; }
+
+.list h2 {
+  margin: 18px 8px 4px;
+  font-size: 12px;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--x-text-soft);
+}
+
+.list .section-desc { margin: -2px 8px 6px; font-size: 12px; line-height: 1.45; color: var(--x-text-soft); }
+
+.list ul { margin: 0; padding: 0; list-style: none; }
+
+.item {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 12px;
+  width: 100%;
+  padding: 6px 8px;
+  border: 0;
+  border-radius: 5px;
+  background: none;
+  color: inherit;
+  font: inherit;
+  font-size: 14px;
+  line-height: 20px;
+  text-align: left;
+  cursor: pointer;
+}
+
+.item:hover { background: var(--x-wash); }
+.item[aria-current='true'] { background: color-mix(in srgb, var(--x-accent) 24%, transparent); color: #fff; }
+.item .dims { flex: none; font-size: 12px; color: var(--x-text-soft); font-variant-numeric: tabular-nums; }
+
+.no-match { margin: 0; padding: 12px 16px 0; font-size: 13px; color: var(--x-text-soft); }
+
+.sidebar-hint {
+  margin: 0;
+  padding: 12px 16px 16px;
+  border-top: 1px solid var(--x-line);
+  font-size: 12px;
+  line-height: 1.6;
+  color: var(--x-text-soft);
+}
+
+/* ---------- The canvas ---------- */
+
+.viewport {
+  position: relative;
+  flex: 1;
+  overflow: hidden;
+  touch-action: none;
+  background-color: var(--x-canvas);
+  background-image: radial-gradient(circle at 1px 1px, var(--x-dot) 1px, transparent 0);
+  background-size: var(--grid, 32px) var(--grid, 32px);
+  outline: none;
+}
+
+.viewport.is-panning, .viewport.is-panning * { cursor: grabbing; }
+.viewport.is-space { cursor: grab; }
+
+.world { position: absolute; left: 0; top: 0; transform-origin: 0 0; }
+
+.frame {
+  position: absolute;
+  background: #FFFFFF;
+  box-shadow: 0 1px 3px rgb(0 0 0 / 0.45), 0 10px 40px rgb(0 0 0 / 0.35);
+}
+
+/* The canvas takes every pointer event (wheel included, so Ctrl + scroll never zooms the page):
+   designs are pictures here, and Open shows one on its own. */
+.frame iframe { display: block; width: 100%; height: 100%; border: 0; pointer-events: none; }
+
+/* Designs the search leaves out stay in place, faded. */
+.frame.is-dimmed { opacity: 0.2; }
+
+.overlay { position: absolute; inset: 0; overflow: hidden; pointer-events: none; }
+
+.label, .section-title, .outline, .size { position: absolute; left: 0; top: 0; }
+
+.label {
+  overflow: hidden;
+  font-size: 12px;
+  font-weight: 600;
+  line-height: 16px;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  color: var(--x-text-soft);
+}
+
+.label.is-hover { color: var(--x-text); }
+.label.is-selected { color: var(--x-accent); }
+.label.is-dimmed { opacity: 0.35; }
+
+.section-title { font: 700 20px/24px var(--font-display); letter-spacing: 0.01em; white-space: nowrap; color: var(--x-text); }
+
+.outline--hover { box-shadow: 0 0 0 1px var(--x-accent); }
+.outline--selected { box-shadow: 0 0 0 2px var(--x-accent); }
+
+.size {
+  padding: 2px 6px;
+  border-radius: 4px;
+  background: var(--x-accent);
+  color: #FFFFFF;
+  font-size: 11px;
+  font-weight: 600;
+  line-height: 14px;
+  white-space: nowrap;
+  font-variant-numeric: tabular-nums;
+}
+
+/* ---------- Toolbar, shortcuts, messages ---------- */
+
+.toolbar {
+  position: absolute;
+  bottom: 16px;
+  left: 50%;
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding: 4px;
+  border: 1px solid var(--x-line);
+  border-radius: 10px;
+  background: var(--x-raised);
+  box-shadow: 0 8px 28px rgb(0 0 0 / 0.4);
+  transform: translateX(-50%);
+}
+
+.tool {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  min-width: 34px;
+  height: 34px;
+  padding: 0 8px;
+  border: 0;
+  border-radius: 6px;
+  background: none;
+  color: var(--x-text);
+  font: inherit;
+  font-size: 13px;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.tool:hover { background: var(--x-wash); }
+.tool[aria-pressed='true'] { color: var(--x-accent); }
+.tool[aria-disabled='true'] { opacity: 0.4; pointer-events: none; }
+
+.tool svg {
+  width: 17px;
+  height: 17px;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+}
+
+.zoom { min-width: 58px; font-variant-numeric: tabular-nums; }
+
+.sep { width: 1px; height: 20px; margin: 0 4px; background: var(--x-line); }
+
+.live { display: inline-flex; align-items: center; gap: 6px; padding: 0 8px; font-size: 12px; color: var(--x-text-soft); }
+.live::before { content: ''; width: 7px; height: 7px; border-radius: 50%; background: var(--x-live); }
+.live.is-off::before { background: var(--x-text-soft); }
+
+.help {
+  position: absolute;
+  right: 16px;
+  bottom: 72px;
+  width: min(340px, calc(100% - 32px));
+  padding: 14px 16px 10px;
+  border: 1px solid var(--x-line);
+  border-radius: 10px;
+  background: var(--x-raised);
+  box-shadow: 0 8px 28px rgb(0 0 0 / 0.4);
+  font-size: 13px;
+}
+
+.help h2 { margin: 0 0 8px; font: 700 18px/1.2 var(--font-display); }
+.help dl { margin: 0; }
+.help dl > div { display: flex; justify-content: space-between; gap: 12px; padding: 5px 0; border-top: 1px solid var(--x-line); }
+.help dt { color: var(--x-text-soft); }
+.help dd { margin: 0; text-align: right; }
+
+.toast {
+  position: absolute;
+  top: 16px;
+  left: 50%;
+  max-width: calc(100% - 32px);
+  padding: 8px 14px;
+  border: 1px solid var(--x-line);
+  border-radius: 8px;
+  background: var(--x-raised);
+  font-size: 13px;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  opacity: 0;
+  pointer-events: none;
+  transform: translateX(-50%);
+  transition: opacity 0.2s;
+}
+
+.toast.is-on { opacity: 1; }
+
+.notice {
+  position: absolute;
+  inset: 0;
+  display: grid;
+  place-content: center;
+  gap: 8px;
+  padding: 32px;
+  background: var(--x-canvas);
+  font-size: 15px;
+  line-height: 1.6;
+  text-align: center;
+}
+
+.notice-mark { justify-self: center; width: auto; height: 72px; margin-bottom: 8px; }
+.notice strong { font: 800 24px/1.2 var(--font-display); }
+.notice p { max-width: 34em; margin: 0; color: var(--x-text-soft); }
+.notice code { padding: 2px 6px; border-radius: 4px; background: var(--x-raised); color: var(--x-text); font-size: 14px; }
+
+/* Phones: the toolbar keeps its icons only. */
+@media (max-width: 520px) {
+  .toolbar { bottom: 10px; }
+  .tool span { display: none; }
+  .zoom { min-width: 48px; }
+  .live { padding: 0 6px; font-size: 0; }
+  .help { bottom: 64px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .toast { transition: none; }
+}