create-avocado-site 0.19.0 → 0.21.0

package/assets/logos/avocado-hub.svg

@@ -1,10 +1,24 @@
 <svg width="128" height="128" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
   <title id="title">The Avocado Hub logo</title>
-  <desc id="desc">Stylized avocado mark — brand green shell, warm cream flesh, muted brown stone.</desc>
-  <!-- One green, and it is the brand's. The mark previously used #1F7A3A over
-       #7ED957: two greens, neither of them the #0f766e on every button, and the
-       lime saturated well past anything else on the page. -->
-  <path d="M64 8C88 8 112 40 112 72C112 104 88 120 64 120C40 120 16 104 16 72C16 40 40 8 64 8Z" fill="#0f766e"/>
-  <path d="M64 18C82 18 100 44 100 72C100 100 82 110 64 110C46 110 28 100 28 72C28 44 46 18 64 18Z" fill="#e9e4d4"/>
-  <circle cx="64" cy="72" r="20" fill="#8a6a4f"/>
+  <desc id="desc">Avocado cross-section — near-black skin, chartreuse flesh, near-black stone.</desc>
+  <!--
+    The original silhouette, recoloured. Transparent ground, and the same two
+    fills on either page ground.
+
+    The mark is loaded through an img element, so it sits outside the page's
+    cascade: it cannot resolve a custom property and cannot see the dark class
+    on the html element. One colouring therefore has to hold on #12170F and on
+    #F2F3EA, and chartreuse alone does not — roughly 11:1 against the dark
+    ground and 1.3:1 against the light one, so a chartreuse silhouette that
+    reads as a mark in dark reads as a smudge in light.
+
+    Green in the flesh and near-black in the skin solves it with no theme
+    logic. On the dark ground the skin is the ground, so what you see is the
+    chartreuse flesh with the stone punched out of it. On the light ground the
+    same skin becomes a heavy outline with the flesh inside. Two renderings,
+    one file, nothing conditional.
+  -->
+  <path d="M64 8C88 8 112 40 112 72C112 104 88 120 64 120C40 120 16 104 16 72C16 40 40 8 64 8Z" fill="#12170F"/>
+  <path d="M64 18C82 18 100 44 100 72C100 100 82 110 64 110C46 110 28 100 28 72C28 44 46 18 64 18Z" fill="#C5E035"/>
+  <circle cx="64" cy="72" r="20" fill="#12170F"/>
 </svg>

package/dist/templates/demo-app.js

@@ -1,5 +1,35 @@
+import { fileURLToPath } from "node:url";
 import { AVOCADO, NEXT, REACT, TYPESCRIPT, TYPES_NODE, TYPES_REACT, TYPES_REACT_DOM } from "../versions.js";
 import { DEMO_SITE_CONFIG_JSON } from "./demo-content.js";
+/*
+ * The theme, as a file on disk rather than a template literal.
+ *
+ * It is 300 lines of token values with no interpolation in it, and it has to
+ * stay identical to the one `apps/site` wears or the scaffold drifts into a
+ * near-miss of the demo. `scripts/sync-demo-seed.mjs` writes it here from
+ * `apps/site/app/theme-night-harvest.css`; like the demo assets beside it,
+ * this file is generated and must not be edited in place.
+ *
+ * Resolved relative to the package root — two levels up from both
+ * `src/templates` and `dist/templates`.
+ */
+const THEME_FILE = fileURLToPath(new URL("../../theme/night-harvest.css", import.meta.url));
+/*
+ * The theme control, on the same terms.
+ *
+ * `layout.tsx` below has always carried a pre-paint script that reads
+ * `site-theme-v1` out of localStorage — and until these two files were added,
+ * nothing in a scaffolded project ever wrote that key. Half a feature: the
+ * page followed the OS and offered no way to say otherwise, while the demo it
+ * is a copy of has a control in the header and another under the footer.
+ *
+ * Both are generated by `scripts/sync-demo-seed.mjs` from `apps/site`, so the
+ * scaffold's control is the demo's control rather than a re-creation of it.
+ * Do not edit them here.
+ */
+const CONTROL_FILE = fileURLToPath(new URL("../../theme/theme-toggle.tsx", import.meta.url));
+const CONTROL_CSS_FILE = fileURLToPath(new URL("../../theme/theme-toggle.css", import.meta.url));
+const CHROME_CSS_FILE = fileURLToPath(new URL("../../theme/site-chrome.css", import.meta.url));
 /**
  * The name the scaffolded site renders in its own header. Read from the seed
  * rather than restated, so it cannot drift from what the preview shows — the
@@ -404,9 +434,18 @@ if (siteUp) open(OPEN_URL)
  * Without \`@avocadostudio-ai/blocks/styles.css\` every block renders correct,
  * complete, unstyled HTML — which does not read as "a stylesheet is missing",
  * it reads as "this product produces ugly pages".
+ *
+ * `./theme.css` comes second, because a theme is a set of values for the
+ * tokens that stylesheet declares and the later declaration wins. It is the
+ * same file `apps/site` wears, copied in by `scripts/sync-demo-seed.mjs`, so
+ * a scaffold looks like the demo everyone was shown rather than like the
+ * package defaults underneath it.
  */
 function globalsCss() {
     return `@import "@avocadostudio-ai/blocks/styles.css";
+@import "./theme.css";
+@import "./theme-toggle.css";
+@import "./site-chrome.css";
 
 :root {
   color-scheme: light dark;
@@ -416,33 +455,257 @@ function globalsCss() {
   box-sizing: border-box;
 }
 
+/*
+ * The base rules are the demo site's, token by token.
+ *
+ * This used to hardcode \`ui-sans-serif, system-ui, …\` here, after the theme
+ * import — so the theme shipped Archivo, declared it as \`--font-body\`, loaded
+ * it through \`next/font\`, and then this rule won. Headings came out in Anton
+ * and every other word on the page in the system sans, which is close enough
+ * to right that nobody reads it as a bug.
+ */
 html,
 body {
   margin: 0;
   padding: 0;
+  font-family: var(--font-body);
+  font-size: 16px;
+  line-height: 1.5;
+  background: var(--bg-0);
+  color: var(--text-100);
+  -webkit-font-smoothing: antialiased;
 }
 
-body {
-  font-family:
-    ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-  -webkit-font-smoothing: antialiased;
+/*
+ * The reset the demo site gets from Tailwind, restated without Tailwind.
+ *
+ * \`apps/site\` imports \`tailwindcss\`, whose preflight zeroes every margin and
+ * padding, sizes headings from their block rather than the UA, makes images
+ * block-level and lets buttons inherit the page's font. This project has no
+ * Tailwind, and every one of those showed up as a difference against the demo
+ * it was meant to reproduce: footer headings at the UA's 1.5em with a 0.83em
+ * margin under them, carousel arrows squeezed by the UA's \`1px 6px\` button
+ * padding, a slide 61px taller than its picture.
+ *
+ * It sits in \`@layer base\` for the same reason Tailwind's does: a layered rule
+ * loses to every unlayered one whatever its specificity, so a block stylesheet
+ * or a rule further down this file always wins over it — which is the cascade
+ * the demo renders with.
+ */
+@layer base {
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+    border: 0 solid;
+  }
+
+  html {
+    line-height: 1.5;
+    -webkit-text-size-adjust: 100%;
+    tab-size: 4;
+    -webkit-tap-highlight-color: transparent;
+  }
+
+  hr {
+    height: 0;
+    color: inherit;
+    border-top-width: 1px;
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    font-size: inherit;
+    font-weight: inherit;
+  }
+
+  a {
+    color: inherit;
+    text-decoration: inherit;
+  }
+
+  b,
+  strong {
+    font-weight: bolder;
+  }
+
+  code,
+  kbd,
+  samp,
+  pre {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+    font-size: 1em;
+  }
+
+  small {
+    font-size: 80%;
+  }
+
+  table {
+    text-indent: 0;
+    border-color: inherit;
+    border-collapse: collapse;
+  }
+
+  ol,
+  ul,
+  menu {
+    list-style: none;
+  }
+
+  img,
+  svg,
+  video,
+  canvas,
+  audio,
+  iframe,
+  embed,
+  object {
+    display: block;
+    vertical-align: middle;
+  }
+
+  img,
+  video {
+    max-width: 100%;
+    height: auto;
+  }
+
+  button,
+  input,
+  select,
+  optgroup,
+  textarea,
+  ::file-selector-button {
+    font: inherit;
+    font-feature-settings: inherit;
+    font-variation-settings: inherit;
+    letter-spacing: inherit;
+    color: inherit;
+    border-radius: 0;
+    background-color: transparent;
+    opacity: 1;
+  }
+
+  ::placeholder {
+    opacity: 1;
+  }
+
+  textarea {
+    resize: vertical;
+  }
+
+  button,
+  input:where([type="button"], [type="reset"], [type="submit"]),
+  ::file-selector-button {
+    appearance: button;
+  }
+
+  [hidden]:where(:not([hidden="until-found"])) {
+    display: none !important;
+  }
+}
+
+h1,
+h2,
+h3 {
+  font-family: var(--font-heading);
+}
+
+h1,
+h2,
+h3,
+p {
+  margin-top: 0;
+}
+
+ul {
+  padding-left: 18px;
+  margin: 0;
+}
+
+a {
+  color: var(--link);
+}
+
+main {
+  width: 100%;
+  margin: 0;
+  padding: 0;
 }
 `;
 }
 function layout(config) {
     return `import type { ReactNode } from "react"
+import { Anton, Archivo } from "next/font/google"
+import { SiteThemeToggle } from "./theme-toggle"
 import "./globals.css"
 
 /*
- * Deliberately minimal. Every page's own <title> and description come from
- * \`generateMetadata\` in app/[[...slug]]/page.tsx, which derives them from the
- * page content — a title set here would be inherited by all nine pages and
+ * The theme's two faces, self-hosted by \`next/font\` with a metric-matched
+ * local fallback so the page does not reflow as they land. \`theme.css\` points
+ * \`--font-display\` and \`--font-body\` at these variables; without them the
+ * whole thing falls back to system sans and reads like a different design.
+ *
+ * Anton has one cut, so asking it for a bold gets a synthesised one — the
+ * display weight token stays at 400.
+ */
+const anton = Anton({ weight: "400", subsets: ["latin"], display: "swap", variable: "--font-anton" })
+const archivo = Archivo({ weight: ["400", "500"], subsets: ["latin"], display: "swap", variable: "--font-archivo" })
+
+/*
+ * Runs before first paint so the theme never flashes.
+ *
+ * The query is \`prefers-color-scheme: light\`, not \`: dark\`: this is a dark
+ * theme with a light half, so dark is the fallback and light is the opt-in. A
+ * stored value is a pin; no stored value follows the system.
+ */
+const themeScript = \`(function(){try{var t=localStorage.getItem('site-theme-v1');var d=t==='dark'||(t!=='light'&&!matchMedia('(prefers-color-scheme:light)').matches);if(d)document.documentElement.classList.add('dark')}catch(e){document.documentElement.classList.add('dark')}})()\`
+
+/*
+ * Otherwise deliberately minimal. Every page's own <title> and description come
+ * from \`generateMetadata\` in app/[[...slug]]/page.tsx, which derives them from
+ * the page content — a title set here would be inherited by all nine pages and
  * override none of them.
  */
 export default function RootLayout({ children }: { children: ReactNode }) {
   return (
-    <html lang="en">
-      <body>{children}</body>
+    <html
+      lang="en"
+      suppressHydrationWarning
+      className={\`theme-night-harvest \${anton.variable} \${archivo.variable}\`}
+      style={{ background: "var(--bg-0, #12170f)" }}
+    >
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeScript }} />
+      </head>
+      <body style={{ background: "var(--bg-0, #12170f)" }}>
+        {children}
+        {/*
+          Two controls, one state — see the note in \`theme-toggle.tsx\`.
+
+          The header copy is portalled into the nav the SiteHeader block
+          renders, because that markup belongs to the blocks package rather
+          than to this app; as a real child of that flex row it inherits the
+          sticky positioning instead of guessing at the header's height.
+
+          The footer copy needs no portal. \`children\` is the whole page
+          including the footer, so a sibling after it lands exactly where the
+          demo puts it: on the footer's own ground, below the last link.
+        */}
+        <SiteThemeToggle portalTo=".site-top-nav-inner" />
+        <div className="site-theme-bar">
+          <SiteThemeToggle />
+        </div>
+      </body>
     </html>
   )
 }
@@ -619,6 +882,10 @@ export function demoAppTemplates(config) {
         { path: "scripts/dev.mjs", content: devScript(config) },
         { path: "app/layout.tsx", content: layout(config) },
         { path: "app/globals.css", content: globalsCss() },
+        { path: "app/theme.css", source: THEME_FILE },
+        { path: "app/theme-toggle.tsx", source: CONTROL_FILE },
+        { path: "app/theme-toggle.css", source: CONTROL_CSS_FILE },
+        { path: "app/site-chrome.css", source: CHROME_CSS_FILE },
         { path: "app/api/avocado/[[...path]]/route.ts", content: orchestratorRoute(config) },
     ];
 }

package/dist/versions.d.ts

@@ -17,7 +17,7 @@
  * `@avocadostudio-ai/orchestrator-core`, already pinned there; naming it again
  * here is how a project ends up with two.
  */
-export declare const AVOCADO = "0.19.0";
+export declare const AVOCADO = "0.21.0";
 /**
  * Next 15.5.25 rather than 16, because that is the version every example app
  * and the demo site in this repository build and test against. The SDK

package/dist/versions.js

@@ -17,7 +17,7 @@
  * `@avocadostudio-ai/orchestrator-core`, already pinned there; naming it again
  * here is how a project ends up with two.
  */
-export const AVOCADO = "0.19.0";
+export const AVOCADO = "0.21.0";
 /**
  * Next 15.5.25 rather than 16, because that is the version every example app
  * and the demo site in this repository build and test against. The SDK

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-avocado-site",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Bootstrap a runnable Avocado Studio demo site, or wire Avocado into an existing Next.js project",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "dist",
     "assets",
+    "theme",
     "README.md",
     "LICENSE"
   ],
@@ -29,14 +30,14 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.9.1",
-    "@avocadostudio-ai/skills": "^0.19.0"
+    "@avocadostudio-ai/skills": "^0.21.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",
     "tsx": "^4.19.0",
     "typescript": "^5.7.3",
-    "@avocadostudio-ai/site-sdk": "0.19.0",
-    "@avocadostudio-ai/shared": "0.19.0"
+    "@avocadostudio-ai/shared": "0.21.0",
+    "@avocadostudio-ai/site-sdk": "0.21.0"
   },
   "license": "Apache-2.0",
   "homepage": "https://docs.avocadostudio.dev",

package/theme/night-harvest.css

@@ -0,0 +1,320 @@
+/*
+ * Theme: Night Harvest
+ *
+ * Chartreuse on near-black, Anton over Archivo, nothing rounded. A set of
+ * values for the tokens the blocks package already reads — there is no Night
+ * Harvest code anywhere, and no block knows this file exists.
+ *
+ * Dark is the theme, not a mode of it. `html.theme-night-harvest.dark` is
+ * therefore the primary declaration and the site's pre-paint script leaves the
+ * `dark` class on unless a visitor has asked for light. The light half is a
+ * genuine inversion rather than a lightening: the band flips from chartreuse
+ * on ink to ink on chartreuse, and the accent stops being legible as text, so
+ * words in the accent switch to a darker relative of the same hue.
+ *
+ * ── The three that are easy to get wrong ──
+ *
+ * `--accent` is a fill and `--accent-ink` is the accent as a word. They are
+ * the same value in dark and different in light: #C5E035 on #F2F3EA is about
+ * 1.3:1, which is a highlighter, not text. Anything that sets `color` reads
+ * `--accent-ink`.
+ *
+ * `--band` and `--on-band` are the full-bleed strip. The band inverts between
+ * themes instead of lightening, so it cannot be derived from the accent.
+ *
+ * `--bg-100` (the panel) against `--bg-0` (the ground) is roughly 1.1:1 in
+ * both themes, and that is the intent. A card is separated by the grid gap.
+ * Do not reach for a border or a shadow to make one "visible".
+ */
+
+/* ── Light ──────────────────────────────────────────────────────────────── */
+
+html.theme-night-harvest {
+  color-scheme: light;
+
+  /* Ground and panel */
+  --bg-0: #f2f3ea;
+  --bg-000: #f2f3ea;
+  --bg-100: #e4e7d7;
+  --bg-200: #e4e7d7;
+  --bg-300: #d5d9c6;
+  --bg-1: #e4e7d7;
+  --surface: #e4e7d7;
+  --card-bg: #e4e7d7;
+  --section-bg: #f2f3ea;
+  --hero-bg: #f2f3ea;
+  --cta-bg: #e4e7d7;
+  --stripe-bg: #e4e7d7;
+  --table-header-bg: #e4e7d7;
+
+  /* The alternating ground. Panel is the same #E4E7D7 a card sits on, so a
+     panel section and the cards inside it read as one surface. */
+  --section-bg-panel: #e4e7d7;
+
+  /* Ink and muted */
+  --text-100: #14190f;
+  --text-200: #14190f;
+  --text-300: #565c4c;
+  --text-400: #565c4c;
+  --text-500: #565c4c;
+  --heading: #14190f;
+  --body: #14190f;
+  --body-secondary: #565c4c;
+  --caption: #565c4c;
+  --prose-body: #14190f;
+  --lead: #565c4c;
+
+  /*
+   * The accent, in its two jobs. `--brand` is the repo's name for "the colour
+   * a word is set in", so it takes the text-safe value; the fill lives in
+   * `--accent` and reaches the primary button through `--btn-primary-bg`.
+   */
+  --accent: #c5e035;
+  --accent-hover: #c5e035;
+  --accent-ink: #46630d;
+  --on-accent: #14190f;
+  --brand: #46630d;
+  --brand-hover: #14190f;
+  --brand-fg: #14190f;
+  --brand-subtle: rgba(197, 224, 53, 0.22);
+  --link: #46630d;
+  --btn-primary-bg: #c5e035;
+  --btn-primary-fg: #14190f;
+
+  /* The band inverts: ink ground, chartreuse type. */
+  --band: #14190f;
+  --on-band: #c5e035;
+  --on-ink: #c5e035;
+
+  /* Hairlines */
+  --rule: rgba(20, 25, 15, 0.16);
+  --border: rgba(20, 25, 15, 0.16);
+  --surface-border: rgba(20, 25, 15, 0.16);
+  --nav-border: rgba(20, 25, 15, 0.16);
+  --footer-border: rgba(20, 25, 15, 0.16);
+  --code-bg: rgba(20, 25, 15, 0.1);
+  --pre-bg: rgba(20, 25, 15, 0.07);
+
+  /* Chrome */
+  --nav-bg: rgba(242, 243, 234, 0.94);
+
+  /*
+   * The footer is a panel, not a slab of ink.
+   *
+   * It was #14190F — the same value as the inverse band — so on any page
+   * ending in a CTA the band ran straight into the footer and the two read as
+   * one undifferentiated dark block a third of the page tall. The boundary
+   * between "the last thing we are asking you to do" and "the small print"
+   * had disappeared.
+   *
+   * Making it the panel ground fixes it in both directions: in light the ink
+   * band now sits against a pale footer, and in dark the chartreuse band sits
+   * against the same panel. The footer is the same surface as a card in both
+   * themes, which is what it is.
+   */
+  --footer-bg: var(--section-bg-panel);
+  --footer-text: #565c4c;
+  --footer-heading: #14190f;
+  --footer-link: #565c4c;
+  --footer-link-hover: #46630d;
+
+  /*
+   * An image position with no image is a flat accent field, not a grey box.
+   * It is a designed state: on a page whose photography is not all there yet,
+   * a chartreuse panel reads as a decision and a grey one reads as a bug.
+   */
+  --placeholder-img: #c5e035;
+  --media-bg: #14190f;
+
+  /*
+   * The hero as a poster.
+   *
+   * Most of the fold, the headline at display scale set solid, and the type
+   * anchored to the bottom of the frame rather than floating in the middle of
+   * it — which is what separates a poster from a stock hero with words on it.
+   *
+   * The scrim sinks the photograph towards the page's own near-black instead
+   * of neutral black. A warm palette with a neutral scrim over its one
+   * photograph reads as two designs, and the grey is the one you notice.
+   */
+  /*
+   * A duotone, built from filters rather than an asset, so it applies to
+   * whatever photograph the content happens to name. Desaturate, lift the
+   * contrast, drop the exposure, then push the whole thing through the
+   * palette's own hue. The photograph stops being a warm neutral standing
+   * beside chartreuse and becomes the dark end of it.
+   */
+  --photo-treatment: grayscale(1) contrast(1.15) brightness(0.55) sepia(0.55) hue-rotate(35deg) saturate(2.6);
+
+  /* 58vh, not 78. The frame was taking the whole fold for a photograph that is
+     mostly empty wall, which is a lot of screen spent on very little. */
+  /* The fruit sits in the upper half of this photograph, so a centred crop
+     takes the top off it. */
+  --hero-image-position: 50% 18%;
+
+  --hero-min-h: min(58vh, 560px);
+  --hero-headline-size: clamp(2.5rem, 5.2vw, 4.5rem);
+  --hero-headline-leading: 0.92;
+  --hero-content-anchor: flex-end;
+  --hero-content-width: 100%;
+  /*
+   * 11ch, not 14. At 14 the headline ran two wide lines straight across the
+   * middle of the frame and landed on the fruit — the photograph had room for
+   * type on the left and the type refused to stay in it. A narrow column is
+   * also simply what a poster does: three short lines stacked hard left read
+   * as deliberate, where two long ones read as a caption that outgrew its box.
+   */
+  --hero-headline-width: 11ch;
+  --scrim: linear-gradient(to bottom, rgb(18 23 15 / 0.35) 0%, rgb(18 23 15 / 0.62) 55%, rgb(18 23 15 / 0.9) 100%);
+  --on-image: #ecefe3;
+  --on-image-muted: rgba(236, 239, 227, 0.82);
+  --on-image-subtle: #c5e035;
+
+  --quote-mark: #46630d;
+  --quote-mark-opacity: 1;
+
+  /* Nothing is rounded. */
+  --radius: 0px;
+  --radius-btn: 0px;
+  --radius-card: 0px;
+  --radius-feature: 0px;
+  --radius-logo: 0px;
+  --radius-input: 0px;
+  --radius-dropdown: 0px;
+
+  /* Flat. The panel/ground relationship does the separating. */
+  --card-shadow: none;
+  --shadow-btn: none;
+  --shadow-float: none;
+  --shadow-dropdown: 0 0 0 1px var(--rule);
+  --shadow-menu: 0 0 0 1px var(--rule);
+
+  /*
+   * Anton has one cut, so the display weight drops to 400 — asking a poster
+   * face for 800 gets you a synthesised bold that ruins its sidebearings.
+   */
+  --font-display: var(--font-anton), Impact, "Haettenschweiler", sans-serif;
+  --font-heading: var(--font-anton), Impact, "Haettenschweiler", sans-serif;
+  --font-body: var(--font-archivo), Helvetica, Arial, sans-serif;
+  --font-label: var(--font-archivo), Helvetica, Arial, sans-serif;
+  --font-quote: var(--font-anton), Impact, sans-serif;
+  --font-display-weight: 400;
+  --font-display-track: -0.005em;
+
+  /*
+   * ~120px BETWEEN sections, which is 56 a side — not 120 a side.
+   *
+   * Sections abut, so each one pays half the gap. Reading "section spacing
+   * holds at 120px" as 120 of padding put 240px of dead ground between a card
+   * row and the next heading, which is not a rhythm, it is a hole.
+   *
+   * 56 rather than 60 because 60 is not on the scale (4 8 12 16 24 32 40 56 80
+   * 120) and a step invented to make one sum come out is how a scale stops
+   * being one. 56 a side gives 112 between, four pixels off the number in the
+   * brief and indistinguishable from it on a page.
+   *
+   * This is the first thing that quietly collapses during an implementation,
+   * so it is one value: every block reads it, and no block sets its own.
+   */
+  --section-pad-y: 56px;
+  --section-pad-y-tight: 56px;
+  --section-pad-y-cta: 56px;
+  --section-pad-y-hero: 56px;
+  --section-pad-x: 40px;
+
+  --section-pad-y-sm: 32px;
+  --section-pad-y-tight-sm: 32px;
+  --section-pad-y-hero-sm: 32px;
+  --section-pad-x-sm: 16px;
+  --section-pad-x-tight-sm: 16px;
+}
+
+/* ── Dark, the primary ──────────────────────────────────────────────────── */
+
+html.theme-night-harvest.dark {
+  color-scheme: dark;
+
+  --bg-0: #12170f;
+  --bg-000: #12170f;
+  --bg-100: #1c2317;
+  --bg-200: #1c2317;
+  --bg-300: #262f1f;
+  --bg-1: #1c2317;
+  --surface: #1c2317;
+  --card-bg: #1c2317;
+  --section-bg: #12170f;
+  --hero-bg: #12170f;
+  --cta-bg: #1c2317;
+  --stripe-bg: #1c2317;
+  --table-header-bg: #1c2317;
+  --section-bg-panel: #1c2317;
+
+  --text-100: #ecefe3;
+  --text-200: #ecefe3;
+  --text-300: #9aa38c;
+  --text-400: #9aa38c;
+  --text-500: #9aa38c;
+  --heading: #ecefe3;
+  --body: #ecefe3;
+  --body-secondary: #9aa38c;
+  --caption: #9aa38c;
+  --prose-body: #ecefe3;
+  --lead: #9aa38c;
+
+  /* Here the fill and the ink are the same value — chartreuse on #12170F is
+     legible as a word. That coincidence is why `--accent-ink` has to exist:
+     the light half proves it is a coincidence. */
+  --accent: #c5e035;
+  --accent-hover: #c5e035;
+  --accent-ink: #c5e035;
+  --on-accent: #12170f;
+  --brand: #c5e035;
+  --brand-hover: #ecefe3;
+  --brand-fg: #12170f;
+  --brand-subtle: rgba(197, 224, 53, 0.12);
+  --link: #c5e035;
+  --btn-primary-bg: #c5e035;
+  --btn-primary-fg: #12170f;
+
+  --band: #c5e035;
+  --on-band: #12170f;
+  --on-ink: #c5e035;
+
+  --rule: rgba(236, 239, 227, 0.2);
+  --border: rgba(236, 239, 227, 0.2);
+  --surface-border: rgba(236, 239, 227, 0.2);
+  --nav-border: rgba(236, 239, 227, 0.2);
+  --footer-border: rgba(236, 239, 227, 0.2);
+  --code-bg: rgba(236, 239, 227, 0.12);
+  --pre-bg: rgba(236, 239, 227, 0.08);
+
+  --nav-bg: rgba(18, 23, 15, 0.94);
+  --footer-bg: var(--section-bg-panel);
+  --footer-text: #9aa38c;
+  --footer-heading: #ecefe3;
+  --footer-link: #9aa38c;
+  --footer-link-hover: #c5e035;
+
+  --placeholder-img: #c5e035;
+  --media-bg: #12170f;
+
+  --quote-mark: #c5e035;
+  --quote-mark-opacity: 1;
+
+  --card-shadow: none;
+  --shadow-btn: none;
+  --shadow-float: none;
+  --shadow-dropdown: 0 0 0 1px var(--rule);
+  --shadow-menu: 0 0 0 1px var(--rule);
+
+  /* Status fills, restated so they sit in the palette rather than arriving
+     from the package's slate-and-emerald defaults. */
+  --banner-success-bg: #1c2317;
+  --banner-success-text: #c5e035;
+  --banner-warning-bg: #1c2317;
+  --banner-warning-text: #ecefe3;
+  --error-bg: #1c2317;
+  --error-border: rgba(236, 239, 227, 0.2);
+  --error-text: #ecefe3;
+  --error-detail: #9aa38c;
+}

package/theme/site-chrome.css

@@ -0,0 +1,333 @@
+/*
+ * The demo's skin on the SiteHeader block, in a file of its own because it
+ * ships twice.
+ *
+ * `scripts/sync-demo-seed.mjs` copies this into `create-avocado-site`, which
+ * writes it into every scaffolded project — so a scaffold's header is the
+ * header on the demo site rather than a near-miss of it. Before that, the two
+ * agreed on markup and disagreed on four gaps, a padding and a breakpoint:
+ * identical HTML, a nav row 19px narrower, and a burger that appeared at a
+ * different window width.
+ *
+ * It is NOT in `@avocadostudio-ai/blocks`. The package's own header styles are
+ * the neutral default every integrator inherits, and quietly moving the demo's
+ * values into them would restyle the header of every site that installs the
+ * package to match one design. A skin belongs with the design it is part of.
+ *
+ * Generated file at the far end of the copy — edit this one.
+ */
+
+/* Site chrome — navigation */
+
+.site-top-nav {
+  position: sticky;
+  top: 0;
+  z-index: 20;
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+  gap: 18px;
+  padding: 14px 20px;
+  border-bottom: 1px solid var(--nav-border);
+  background: var(--nav-bg);
+  backdrop-filter: blur(4px);
+  container-type: inline-size;
+  container-name: site-nav;
+}
+
+.site-brand {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-width: 0;
+  text-decoration: none;
+  color: inherit;
+}
+
+.site-logo {
+  width: 38px;
+  height: 38px;
+  border: none;
+  border-radius: var(--radius-logo);
+  object-fit: contain;
+  display: block;
+}
+
+/* Size, weight and colour are the package's (`.site-brand`); restating them
+   here — at 800 and `var(--brand)` — made the wordmark a third green thing in
+   the header. Only the truncation is local. */
+.site-brand-text {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.site-nav-links {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.site-nav-links-desktop {
+  margin-left: 10px;
+}
+
+.site-mobile-menu {
+  display: none;
+}
+
+.site-mobile-menu-button {
+  /* A <button> starts from the UA's own 13.33px Arial. This app has a reset
+     that says otherwise and a scaffolded project does not, so the rule has to
+     be here rather than assumed. Same reason as `.site-theme-toggle`. */
+  font: inherit;
+  min-height: 44px;
+  min-width: 44px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  cursor: pointer;
+}
+
+
+.site-mobile-menu summary {
+  list-style: none;
+  cursor: pointer;
+}
+
+.site-mobile-menu summary::-webkit-details-marker {
+  display: none;
+}
+
+/*
+ * The burger's box, removed.
+ *
+ * It was a 38x36 bordered tile filled with `--brand-subtle` holding three
+ * green bars — the only element in the header wearing a container, sitting
+ * next to a theme control that is three strokes and nothing else. The package
+ * already draws the icon flat, in `currentColor`, so deleting the local
+ * override is the whole change: three lines, the same weight and colour as
+ * the icon beside them, on a 44px target the button still owns.
+ */
+
+/*
+ * Only the underline treatment belongs to this site. Colour, size, weight and
+ * padding used to be restated here as brand/0.9375rem/700 — a tie on
+ * specificity with the package's own `.site-nav-links-desktop > a`, won on
+ * source order because this file is imported after it. The visible result was a
+ * nav in three resting colours: plain links green, group triggers green, and
+ * only the active item near-black. Whoever retuned the package rule never saw
+ * it take effect.
+ */
+.site-nav-links a {
+  text-decoration: none;
+  text-decoration-thickness: 2px;
+  text-underline-offset: 0.32em;
+}
+
+/*
+ * The rule under a nav item is drawn, not switched on.
+ *
+ * A background gradient sized from 0% to 100% rather than a pseudo-element,
+ * because `background-size` interpolates and `text-decoration` does not — and
+ * it needs no extra box, so it cannot disturb the flex row it sits in.
+ */
+@media (prefers-reduced-motion: no-preference) {
+  .site-nav-links-desktop > a {
+    background-image: linear-gradient(var(--accent-ink), var(--accent-ink));
+    background-repeat: no-repeat;
+    background-position: 0.75rem 78%;
+    background-size: 0% 2px;
+    transition:
+      background-size var(--motion-fast) var(--ease-silk),
+      color var(--motion-fast) var(--ease-silk);
+  }
+
+  .site-nav-links-desktop > a:hover {
+    background-size: calc(100% - 1.5rem) 2px;
+  }
+
+  /* The active item already carries its own underline; sweeping a second one
+     underneath it just thickens the first. */
+  .site-nav-links-desktop > a.is-active:hover {
+    background-size: 0% 2px;
+  }
+}
+
+/*
+ * The active item was near-black under a 4px slab while its neighbours were
+ * muted grey — two jumps at once, weight and colour, for a state that only has
+ * to say "you are here". A 2px rule in the accent says it once, and leaves the
+ * colour difference to do the rest.
+ */
+.site-nav-links a.is-active {
+  text-decoration: underline;
+  text-decoration-thickness: 2px;
+  text-decoration-color: var(--accent-ink);
+}
+
+.site-top-nav:has(.site-mobile-menu.is-open) {
+  border-bottom: none !important;
+}
+
+/*
+ * The scrim behind an open mobile menu.
+ *
+ * Top level, not inside the container query below, and that is the whole bug
+ * it used to have: `@container site-nav` only matches descendants of the
+ * header, and the backdrop is a sibling of it. So none of this applied, the
+ * package's own `z-index: 99` stood, and a scrim meant to sit *under* the
+ * header (`z-index: 20`) sat over it — swallowing every tap inside the open
+ * menu. Expanding a nav group did nothing; the click never reached the button.
+ */
+.site-mobile-backdrop {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 19;
+  background: rgb(from var(--nav-bg) r g b / 0.5);
+  backdrop-filter: blur(4px);
+}
+
+/* Mobile — uses a container query on the header so the burger menu kicks in
+   based on the header's own width (works inside the editor iframe regardless
+   of viewport width). */
+
+@container site-nav (max-width: 900px) {
+  .site-top-nav {
+    align-items: center;
+    flex-direction: row;
+    justify-content: space-between;
+    flex-wrap: wrap;
+    padding: 12px 16px;
+  }
+
+  .site-nav-links-desktop {
+    display: none;
+  }
+
+  /* The burger keeps the outer edge: it is the one control a thumb reaches
+     for without looking. The theme control sits inboard of it and carries the
+     `auto` margin for both — two auto margins in one row do not stack, they
+     split the free space between them. */
+  .site-mobile-menu {
+    display: block;
+    order: 3;
+    position: static;
+    z-index: 3;
+    margin-left: 0;
+  }
+
+  /* Flat in every state — three lines and nothing else. The open state used
+     to tint the button green, which drew a box round the burger at exactly
+     the moment the menu below it is already saying the same thing. */
+
+  .site-mobile-menu.is-open .burger-icon i:nth-child(1) {
+    transform: translateY(6px) rotate(45deg);
+  }
+
+  .site-mobile-menu.is-open .burger-icon i:nth-child(2) {
+    opacity: 0;
+  }
+
+  .site-mobile-menu.is-open .burger-icon i:nth-child(3) {
+    transform: translateY(-6px) rotate(-45deg);
+  }
+
+  .burger-icon i {
+    transition: transform 0.2s ease, opacity 0.2s ease;
+  }
+
+  .site-top-nav-inner > .site-theme-toggle {
+    margin-left: auto;
+    order: 2;
+  }
+
+  .site-mobile-menu summary {
+    min-height: 44px;
+    min-width: 44px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .site-nav-links-mobile {
+    position: absolute;
+    top: 100%;
+    left: 0;
+    right: 0;
+    width: 100%;
+    max-height: min(65vh, 520px);
+    overflow-y: auto;
+    display: flex;
+    flex-direction: column;
+    /*
+     * `stretch`, not the `center` this inherits from `.site-nav-links`.
+     *
+     * The base rule centres a horizontal row of links, which is right for the
+     * desktop header and wrong the moment the same element becomes a column:
+     * every row shrank to the width of its own label and sat centred, so the
+     * menu read as five differently-sized pills down the middle of the screen.
+     * The `text-align: left` below has been there the whole time and never had
+     * a box wide enough to act in.
+     */
+    align-items: stretch;
+    gap: 0;
+    padding: 6px 16px;
+    border-bottom: 1px solid var(--nav-border);
+    /* Opaque. It was `--brand-subtle`, a translucent accent wash, so the page
+       scrolled visibly underneath the open menu. */
+    background: var(--bg-100);
+    box-shadow: var(--shadow-menu);
+    z-index: 20;
+  }
+
+  /*
+   * One row treatment for every row.
+   *
+   * A plain link was 46px tall at 14px with a hairline under it; a dropdown
+   * trigger was 37px tall at 16px with none. Three row heights and two type
+   * sizes in a five-item menu, and the hairlines landing under some rows and
+   * not others — which is what made one divider look like a stray rule rather
+   * than a list.
+   */
+  .site-nav-links-mobile > a,
+  .site-nav-links-mobile .site-nav-mobile-group-trigger {
+    display: flex;
+    align-items: center;
+    width: 100%;
+    text-align: left;
+    min-height: var(--tap-min);
+    padding: 12px 4px;
+    font-size: 0.9375rem;
+    border-bottom: 1px solid var(--nav-border);
+    border-radius: 0;
+    text-decoration: none;
+  }
+
+  .site-nav-links-mobile > *:last-child > .site-nav-mobile-group-trigger,
+  .site-nav-links-mobile > a:last-child {
+    border-bottom: 0;
+  }
+
+  /* The nested children of an open group are one step in and one step
+     quieter, so the group reads as a group rather than as more top-level
+     items that happen to be indented. */
+  .site-nav-links-mobile .site-nav-mobile-group-children a {
+    min-height: var(--tap-min);
+    display: flex;
+    align-items: center;
+    font-size: 0.9375rem;
+  }
+
+  .site-nav-links-mobile a.is-active {
+    font-weight: 700;
+    text-decoration: none;
+  }
+}

package/theme/theme-toggle.css

@@ -0,0 +1,104 @@
+/*
+ * The theme control's styles, in a file of their own because they ship twice.
+ *
+ * `theme-toggle.tsx` and this stylesheet are copied into
+ * `create-avocado-site` by `scripts/sync-demo-seed.mjs` and written into every
+ * scaffolded project, so a scaffold gets the same control the demo site has
+ * rather than a pre-paint script reading a storage key nothing ever writes.
+ *
+ * They are NOT in `@avocadostudio-ai/blocks`: the SiteHeader block does not
+ * render a theme control, and CSS in the package for an element the package
+ * never emits is the dead-stylesheet trap documented in
+ * `blocks/site-header/styles.css`. The host app owns the control; the host app
+ * owns its styles; one source file feeds both hosts.
+ *
+ * Breakpoint-independent on purpose. The app collapses its nav at 900px and
+ * the package's own header collapses at 768px, so the rule that reorders this
+ * control against the burger lives with each of those media queries rather
+ * than here.
+ */
+
+/*
+ * The theme control, in the footer.
+ *
+ * It was styled as a 38x36 icon square for a header slot it was never
+ * actually placed in. In the footer it can afford a label, which removes the
+ * guess a lone sun-or-moon glyph always asks of the reader: does the icon
+ * show the theme I am in, or the one I would get?
+ */
+.site-theme-bar {
+  display: flex;
+  justify-content: center;
+  padding: 0 var(--section-pad-x) var(--section-pad-y-tight);
+  background: var(--footer-bg);
+}
+
+/*
+ * Icon only, and square.
+ *
+ * It carried a text label — "System" / "Light" / "Dark" — which on a strip of
+ * its own read as a lone word in a box rather than as a control. The meaning
+ * moves to `aria-label` and `title`, where a screen reader and a hover can
+ * both reach it, and the button becomes the one square thing a reader's eye
+ * can skip until they want it.
+ */
+/*
+ * Borderless.
+ *
+ * It was a 44px square with a 1px rule round it holding an 18px hairline
+ * glyph — the box was the loudest part of the control and the icon the
+ * quietest, which is backwards for something a reader should be able to skip
+ * until they want it. The target stays 44px; only the box goes.
+ */
+.site-theme-toggle {
+  /* A <button> does not inherit the page's font, and outside this app there is
+     no CSS reset to say otherwise — the control came out at the UA's 13.33px
+     Arial in a scaffolded project. Nothing visible sits inside it, so the only
+     way to see it is to measure it. */
+  font: inherit;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: var(--tap-min);
+  height: var(--tap-min);
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-btn);
+  background: transparent;
+  color: var(--text-300);
+  cursor: pointer;
+  transition: color 0.15s;
+}
+
+/* Colour only. A filled hover square is the bordered box coming back in a
+   different guise — on an icon button the glyph is the affordance. */
+.site-theme-toggle:hover {
+  color: var(--accent-ink);
+}
+
+/* On the footer's own ground, which is a different surface from the page. */
+.site-theme-bar .site-theme-toggle {
+  color: var(--footer-link);
+}
+
+.site-theme-bar .site-theme-toggle:hover {
+  color: var(--footer-link-hover);
+}
+
+/* Portalled into the header's inner flex row; `auto` pushes it to the far
+   right without the row needing to know it is there. */
+.site-top-nav-inner > .site-theme-toggle {
+  margin-left: auto;
+}
+
+.site-theme-toggle-icon {
+  /* The attributes on the element carry the real size; these are belt and
+     braces for a flex context. Fill and stroke are set per shape on the
+     element now — these icons are solid forms with stroked rays, not one
+     uniformly-outlined drawing. */
+  flex: none;
+  width: 20px;
+  height: 20px;
+  stroke-linejoin: round;
+}

package/theme/theme-toggle.tsx

@@ -0,0 +1,196 @@
+"use client"
+
+import { useCallback, useEffect, useState } from "react"
+import { createPortal } from "react-dom"
+
+const SITE_THEME_STORAGE_KEY = "site-theme-v1"
+
+type Choice = "system" | "light" | "dark"
+
+const ORDER: Choice[] = ["system", "light", "dark"]
+const LABEL: Record<Choice, string> = { system: "System", light: "Light", dark: "Dark" }
+
+/**
+ * Three states, not two: follow the system, or pin light, or pin dark.
+ *
+ * "Follow the system" is the absence of a stored value, which is what makes it
+ * a real third state rather than a label on one of the other two — a visitor
+ * who has never touched the control tracks their OS for as long as the page is
+ * open, and one who has chosen keeps their choice across visits.
+ *
+ * `prefers-color-scheme: light` and not `: dark`. Night Harvest is a dark
+ * theme with a light half, so the fallback is dark and light is the opt-in.
+ * That is the same way round as the token contract itself, where the light
+ * values sit inside a `prefers-color-scheme: light` query and dark is what
+ * `:root` says. A browser that expresses no preference gets the theme's
+ * primary state rather than its secondary one.
+ *
+ * It writes the `dark` class on `<html>`, not `data-theme`. The brief asks for
+ * the attribute and the attribute would be the nicer contract, but the class
+ * is already what decides the theme here: `_tokens.css` keys its dark half on
+ * `.dark`, so does `theme-modern-orange.css`, so does every consumer of the
+ * blocks package, and so does the pre-paint script in `layout.tsx`. Two
+ * mechanisms for one state is how a theme ends up half-applied, so this is
+ * flagged rather than fudged.
+ */
+/*
+ * Both copies of the control answer to one state.
+ *
+ * There are two on the page — one in the header, one in the footer — and two
+ * React instances do not share a `useState`. Without this, clicking the header
+ * button changed the theme and left the footer button still reporting the old
+ * one, which is the kind of thing that looks like a caching bug.
+ */
+const THEME_EVENT = "site-theme-change"
+
+export function SiteThemeToggle({ portalTo }: { portalTo?: string } = {}) {
+  const [choice, setChoice] = useState<Choice>("system")
+  const [resolved, setResolved] = useState<"light" | "dark">("dark")
+
+  /* Kept identical to the pre-paint script in `layout.tsx`. If the two ever
+     disagree the page paints one theme and then visibly switches to the
+     other, which is the flash the script exists to prevent. */
+  const resolve = useCallback((c: Choice): "light" | "dark" => {
+    if (c !== "system") return c
+    return window.matchMedia?.("(prefers-color-scheme: light)").matches ? "light" : "dark"
+  }, [])
+
+  const [host, setHost] = useState<Element | null>(null)
+  useEffect(() => {
+    if (!portalTo) return
+    /*
+     * The header is a block renderer's output, not this app's markup, so the
+     * control is placed into it after mount rather than by editing the
+     * package. A portal keeps it a real child of the nav — it inherits the
+     * sticky positioning and the flex row, and needs no absolute placement
+     * guessing at the header's height.
+     */
+    setHost(document.querySelector(portalTo))
+  }, [portalTo])
+
+  useEffect(() => {
+    const stored = window.localStorage.getItem(SITE_THEME_STORAGE_KEY)
+    const next: Choice = stored === "light" || stored === "dark" ? stored : "system"
+    setChoice(next)
+    setResolved(resolve(next))
+  }, [resolve])
+
+  /* Track the OS for as long as the visitor is on "system". Re-subscribing on
+     every change of `choice` is what stops a pinned theme from being dragged
+     back by the OS mid-session. */
+  useEffect(() => {
+    if (choice !== "system") return
+    const mq = window.matchMedia?.("(prefers-color-scheme: light)")
+    if (!mq) return
+    const onChange = () => setResolved(resolve("system"))
+    mq.addEventListener("change", onChange)
+    return () => mq.removeEventListener("change", onChange)
+  }, [choice, resolve])
+
+  useEffect(() => {
+    const onPeer = (e: Event) => {
+      const next = (e as CustomEvent<Choice>).detail
+      setChoice(next)
+      setResolved(resolve(next))
+    }
+    window.addEventListener(THEME_EVENT, onPeer)
+    return () => window.removeEventListener(THEME_EVENT, onPeer)
+  }, [resolve])
+
+  useEffect(() => {
+    const root = window.document.documentElement
+    /*
+     * Colour transitions are right for a hover and wrong for a theme change:
+     * every button, link and nav item carries one, so flipping the control
+     * sent all of them on their own 150ms journey and the page dissolved
+     * rather than switched. This kills transitions for exactly one frame —
+     * see `[data-theme-switching]` in the blocks package's `_base.css`.
+     */
+    root.setAttribute("data-theme-switching", "")
+    root.classList.toggle("dark", resolved === "dark")
+    const frame = window.requestAnimationFrame(() =>
+      window.requestAnimationFrame(() => root.removeAttribute("data-theme-switching"))
+    )
+    return () => window.cancelAnimationFrame(frame)
+  }, [resolved])
+
+  const handleClick = () => {
+    const next = ORDER[(ORDER.indexOf(choice) + 1) % ORDER.length]
+    setChoice(next)
+    setResolved(resolve(next))
+    window.dispatchEvent(new CustomEvent(THEME_EVENT, { detail: next }))
+    /*
+     * Not inside the preview iframe: an editor session should not leave a
+     * pinned preference behind in the published site's own storage.
+     */
+    if (window.parent === window) {
+      try {
+        if (next === "system") window.localStorage.removeItem(SITE_THEME_STORAGE_KEY)
+        else window.localStorage.setItem(SITE_THEME_STORAGE_KEY, next)
+      } catch {
+        // Blocked storage — the class toggle above still applies for this visit.
+      }
+    }
+  }
+
+  const nextLabel = LABEL[ORDER[(ORDER.indexOf(choice) + 1) % ORDER.length]]
+
+  const button = (
+    <button
+      type="button"
+      className="site-theme-toggle"
+      onClick={handleClick}
+      /* Icon only, so the label has to live somewhere a screen reader can
+         reach. It reports the state the control is IN and names the one the
+         next press gives — a control that only says what it will do leaves a
+         reader guessing what it is currently doing. */
+      aria-label={`Theme: ${LABEL[choice]}. Switch to ${nextLabel}.`}
+      title={`Theme: ${LABEL[choice]} — switch to ${nextLabel}`}
+    >
+      {/*
+        `width`/`height` attributes as well as the CSS. An inline SVG carries
+        no intrinsic size, so as a flex item it resolves to a zero-width
+        content box and the CSS width loses to `flex-shrink` — the icon
+        measured 0x16 and the button looked like an empty bordered square.
+      */}
+      <svg
+        className="site-theme-toggle-icon"
+        width="20"
+        height="20"
+        viewBox="0 0 24 24"
+        /* Outline only, and declared once here so every shape inherits it.
+           The set used to mix filled forms with stroked rays — a solid screen,
+           a solid disc, a solid crescent — which read as three weights of icon
+           rather than one family. One stroke width, no fills. */
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.8"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        aria-hidden="true"
+      >
+        {choice === "system" ? (
+          /* A monitor: "whatever this machine is set to". */
+          <>
+            <rect x="2.8" y="4.2" width="18.4" height="12.6" rx="2.2" />
+            <path d="M12 16.8v3.4M8.4 20.2h7.2" />
+          </>
+        ) : choice === "light" ? (
+          /* A ring and eight rays. The rays stop short of the ring so the two
+             stay legible as separate strokes at 20px. */
+          <>
+            <circle cx="12" cy="12" r="4.4" />
+            <path d="M12 2.2v2.4M12 19.4v2.4M2.2 12h2.4M19.4 12h2.4M5.1 5.1l1.7 1.7M17.2 17.2l1.7 1.7M18.9 5.1l-1.7 1.7M6.8 17.2l-1.7 1.7" />
+          </>
+        ) : (
+          /* A crescent cut from one disc by another, so the terminator is a
+             true circular arc rather than a drawn curve. */
+          <path d="M21.4 14.2A9.6 9.6 0 1 1 10.3 2.4a7.6 7.6 0 0 0 11.1 11.8Z" />
+        )}
+      </svg>
+    </button>
+  )
+
+  if (!portalTo) return button
+  return host ? createPortal(button, host) : null
+}