@rmdes/indiekit-endpoint-site-config 1.0.0-beta.3 → 1.0.0-beta.5

package/lib/controllers/api.js

@@ -79,14 +79,6 @@ export function apiRouter(Indiekit) {
           ? req.query.previewMode
           : configForPreview.branding.mode;
 
-      // We render theme.css with the pending mode so the preview iframe
-      // shows colors for the chosen side without needing JS to flip
-      // .dark on the iframe (which works too — both paths are wired).
-      const themeConfig = {
-        ...configForPreview,
-        branding: { ...configForPreview.branding, mode: previewMode },
-      };
-
       // Run contrast check on the preview's resolved state so the iframe
       // can show whether the visible colors are passing. Wrapped in try
       // so a broken accentBase doesn't blow up the preview.
@@ -96,7 +88,10 @@ export function apiRouter(Indiekit) {
         contrastResults = [];
       }
 
-      const themeCss = renderThemeCss(themeConfig);
+      // Preview always emits both light + dark (class-scoped) so the iframe's
+      // Light/Dark toggle works regardless of the saved mode. `previewMode`
+      // only selects which side is shown FIRST (via the toggle JS below).
+      const themeCss = renderThemeCss(configForPreview, { preview: true });
       res.setHeader("Content-Type", "text/html");
       res.setHeader("X-Content-Type-Options", "nosniff");
       res.setHeader("Cache-Control", "no-store");
@@ -186,10 +181,12 @@ export function apiRouter(Indiekit) {
  * elements (heading, body text, link, action button, card, focus state,
  * alert pills) so users see how each token affects real surfaces.
  *
- * The light/dark mode toggle is a vanilla `<button>` with inline JS that
- * adds/removes a `.dark` class on the document element AND persists the
- * choice in localStorage. The persisted choice is read on load and
- * applied to the html element.
+ * The light/dark mode toggle is a vanilla `<button>` with inline JS that sets
+ * an explicit `.light` OR `.dark` class on the document element (mutually
+ * exclusive) AND persists the choice in localStorage. Because the preview
+ * theme CSS (rendered with { preview: true }) ships both class-scoped blocks,
+ * the toggle always works — independent of the saved mode and the host OS
+ * color-scheme preference. The persisted choice is read on load and applied.
  *
  * Exported for unit testing.
  */
@@ -364,8 +361,13 @@ ${themeCss}
       var buttons = document.querySelectorAll('[data-pv-mode]');
 
       function apply(mode) {
-        if (mode === 'dark') html.classList.add('dark');
-        else html.classList.remove('dark');
+        if (mode === 'dark') {
+          html.classList.add('dark');
+          html.classList.remove('light');
+        } else {
+          html.classList.add('light');
+          html.classList.remove('dark');
+        }
         buttons.forEach(function (b) {
           var active = b.getAttribute('data-pv-mode') === mode;
           b.classList.toggle('pv-toggle--active', active);

package/lib/controllers/branding.js

@@ -53,11 +53,11 @@ export const ACCENT_SUGGESTIONS = Object.freeze([
  * @type {ReadonlyArray<{slug: string, label: string}>}
  */
 export const SURFACE_PRESET_OPTIONS = Object.freeze([
-  Object.freeze({ slug: "warm-stone",   label: "Warm Stone" }),
-  Object.freeze({ slug: "warm-gray",    label: "Warm Gray" }),
-  Object.freeze({ slug: "stone",        label: "Stone (Neutral)" }),
-  Object.freeze({ slug: "cool-slate",   label: "Cool Slate" }),
-  Object.freeze({ slug: "neutral-zinc", label: "Neutral Zinc" }),
+  Object.freeze({ slug: "warm-stone", label: "Warm Stone" }),
+  Object.freeze({ slug: "clay",       label: "Clay" }),
+  Object.freeze({ slug: "stone",      label: "Stone (Neutral)" }),
+  Object.freeze({ slug: "cool-slate", label: "Cool Slate" }),
+  Object.freeze({ slug: "sage",       label: "Sage" }),
 ]);
 
 /**
@@ -454,7 +454,14 @@ export function brandingRouter(Indiekit) {
         activeTab: "branding",
         curatedFonts: CURATED_FONTS,
         roleDefaults,
-        surfacePresets: SURFACE_PRESET_OPTIONS,
+        // Attach each preset's tone ramp (50→950) so the view can render a
+        // swatch strip — letting operators SEE each palette's identity before
+        // selecting it (the light-end tones look similar; the ramp shows the
+        // full character of each preset).
+        surfacePresets: SURFACE_PRESET_OPTIONS.map((opt) => ({
+          ...opt,
+          ramp: Object.values(SURFACE_PRESETS[opt.slug] || {}),
+        })),
         accentSuggestions: ACCENT_SUGGESTIONS,
         contrastResults,
         contrastFailures,

package/lib/render/surface-presets.js

@@ -1,8 +1,14 @@
-// `cool-slate`, `neutral-zinc`, `warm-gray`, and `stone` palette values are
-// derived from Tailwind CSS, MIT License — Copyright (c) Tailwind Labs, Inc.
-// https://tailwindcss.com/docs/customizing-colors
+// Surface presets — the neutral/tinted base palettes offered in the branding
+// admin. Each is an 11-step tone ramp (50 lightest → 950 darkest).
 //
-// `warm-stone` is the original rmendes.net palette.
+//   warm-stone — warm taupe/brown (original rmendes.net palette)
+//   cool-slate — blue-gray (Tailwind "slate")
+//   stone      — true neutral gray (Tailwind "neutral")
+//   sage       — green-tinted neutral
+//   clay       — terracotta/rose-tinted warm
+//
+// `cool-slate` and `stone` ramps are from Tailwind CSS (MIT License,
+// Copyright (c) Tailwind Labs, Inc. — https://tailwindcss.com/docs/colors).
 export const SURFACE_PRESETS = Object.freeze({
   "warm-stone": Object.freeze({
     50:  "#faf8f5", 100: "#f4f2ee", 200: "#e8e5df",
@@ -16,18 +22,19 @@ export const SURFACE_PRESETS = Object.freeze({
     600: "#475569", 700: "#334155", 800: "#1e293b",
     900: "#0f172a", 950: "#020617",
   }),
-  "neutral-zinc": Object.freeze({
-    50:  "#fafafa", 100: "#f4f4f5", 200: "#e4e4e7",
-    300: "#d4d4d8", 400: "#a1a1aa", 500: "#71717a",
-    600: "#52525b", 700: "#3f3f46", 800: "#27272a",
-    900: "#18181b", 950: "#09090b",
+  // Sage — green-tinted neutral.
+  "sage": Object.freeze({
+    50:  "#f3f7f1", 100: "#e6efe3", 200: "#cfe0ca",
+    300: "#aecaa6", 400: "#82a878", 500: "#5e8a5a",
+    600: "#496e47", 700: "#3a5638", 800: "#283a27",
+    900: "#1a271a", 950: "#0e150e",
   }),
-  "warm-gray": Object.freeze({
-    // Tailwind "stone" rebranded as a warm-leaning gray.
-    50:  "#fafaf9", 100: "#f5f5f4", 200: "#e7e5e4",
-    300: "#d6d3d1", 400: "#a8a29e", 500: "#78716c",
-    600: "#57534e", 700: "#44403c", 800: "#292524",
-    900: "#1c1917", 950: "#0c0a09",
+  // Clay — terracotta/rose-tinted warm.
+  "clay": Object.freeze({
+    50:  "#faf4f1", 100: "#f4e7e1", 200: "#e8d2c7",
+    300: "#d8b3a2", 400: "#c08b73", 500: "#a8705a",
+    600: "#8a5642", 700: "#6d4334", 800: "#492d23",
+    900: "#2f1d16", 950: "#1a0f0b",
   }),
   "stone": Object.freeze({
     // Tailwind "neutral" — the truest gray with no warm or cool bias.

package/lib/render/write-theme-css.js

@@ -209,9 +209,18 @@ export function resolveBothModes(branding) {
  * Tier 3 contract. Mode handling follows the v2 spec §6.1.
  *
  * @param {object} config - Merged site config object (output of mergeWithDefaults)
+ * @param {object} [options]
+ * @param {boolean} [options.preview=false] - Preview mode. The live-preview
+ *   iframe is a design tool: its Light/Dark toggle must ALWAYS work regardless
+ *   of the saved `mode`. So in preview mode we emit BOTH a light and a dark
+ *   set, scoped to explicit `.light` / `.dark` classes (driven by the toolbar
+ *   toggle), with `:root` defaulting to light. No `prefers-color-scheme` media
+ *   query is used — the operator's explicit toggle choice should win over the
+ *   host OS preference while inspecting a design. The production path (no
+ *   options) is unchanged and still honors `mode` per spec §6.1.
  * @returns {string} CSS source ready to be written or served
  */
-export function renderThemeCss(config) {
+export function renderThemeCss(config, options = {}) {
   const branding = config.branding;
   const { light, dark, surface, accent } = resolveBothModes(branding);
   const mode = branding.mode || "auto";
@@ -225,6 +234,36 @@ export function renderThemeCss(config) {
     typographyBlock(branding.typography),
   ].join("\n");
 
+  // Preview mode: emit both light and dark as explicit, class-scoped blocks so
+  // the iframe's Light/Dark toggle is always functional and OS-independent.
+  if (options.preview === true) {
+    return [
+      ":root {",
+      shared,
+      "  /* Tier 3 — alerts (light) */",
+      tier3Block("light"),
+      "  /* Tier 2 — semantic roles (light) */",
+      tier2Block(light),
+      "}",
+      "",
+      // Explicit light class so the toggle can force light over any default.
+      ".light {",
+      "  /* Tier 3 — alerts (light) */",
+      tier3Block("light"),
+      "  /* Tier 2 — semantic roles (light) */",
+      tier2Block(light),
+      "}",
+      "",
+      ".dark {",
+      "  /* Tier 3 — alerts (dark) */",
+      tier3Block("dark"),
+      "  /* Tier 2 — semantic roles (dark) */",
+      tier2Block(dark),
+      "}",
+      "",
+    ].join("\n");
+  }
+
   // Tier 3 alerts vary by mode (different RGB values for light vs dark).
   // For "light" / "dark" modes we emit only the matching set in :root.
   // For "auto" we put light alerts in :root and dark alerts in both

package/locales/en.json

@@ -78,7 +78,7 @@
         "advancedDesc": "Most sites should leave these alone — the palette already derives them. Override only if you have a strong reason."
       },
       "surfacePreset": "Surface preset",
-      "surfacePresetHint": "Pick a neutral base palette. Warm Stone is cream/brown. Cool Slate is blue-gray. Neutral Zinc is a pure gray. Custom lets you define all 11 tones manually.",
+      "surfacePresetHint": "Pick a base palette. Warm Stone is cream/brown, Clay is terracotta/rose, Stone is a pure gray, Cool Slate is blue-gray, Sage is green-tinted. Custom lets you define all 11 tones manually.",
       "surfacePresetCustom": "Custom (advanced)",
       "surfaceCustom": "Custom surface tones",
       "surfaceCustomHint": "11 tones from lightest (50) to darkest (950). Applied only when the surface preset above is set to Custom.",

package/locales/fr.json

@@ -78,7 +78,7 @@
         "advancedDesc": "La plupart des sites devraient laisser ces options telles quelles — la palette les dérive déjà. Ne les remplacez qu'avec une bonne raison."
       },
       "surfacePreset": "Palette de fond",
-      "surfacePresetHint": "Choisissez une palette neutre de base. Warm Stone est crème/brun. Cool Slate est bleu-gris. Neutral Zinc est un gris pur. Custom vous permet de définir manuellement les 11 tons.",
+      "surfacePresetHint": "Choisissez une palette de base. Warm Stone est crème/brun, Clay est terracotta/rosé, Stone est un gris pur, Cool Slate est bleu-gris, Sage est teinté vert. Custom vous permet de définir manuellement les 11 tons.",
       "surfacePresetCustom": "Personnalisé (avancé)",
       "surfaceCustom": "Tons personnalisés",
       "surfaceCustomHint": "11 tons du plus clair (50) au plus sombre (950). Appliqué uniquement lorsque la palette de fond ci-dessus est définie sur Personnalisé.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmdes/indiekit-endpoint-site-config",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "type": "module",
   "description": "Site identity, branding, and navigation configuration for Indiekit",
   "main": "index.js",

package/views/site-config-branding.njk

@@ -122,6 +122,32 @@
     background: color-mix(in srgb, var(--color-primary, #0066cc) 8%, var(--color-background, #fff));
   }
 
+  /* Surface preset options with a tone-ramp preview */
+  .sc-preset-option {
+    flex-direction: column;
+    align-items: stretch;
+    gap: var(--space-2xs, 0.375rem);
+    min-width: 9rem;
+  }
+
+  .sc-preset-option__head {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2xs, 0.375rem);
+  }
+
+  .sc-preset-ramp {
+    display: flex;
+    height: 0.85rem;
+    border-radius: 0.2rem;
+    overflow: hidden;
+    border: 1px solid var(--color-outline-variant, #ddd);
+  }
+
+  .sc-preset-chip {
+    flex: 1 1 0;
+  }
+
   /* Generic color picker (palette inputs) */
   .sc-color-picker {
     display: flex;
@@ -495,10 +521,19 @@
         <p class="field__hint">{{ __("siteConfig.branding.surfacePresetHint") }}</p>
         <div class="sc-radio-group">
           {% for preset in surfacePresets %}
-            <label class="sc-radio-label">
-              <input type="radio" name="surfacePreset" value="{{ preset.slug }}"
-                     {% if config.branding.surfacePreset == preset.slug %}checked{% endif %}>
-              {{ preset.label }}
+            <label class="sc-radio-label sc-preset-option">
+              <span class="sc-preset-option__head">
+                <input type="radio" name="surfacePreset" value="{{ preset.slug }}"
+                       {% if config.branding.surfacePreset == preset.slug %}checked{% endif %}>
+                {{ preset.label }}
+              </span>
+              {% if preset.ramp %}
+              <span class="sc-preset-ramp" aria-hidden="true">
+                {% for tone in preset.ramp %}
+                  <span class="sc-preset-chip" style="background-color: {{ tone }};"></span>
+                {% endfor %}
+              </span>
+              {% endif %}
             </label>
           {% endfor %}
           <label class="sc-radio-label">