From ca02182f8925fc4aaf3fa39854bc923632a0f191 Mon Sep 17 00:00:00 2001
From: Luca Pattocchio <15154851+Kasui92@users.noreply.github.com>
Date: Sun, 6 Sep 2026 19:24:32 +0200
Subject: [PATCH 1/6] fix: restore border-box on the showcase chrome

---
 www/src/styles/site.css | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/www/src/styles/site.css b/www/src/styles/site.css
index ca005c1..2c70bcf 100644
--- a/www/src/styles/site.css
+++ b/www/src/styles/site.css
@@ -7,6 +7,14 @@
   --site-page-padding: var(--identity-page-padding);
 }
 
+/* JAAD gets this from Tailwind's preflight; without it, padding is added to
+   width and .site-main overflows the viewport by its own padding. */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
 html {
   background-color: var(--identity-background);
   color: var(--identity-foreground);

From 6906cf3516cadf0eecad9d67e91f4f57a87600c3 Mon Sep 17 00:00:00 2001
From: Luca Pattocchio <15154851+Kasui92@users.noreply.github.com>
Date: Sun, 6 Sep 2026 19:24:43 +0200
Subject: [PATCH 2/6] feat: add the theme picker to the showcase

---
 tests/build/smoke.mjs                    | 40 ++++++++++++++
 www/astro.config.mjs                     | 27 +++++++++-
 www/src/components/SiteThemePicker.astro | 61 ++++++++++++++++++++++
 www/src/components/SiteThemeToggle.astro | 66 ------------------------
 www/src/layouts/SiteLayout.astro         | 53 ++++++++++++++++---
 www/src/styles/jaamd.css                 | 23 +++++++--
 www/src/styles/site.css                  | 48 +++++++++--------
 www/src/themes.ts                        | 25 +++++++++
 8 files changed, 239 insertions(+), 104 deletions(-)
 create mode 100644 www/src/components/SiteThemePicker.astro
 delete mode 100644 www/src/components/SiteThemeToggle.astro
 create mode 100644 www/src/themes.ts

diff --git a/tests/build/smoke.mjs b/tests/build/smoke.mjs
index 4b14f0b..0f78c92 100644
--- a/tests/build/smoke.mjs
+++ b/tests/build/smoke.mjs
@@ -138,6 +138,46 @@ check(
   "the anchor icon stays invisible on the deeper levels",
 );
 
+// ─── themes ──────────────────────────────────────────────────────────────────
+
+const themeSlugs = [
+  ...new Set([...html.matchAll(/html\[data-jaamd-theme="([a-z0-9-]+)"\]/g)].map((m) => m[1])),
+];
+
+check(
+  `themes: ${themeSlugs.length} scoped in the page`,
+  themeSlugs.length > 0,
+  "the layout did not inject the re-scoped theme CSS",
+);
+
+// Authored on :root, so without re-scoping only the last import would ever win.
+check(
+  "themes: none left on bare :root",
+  !/(^|\})\s*:root\s*\{[^}]*--jaamd-color-primary/.test(html),
+  "a theme reached the page unscoped and will override every other one",
+);
+
+check(
+  "themes: the site bridge is scoped too",
+  /\[data-jaamd-theme=("?)jaamd\1\]/.test(css),
+  "an unscoped bridge outranks the themes, so only secondary colours would change",
+);
+
+// One Shiki variable per theme is what lets code follow the switch.
+for (const slug of themeSlugs) {
+  check(
+    `themes: ${slug} has its Shiki colours baked`,
+    html.includes(`--shiki-${slug}:`),
+    `add ${slug} to shikiConfig.themes, or its code blocks keep the previous theme`,
+  );
+}
+
+check(
+  "themes: the picker lists every theme plus the site's own",
+  countOf(/<option value="/g) === themeSlugs.length + 1,
+  "the picker is built from the manifest; an option is missing",
+);
+
 // ─── the rest of the pipeline still ships ────────────────────────────────────
 
 check(
diff --git a/www/astro.config.mjs b/www/astro.config.mjs
index 91c1d18..80d6c2d 100644
--- a/www/astro.config.mjs
+++ b/www/astro.config.mjs
@@ -1,9 +1,34 @@
 import { defineConfig, fontProviders } from "astro/config";
 import jaamd from "@lancher-dev/jaamd";
+import { themes } from "@lancher-dev/jaamd/themes";
+
+// Shiki takes arbitrary theme keys and emits --shiki-<key> per token, so every
+// theme is baked at build time and switched with CSS. jaamd's own option accepts
+// only light/dark, so the rest are added here, after it.
+const shikiThemes = {
+  light: "github-light",
+  dark: "one-dark-pro",
+  ...Object.fromEntries(themes.map((t) => [t.slug, t.shiki])),
+};
+
+/** @type {import("astro").AstroIntegration} */
+const shikiMultiTheme = {
+  name: "www:shiki-themes",
+  hooks: {
+    "astro:config:setup": ({ updateConfig }) => {
+      updateConfig({
+        markdown: { shikiConfig: { themes: shikiThemes, defaultColor: false } },
+      });
+    },
+  },
+};
 
 export default defineConfig({
   site: "https://jaamd.lancher.dev",
-  integrations: [jaamd({ theme: { light: "github-light", dark: "one-dark-pro" } })],
+  integrations: [
+    jaamd({ theme: { light: "github-light", dark: "one-dark-pro" } }),
+    shikiMultiTheme,
+  ],
   fonts: [
     {
       provider: fontProviders.google(),
diff --git a/www/src/components/SiteThemePicker.astro b/www/src/components/SiteThemePicker.astro
new file mode 100644
index 0000000..377708c
--- /dev/null
+++ b/www/src/components/SiteThemePicker.astro
@@ -0,0 +1,61 @@
+---
+import { siteThemes, SITE_THEME } from "../themes.ts";
+---
+
+<site-theme-picker class="site-theme-picker">
+  <label class="sr-only" for="theme">Theme</label>
+  <select id="theme" name="theme">
+    {
+      siteThemes.map((theme) => (
+        <option value={theme.slug} selected={theme.slug === SITE_THEME.slug}>
+          {theme.name}
+        </option>
+      ))
+    }
+  </select>
+</site-theme-picker>
+
+<script>
+  import { themeModes, THEME_STORAGE_KEY, SITE_THEME } from "../themes.ts";
+
+  const prefersDark = matchMedia("(prefers-color-scheme: dark)");
+
+  function apply(slug: string) {
+    const mode = themeModes[slug] ?? SITE_THEME.mode;
+    document.documentElement.dataset.jaamdTheme = slug;
+    document.documentElement.classList.toggle(
+      "dark",
+      mode === "dark" || (mode === "system" && prefersDark.matches),
+    );
+  }
+
+  class SiteThemePicker extends HTMLElement {
+    connectedCallback() {
+      const select = this.querySelector("select");
+      if (!select) return;
+
+      // The boot script already chose; reflect it rather than reset it.
+      const current = document.documentElement.dataset.jaamdTheme;
+      if (current && themeModes[current]) select.value = current;
+
+      select.addEventListener("change", () => {
+        apply(select.value);
+        try {
+          localStorage.setItem(THEME_STORAGE_KEY, select.value);
+        } catch {
+          // Private browsing.
+        }
+      });
+
+      // Only the site's own theme follows the system, and only while it is active.
+      prefersDark.addEventListener("change", () => {
+        const slug = document.documentElement.dataset.jaamdTheme;
+        if (slug && themeModes[slug] === "system") apply(slug);
+      });
+    }
+  }
+
+  if (!customElements.get("site-theme-picker")) {
+    customElements.define("site-theme-picker", SiteThemePicker);
+  }
+</script>
diff --git a/www/src/components/SiteThemeToggle.astro b/www/src/components/SiteThemeToggle.astro
deleted file mode 100644
index 1ba2793..0000000
--- a/www/src/components/SiteThemeToggle.astro
+++ /dev/null
@@ -1,66 +0,0 @@
-<site-theme-toggle>
-  <button
-    type="button"
-    class="site-theme-button"
-    aria-label="Dark theme"
-    title="Toggle color theme"
-  >
-    <svg
-      class="site-theme-icon-dark"
-      fill="none"
-      stroke="currentColor"
-      viewBox="0 0 24 24"
-      aria-hidden="true"
-    >
-      <path
-        stroke-linecap="round"
-        stroke-linejoin="round"
-        stroke-width="2"
-        d="M20.354 15.354A9 9 0 018.646 3.646 9.003 9.003 0 0012 21a9.003 9.003 0 008.354-5.646z"
-      ></path>
-    </svg>
-
-    <svg
-      class="site-theme-icon-light"
-      fill="none"
-      stroke="currentColor"
-      viewBox="0 0 24 24"
-      aria-hidden="true"
-    >
-      <path
-        stroke-linecap="round"
-        stroke-linejoin="round"
-        stroke-width="2"
-        d="M12 3v1m0 16v1m9-9h-1M4 12H3m15.364 6.364l-.707-.707M6.343 6.343l-.707-.707m12.728 0l-.707.707M6.343 17.657l-.707.707M16 12a4 4 0 11-8 0 4 4 0 018 0z"
-      ></path>
-    </svg>
-  </button>
-</site-theme-toggle>
-
-<script>
-  class SiteThemeToggle extends HTMLElement {
-    connectedCallback() {
-      const button = this.querySelector("button");
-      if (!button) return;
-
-      const sync = (isDark: boolean) =>
-        button.setAttribute("aria-pressed", String(isDark));
-
-      sync(document.documentElement.classList.contains("dark"));
-
-      button.addEventListener("click", () => {
-        const isDark = document.documentElement.classList.toggle("dark");
-        sync(isDark);
-        try {
-          localStorage.setItem("theme", isDark ? "dark" : "light");
-        } catch {
-          // Private browsing.
-        }
-      });
-    }
-  }
-
-  if (!customElements.get("site-theme-toggle")) {
-    customElements.define("site-theme-toggle", SiteThemeToggle);
-  }
-</script>
diff --git a/www/src/layouts/SiteLayout.astro b/www/src/layouts/SiteLayout.astro
index 08662c3..b61fe80 100644
--- a/www/src/layouts/SiteLayout.astro
+++ b/www/src/layouts/SiteLayout.astro
@@ -1,11 +1,41 @@
 ---
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
 import { Font } from "astro:assets";
+import { themes as packageThemes } from "@lancher-dev/jaamd/themes";
 import "@lancher-dev/jaamd/default.css";
 import "@lancher-dev/jaamd/styles.css";
 import "../styles/identity.css";
 import "../styles/jaamd.css";
 import "../styles/site.css";
-import SiteThemeToggle from "../components/SiteThemeToggle.astro";
+import SiteThemePicker from "../components/SiteThemePicker.astro";
+import { themeModes, THEME_STORAGE_KEY, SITE_THEME } from "../themes.ts";
+
+const require = createRequire(import.meta.url);
+
+// Themes are authored on :root, so importing more than one would just let the
+// last win. Re-scoped here, at build time, so they can coexist and be switched.
+const themeCss = packageThemes
+  .map(({ slug }) => {
+    const source = readFileSync(
+      require.resolve(`@lancher-dev/jaamd/themes/${slug}.css`),
+      "utf8",
+    );
+    const scope = `html[data-jaamd-theme="${slug}"]`;
+
+    // Shiki bakes one variable per configured theme; this picks which one the
+    // code reads. More specific than shiki-dual.css, so injection order is moot.
+    const code = `${scope}.dark .jaamd-content .astro-code span,
+${scope}.dark .jaamd-content .shiki span {
+  color: var(--shiki-${slug}) !important;
+  font-style: var(--shiki-${slug}-font-style) !important;
+  font-weight: var(--shiki-${slug}-font-weight) !important;
+  text-decoration: var(--shiki-${slug}-text-decoration) !important;
+}`;
+
+    return `${source.replace(/^:root \{$/m, `${scope} {`)}\n${code}`;
+  })
+  .join("\n\n");
 
 const title = "JAAMD";
 const description =
@@ -13,13 +43,19 @@ const description =
 const canonical = new URL(Astro.url.pathname, Astro.site).href;
 const ogImage = new URL("/og-image.png", Astro.site).href;
 
-// Inline and before paint: a class set from a module would flash the wrong theme.
+// Inline and before paint: applied from a module, the wrong theme would flash.
 const themeScript = `(function () {
-  try {
-    var t = localStorage.getItem("theme");
-    if (t === "dark" || (!t && matchMedia("(prefers-color-scheme: dark)").matches))
-      document.documentElement.classList.add("dark");
-  } catch (e) {}
+  var modes = ${JSON.stringify(themeModes)};
+  var slug;
+  try { slug = localStorage.getItem(${JSON.stringify(THEME_STORAGE_KEY)}); } catch (e) {}
+  if (!modes[slug]) slug = ${JSON.stringify(SITE_THEME.slug)};
+
+  var mode = modes[slug];
+  var dark = mode === "dark" ||
+    (mode === "system" && matchMedia("(prefers-color-scheme: dark)").matches);
+
+  document.documentElement.dataset.jaamdTheme = slug;
+  document.documentElement.classList.toggle("dark", dark);
 })();`;
 ---
 
@@ -40,6 +76,7 @@ const themeScript = `(function () {
     <meta property="og:url" content={canonical} />
     <meta property="og:image" content={ogImage} />
     <meta name="twitter:card" content="summary_large_image" />
+    <style is:inline set:html={themeCss}></style>
     <script is:inline set:html={themeScript} />
   </head>
   <body data-site-layout>
@@ -50,7 +87,7 @@ const themeScript = `(function () {
           <a href="https://github.com/lancher-dev/jaamd">GitHub</a>
           <a href="https://www.npmjs.com/package/@lancher-dev/jaamd">npm</a>
         </nav>
-        <SiteThemeToggle />
+        <SiteThemePicker />
       </div>
     </header>
 
diff --git a/www/src/styles/jaamd.css b/www/src/styles/jaamd.css
index 8be4c1a..f8720e6 100644
--- a/www/src/styles/jaamd.css
+++ b/www/src/styles/jaamd.css
@@ -1,16 +1,31 @@
-/* Bridge from the site identity to JAAMD's own seeds, so the markdown body and
-   the chrome around it are the same design. Unlayered, so it outranks
-   @layer jaamd.defaults in both themes; the identity tokens carry dark mode. */
+/* Bridge between the site identity and JAAMD's tokens. Unlayered, so it outranks
+   @layer jaamd.defaults; the themes it competes with are unlayered too, so the
+   attribute selectors are what keep them apart. */
 
-:root {
+/* Typography is the site's in every theme: the palette changes, the type does not. */
+html {
   --jaamd-font-sans: var(--identity-font-sans);
   --jaamd-font-serif: var(--identity-font-serif);
   --jaamd-font-mono: var(--identity-font-mono);
   --jaamd-font-size: 1.125rem;
   --jaamd-line-height: 1.6;
+}
 
+/* The site's own theme, and the state before the boot script runs. */
+html:not([data-jaamd-theme]),
+html[data-jaamd-theme="jaamd"] {
   --jaamd-bg: var(--identity-background);
   --jaamd-color-fg: var(--identity-foreground);
   --jaamd-color-fg-bright: var(--identity-foreground-bright);
   --jaamd-color-primary: var(--identity-primary);
 }
+
+/* Every package theme, in reverse: the chrome follows the article rather than the
+   site knowing each palette. Borders and muted text derive from these in
+   identity.css, so four seeds are enough. */
+html[data-jaamd-theme]:not([data-jaamd-theme="jaamd"]) {
+  --identity-background: var(--jaamd-bg);
+  --identity-foreground: var(--jaamd-color-fg);
+  --identity-foreground-bright: var(--jaamd-color-fg-bright);
+  --identity-primary: var(--jaamd-color-primary);
+}
diff --git a/www/src/styles/site.css b/www/src/styles/site.css
index 2c70bcf..5203b17 100644
--- a/www/src/styles/site.css
+++ b/www/src/styles/site.css
@@ -111,45 +111,43 @@ a {
   text-align: center;
 }
 
-.site-theme-button {
-  display: flex;
-  width: 2.25rem;
-  height: 2.25rem;
-  cursor: pointer;
-  align-items: center;
-  justify-content: center;
-  border: 0;
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+.site-theme-picker select {
+  padding: 0.35rem 0.5rem;
+  border: 1px solid var(--identity-border);
   border-radius: 0.5rem;
   background: transparent;
   color: var(--identity-foreground-secondary);
+  font-family: inherit;
+  font-size: 0.875rem;
+  cursor: pointer;
   transition: color 200ms ease-in-out;
 }
 
-.site-theme-button:hover {
+.site-theme-picker select:hover {
   color: var(--identity-foreground-bright);
 }
 
-.site-theme-button:focus-visible {
+.site-theme-picker select:focus-visible {
   outline: 2px solid var(--identity-primary);
   outline-offset: 2px;
   color: var(--identity-foreground-bright);
 }
 
-.site-theme-button svg {
-  width: 1.25rem;
-  height: 1.25rem;
-}
-
-.site-theme-icon-light {
-  display: none;
-}
-
-html.dark .site-theme-icon-dark {
-  display: none;
-}
-
-html.dark .site-theme-icon-light {
-  display: block;
+/* The list is painted by the OS, which does not inherit the transparent background. */
+.site-theme-picker option {
+  background: var(--identity-background);
+  color: var(--identity-foreground);
 }
 
 /* ─── Hero ─────────────────────────────────────────────────────────────────── */
diff --git a/www/src/themes.ts b/www/src/themes.ts
new file mode 100644
index 0000000..b918188
--- /dev/null
+++ b/www/src/themes.ts
@@ -0,0 +1,25 @@
+import { themes as packageThemes } from "@lancher-dev/jaamd/themes";
+
+export type SiteThemeMode = "light" | "dark" | "system";
+
+export interface SiteTheme {
+  slug: string;
+  name: string;
+  mode: SiteThemeMode;
+}
+
+/** The site's own palette, and the only entry that follows the operating system. */
+export const SITE_THEME: SiteTheme = {
+  slug: "jaamd",
+  name: "JAAMD",
+  mode: "system",
+};
+
+export const siteThemes: SiteTheme[] = [SITE_THEME, ...packageThemes];
+
+export const THEME_STORAGE_KEY = "jaamd-theme";
+
+/** slug → mode, the only thing the picker and the boot script need to agree on. */
+export const themeModes: Record<string, SiteThemeMode> = Object.fromEntries(
+  siteThemes.map((t) => [t.slug, t.mode]),
+);

From 87a576057d7723afe7c11fd955e061a7870725e7 Mon Sep 17 00:00:00 2001
From: Luca Pattocchio <15154851+Kasui92@users.noreply.github.com>
Date: Sun, 6 Sep 2026 19:24:44 +0200
Subject: [PATCH 3/6] upd: document the themes in the showcase

---
 www/src/content/showcase.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/www/src/content/showcase.md b/www/src/content/showcase.md
index f8a625b..e323a2b 100644
--- a/www/src/content/showcase.md
+++ b/www/src/content/showcase.md
@@ -3,6 +3,7 @@ you see below is the integration's own output.
 
 :::toc[Components]
 - [Installation](#installation)
+- [Themes](#themes)
 - [Table of contents](#table-of-contents)
 - [Alerts](#alerts)
 - [Code tabs](#code-tabs)
@@ -40,6 +41,23 @@ import MarkdownContent from "@lancher-dev/jaamd/components";
 
 ---
 
+## Themes
+
+The picker in the header switches between JAAMD's own palette, which follows your
+system, and the presets the package ships. The whole page follows — including the
+syntax colours, because Shiki bakes one variable per theme at build time and the
+switch is pure CSS.
+
+```css
+@import "@lancher-dev/jaamd/default.css";
+@import "@lancher-dev/jaamd/themes/nord.css";
+```
+
+A theme declares nine seed colours and everything else derives from them. Adding
+one is a directory and a manifest entry.
+
+---
+
 ## Table of contents
 
 The block above is markdown you write yourself: nothing is generated, so the

From 0409ec7655e96934a98801c5c41e1149d26ed04a Mon Sep 17 00:00:00 2001
From: Luca Pattocchio <15154851+Kasui92@users.noreply.github.com>
Date: Sun, 6 Sep 2026 20:13:41 +0200
Subject: [PATCH 4/6] feat: port five palettes from jaad and add the dual theme
 mode

---
 .../jaamd/src/themes/catppuccin/index.css     | 31 +++++++++++
 packages/jaamd/src/themes/gruvbox/index.css   | 33 ++++++++++++
 packages/jaamd/src/themes/index.ts            | 39 ++++++++++++--
 .../jaamd/src/themes/rose-pine-moon/index.css | 33 ++++++++++++
 packages/jaamd/src/themes/rose-pine/index.css | 33 ++++++++++++
 .../jaamd/src/themes/tokyo-night/dark.css     | 18 +++++++
 .../jaamd/src/themes/tokyo-night/index.css    | 18 +++++++
 scripts/build-themes.mjs                      | 22 ++++++--
 tests/unit/themes.mjs                         | 53 +++++++++++++++----
 9 files changed, 262 insertions(+), 18 deletions(-)
 create mode 100644 packages/jaamd/src/themes/catppuccin/index.css
 create mode 100644 packages/jaamd/src/themes/gruvbox/index.css
 create mode 100644 packages/jaamd/src/themes/rose-pine-moon/index.css
 create mode 100644 packages/jaamd/src/themes/rose-pine/index.css
 create mode 100644 packages/jaamd/src/themes/tokyo-night/dark.css
 create mode 100644 packages/jaamd/src/themes/tokyo-night/index.css

diff --git a/packages/jaamd/src/themes/catppuccin/index.css b/packages/jaamd/src/themes/catppuccin/index.css
new file mode 100644
index 0000000..55511c9
--- /dev/null
+++ b/packages/jaamd/src/themes/catppuccin/index.css
@@ -0,0 +1,31 @@
+/* JAAMD theme — Catppuccin. Latte in light, Mocha in dark. */
+
+:root {
+  --jaamd-bg:                     #eff1f5;
+  --jaamd-color-fg:               #4c4f69;
+  --jaamd-color-fg-bright:        #4c4f69;
+  --jaamd-color-primary:          #1e66f5;
+  --jaamd-color-success:          #40a02b;
+  --jaamd-alert-note-color:       #1e66f5;
+  --jaamd-alert-tip-color:        #40a02b;
+  --jaamd-alert-important-color:  #1e66f5;
+  --jaamd-alert-warning-color:    #df8e1d;
+  --jaamd-alert-caution-color:    #d20f39;
+
+  --jaamd-em-fg:                  #8839ef;
+}
+
+html.dark {
+  --jaamd-bg:                     #1e1e2e;
+  --jaamd-color-fg:               #cdd6f4;
+  --jaamd-color-fg-bright:        #cdd6f4;
+  --jaamd-color-primary:          #89b4fa;
+  --jaamd-color-success:          #a6e3a1;
+  --jaamd-alert-note-color:       #89b4fa;
+  --jaamd-alert-tip-color:        #a6e3a1;
+  --jaamd-alert-important-color:  #89b4fa;
+  --jaamd-alert-warning-color:    #f9e2af;
+  --jaamd-alert-caution-color:    #f38ba8;
+
+  --jaamd-em-fg:                  #cba6f7;
+}
diff --git a/packages/jaamd/src/themes/gruvbox/index.css b/packages/jaamd/src/themes/gruvbox/index.css
new file mode 100644
index 0000000..537ae0e
--- /dev/null
+++ b/packages/jaamd/src/themes/gruvbox/index.css
@@ -0,0 +1,33 @@
+/* JAAMD theme — Gruvbox. Light and dark, following the toggle. */
+
+:root {
+  --jaamd-bg:                     #fbf1c7;
+  --jaamd-color-fg:               #3c3836;
+  --jaamd-color-fg-bright:        #282828;
+  --jaamd-color-primary:          #458588;
+  --jaamd-color-success:          #98971a;
+  --jaamd-alert-note-color:       #458588;
+  --jaamd-alert-tip-color:        #98971a;
+  --jaamd-alert-important-color:  #458588;
+  --jaamd-alert-warning-color:    #d79921;
+  --jaamd-alert-caution-color:    #cc241d;
+
+  --jaamd-border-strong:          #d5c4a1;
+  --jaamd-em-fg:                  #b16286;
+}
+
+html.dark {
+  --jaamd-bg:                     #282828;
+  --jaamd-color-fg:               #ebdbb2;
+  --jaamd-color-fg-bright:        #fbf1c7;
+  --jaamd-color-primary:          #83a598;
+  --jaamd-color-success:          #b8bb26;
+  --jaamd-alert-note-color:       #83a598;
+  --jaamd-alert-tip-color:        #b8bb26;
+  --jaamd-alert-important-color:  #83a598;
+  --jaamd-alert-warning-color:    #fabd2f;
+  --jaamd-alert-caution-color:    #fb4934;
+
+  --jaamd-border-strong:          #665c54;
+  --jaamd-em-fg:                  #d3869b;
+}
diff --git a/packages/jaamd/src/themes/index.ts b/packages/jaamd/src/themes/index.ts
index d27ad94..c9ae459 100644
--- a/packages/jaamd/src/themes/index.ts
+++ b/packages/jaamd/src/themes/index.ts
@@ -3,21 +3,52 @@
  * this instead of hardcoding a list, and `tests/unit/themes.mjs` checks that
  * each entry matches a directory that honours the token contract.
  */
+/**
+ * `light` and `dark` are single palettes that apply in both modes; `dual` carries
+ * both, a `:root` block and an `html.dark` one, and follows whatever decides the
+ * mode. A `dual` theme has no `/dark` variant — its own file already does that.
+ */
+export type JaamdThemeMode = "light" | "dark" | "dual";
+
 export interface JaamdTheme {
   /** Directory name, and the value a `data-jaamd-theme` attribute would carry. */
   slug: string;
   /** Human-readable name, for pickers. */
   name: string;
-  /** Whether the palette expects `html.dark`. Not every theme is dark. */
-  mode: "light" | "dark";
-  /** Shiki theme that pairs with this palette. */
-  shiki: string;
+  mode: JaamdThemeMode;
+  /** Shiki theme that pairs with this palette, or a pair for a `dual` one. */
+  shiki: string | { light: string; dark: string };
 }
 
 export const themes: JaamdTheme[] = [
+  {
+    slug: "catppuccin",
+    name: "Catppuccin",
+    mode: "dual",
+    shiki: { light: "catppuccin-latte", dark: "catppuccin-mocha" },
+  },
   { slug: "dracula", name: "Dracula", mode: "dark", shiki: "dracula" },
+  {
+    slug: "gruvbox",
+    name: "Gruvbox",
+    mode: "dual",
+    shiki: { light: "gruvbox-light-medium", dark: "gruvbox-dark-medium" },
+  },
   { slug: "nord", name: "Nord", mode: "dark", shiki: "nord" },
   { slug: "one-dark", name: "One Dark", mode: "dark", shiki: "one-dark-pro" },
+  {
+    slug: "rose-pine",
+    name: "Rosé Pine",
+    mode: "dual",
+    shiki: { light: "rose-pine-dawn", dark: "rose-pine" },
+  },
+  {
+    slug: "rose-pine-moon",
+    name: "Rosé Pine Moon",
+    mode: "dual",
+    shiki: { light: "rose-pine-dawn", dark: "rose-pine-moon" },
+  },
+  { slug: "tokyo-night", name: "Tokyo Night", mode: "dark", shiki: "tokyo-night" },
 ];
 
 /** Seeds a theme must declare; everything else derives from them in variables.css. */
diff --git a/packages/jaamd/src/themes/rose-pine-moon/index.css b/packages/jaamd/src/themes/rose-pine-moon/index.css
new file mode 100644
index 0000000..5837196
--- /dev/null
+++ b/packages/jaamd/src/themes/rose-pine-moon/index.css
@@ -0,0 +1,33 @@
+/* JAAMD theme — Rosé Pine Moon. Dawn in light, moon in dark. */
+
+:root {
+  --jaamd-bg:                     #faf4ed;
+  --jaamd-color-fg:               #575279;
+  --jaamd-color-fg-bright:        #575279;
+  --jaamd-color-primary:          #286983;
+  --jaamd-color-success:          #286983;
+  --jaamd-alert-note-color:       #56949f;
+  --jaamd-alert-tip-color:        #286983;
+  --jaamd-alert-important-color:  #286983;
+  --jaamd-alert-warning-color:    #ea9d34;
+  --jaamd-alert-caution-color:    #b4637a;
+
+  --jaamd-border-strong:          #9893a5;
+  --jaamd-em-fg:                  #907aa9;
+}
+
+html.dark {
+  --jaamd-bg:                     #232136;
+  --jaamd-color-fg:               #e0def4;
+  --jaamd-color-fg-bright:        #e0def4;
+  --jaamd-color-primary:          #9ccfd8;
+  --jaamd-color-success:          #9ccfd8;
+  --jaamd-alert-note-color:       #3e8fb0;
+  --jaamd-alert-tip-color:        #9ccfd8;
+  --jaamd-alert-important-color:  #9ccfd8;
+  --jaamd-alert-warning-color:    #f6c177;
+  --jaamd-alert-caution-color:    #eb6f92;
+
+  --jaamd-border-strong:          #6e6a86;
+  --jaamd-em-fg:                  #c4a7e7;
+}
diff --git a/packages/jaamd/src/themes/rose-pine/index.css b/packages/jaamd/src/themes/rose-pine/index.css
new file mode 100644
index 0000000..6d4d8a5
--- /dev/null
+++ b/packages/jaamd/src/themes/rose-pine/index.css
@@ -0,0 +1,33 @@
+/* JAAMD theme — Rosé Pine. Dawn in light, main in dark. */
+
+:root {
+  --jaamd-bg:                     #faf4ed;
+  --jaamd-color-fg:               #575279;
+  --jaamd-color-fg-bright:        #575279;
+  --jaamd-color-primary:          #286983;
+  --jaamd-color-success:          #286983;
+  --jaamd-alert-note-color:       #56949f;
+  --jaamd-alert-tip-color:        #286983;
+  --jaamd-alert-important-color:  #286983;
+  --jaamd-alert-warning-color:    #ea9d34;
+  --jaamd-alert-caution-color:    #b4637a;
+
+  --jaamd-border-strong:          #9893a5;
+  --jaamd-em-fg:                  #907aa9;
+}
+
+html.dark {
+  --jaamd-bg:                     #191724;
+  --jaamd-color-fg:               #e0def4;
+  --jaamd-color-fg-bright:        #e0def4;
+  --jaamd-color-primary:          #9ccfd8;
+  --jaamd-color-success:          #9ccfd8;
+  --jaamd-alert-note-color:       #31748f;
+  --jaamd-alert-tip-color:        #9ccfd8;
+  --jaamd-alert-important-color:  #9ccfd8;
+  --jaamd-alert-warning-color:    #f6c177;
+  --jaamd-alert-caution-color:    #eb6f92;
+
+  --jaamd-border-strong:          #6e6a86;
+  --jaamd-em-fg:                  #c4a7e7;
+}
diff --git a/packages/jaamd/src/themes/tokyo-night/dark.css b/packages/jaamd/src/themes/tokyo-night/dark.css
new file mode 100644
index 0000000..8b1c41c
--- /dev/null
+++ b/packages/jaamd/src/themes/tokyo-night/dark.css
@@ -0,0 +1,18 @@
+/* JAAMD theme — Tokyo Night (dark mode only). A dark theme: it applies in both modes. */
+
+html.dark {
+  --jaamd-bg:                     #1a1b26;
+  --jaamd-color-fg:               #a9b1d6;
+  --jaamd-color-fg-bright:        #c0caf5;
+  --jaamd-color-primary:          #7aa2f7;
+  --jaamd-color-success:          #9ece6a;
+  --jaamd-alert-note-color:       #7dcfff;
+  --jaamd-alert-tip-color:        #9ece6a;
+  --jaamd-alert-important-color:  #7aa2f7;
+  --jaamd-alert-warning-color:    #e0af68;
+  --jaamd-alert-caution-color:    #f7768e;
+
+  --jaamd-border-strong:          #565f89;
+  --jaamd-color-primary-light:    #7dcfff;
+  --jaamd-em-fg:                  #bb9af7;
+}
diff --git a/packages/jaamd/src/themes/tokyo-night/index.css b/packages/jaamd/src/themes/tokyo-night/index.css
new file mode 100644
index 0000000..f8f6bd8
--- /dev/null
+++ b/packages/jaamd/src/themes/tokyo-night/index.css
@@ -0,0 +1,18 @@
+/* JAAMD theme — Tokyo Night. A dark theme: it applies in both modes. */
+
+:root {
+  --jaamd-bg:                     #1a1b26;
+  --jaamd-color-fg:               #a9b1d6;
+  --jaamd-color-fg-bright:        #c0caf5;
+  --jaamd-color-primary:          #7aa2f7;
+  --jaamd-color-success:          #9ece6a;
+  --jaamd-alert-note-color:       #7dcfff;
+  --jaamd-alert-tip-color:        #9ece6a;
+  --jaamd-alert-important-color:  #7aa2f7;
+  --jaamd-alert-warning-color:    #e0af68;
+  --jaamd-alert-caution-color:    #f7768e;
+
+  --jaamd-border-strong:          #565f89;
+  --jaamd-color-primary-light:    #7dcfff;
+  --jaamd-em-fg:                  #bb9af7;
+}
diff --git a/scripts/build-themes.mjs b/scripts/build-themes.mjs
index c7fdcfe..cf4dbfb 100644
--- a/scripts/build-themes.mjs
+++ b/scripts/build-themes.mjs
@@ -7,12 +7,17 @@
  * `--check` verifies the committed files instead of writing them.
  */
 
-import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { readdirSync, readFileSync, writeFileSync, rmSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { themes } from "../packages/jaamd/src/themes/index.ts";
+
 const THEMES = join(process.cwd(), "packages", "jaamd", "src", "themes");
 
+/** A dual theme carries both palettes already; a dark-only variant is meaningless. */
+const isDual = (slug) => themes.find((t) => t.slug === slug)?.mode === "dual";
+
 /** The dark variant of a theme's source. */
 export function darkVariant(source) {
   return source
@@ -29,12 +34,23 @@ function run(check) {
   const stale = [];
 
   for (const slug of slugs) {
+    const path = join(THEMES, slug, "dark.css");
+
+    if (isDual(slug)) {
+      if (check) {
+        if (existsSync(path)) stale.push(`${slug} (dual, should have no dark.css)`);
+      } else if (existsSync(path)) {
+        rmSync(path);
+        console.log(`✓ ${slug}/dark.css removed (dual)`);
+      }
+      continue;
+    }
+
     const source = readFileSync(join(THEMES, slug, "index.css"), "utf8");
     const expected = darkVariant(source);
-    const path = join(THEMES, slug, "dark.css");
 
     if (check) {
-      if (readFileSync(path, "utf8") !== expected) stale.push(slug);
+      if (!existsSync(path) || readFileSync(path, "utf8") !== expected) stale.push(slug);
       continue;
     }
 
diff --git a/tests/unit/themes.mjs b/tests/unit/themes.mjs
index 765f60a..8c22059 100644
--- a/tests/unit/themes.mjs
+++ b/tests/unit/themes.mjs
@@ -35,16 +35,30 @@ for (const slug of slugs) {
   );
   if (!entry) continue;
 
+  const dual = entry.mode === "dual";
+
+  check(
+    `${slug}: mode is light, dark or dual`,
+    ["light", "dark", "dual"].includes(entry.mode),
+    `mode was ${JSON.stringify(entry.mode)}; consumers use it to decide html.dark`,
+  );
+
+  const shiki =
+    typeof entry.shiki === "string" ? [entry.shiki] : Object.values(entry.shiki ?? {});
+  const unknown = shiki.filter((name) => !Object.hasOwn(bundledThemes, name));
+
   check(
-    `${slug}: mode is light or dark`,
-    entry.mode === "light" || entry.mode === "dark",
-    `mode was ${JSON.stringify(entry.mode)}; consumers use it to set html.dark`,
+    `${slug}: pairs with real Shiki theme(s)`,
+    shiki.length > 0 && unknown.length === 0,
+    unknown.length
+      ? `not bundled by Shiki: ${unknown.join(", ")}`
+      : "no Shiki theme declared",
   );
 
   check(
-    `${slug}: pairs with a real Shiki theme`,
-    Object.hasOwn(bundledThemes, entry.shiki),
-    `"${entry.shiki}" is not a bundled Shiki theme`,
+    `${slug}: a dual theme declares a Shiki pair`,
+    !dual || (typeof entry.shiki === "object" && entry.shiki.light && entry.shiki.dark),
+    "a dual palette needs a light and a dark Shiki theme to match it",
   );
 
   const indexPath = join(THEMES, slug, "index.css");
@@ -56,8 +70,21 @@ for (const slug of slugs) {
   }
 
   const source = readFileSync(indexPath, "utf8");
-  const missing = REQUIRED_TOKENS.filter(
-    (token) => !new RegExp(`^\\s*${token}\\s*:`, "m").test(source),
+
+  // A dual theme must carry the seeds in both of its blocks, or one mode silently
+  // borrows the other's background.
+  const blocks = dual
+    ? source.split(/^html\.dark \{$/m)
+    : [source];
+
+  check(
+    `${slug}: has both a light and a dark block`,
+    !dual || blocks.length === 2,
+    "a dual theme needs a :root block and an html.dark one",
+  );
+
+  const missing = REQUIRED_TOKENS.filter((token) =>
+    blocks.some((b) => !new RegExp(`^\\s*${token}\\s*:`, "m").test(b)),
   );
 
   check(
@@ -67,9 +94,13 @@ for (const slug of slugs) {
   );
 
   check(
-    `${slug}: dark.css is in sync`,
-    existsSync(darkPath) && readFileSync(darkPath, "utf8") === darkVariant(source),
-    "run `pnpm build:themes` and commit the result",
+    `${slug}: dark.css matches its mode`,
+    dual
+      ? !existsSync(darkPath)
+      : existsSync(darkPath) && readFileSync(darkPath, "utf8") === darkVariant(source),
+    dual
+      ? "a dual theme already covers dark mode; it must not ship a /dark variant"
+      : "run `pnpm build:themes` and commit the result",
   );
 }
 

From 1a3a6a21dd8f55f69a939f059513c862d7164f79 Mon Sep 17 00:00:00 2001
From: Luca Pattocchio <15154851+Kasui92@users.noreply.github.com>
Date: Sun, 6 Sep 2026 20:13:48 +0200
Subject: [PATCH 5/6] upd: rename the site theme to Default and follow dual
 palettes

---
 tests/build/smoke.mjs                    | 19 ++++++---
 www/astro.config.mjs                     |  7 +---
 www/src/components/SiteThemePicker.astro |  6 +--
 www/src/layouts/SiteLayout.astro         | 50 ++++++++++++++++-------
 www/src/styles/jaamd.css                 |  4 +-
 www/src/themes.ts                        | 51 +++++++++++++++++-------
 6 files changed, 91 insertions(+), 46 deletions(-)

diff --git a/tests/build/smoke.mjs b/tests/build/smoke.mjs
index 0f78c92..c8ccc6d 100644
--- a/tests/build/smoke.mjs
+++ b/tests/build/smoke.mjs
@@ -7,6 +7,8 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 
+import { themes } from "../../packages/jaamd/src/themes/index.ts";
+
 const DIST = join(process.cwd(), "www", "dist");
 const PAGE = join(DIST, "index.html");
 
@@ -159,16 +161,21 @@ check(
 
 check(
   "themes: the site bridge is scoped too",
-  /\[data-jaamd-theme=("?)jaamd\1\]/.test(css),
+  /\[data-jaamd-theme=("?)default\1\]/.test(css),
   "an unscoped bridge outranks the themes, so only secondary colours would change",
 );
 
-// One Shiki variable per theme is what lets code follow the switch.
-for (const slug of themeSlugs) {
+// One Shiki variable per key is what lets code follow the switch; a dual theme
+// needs two, or one of its two modes keeps the previous theme's syntax colours.
+for (const theme of themes) {
+  const keys =
+    theme.mode === "dual" ? [theme.slug, `${theme.slug}-dark`] : [theme.slug];
+  const absent = keys.filter((key) => !html.includes(`--shiki-${key}:`));
+
   check(
-    `themes: ${slug} has its Shiki colours baked`,
-    html.includes(`--shiki-${slug}:`),
-    `add ${slug} to shikiConfig.themes, or its code blocks keep the previous theme`,
+    `themes: ${theme.slug} has its Shiki colours baked`,
+    absent.length === 0,
+    `missing --shiki-${absent.join(", --shiki-")} in the rendered code`,
   );
 }
 
diff --git a/www/astro.config.mjs b/www/astro.config.mjs
index 80d6c2d..b910cd3 100644
--- a/www/astro.config.mjs
+++ b/www/astro.config.mjs
@@ -1,15 +1,10 @@
 import { defineConfig, fontProviders } from "astro/config";
 import jaamd from "@lancher-dev/jaamd";
-import { themes } from "@lancher-dev/jaamd/themes";
+import { shikiThemes } from "./src/themes.ts";
 
 // Shiki takes arbitrary theme keys and emits --shiki-<key> per token, so every
 // theme is baked at build time and switched with CSS. jaamd's own option accepts
 // only light/dark, so the rest are added here, after it.
-const shikiThemes = {
-  light: "github-light",
-  dark: "one-dark-pro",
-  ...Object.fromEntries(themes.map((t) => [t.slug, t.shiki])),
-};
 
 /** @type {import("astro").AstroIntegration} */
 const shikiMultiTheme = {
diff --git a/www/src/components/SiteThemePicker.astro b/www/src/components/SiteThemePicker.astro
index 377708c..e446861 100644
--- a/www/src/components/SiteThemePicker.astro
+++ b/www/src/components/SiteThemePicker.astro
@@ -25,7 +25,7 @@ import { siteThemes, SITE_THEME } from "../themes.ts";
     document.documentElement.dataset.jaamdTheme = slug;
     document.documentElement.classList.toggle(
       "dark",
-      mode === "dark" || (mode === "system" && prefersDark.matches),
+      mode === "dark" || (mode === "dual" && prefersDark.matches),
     );
   }
 
@@ -47,10 +47,10 @@ import { siteThemes, SITE_THEME } from "../themes.ts";
         }
       });
 
-      // Only the site's own theme follows the system, and only while it is active.
+      // Dual themes carry both palettes, so they follow the system while active.
       prefersDark.addEventListener("change", () => {
         const slug = document.documentElement.dataset.jaamdTheme;
-        if (slug && themeModes[slug] === "system") apply(slug);
+        if (slug && themeModes[slug] === "dual") apply(slug);
       });
     }
   }
diff --git a/www/src/layouts/SiteLayout.astro b/www/src/layouts/SiteLayout.astro
index b61fe80..7b66bd2 100644
--- a/www/src/layouts/SiteLayout.astro
+++ b/www/src/layouts/SiteLayout.astro
@@ -3,37 +3,59 @@ import { createRequire } from "node:module";
 import { readFileSync } from "node:fs";
 import { Font } from "astro:assets";
 import { themes as packageThemes } from "@lancher-dev/jaamd/themes";
+import type { JaamdTheme } from "@lancher-dev/jaamd/themes";
 import "@lancher-dev/jaamd/default.css";
 import "@lancher-dev/jaamd/styles.css";
 import "../styles/identity.css";
 import "../styles/jaamd.css";
 import "../styles/site.css";
 import SiteThemePicker from "../components/SiteThemePicker.astro";
-import { themeModes, THEME_STORAGE_KEY, SITE_THEME } from "../themes.ts";
+import {
+  themeModes,
+  THEME_STORAGE_KEY,
+  SITE_THEME,
+  shikiKeys,
+} from "../themes.ts";
 
 const require = createRequire(import.meta.url);
 
+/**
+ * Shiki bakes one variable per configured key; this picks which one the code
+ * reads. `.dark` / `:not(.dark)` is not decoration — without it the selector
+ * ties with shiki-dual.css and injection order would decide the winner.
+ */
+function shikiRule(scope: string, key: string) {
+  return `${scope} .jaamd-content .astro-code span,
+${scope} .jaamd-content .shiki span {
+  color: var(--shiki-${key}) !important;
+  font-style: var(--shiki-${key}-font-style) !important;
+  font-weight: var(--shiki-${key}-font-weight) !important;
+  text-decoration: var(--shiki-${key}-text-decoration) !important;
+}`;
+}
+
 // Themes are authored on :root, so importing more than one would just let the
 // last win. Re-scoped here, at build time, so they can coexist and be switched.
 const themeCss = packageThemes
-  .map(({ slug }) => {
+  .map((theme: JaamdTheme) => {
+    const { slug } = theme;
     const source = readFileSync(
       require.resolve(`@lancher-dev/jaamd/themes/${slug}.css`),
       "utf8",
     );
-    const scope = `html[data-jaamd-theme="${slug}"]`;
+    const attr = `[data-jaamd-theme="${slug}"]`;
+    const keys = shikiKeys(theme);
 
-    // Shiki bakes one variable per configured theme; this picks which one the
-    // code reads. More specific than shiki-dual.css, so injection order is moot.
-    const code = `${scope}.dark .jaamd-content .astro-code span,
-${scope}.dark .jaamd-content .shiki span {
-  color: var(--shiki-${slug}) !important;
-  font-style: var(--shiki-${slug}-font-style) !important;
-  font-weight: var(--shiki-${slug}-font-weight) !important;
-  text-decoration: var(--shiki-${slug}-text-decoration) !important;
-}`;
+    const scoped = source
+      .replace(/^:root \{$/m, `html${attr} {`)
+      .replace(/^html\.dark \{$/m, `html.dark${attr} {`);
+
+    const rules = [
+      keys.light && shikiRule(`html${attr}:not(.dark)`, keys.light),
+      keys.dark && shikiRule(`html.dark${attr}`, keys.dark),
+    ].filter(Boolean);
 
-    return `${source.replace(/^:root \{$/m, `${scope} {`)}\n${code}`;
+    return [scoped, ...rules].join("\n");
   })
   .join("\n\n");
 
@@ -52,7 +74,7 @@ const themeScript = `(function () {
 
   var mode = modes[slug];
   var dark = mode === "dark" ||
-    (mode === "system" && matchMedia("(prefers-color-scheme: dark)").matches);
+    (mode === "dual" && matchMedia("(prefers-color-scheme: dark)").matches);
 
   document.documentElement.dataset.jaamdTheme = slug;
   document.documentElement.classList.toggle("dark", dark);
diff --git a/www/src/styles/jaamd.css b/www/src/styles/jaamd.css
index f8720e6..c0c4b1d 100644
--- a/www/src/styles/jaamd.css
+++ b/www/src/styles/jaamd.css
@@ -13,7 +13,7 @@ html {
 
 /* The site's own theme, and the state before the boot script runs. */
 html:not([data-jaamd-theme]),
-html[data-jaamd-theme="jaamd"] {
+html[data-jaamd-theme="default"] {
   --jaamd-bg: var(--identity-background);
   --jaamd-color-fg: var(--identity-foreground);
   --jaamd-color-fg-bright: var(--identity-foreground-bright);
@@ -23,7 +23,7 @@ html[data-jaamd-theme="jaamd"] {
 /* Every package theme, in reverse: the chrome follows the article rather than the
    site knowing each palette. Borders and muted text derive from these in
    identity.css, so four seeds are enough. */
-html[data-jaamd-theme]:not([data-jaamd-theme="jaamd"]) {
+html[data-jaamd-theme]:not([data-jaamd-theme="default"]) {
   --identity-background: var(--jaamd-bg);
   --identity-foreground: var(--jaamd-color-fg);
   --identity-foreground-bright: var(--jaamd-color-fg-bright);
diff --git a/www/src/themes.ts b/www/src/themes.ts
index b918188..edd7c48 100644
--- a/www/src/themes.ts
+++ b/www/src/themes.ts
@@ -1,25 +1,46 @@
 import { themes as packageThemes } from "@lancher-dev/jaamd/themes";
+import type { JaamdTheme, JaamdThemeMode } from "@lancher-dev/jaamd/themes";
 
-export type SiteThemeMode = "light" | "dark" | "system";
-
-export interface SiteTheme {
-  slug: string;
-  name: string;
-  mode: SiteThemeMode;
-}
-
-/** The site's own palette, and the only entry that follows the operating system. */
-export const SITE_THEME: SiteTheme = {
-  slug: "jaamd",
-  name: "JAAMD",
-  mode: "system",
+/**
+ * The site's own palette. `dual` like any theme that carries both a light and a
+ * dark block: with one picker and no separate toggle, those follow the system.
+ */
+export const SITE_THEME: JaamdTheme = {
+  slug: "default",
+  name: "Default",
+  mode: "dual",
+  shiki: { light: "github-light", dark: "one-dark-pro" },
 };
 
-export const siteThemes: SiteTheme[] = [SITE_THEME, ...packageThemes];
+export const siteThemes: JaamdTheme[] = [SITE_THEME, ...packageThemes];
 
 export const THEME_STORAGE_KEY = "jaamd-theme";
 
 /** slug → mode, the only thing the picker and the boot script need to agree on. */
-export const themeModes: Record<string, SiteThemeMode> = Object.fromEntries(
+export const themeModes: Record<string, JaamdThemeMode> = Object.fromEntries(
   siteThemes.map((t) => [t.slug, t.mode]),
 );
+
+/**
+ * Shiki bakes one set of variables per key. A dual theme needs two, so its dark
+ * palette gets `<slug>-dark`.
+ */
+export function shikiKeys(theme: JaamdTheme): { light?: string; dark?: string } {
+  if (typeof theme.shiki === "string") {
+    return theme.mode === "light" ? { light: theme.slug } : { dark: theme.slug };
+  }
+  return { light: theme.slug, dark: `${theme.slug}-dark` };
+}
+
+export const shikiThemes: Record<string, string> = Object.fromEntries(
+  siteThemes.flatMap((theme) => {
+    const keys = shikiKeys(theme);
+    const shiki = theme.shiki;
+    return typeof shiki === "string"
+      ? [[keys.light ?? keys.dark!, shiki]]
+      : [
+          [keys.light!, shiki.light],
+          [keys.dark!, shiki.dark],
+        ];
+  }),
+);

From 788298ad18e60262bc7a20204c2737fd3650f7c0 Mon Sep 17 00:00:00 2001
From: Luca Pattocchio <15154851+Kasui92@users.noreply.github.com>
Date: Sun, 6 Sep 2026 20:13:48 +0200
Subject: [PATCH 6/6] upd: document the dual theme mode and the ported palettes

---
 CONTRIBUTING.md          | 19 +++++++++++++------
 packages/jaamd/README.md | 26 +++++++++++++++++---------
 2 files changed, 30 insertions(+), 15 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e3b6544..a140683 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -15,7 +15,9 @@ A theme is a directory under `packages/jaamd/src/themes/<slug>/` plus one entry
 
 ### 1. Write `index.css`
 
-One `:root` block of `--jaamd-*` declarations. These **seeds are required**:
+A `:root` block of `--jaamd-*` declarations. A theme that has both a light and a
+dark palette adds a second block on `html.dark`, and must repeat the seeds there —
+otherwise one mode borrows the other's background. These **seeds are required**:
 
 | Token | What it is |
 |---|---|
@@ -38,9 +40,13 @@ Do not restate the font tokens: they are the defaults already.
 
 ### 2. Declare it
 
-Add an entry to `src/themes/index.ts` with the directory name as `slug`, a readable
-`name`, the `mode` the palette expects (`"light"` or `"dark"` — themes are not
-assumed to be dark), and the `shiki` theme that pairs with it.
+Add an entry to `src/themes/index.ts` with the directory name as `slug` and a
+readable `name`, plus:
+
+| `mode` | The palette is | `shiki` |
+|---|---|---|
+| `"light"` / `"dark"` | one palette, applying in both modes | one theme name |
+| `"dual"` | two palettes, `:root` and `html.dark` | `{ light, dark }` |
 
 ### 3. Generate the dark variant
 
@@ -48,8 +54,9 @@ assumed to be dark), and the `shiki` theme that pairs with it.
 pnpm build:themes
 ```
 
-`dark.css` is `index.css` under `html.dark`, generated and committed. Never edit it
-by hand.
+`dark.css` is `index.css` under `html.dark` — the variant for using a single-palette
+theme only in dark mode. It is generated and committed; never edit it by hand. A
+`dual` theme covers dark mode itself and gets no `dark.css`.
 
 ### 4. Check it
 
diff --git a/packages/jaamd/README.md b/packages/jaamd/README.md
index 353dd0b..1fb8b3f 100644
--- a/packages/jaamd/README.md
+++ b/packages/jaamd/README.md
@@ -375,14 +375,20 @@ The default set includes dark-mode overrides activated by the `dark` class on
 
 ### Theme presets
 
-Three presets restyle all `--jaamd-*` variables to match popular editor colour
-schemes:
-
-| Preset | Import | Recommended Shiki theme |
-|--------|--------|------------------------|
-| Dracula | `@lancher-dev/jaamd/themes/dracula` | `dracula` |
-| Nord | `@lancher-dev/jaamd/themes/nord` | `nord` |
-| One Dark | `@lancher-dev/jaamd/themes/one-dark` | `one-dark-pro` |
+Eight presets restyle the `--jaamd-*` palette to match popular editor colour
+schemes. A **dual** preset carries a light and a dark palette and follows
+`html.dark`; the others are one palette that applies in both modes.
+
+| Preset | Import | Kind | Recommended Shiki theme |
+|--------|--------|------|------------------------|
+| Catppuccin | `@lancher-dev/jaamd/themes/catppuccin` | dual | `catppuccin-latte` / `catppuccin-mocha` |
+| Dracula | `@lancher-dev/jaamd/themes/dracula` | dark | `dracula` |
+| Gruvbox | `@lancher-dev/jaamd/themes/gruvbox` | dual | `gruvbox-light-medium` / `gruvbox-dark-medium` |
+| Nord | `@lancher-dev/jaamd/themes/nord` | dark | `nord` |
+| One Dark | `@lancher-dev/jaamd/themes/one-dark` | dark | `one-dark-pro` |
+| Rosé Pine | `@lancher-dev/jaamd/themes/rose-pine` | dual | `rose-pine-dawn` / `rose-pine` |
+| Rosé Pine Moon | `@lancher-dev/jaamd/themes/rose-pine-moon` | dual | `rose-pine-dawn` / `rose-pine-moon` |
+| Tokyo Night | `@lancher-dev/jaamd/themes/tokyo-night` | dark | `tokyo-night` |
 
 As a standalone theme, replacing the default light theme:
 
@@ -396,7 +402,9 @@ jaamd({ theme: "dracula" })
 @import "@lancher-dev/jaamd/styles.css";
 ```
 
-Scoped to `html.dark` via the `/dark` variant:
+A single-palette preset can also be scoped to `html.dark` via the `/dark` variant,
+to use it as the dark half of your own light theme. Dual presets already cover both
+modes and have no `/dark`:
 
 ```css
 @import "@lancher-dev/jaamd/themes/dracula/dark.css";