Build a theme with an agent

A theme in Spillway is a kit of tokens, blocks (shared blocks and page templates built from the core blocks) and page templates, with screenshots, published to the registry with "kind": "theme". Themes do not ship code: the look comes from the theme tokens the server emits as CSS custom properties, the custom tokens a stylesheet may use, and the way pages are composed. Read theming.md and kits.md first.

The prompt

Paste into the agent in a checkout of the Spillway repository, brackets filled:

Build a Spillway CMS theme named "[name]" for [who it is for: e.g. a small-town newspaper] as a kit at
packages/kits/[dir]/kit.json with "kind": "theme", following docs/theming.md and docs/kits.md.
Model the manifest on packages/kits/higher-ed/kit.json.

Design: [palette: one brand color, text and background colors, an accent; type: body and heading
font stacks (system fonts unless a free webfont is named); radius; max width]. Restrained, readable,
WCAG AA contrast for text on every background.

Requirements:
- theme.json next to kit.json: a W3C design tokens (DTCG) file that Brand → Import brand (Design tokens) maps
  onto colorPrimary, colorText, colorBackground, fontBody, fontHeading, radius and maxWidth, plus
  custom tokens (named color-*, space-*, …) for anything else; no token the pages do not use.
- Page templates as kit pages: Home (home: true), an article/listing page, a contact page, a
  campaign landing page, each composed from core blocks (Hero, Cards, Columns, Text, Image,
  Collection, Form, CallToAction) with unique props.id, real-sounding placeholder copy and no lorem
  ipsum. Image blocks use small inline SVG placeholders from the kit's media list ($media:<key>:url).
- Two or three shared blocks (a promo band, a contact card) as sample content of the built-in
  shared-block library, if the server version exposes them to kits; otherwise as page sections.
- screenshots/: one PNG per template page at 1280 px wide, captured from a local install
  (node e2e helpers or Playwright), listed in the manifest's "screenshots" array.
- README.md: who it is for, the palette and fonts, what each template is for, how to install
  (kit install, then import theme.json under Brand → Import brand, apply to the draft and publish).
- Keep every page server-safe: no scripts, no external stylesheets; the only CSS is custom tokens.

Install it on a fresh site (spillway kit install [key] --sample, then import theme.json), check every
template page renders at 360 px and 1280 px without horizontal scroll, and run
pnpm --filter @spillway-cms/core exec vitest run kits. Report what you built. Do not publish.

What to check

1. Contrast and readability. Body text on the background and button text on the primary color meet WCAG AA (4.5:1). Check with any contrast tool; the agent's claim is not enough.
2. The tokens import. Brand → Import brand → Design tokens with theme.json: every named token maps, the custom tokens appear, no notes you do not understand; apply to the draft and publish. GET /api/theme/tokens.css shows them.
3. The templates render at phone and desktop width, with the site's real menus, and look like the screenshots.
4. Nothing executable. The kit holds JSON and images only; Text blocks in HTML mode contain markup the sanitizer keeps.
5. Install twice. The second install reports nothing created, so the theme can be re-applied without duplicating pages.
6. Screenshots are honest: taken from the installed theme on this Spillway version, not mock-ups.

Publish with publish.md: themes go live after the automated checks and appear in the theme directory, where the fleet renders a preview site per theme on demand.

Spillway 0.1.0 · Edit this page on GitHub