feat(docs): make warm paper the default light theme

apps/docs/astro.config.mjs

@@ -235,16 +235,14 @@ export default defineConfig({
         "The production-grade SaaS starter, built to be set up by an agent. Auth, billing, queues, email and observability already wired, with the architecture enforced by lint and CI. MIT, open source.",
       favicon: "/favicon.svg",
       /*
-       * Load order matters. redesign.css is the skin ported from tsforge and
-       * has to come last so it owns the final look; custom.css stays intact
-       * underneath for the accessible-table wrapper, the mermaid theme and
-       * the .bs-landing inline-code reset. Removing the last entry reverts
-       * the site to the previous green/rounded look.
+       * Shared tokens and accessible component styles load first. The base
+       * skin maps them to Starlight; paper.css supplies light-only art direction.
        */
       customCss: [
         "./src/styles/tailwind.css",
         "./src/styles/custom.css",
         "./src/styles/redesign.css",
+        "./src/styles/paper.css",
       ],
       plugins: [
         /*

apps/docs/src/components/ThemeProvider.astro

@@ -1,26 +1,31 @@
 ---
-/*
- * Starlight ThemeProvider override.
- *
- * Default behaviour reads OS prefers-color-scheme and uses light for
- * users whose OS is light. We force dark as the default for first-time
- * visitors so the docs match the brand surface; the toggle still works
- * and the user's pick persists in localStorage, so we only override the
- * "no stored preference" branch.
- */
+/* First visits start in light mode. Explicit light/dark and the stored
+ * empty-string Auto preference remain compatible with Starlight's picker. */
 import { Icon } from "@astrojs/starlight/components";
 ---
 
 {/* Inlined to avoid FOUC. */}
 <script is:inline>
   window.StarlightThemeProvider = (() => {
-    const storedTheme =
-      typeof localStorage !== "undefined" &&
-      localStorage.getItem("starlight-theme");
-    const theme = storedTheme || "dark";
-    document.documentElement.dataset.theme = theme === "light" ? "light" : "dark";
+    let storedTheme = null;
+    try {
+      storedTheme = localStorage.getItem("starlight-theme");
+      if (storedTheme === null) {
+        localStorage.setItem("starlight-theme", "light");
+        storedTheme = "light";
+      }
+    } catch {
+      // Rendering still has a deterministic default when storage is unavailable.
+    }
+    const preference = storedTheme === null ? "light" : storedTheme || "auto";
+    const systemTheme = matchMedia("(prefers-color-scheme: dark)").matches
+      ? "dark"
+      : "light";
+    const theme = preference === "auto" ? systemTheme : preference;
+    document.documentElement.dataset.theme =
+      theme === "dark" ? "dark" : "light";
     return {
-      updatePickers(theme = storedTheme || "auto") {
+      updatePickers(theme = preference) {
         document.querySelectorAll("starlight-theme-select").forEach((picker) => {
           const select = picker.querySelector("select");
           if (select) select.value = theme;

apps/docs/src/styles/paper.css

@@ -0,0 +1,145 @@
+/* Light-only art direction. Geometry stays shared with the dark theme;
+   paper surfaces, display typography and ink treatments live here. */
+html[data-theme="light"] body {
+  background:
+    url("/paper-grain.svg"),
+    linear-gradient(var(--paper-grid) 1px, transparent 1px),
+    linear-gradient(90deg, var(--paper-grid) 1px, transparent 1px),
+    var(--background) !important;
+  background-size:
+    180px 180px,
+    28px 28px,
+    28px 28px;
+}
+
+/* Keep the reading column quiet; the grid belongs to the surrounding sheet. */
+html[data-theme="light"]:not([data-has-hero]) .main-pane {
+  background: var(--background);
+}
+
+[data-theme="light"] .bs-landing #bs-hero-title {
+  max-width: 12ch;
+  font-family: var(--font-display);
+  font-size: clamp(3.25rem, 5.8vw, 5.5rem);
+  font-weight: 700;
+  line-height: 0.99;
+  letter-spacing: -0.055em;
+  text-wrap: balance;
+}
+
+[data-theme="light"] #bs-hero-title span {
+  color: var(--accent);
+}
+
+[data-theme="light"] .bs-landing .bs-section-heading h2,
+[data-theme="light"] .bs-landing h2 {
+  font-family: var(--font-display);
+  font-size: clamp(2.1rem, 3.5vw, 3.25rem);
+  font-weight: 700;
+  letter-spacing: -0.035em;
+  line-height: 1.08;
+}
+
+[data-theme="light"] :is(h1[data-page-title], .content-panel h1) {
+  font-family: var(--font-display);
+  letter-spacing: -0.035em;
+}
+
+[data-theme="light"] .bs-hero-tech {
+  border-top: 3px solid var(--primary);
+  padding-top: 14px;
+}
+
+[data-theme="light"] .bs-machine {
+  background: var(--card);
+  border-color: var(--border-strong);
+  box-shadow: var(--paper-shadow);
+}
+
+[data-theme="light"] .bs-machine-caption {
+  padding-block: 18px;
+  background: var(--secondary);
+  line-height: 1.6;
+}
+
+[data-theme="light"] .bs-machine-id > span {
+  box-shadow: none;
+}
+
+[data-theme="light"] .bs-machine-steps button > span {
+  opacity: 1;
+}
+
+/* One ink per layer, with a pale wash underneath the technical drawing. */
+[data-theme="light"] .bs-machine-layer[data-layer="0"] {
+  --layer-ink: #386d7b;
+}
+
+[data-theme="light"] .bs-machine-layer[data-layer="1"] {
+  --layer-ink: #836343;
+}
+
+[data-theme="light"] .bs-machine-layer[data-layer="2"] {
+  --layer-ink: #716080;
+}
+
+[data-theme="light"] .bs-machine-layer[data-layer="3"] {
+  --layer-ink: #52704a;
+}
+
+[data-theme="light"] .bs-machine-layer .bs-machine-plane {
+  fill: color-mix(in srgb, var(--layer-ink) 13%, var(--card));
+  stroke: var(--layer-ink);
+}
+
+[data-theme="light"] .bs-machine-layer .bs-machine-edge {
+  fill: color-mix(in srgb, var(--layer-ink) 22%, var(--card));
+  stroke: var(--layer-ink);
+}
+
+[data-theme="light"] .bs-machine-layer[data-selected="true"] .bs-machine-plane {
+  fill: color-mix(in srgb, var(--layer-ink) 22%, var(--card));
+  stroke-width: 1.5;
+}
+
+[data-theme="light"]
+  .bs-machine[data-stage="1"]
+  [data-layer="1"]
+  .bs-machine-plane {
+  stroke: var(--warning);
+}
+
+[data-theme="light"] .bs-machine-grid {
+  opacity: 0.12;
+}
+
+[data-theme="light"] .bs-machine-status,
+[data-theme="light"] .bs-machine-layers {
+  background: color-mix(in srgb, var(--background) 70%, var(--card));
+}
+
+[data-theme="light"] .bs-guardrail-demo {
+  box-shadow: var(--paper-shadow);
+  border-color: var(--border-strong);
+}
+
+[data-theme="light"] .bs-demo-editor {
+  background: var(--code-surface);
+}
+
+[data-theme="light"] .bs-closing .bs-closing-brand {
+  font-family: var(--font-display);
+  font-weight: 700;
+  font-size: 1.75rem;
+  letter-spacing: -0.04em;
+}
+
+[data-theme="light"] .bs-closing {
+  border-top: 3px double var(--border-strong);
+}
+
+@media (max-width: 640px) {
+  [data-theme="light"] .bs-landing #bs-hero-title {
+    font-size: clamp(3rem, 12vw, 4.25rem);
+  }
+}

apps/docs/src/styles/redesign.css

@@ -348,7 +348,8 @@ site-search button[data-open-modal]:hover {
 site-search kbd {
   border-radius: 0;
   background: none;
-  border: 1px solid var(--border);
+  border: 0;
+  box-shadow: none;
   font-family: var(--sl-font-mono);
 }
 

apps/docs/src/styles/tailwind.css

@@ -4,18 +4,8 @@
 @source "../components/**/*.{astro,tsx,jsx,ts,js}";
 @source "../content/**/*.{mdx,astro,tsx,jsx}";
 
-/* =====================================================================
-   Design tokens, ported from tsforge (apps/docs) so the two sites read as
-   one product: OKLCH ramp, cyan primary, zero radius, Inter + JetBrains
-   Mono. `redesign.css` maps these onto Starlight's --sl-* variables and
-   owns the final look; this file only declares the palette and the
-   utilities the landing components use.
-
-   tsforge is dark-only and forces `color-scheme: dark` on every theme.
-   BoringStack ships a working theme toggle in its header, so the light
-   ramp below is derived from the same hues rather than dropped. Removing
-   the `[data-theme="light"]` block is all it takes to go dark-only.
-   ===================================================================== */
+/* Shared semantic tokens. Dark uses cool instrument-panel colours; light
+   uses paper, graphite and archival inks. Components consume the same roles. */
 
 :root,
 :root[data-theme="dark"] {
@@ -52,32 +42,36 @@
   --font-mono: "JetBrains Mono", ui-monospace, "SF Mono", Menlo, monospace;
 }
 
-/* Same hues, inverted lightness. Primary drops to L 0.52 because the dark
-   ramp's L 0.78 cyan cannot carry 4.5:1 against a near-white page. */
+/* Warm paper with dark inks: text and interactive colours stay distinct
+   from the softer decorative tints used on the architecture drawing. */
 :root[data-theme="light"] {
-  --background: oklch(0.99 0.003 260);
-  --foreground: oklch(0.21 0.02 265);
-  --card: oklch(0.97 0.006 260);
-  --card-foreground: oklch(0.21 0.02 265);
-  --popover: oklch(0.97 0.006 260);
-  --popover-foreground: oklch(0.21 0.02 265);
-  --primary: oklch(0.52 0.11 210);
-  --primary-foreground: oklch(0.99 0.003 260);
-  --secondary: oklch(0.94 0.008 260);
-  --secondary-foreground: oklch(0.21 0.02 265);
-  --muted: oklch(0.95 0.006 260);
-  --muted-foreground: oklch(0.44 0.02 260);
-  --accent: oklch(0.47 0.17 300);
-  --accent-foreground: oklch(0.99 0.003 260);
-  --destructive: oklch(0.52 0.2 22);
-  --destructive-foreground: oklch(0.99 0.003 260);
-  --success: oklch(0.5 0.14 155);
-  --warning: oklch(0.55 0.13 75);
-  --border: oklch(0.89 0.008 260);
-  --border-strong: oklch(0.76 0.015 260);
-  --input: oklch(0.88 0.01 260);
-  --ring: oklch(0.52 0.11 210);
-  --code-surface: oklch(0.96 0.006 260);
+  --background: #f3efdf;
+  --foreground: #30382f;
+  --card: #faf7ed;
+  --card-foreground: var(--foreground);
+  --popover: #faf7ed;
+  --popover-foreground: var(--foreground);
+  --primary: #355a49;
+  --primary-foreground: #fffaf0;
+  --secondary: #e5e0cf;
+  --secondary-foreground: var(--foreground);
+  --muted: #eae5d5;
+  --muted-foreground: #595d50;
+  --accent: #a24430;
+  --accent-foreground: #fffaf0;
+  --destructive: #a23930;
+  --destructive-foreground: #fffaf0;
+  --success: #456740;
+  --warning: #805913;
+  --border: #cbc8b6;
+  --border-strong: #8d9380;
+  --input: #cbc8b6;
+  --ring: var(--primary);
+  --code-surface: #eae7d8;
+  --font-display:
+    "Iowan Old Style", "Palatino Linotype", "Book Antiqua", Georgia, serif;
+  --paper-grid: rgb(78 109 98 / 5%);
+  --paper-shadow: 4px 5px 0 rgb(57 64 43 / 8%);
 }
 
 @theme inline {