@desplega.ai/agent-swarm 2.7.5 → 2.7.7

package/templates/skills/pages/content.md

@@ -1,12 +1,12 @@
-# Pages — DB-backed Static Artifacts
+# Pages: DB-backed Static Artifacts
 
 DB-backed static content (HTML or JSON) served by the API directly. Cheap,
 versioned, share-able by URL. No server process, no tunnel, no port
 allocation.
 
 A page should be a clean human-facing artifact, not a raw dump with a URL. This
-skill covers both halves: **how to publish** a page, and **the taste baseline**
-every page should meet.
+skill covers both halves: **how to publish** a page, and **the design system**
+every page should use.
 
 > **Capability gate**: the `create_page` MCP tool is only available when the
 > agent's `CAPABILITIES` env var includes `pages`
@@ -29,10 +29,10 @@ in a single call), use pages. If it needs stored data and actions, use apps.
 
 Do **not** use pages for:
 
-- In-flight progress notes — use `store-progress.progress`
+- In-flight progress notes: use `store-progress.progress`
 - Secrets, private credentials, or unapproved personal data
-- Large binary files — use agent-fs for PNG/MP4
-- Raw verbose logs — summarize, and link the raw file as an artifact
+- Large binary files: use agent-fs for PNG/MP4
+- Raw verbose logs: summarize, and link the raw file as an artifact
 
 ## Quick Start
 
@@ -47,7 +47,7 @@ Do **not** use pages for:
   "authMode": "authed",
   "body": "<!doctype html><html><body><h1>Q2 Status</h1>...</body></html>"
 }
-// → { id, version: 1, app_url, api_url }
+// → { id, version: 1, designVersion: 2, app_url, api_url }
 ```
 
 Share `app_url` (the SPA route) for the general case; share `api_url` for a
@@ -56,8 +56,8 @@ no-SPA-required direct link.
 Use `authMode: "public"` only when the page is intentionally safe for anyone
 with the URL to view.
 
-A complete, styled report body that follows the baseline below is bundled at
-**`examples/report-page.html`** — copy it as your starting point rather than
+A complete report built from the design system below is bundled at
+**`examples/report-page.html`**. Copy it as your starting point instead of
 writing CSS from scratch.
 
 ### Authed JSON dashboard
@@ -80,28 +80,451 @@ swarm API.
 
 ---
 
-# Design baseline
+# Design system
+
+HTML pages with `designVersion: 2` get the swarm design system. It is the
+dashboard's own look (the Hive preset), built from the dashboard's theme
+tokens. One theme switch restyles the whole page. New pages get
+`designVersion: 2` by default.
+
+The design system styles HTML pages only. JSON pages render inside the
+dashboard and use the dashboard theme.
+
+Before you create a page, write a one-line design read for yourself:
+
+> Reading this as: `<page kind>` for `<audience>`, using the design system plus `<density needs>`.
+
+## What a designVersion 2 page gets
+
+The API injects these into the `<head>` of every designVersion 2 HTML page:
+
+- **Element defaults**: plain HTML elements look finished with zero CSS. See Element defaults below for the full list.
+- **Theme tokens**: CSS variables such as `var(--color-primary)`. Each color token has a light value and a dark value.
+- **Primitives**: `swarm-*` classes for page structure, metrics, panels, badges, tables, buttons, and callouts.
+- **Tailwind v4 utilities** that map to the tokens, such as `bg-card` and `text-muted-foreground`. Preflight stays off, so the element defaults stay.
+- **Fonts**: Space Grotesk for text and Space Mono for code.
+- **Light print**: print always uses the light tokens.
+
+The element defaults, the primitives, and the Tailwind utilities sit in CSS
+cascade layers. A Tailwind utility beats a primitive, and a primitive beats an
+element default. Your own `<style>` rules are not in a layer, so they beat all
+three. Use your own CSS for layout, and take every color from a token. For an
+edge-to-edge layout, set `body { padding: 0 }`.
+
+## Element defaults
+
+The head styles these elements. They need no class. Do not restyle an element
+only to get the look that it already has.
+
+| Element | Default look |
+|---|---|
+| `html`, `body` | The background and foreground tokens. The body uses `--font-sans` at 15px with a 1.55 line height. It has 24px of padding, and 16px at 640px wide and below. |
+| `h1` to `h6` | Weight 600. `h1` is 30px, `h2` is 20px, `h3` is 16px, `h4` is 15px, and `h5` and `h6` are 13px. |
+| `p`, `ul`, `ol`, `li` | Paragraphs and lists have a 12px bottom margin. List markers are muted. |
+| `dl`, `dt`, `dd` | `dt` is weight 500. For a key and value grid, use `.swarm-kv`. |
+| `a` | The primary color with a soft underline. The underline gets stronger on hover. |
+| `strong`, `b` | Weight 600. |
+| `mark` | A soft highlight in the pending tone. |
+| `hr` | A 1px `--color-border-subtle` rule, with 32px above and below. |
+| `blockquote` | Muted text with a 2px left rule. |
+| `code`, `samp` | `--font-mono` at 0.85em. `code` has a muted fill. |
+| `kbd` | A key with a 1px border and a thicker bottom edge, in `--font-mono`. |
+| `pre` | A bordered surface block in `--font-mono`. It scrolls when a line is too long. |
+| `img`, `video` | Block elements that are never wider than their container. |
+| `figure`, `figcaption` | `figcaption` is 13px muted text, 8px below the content. |
+| `table`, `th`, `td` | Full width, 14px, collapsed borders, and tabular digits. `th` is an 11px uppercase muted label. Each row has a subtle bottom rule. |
+| `caption` | 13px muted text, aligned left. |
+| `tfoot` | A totals row: weight 600 with a `--color-border` rule above it. Print shows it once, at the end of the table. |
+| `th scope="row"` | A row header that looks like a normal cell. |
+| `details`, `summary` | `summary` is weight 500 with a muted marker. |
+| Text `input`, `select`, `textarea` | The `.swarm-input` look. `select` has its own arrow. `textarea` is at least 80px tall and resizes vertically. |
+| `button`, and `input` of type `button`, `submit`, or `reset` | The outline `.swarm-button` look. A plain `<button>` needs no class. |
+| `input type="file"` | A small outline button opens the file picker. |
+| Checkbox, radio, range, `progress` | The primary color. |
+| `fieldset`, `legend` | A bordered group with a 13px muted legend. |
+| Form states | Placeholders are muted. Disabled controls have 50% opacity. `aria-invalid="true"` makes the border destructive. |
+| `:focus-visible` | A 2px ring in `--color-ring`. |
+| `::selection` | The primary fill. |
+| Every element | `border: 0 solid var(--color-border)`. A bare `border` class draws a 1px line in the border token. |
+
+Blocks such as `p`, lists, `table`, `pre`, and `figure` have a 12px or 16px
+bottom margin. A heading that is the first child of its container has no top
+margin. The last block in a container has no bottom margin.
+
+The head sets `<base target="_blank">`, so a link to another page opens in a
+new tab. A link inside the page (`href="#id"`) without a `target` stays in the
+page.
+
+## No hardcoded colors
+
+Take every color from a token. Inside the dashboard, the page follows the
+viewer's theme and mode. A hardcoded color stays the same in every theme and
+mode, so it can break contrast.
+
+- Do not write color literals: hex values (`#2563eb`), `rgb()`, `rgba()`, `hsl()`, `hsla()`, `oklch()`, or named colors such as `white` and `black`.
+- Do not use Tailwind palette classes such as `bg-blue-500`, `text-zinc-600`, `bg-white`, or `text-black`, or arbitrary colors such as `bg-[#fff]`. They ignore the theme. For example, a `bg-white` card in dark mode puts light text on white.
+- In CSS, use `var(--color-*)`. In markup, use the Tailwind class of the token, such as `bg-primary` or `text-muted-foreground`.
+- For a tint, add an opacity modifier: `bg-primary/10`. In CSS, write `color-mix(in oklab, var(--color-primary) 10%, transparent)`.
+- In inline SVG, use `fill-chart-1`, `stroke-border`, or `currentColor`.
+- For a canvas chart, read the token value at runtime: `getComputedStyle(document.documentElement).getPropertyValue("--color-chart-1")`.
+
+`create_page` counts the hardcoded colors in your `<style>` blocks, `style`
+attributes, and `class` attributes. At 8 or more, its result tells you to use
+tokens. A page with 8 or more hardcoded colors stays light, also when the
+viewer uses dark mode.
+
+To restyle a page, set `theme` or `themeTokens` (see Theming). Do not write
+your own palette.
+
+## Theme tokens
+
+The tokens use the dashboard's names. The font and radius tokens have one
+value for both modes.
+
+| CSS variable | Tailwind class | Meaning |
+|---|---|---|
+| `--color-background` | `bg-background` | The page canvas. |
+| `--color-foreground` | `text-foreground` | Main text. |
+| `--color-card`, `--color-card-foreground` | `bg-card`, `text-card-foreground` | Panels and the text on them. |
+| `--color-surface` | `bg-surface` | A recessed step between canvas and card, for nested blocks. |
+| `--color-popover`, `--color-popover-foreground` | `bg-popover`, `text-popover-foreground` | Menus, tooltips, and other floating layers. |
+| `--color-primary`, `--color-primary-foreground` | `bg-primary`, `text-primary`, `text-primary-foreground` | The one accent: links, primary buttons, and active state. The foreground is the text on a primary fill. |
+| `--color-secondary`, `--color-secondary-foreground` | `bg-secondary`, `text-secondary-foreground` | Secondary buttons and quiet fills. |
+| `--color-muted`, `--color-muted-foreground` | `bg-muted`, `text-muted-foreground` | Quiet resting fills. Secondary text, labels, and captions. |
+| `--color-accent`, `--color-accent-foreground` | `hover:bg-accent`, `text-accent-foreground` | The hover and highlight fill. For the brand accent, use `primary`. |
+| `--color-destructive`, `--color-destructive-foreground` | `bg-destructive`, `text-destructive` | Destructive actions only. |
+| `--color-border` | `border-border` | Structure lines: panels, inputs, table frames. |
+| `--color-border-subtle` | `border-border-subtle`, `divide-border-subtle` | Quiet lines: row rules and separators. |
+| `--color-input` | `border-input` | Form control borders. |
+| `--color-ring` | `ring-ring`, `outline-ring` | The focus ring. |
+| `--color-chart-1` to `--color-chart-5` | `bg-chart-1`, `fill-chart-2`, `stroke-chart-3` | Chart series, in order. |
+| `--color-status-<tone>` | `bg-status-success` | A pale status fill. |
+| `--color-status-<tone>-strong` | `text-status-error-strong` | Status text on a neutral surface. |
+| `--color-status-<tone>-foreground` | `text-status-success-foreground` | The text on a pale status fill. |
+| `--color-status-success-solid`, `--color-status-active-solid` | `bg-status-success-solid` | Saturated stops for small dots and icons. |
+| `--font-sans` | `font-sans` | Text. Space Grotesk by default. |
+| `--font-mono` | `font-mono` | Code, IDs, logs, and other machine output. Space Mono by default. |
+| `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl` | `rounded-sm`, `rounded-md`, `rounded-lg`, `rounded-xl` | Corner radii, from tags (`sm`) to panels (`xl`). |
+
+`<tone>` is `success`, `active`, `error`, `info`, `pending`, `warning`,
+`paused`, or `neutral`. Status colors carry meaning. Use them for states, not
+for decoration.
+
+The old `--swarm-bg`, `--swarm-card`, `--swarm-border`, `--swarm-text`,
+`--swarm-muted`, and `--swarm-primary` variables still work. On designVersion
+2 pages, they are aliases of the tokens. Use the token names in new pages.
+
+## Primitives
+
+The primitives are plain CSS classes. They use only tokens, so they work in
+both modes and under every preset. Add Tailwind utilities for spacing and
+layout.
+
+**`.swarm-page`**: the reading spine. It centers the content at a maximum width of 1120px.
+
+```html
+<main class="swarm-page">...</main>
+```
+
+**`.swarm-eyebrow`**: a small uppercase label above a title.
+
+```html
+<p class="swarm-eyebrow">Weekly report · 2026-10-31</p>
+```
+
+**`.swarm-lede`**: the summary paragraph under the title. It is larger, muted, and about 68 characters wide.
+
+```html
+<p class="swarm-lede">Error rates fell 40% after the retry fix shipped.</p>
+```
+
+**`.swarm-section`**: a titled block with vertical rhythm.
+
+```html
+<section class="swarm-section"><h2>Findings</h2><p>...</p></section>
+```
+
+**`.swarm-metrics`** and **`.swarm-metric`**: a responsive grid of key numbers. Each metric holds a `.swarm-metric-value` (large, tabular digits) and a `.swarm-metric-label` (muted). Add a `data-tone` (see Tones) to a metric to color its value. Without it, the value uses the foreground color.
+
+```html
+<div class="swarm-metrics">
+  <div class="swarm-metric"><div class="swarm-metric-value">18.6k</div><div class="swarm-metric-label">Clicks</div></div>
+  <div class="swarm-metric" data-tone="error"><div class="swarm-metric-value">7</div><div class="swarm-metric-label">Failed runs</div></div>
+</div>
+```
+
+**`.swarm-panel`** (alias **`.swarm-card`**): a flat surface with a 1px border, the `--radius-xl` radius, and padding. Do not put a panel inside a panel.
+
+```html
+<div class="swarm-panel"><h3>Owner</h3><p>Platform team</p></div>
+```
+
+**`.swarm-badge`**: a soft status pill that never wraps. Set `data-tone` to a tone (see Tones). The default is `neutral`. Add `data-dot` for a leading dot in the tone color. The badge has a 6px gap between the dot and the text, so do not add margins inside a badge.
+
+```html
+<span class="swarm-badge" data-tone="success" data-dot>Healthy</span>
+```
+
+For a category label (a team, a region, a product line), do not use a status tone. Use a neutral badge with a dot, and set the dot color with `--swarm-dot` and a chart token. Give each category its own token, from `--color-chart-1` to `--color-chart-5`.
+
+```html
+<span class="swarm-badge" data-dot style="--swarm-dot: var(--color-chart-1)">Construction</span>
+<span class="swarm-badge" data-dot style="--swarm-dot: var(--color-chart-2)">Interiors</span>
+```
 
-Before creating a page, write a one-line design read for yourself:
+**`.swarm-table-wrap`** and **`.swarm-table`**: a scroll container and a compact table. The table has a sticky header, subtle row rules, and row hover. Add `.num` to number cells: right aligned, tabular, no wrap. Add `.nowrap` to keep any cell on one line.
 
-> Reading this as: `<page kind>` for `<audience>`, using minimalist taste plus `<density needs>`.
+The wrap is already a bordered card surface: the card fill, a 1px border, and the `--radius-xl` radius. Do not put it inside a panel. Its maximum height is `min(70vh, 720px)`. A taller table scrolls inside the wrap, and the header stays in view. To remove the cap, add `max-h-none` to the wrap. Then the page scrolls instead, and the header does not stay in view. Print always removes the cap. When the table is wider than the wrap, a soft shadow shows at each side that hides columns.
+
+```html
+<div class="swarm-table-wrap">
+  <table class="swarm-table">
+    <thead><tr><th>Route</th><th class="num">p95 ms</th></tr></thead>
+    <tbody><tr><td class="nowrap">/api/tasks</td><td class="num">182</td></tr></tbody>
+  </table>
+</div>
+```
+
+**`.swarm-button`**: a button look for `<button>` and `<a>`. Set `data-variant` to `outline` (the default), `primary`, or `ghost`. A plain `<button>` also gets the outline look. For a bare icon button, remove it with utilities: `border-0 bg-transparent p-0`.
+
+```html
+<button class="swarm-button" data-variant="primary" type="button">Rerun checks</button>
+```
+
+**`.swarm-input`**: the look for text inputs and selects. Plain form controls get the same base look.
+
+```html
+<input class="swarm-input" type="search" placeholder="Filter rows" aria-label="Filter rows">
+```
+
+**`.swarm-toolbar`**: a row for search, filters, and actions. It wraps on narrow screens. A text or search input placed directly in the toolbar grows to fill the free space, so do not give it a fixed width.
+
+```html
+<div class="swarm-toolbar">
+  <input class="swarm-input" type="search" placeholder="Filter" aria-label="Filter">
+  <button class="swarm-button" type="button">Reset</button>
+</div>
+```
+
+**`.swarm-segmented`**: a segmented control. Mark the active item with `aria-pressed="true"` or `data-active`.
+
+```html
+<div class="swarm-segmented" role="group" aria-label="Range">
+  <button type="button" aria-pressed="true">Week</button>
+  <button type="button" aria-pressed="false">Month</button>
+</div>
+```
+
+**`.swarm-callout`**: a box for a finding or a note. Set `data-tone` to a tone (see Tones). The default is `info`.
+
+```html
+<div class="swarm-callout" data-tone="warning"><strong>Retry storm.</strong> Three agents retried one task 40 times.</div>
+```
+
+**`.swarm-kv`**: a key and value grid for a `<dl>`. Each `<dt>` is a muted key, and the `<dd>` after it holds the value.
+
+```html
+<dl class="swarm-kv"><dt>Owner</dt><dd>Platform team</dd><dt>Window</dt><dd>7 days</dd></dl>
+```
+
+### Tones
+
+`.swarm-badge`, `.swarm-callout`, and `.swarm-metric` share one set of
+`data-tone` values:
+
+| `data-tone` | Use it for | Color token |
+|---|---|---|
+| `neutral` | Offline, backlog, cancelled, skipped, or not reviewed. The badge default. | `--color-status-neutral` |
+| `primary` | A highlight that is not a state, in the page accent. | `--color-primary` |
+| `success` | Completed, healthy, approved, or passed. | `--color-status-success` |
+| `warning` | Timeouts, threshold warnings, and risks to fix soon. | `--color-status-warning` |
+| `error` | Failed, unhealthy, rejected, or blocked. | `--color-status-error` |
+| `info` | Facts and notes. The callout default. | `--color-status-info` |
+| `pending` | Pending, waiting, or starting. | `--color-status-pending` |
+| `paused` | Paused or in review. | `--color-status-paused` |
+| `active` | Running, busy, or in progress. | `--color-status-active` |
+
+Each status tone uses its token for fills and borders, and its `-strong` token
+for text. `primary` uses `--color-primary` for both. A badge takes its text,
+fill, and border from the tone. A callout takes only its fill and border from
+the tone, so its text keeps the foreground color. A metric colors its value.
+
+The bundled **`examples/report-page.html`** puts these together, with zero
+color literals.
+
+## Theming
+
+The API picks the preset of a designVersion 2 page in this order:
+
+1. The page's `theme`, when it is set.
+2. The viewer's dashboard preset, when the page opens inside the dashboard.
+3. `hive`.
+
+Then the page's `themeTokens` apply on top of the preset. The mode (light or
+dark) always comes from the viewer. `create_page`, `POST /api/pages`, and
+`PUT /api/pages/:id` accept both fields.
+
+### `theme`: a preset id
+
+| Id | Look |
+|---|---|
+| `hive` | The default: a zinc field with one amber accent. |
+| `meadow`, `iris`, `rose` | The Hive field with an emerald, violet, or deep rose accent. |
+| `cobalt` | A cool slate field with a saturated blue accent. |
+| `ember` | A warm stone field with a burnt orange accent. |
+| `carbon` | Pure monochrome. |
+| `paper` | The warm editorial paper look: an off-white canvas, white cards, warm borders, and a blue accent. |
+| `github`, `vscode`, `material`, `solarized`, `tokyo`, `monokai`, `gruvbox`, `catppuccin` | Classic editor and platform palettes, with their own status colors. |
+
+An unknown id fails the write, and the error lists the valid ids. Set `theme`
+only when the page needs a fixed look. Without it, the page matches the
+viewer's dashboard. On an update, `theme: null` clears it. An update or upsert
+that omits `theme` keeps the stored preset.
+
+### `themeTokens`: token overrides
+
+`themeTokens` overrides individual tokens on top of the preset. Tokens that
+you do not set keep their preset values. The input has two formats: a token
+map (the default) and a CSS block (`"format": "css"`). Another `format` fails
+the write.
+
+**Set colors for both modes.** A color that you set only in `light` does not
+reach dark mode. Dark mode keeps the preset's dark value for that token. So
+set each color in both the `light` and the `dark` map, or add a `.dark` block
+in the css format. Fonts and radius have one value for both modes. A font or
+radius token that you set only in `light` applies to dark mode too.
+
+**Send the full map.** A write that sends `themeTokens` replaces the stored
+map. It does not merge with it. A token that you leave out goes back to its
+preset value. An update or upsert that omits `themeTokens` keeps the stored
+map. On an update, `themeTokens: null` clears it.
+
+A token map:
+
+```jsonc
+// Tool call: create_page
+{
+  "title": "Launch review",
+  "contentType": "text/html",
+  "body": "<!doctype html>...",
+  "theme": "paper",
+  "themeTokens": {
+    "light": { "--color-primary": "oklch(0.52 0.15 150)", "--color-ring": "oklch(0.52 0.15 150)", "--radius-xl": "14px" },
+    "dark": { "--color-primary": "oklch(0.72 0.14 150)", "--color-ring": "oklch(0.72 0.14 150)" }
+  }
+}
+```
+
+A CSS block takes the output of shadcn, tweakcn, or a Tailwind v4 `@theme`
+block without changes. A `@theme` block holds light values only, so add a
+`.dark` block for dark mode. Send the block as one string:
+`"themeTokens": { "format": "css", "css": "<the block>" }`. For example, this
+shadcn paste:
+
+```css
+:root {
+  --radius: 0.5rem;
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --sidebar: oklch(0.985 0 0);
+}
+.dark {
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+}
+```
+
+sets the primary colors for both modes and all four radius tokens. `--sidebar`
+is not a page token, so the response lists it in `ignoredTokens`.
+
+The importer rules:
+
+- `--color-primary`, `--primary`, `color-primary`, and `primary` all name the same token. Font and radius names work the same way (`--font-sans`, `font-sans`).
+- In a CSS block, `:root`, `:host`, `html`, `@theme`, and `@theme inline` set the light values. `.dark`, `:root.dark`, `html.dark`, and `[data-theme=dark]` (quoted or not) set the dark values. So does `:root`, `:host`, or `html` inside `@media (prefers-color-scheme: dark)`. A selector list such as `:root, :host` also works.
+- The importer skips comments and blocks under other selectors. The response lists the custom properties of a skipped block in `ignoredTokens` with the block, for example `--ring (in .card)`. A CSS block with no light or dark block fails the write.
+- A shadcn `--radius` sets all four radius tokens. `sm` is the radius minus 4px, `md` is minus 2px, `lg` is the radius, and `xl` is plus 4px.
+- The importer wraps a bare HSL triplet from an older shadcn theme (`222.2 47.4% 11.2%`) as `hsl(222.2 47.4% 11.2%)`.
+- The importer ignores names outside the token contract, such as `--sidebar`, `--shadow-sm`, and `--font-serif`. It does not reject them. The response lists them in `ignoredTokens`.
+- The importer drops a token whose value references a variable outside the contract, such as `--font-sans: var(--font-geist-sans)`. The response lists it in `ignoredTokens` with the variable that it references, for example `--font-sans (references --font-geist-sans)`. Write the value itself instead, for example a font stack.
+- A value has 1 to 200 characters. It must not contain `;`, `{`, `}`, `<`, `>`, `\`, or a line break. It must not contain `url(`, `expression(`, `@import`, or `javascript:`. A bad value fails the write.
+- The API stores the tokens in normalized form.
+
+When you change `--color-primary`, also set `--color-ring`. If the text on the
+new accent needs more contrast, set `--color-primary-foreground` too.
+
+Do not set tokens in your own `:root` rule. The theme's dark rule is more
+specific, so your value reaches light mode only.
+
+To use another font, load it from Google Fonts in your page `<head>`. Then set
+`--font-sans` in `themeTokens`.
+
+## Dark mode
+
+Inside the dashboard, a designVersion 2 page follows the viewer's mode. In dark
+mode, the injected head adds the `dark` class to `<html>`, and the tokens
+switch to their dark values. A page built on tokens needs no extra dark-mode
+code.
+
+- Do not set `color-scheme` yourself. The theme sets it.
+- A `themeTokens` color that you set only in `light` does not reach dark mode. Set it in both maps (see `themeTokens`).
+- Use the `dark:` variant only for a rare mode-specific change, such as a logo pair: `<img class="dark:hidden" ...>` and `<img class="hidden dark:block" ...>`.
+- A direct link (`api_url`) renders in light mode, with the page `theme` or Hive.
+- To check a page in dark mode, add `?__swarm-mode=dark` to its `api_url`. On a page without a `theme`, add `__swarm-theme=<preset id>` to try a preset.
+- Do not use `__swarm-mode` or `__swarm-theme` as your own query parameters.
+
+## Design versions
+
+Each page has a `designVersion`. It is separate from the edit `version`
+counter.
+
+- `1`: the old head, with the Tailwind v3 Play CDN and the `--swarm-*` hex tokens, in light mode only. Pages created before the design system have version 1. They keep their old look and ignore the viewer's theme and mode.
+- `2`: the design system. New pages get version 2 by default.
+
+An upsert or update that omits `designVersion` keeps the stored version. The
+`create_page` result reports the saved `designVersion`. A page created before
+the design system stays on version 1, also when you upsert it with design
+system markup. So pass `designVersion: 2` when you rewrite an old page or
+upsert a recurring report. On a version 2 page, it changes nothing.
+
+To move a version 1 page, rewrite it and pass `designVersion: 2`. Then fix these
+Tailwind v3 to v4 changes:
+
+| v3 class (version 1) | v4 class (version 2) |
+|---|---|
+| `shadow-sm`, `shadow` | `shadow-xs`, `shadow-sm` |
+| `rounded-sm`, `rounded` | `rounded-xs`, `rounded-sm` |
+| `ring` (3px) | `ring-3`. A bare `ring` is now 1px. |
+| `outline-none` | `outline-hidden`. `outline-none` now sets `outline-style: none`. |
+| `bg-opacity-50` and the other `*-opacity-*` classes | Removed. Use an opacity modifier, such as `bg-primary/50`. |
+| `bg-[--my-var]` | `bg-(--my-var)` |
+
+Also check these points:
+
+- A bare `border` draws a `--color-border` line (Tailwind v3 drew gray). For another line, name its token, such as `border-border-subtle`.
+- Remove any Tailwind `<script>` or `tailwind.config` that the page loads itself. The head already loads Tailwind v4.
+- Do not write any `@import` in a `text/tailwindcss` block. `@import "tailwindcss"` enables Preflight again, and the browser also requests every `@import` path as a file next to the page.
+- Replace the color literals with tokens.
 
 ## Universal baseline
 
-The baseline is `taste-minimalist-skill`. Apply it to every page — reports,
-dashboards, tables, audits, public explainers, data-heavy summaries.
+The design system overrides `taste-minimalist-skill`. It replaces every color,
+font, spacing, and motion value in the taste skill. Use the taste skill only
+for restraint in layout and copy.
 
-- Use a warm monochrome canvas (`#FFFFFF`, `#FBFBFA`, `#F7F6F3`) with charcoal text and scarce muted accents.
-- Build a clear type hierarchy with premium/system typography; use monospace for code, metadata, and `<kbd>`.
-- Use macro-whitespace and strong alignment. Give summaries room to breathe and keep tables compact enough to scan.
-- Prefer flat surfaces: crisp `1px` borders, `8px` or `12px` radii, and practically no shadows.
-- Use restrained motion only where it clarifies hierarchy or interaction state.
+- Keep the canvas quiet. Let the theme supply the field and the text colors, and use the accent sparingly.
+- Build a clear type hierarchy with the built-in heading scale. Use `font-mono` for IDs, metadata, and machine output. The head already styles `<code>`, `<pre>`, and `<kbd>`.
+- Use whitespace and strong alignment. Give summaries room to breathe and keep tables compact enough to scan.
+- Prefer flat surfaces: crisp `1px` borders and practically no shadows.
+- Use motion only where it clarifies hierarchy or interaction state. Do not animate content blocks on scroll.
 - Keep visual language quiet and precise: no AI-purple gradient mesh, centered hero plus three equal cards, decorative glassmorphism, emojis as UI decoration, fake screenshots made from rectangles, oversized decorative art, nested cards, or low-contrast text.
 - Make responsive behavior explicit: readable type, stable grids, horizontal table scroll where needed, and no overlapping content.
 
-If the full minimalist source is available, use `taste-minimalist-skill` for the
-deeper primitives: bento grids, status badges, `<kbd>` keys, flat tables, code
-blocks, and the detailed anti-slop checks.
+When the full `taste-minimalist-skill` source is available, take only its
+restraint rules: the banned elements, and plain, specific copy with realistic
+names and no AI clichés. Ignore its hex colors, font stacks, `py-24` and
+`py-32` section padding, scroll animations, background gradients, fake window
+chrome, and uppercase badges. The tokens, the element defaults, and the
+`swarm-*` primitives replace them.
 
 ## Report density layer
 
@@ -113,16 +536,14 @@ information-architecture layer, not a separate aesthetic.
 Every dense page should be useful at a glance.
 
 - Put the page's point in the first viewport: title, one-sentence summary, and 3-6 key numbers or statuses.
-- Use a single-column reading spine with `max-width: 1120px`; keep prose measure around 65-75 characters and reserve denser grids for metrics/evidence.
-- Use premium/system typography unless there is a clear brand reason not to: `"SF Pro Display", "Geist Sans", "Helvetica Neue", ui-sans-serif, system-ui, sans-serif`.
-- Use the minimalist palette: warm off-white background, charcoal text, white or near-white panels, light borders, one scarce accent, and semantic colors for statuses only.
-- Use a consistent spacing scale: `8, 12, 16, 24, 32, 48, 72`.
-- Use clear type hierarchy: page title 36-48px desktop / 30-36px mobile, section titles 22-28px, body 15-16px, supporting text 13-14px.
-- Keep tables readable: sticky/scannable headers where useful, padded cells, zebra-free or very subtle row borders, `tabular-nums` for numbers, horizontal scroll on narrow screens.
-- Prefer flat bordered cards only for repeated records or metrics. Do not nest cards inside cards.
-- Use shadows only when they solve a hierarchy problem; keep them ultra-diffuse and below `0.05` opacity.
+- Use a single-column reading spine (`.swarm-page`, 1120px wide). Keep prose near 65-75 characters, and use denser grids only for metrics and evidence.
+- For your own gaps and margins, use the steps that the primitives use most: 4, 8, 12, 16, 24, and 40px. In Tailwind units, that is `1`, `2`, `3`, `4`, `6`, and `10` (for example, `gap-4` is 16px).
+- Keep the built-in type scale (`h1` about 30px, body 15px). Do not inflate titles to hero sizes.
+- Keep tables readable: `.swarm-table` gives a sticky header, padded cells, subtle row rules, and tabular numbers. Put it in a `.swarm-table-wrap` so it scrolls on narrow screens.
+- Prefer flat bordered panels only for repeated records or metrics. Do not nest panels inside panels. A `.swarm-table-wrap` is already a panel.
+- Use a shadow only when it solves a hierarchy problem, and keep it barely visible (`shadow-xs`).
 - Hide raw JSON behind a collapsed `<details>` block at the bottom.
-- Make mobile explicit with media queries: single-column grids, reduced padding, no overflow except intentional table scroll.
+- Mobile is built in. At 640px wide and below, the body padding drops to 16px. The metric grid and the toolbar wrap, and a toolbar search input grows to fill its row. Add responsive variants only for your own grids, such as `grid-cols-1 md:grid-cols-2`. Allow no overflow except table scroll.
 
 ## Content structure
 
@@ -150,9 +571,9 @@ Before publishing:
 - Raw JSON/logs are collapsed or linked, not the primary experience.
 - No nested cards, decorative gradients, oversized art, or cramped default browser styles.
 - No text overlaps, clipped buttons, or unreadable low-contrast text.
-
-Pages inject a default body theme. For a custom palette, set `body` background, color, font, and padding explicitly in your stylesheet.
-Setting these properties only on `:root` does not replace the injected body styles.
+- No color literals. Every color comes from a token, in CSS or as a Tailwind class.
+- The page reads well in light and dark mode. Add `?__swarm-mode=dark` to the `api_url` to check.
+- The `create_page` result shows `designVersion: 2`. If it shows 1, publish again with `designVersion: 2`.
 
 ---
 
@@ -180,7 +601,7 @@ To check a page by screenshot, open it from an origin its data endpoints allow.
 | URL | Shape | Notes |
 |---|---|---|
 | `app_url` | `${APP_URL}/pages/:id` | SPA route. Renders HTML in a sandboxed iframe, JSON via `@json-render/react`. Default share target. |
-| `app_url` (full mode) | `${APP_URL}/pages/:id?mode=full` | Same SPA route, maximized — hides the SPA sidebar/header so the page body gets the full viewport. Slim header with title + Exit-Full button. Useful for embeds + standalone dashboards. |
+| `app_url` (full mode) | `${APP_URL}/pages/:id?mode=full` | Same SPA route, maximized: hides the SPA sidebar/header so the page body gets the full viewport. Slim header with title + Exit-Full button. Useful for embeds + standalone dashboards. |
 | `api_url` | `${MCP_BASE_URL}/p/:id` | Direct API render. HTML inlines and serves; JSON 302-redirects to `app_url`. Useful for no-SPA-required links. |
 
 `${APP_URL}` is the deployment's SPA origin and `${MCP_BASE_URL}` is its API
@@ -199,14 +620,14 @@ where the unfurl preview only follows the API origin).
 Every overwrite (update via `update_page` or `PUT /api/pages/:id`) snapshots
 the **pre-update** state into `page_versions` and writes the new state to the
 parent row. The wire `version` field is a monotonically-increasing
-"edit counter" — version 1 is the initial create.
+"edit counter": version 1 is the initial create.
 
 | Operation | Endpoint | Returns |
 |---|---|---|
 | List versions | `GET /api/pages/:id/versions` | `{ versions: PageVersion[] }` newest first |
 | Read a version | `GET /api/pages/:id/versions/:version` | Single snapshot |
 
-Snapshots are full body copies — keep this in mind for large pages (the
+Snapshots are full body copies. Keep this in mind for large pages (the
 per-version body cap is 5 MiB).
 
 ## Browser SDK
@@ -214,8 +635,8 @@ per-version body cap is 5 MiB).
 Every HTML page automatically gets `window.SwarmSDK` (the class) and
 `window.swarmSdk` (a ready-to-use singleton) injected. The SDK routes through
 the `/@swarm/api/*` proxy, which resolves the page's own `page_session_<id>`
-cookie to a user identity and forwards with proper auth headers server-side —
-your page never sees or handles tokens. The SDK names its page in the
+cookie to a user identity and forwards with proper auth headers server-side.
+Your page never sees or handles tokens. The SDK names its page in the
 `X-Swarm-Page-Id` header. A direct `fetch('/@swarm/api/...')` from the page
 works too: the proxy falls back to the `/p/<id>` Referer.
 
@@ -239,7 +660,7 @@ Inline usage:
 
 ```html
 <script>
-  // Singleton is ready immediately — no `new SwarmSDK()` needed.
+  // Singleton is ready immediately: no `new SwarmSDK()` needed.
   const tasks = await window.swarmSdk.tasks.list({ status: 'in_progress' });
   const agents = await window.swarmSdk.agents.list();
 
@@ -263,7 +684,7 @@ HTTP status.
 
 ### Full signature
 
-This is the entire surface — copy it into your page if you want autocomplete
+This is the entire surface. Copy it into your page if you want autocomplete
 hints in an editor. The runtime version is auto-injected; you don't need to
 include this in the page source.
 
@@ -323,21 +744,25 @@ class SwarmSDK {
 
 For the full list of fields each endpoint accepts/returns, see
 [**docs.agent-swarm.dev/docs/api-reference**](https://docs.agent-swarm.dev/docs/api-reference).
-The SDK is a thin domain wrapper — anything documented there is reachable.
+The SDK is a thin domain wrapper: anything documented there is reachable.
 
-## Built-in primitives
+## Built-in web components
 
-Every HTML page automatically gets a small set of zero-dep web components
-auto-injected alongside the Browser SDK. Drop them into your page body —
-no `<script>` import, no bundling, no Tailwind required (though Tailwind
-Play CDN is loaded, so utility classes work too).
+Every HTML page automatically gets a small set of zero-dep web components,
+injected beside the Browser SDK. Put them in your page body. They need no
+`<script>` import, no bundling, and no Tailwind. Tailwind utilities also work:
+Tailwind v4 on designVersion 2 pages, and the Tailwind v3 Play CDN on
+designVersion 1 pages. For the `swarm-*` CSS classes, see Primitives under
+Design system.
 
-### `<swarm-diff>` — unified diff renderer
+### `<swarm-diff>`: unified diff renderer
 
 Render a unified diff with a two-column gutter, severity annotations, and a
 deterministic anchor id per hunk (so deep-linking + jump lists work). The
 element reads its payload from its `textContent` as JSON of shape
 `{ hunks: [{ old_start, old_lines, new_start, new_lines, lines, annotations? }] }`.
+On designVersion 2 pages, its colors and fonts follow the theme tokens and dark
+mode.
 
 ```html
 <swarm-diff
@@ -345,21 +770,25 @@ element reads its payload from its `textContent` as JSON of shape
   base-sha="abc123"
   head-sha="def456">
 { "hunks": [
-    { "old_start": 10, "old_lines": 3, "new_start": 10, "new_lines": 4,
+    { "old_start": 10, "old_lines": 2, "new_start": 10, "new_lines": 3,
       "lines": [
-        { "type": "context", "text": "  const x = 1;" },
-        { "type": "del",     "text": "- console.log(x);" },
-        { "type": "add",     "text": "+ logger.info({ x });" },
-        { "type": "add",     "text": "+ return x;" }
+        { "type": "context", "text": "export function load(id) {" },
+        { "type": "del",     "text": "  console.log(id);" },
+        { "type": "add",     "text": "  logger.info({ id });" },
+        { "type": "add",     "text": "  return cache.get(id);" }
       ],
       "annotations": [
-        { "line": 12, "severity": "warn", "text": "Avoid raw console.log" }
+        { "line": 12, "severity": "warn", "text": "Returns undefined on a cache miss" }
       ]
     }
 ] }
 </swarm-diff>
 ```
 
+The browser reads the JSON as HTML text first. Inside the JSON, write `<` as
+`\u003c` and `&` as `\u0026`. Otherwise the browser turns
+`Promise<void>` into a tag, and `&amp;` into `&`.
+
 **Inputs**
 
 | Attribute | Required | Notes |
@@ -368,28 +797,47 @@ element reads its payload from its `textContent` as JSON of shape
 | `base-sha` | no | Pre-change SHA. Rendered in the header next to `head-sha`. |
 | `head-sha` | no | Post-change SHA. |
 
+**Hunk shape**
+
+| Field | Notes |
+|---|---|
+| `old_start`, `new_start` | The first line number on the old side and on the new side. |
+| `old_lines` | The number of context and deleted lines in the hunk. |
+| `new_lines` | The number of context and added lines in the hunk. |
+
+The hunk header shows `@@ -old_start,old_lines +new_start,new_lines @@`. The
+component prints the counts that you send. It does not check them.
+
 **Line shape**
 
 | Field | Values | Notes |
 |---|---|---|
 | `type` | `context` \| `add` \| `del` | Drives row tint (green / red / neutral) and gutter line numbering. |
-| `text` | string | Rendered verbatim (HTML-escaped). |
+| `text` | string | The line without its `+`, `-`, or space marker. The component draws the marker in its own column. Keep the indentation. The text is HTML-escaped. |
 
-**Annotation shape** — attaches to a NEW-side line by line number; rendered
-as a margin badge on that row.
+**Annotation shape**: a margin badge on one row.
 
 | Field | Values | Notes |
 |---|---|---|
-| `line` | integer | New-side line number (falls back to old-side if no add for that line). |
+| `line` | integer | The new-side line number of an added or context row. For a deleted row, use its old-side number. If a deleted row and another row have that number, the badge shows on both. |
 | `severity` | `error` \| `warn` \| `info` | Drives badge color. |
 | `text` | string | Badge body. |
 
 **Anchor id**
 
-Each hunk gets `id="swarm-diff-<file-slug>-<old_start>"` for deep-linking.
-Use `<swarm-diff-jumps></swarm-diff-jumps>` anywhere in the page body to
-render a tiny "Jump to" navigation of every diff hunk on the page —
-handy when an agent ships a multi-file annotated PR.
+Each hunk gets an anchor with `id="swarm-diff-<slug>"`. The slug is
+`<file>-<old_start>` in lowercase. Each run of characters other than `a-z` and
+`0-9` becomes one `-`, and a `-` at the start or end is removed. For example,
+`file="src/foo.ts"` with `old_start: 10` gives `id="swarm-diff-src-foo-ts-10"`.
+Without `file`, the slug starts with `hunk`. When `old_start` is 0 or missing,
+the slug ends with the hunk's position (1 for the first hunk). Two hunks with
+the same file and `old_start` get the same id, so keep them unique.
+
+Link to a hunk with `href="#swarm-diff-src-foo-ts-10"`. On a designVersion 1
+page, add `target="_self"` to the link, or it opens in a new tab. Use
+`<swarm-diff-jumps></swarm-diff-jumps>` anywhere in the page body to render a
+tiny "Jump to" navigation of every diff hunk on the page. It is handy when an
+agent ships a multi-file annotated PR.
 
 **Programmatic form**
 
@@ -409,21 +857,26 @@ A full annotated-PR page using `<swarm-diff>` is bundled at
 
 ## Print / PDF export
 
-Every HTML page also gets a `@media print` rule baked into the head defaults:
-- Light theme on print (white background, black text, underlined black links).
-- Anything with the `.no-print` class is hidden (annotation badges and the
-  jump list already carry this class — use it on agent-emitted chrome you
-  want suppressed in PDF exports).
-- `.swarm-card` and `<swarm-diff>` get `break-inside: avoid` so they don't
-  split mid-element across pages.
-
-Trigger the export from the SPA's "Export PDF" button on `/pages/:id` — it
+Every HTML page also gets `@media print` rules in its injected head. Print is
+always light:
+- A designVersion 2 page prints with its light tokens, also when the viewer
+  runs dark mode.
+- The page prints on a white background, with black text and underlined
+  links.
+- Anything with the `.no-print` class is hidden. Annotation badges and the
+  jump list already carry this class. Add it to page chrome that you want out
+  of the PDF.
+- `.swarm-panel`, `.swarm-card`, `.swarm-metric`, and `<swarm-diff>` get
+  `break-inside: avoid`, so they do not split across pages. (On designVersion
+  1 pages, only `.swarm-card` and `<swarm-diff>` get it.)
+
+Trigger the export from the SPA's "Export PDF" button on `/pages/:id`. It
 opens the iframe's native print dialog (HTML pages) or the SPA's print
-dialog (JSON pages). The browser's "Print → Save as PDF" handles the actual
-file. No headless Chromium, no server-side rendering — zero infra weight.
+dialog (JSON pages). The browser's "Print → Save as PDF" makes the actual
+file. No headless Chromium, no server-side rendering, zero infra weight.
 
-> Want a custom print layout? Override the print styles in your page's own
-> `<style>` block — agent CSS always wins over the head defaults.
+> Want a custom print layout? Add `@media print` rules to your page's own
+> `<style>` block.
 
 ## Viewer feedback
 
@@ -458,7 +911,7 @@ redirecting to the SPA), `401`/`403` (auth gate), and `404` do NOT bump.
 The count is exposed on `GET /api/pages` listing (`viewCount` field) and the
 SPA `/pages` index renders it as a small eye-count badge per row.
 
-No per-viewer dedup — this is a coarse popularity signal, not analytics.
+No per-viewer dedup: this is a coarse popularity signal, not analytics.
 Bumps are best-effort (wrapped in try/catch so a counter write never fails
 the response).
 
@@ -499,7 +952,7 @@ See the `@json-render/core` docs for the supported node types (`text`,
   `passwordHash`) and the page's own KV. Every other route returns 403, and every RBAC verb denies a guest.
 - Browser SDK memory operations use the page owner's agent scope through verified page execution context.
   Viewer authentication, permissions, and audit identity remain separate from this resource scope.
-- Treat agent-generated HTML / JSON like trusted code — the agent already
+- Treat agent-generated HTML / JSON like trusted code: the agent already
   has equivalent MCP access, so a malicious page is no worse than a
   malicious tool call. But: don't ship pages to **external** users (via
   `password`) without reviewing the body first.
@@ -509,14 +962,14 @@ See the `@json-render/core` docs for the supported node types (`text`,
   page still has the SwarmSDK access of its session: full for user and
   operator sessions, page record and KV only for password guests.
 - All page bodies pass through `scrubSecrets` at the egress boundary
-  (`/p/:id`, `/p/:id.json`, listing endpoint) — accidental secrets in
+  (`/p/:id`, `/p/:id.json`, listing endpoint). Accidental secrets in
   the body get masked at serve time, not at write time. Don't rely on
-  scrubbing as a security boundary — keep secrets out of bodies.
+  scrubbing as a security boundary. Keep secrets out of bodies.
 
 ## Limits
 
 - **Body size**: 5 MiB per version (HTML or JSON). Bumping requires careful
-  thought about SQLite write-amplification — full bodies are snapshotted on
+  thought about SQLite write-amplification: full bodies are snapshotted on
   every update.
 - **TTL**: none. Pages persist until explicitly deleted via `DELETE
   /api/pages/:id` (or the SPA listing UI when it gains a delete affordance).
@@ -538,11 +991,11 @@ human-facing summary.
 
 ## See Also
 
-- The **`apps`** skill — schema-backed records, named queries, and actions.
-- The **`agent-fs`** skill — durable file storage and share links.
-- The **`kv-storage`** skill — page-scoped state via `swarmSdk.kv`.
-- `runbooks/secret-scrubbing.md` — egress scrubbing details.
-- SPA listing: `${APP_URL}/pages` — the same `APP_URL` used for share links above.
+- The **`apps`** skill: schema-backed records, named queries, and actions.
+- The **`agent-fs`** skill: durable file storage and share links.
+- The **`kv-storage`** skill: page-scoped state via `swarmSdk.kv`.
+- `runbooks/secret-scrubbing.md`: egress scrubbing details.
+- SPA listing: `${APP_URL}/pages`, the same `APP_URL` used for share links above.
   Prefer the `app_url` that `create_page` returns; build URLs by hand only when
   you have no page id.
 
@@ -609,7 +1062,7 @@ Array insertion takes `path`, `index`, and `values`. Text editing takes `path`,
 Presence updates default to one transmission per 50 milliseconds. Presence never enters the persisted document.
 Use `await room.close()` when the page no longer needs a room.
 
-### `<swarm-cursors>` — shared page pointers
+### `<swarm-cursors>`: shared page pointers
 
 Add this element to opt a page into named cursors for an existing room: