putdotio
diff --git a/‎scripts/smoke-static.ts‎
Lines changed: 3 additions & 2 deletions b/‎scripts/smoke-static.ts‎
Lines changed: 3 additions & 2 deletions
diff --git a/‎system/README.md‎
Lines changed: 16 additions & 4 deletions b/‎system/README.md‎
Lines changed: 16 additions & 4 deletions
@@ -3,7 +3,7 @@ import process from "node:process";
 
 const port = Number(process.env.PORT ?? String(4200 + Math.floor(Math.random() * 1000)));
 const baseUrl = `http://127.0.0.1:${port}`;
-const paths = ["/", "/design-system.html", "/design-system-light.html", "/tokens.css", "/preview/web-shell.html"];
+const paths = ["/", "/design-system.html", "/design-system.html?theme=light", "/design-system-light.html", "/tokens.css", "/preview/web-shell.html"];
 
 function wait(ms: number) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -32,7 +32,8 @@ async function smokePath(pathname: string) {
   }
 
   const text = await response.text();
-  if (pathname.endsWith(".html") || pathname === "/") {
+  const cleanPathname = pathname.split("?", 1)[0] ?? pathname;
+  if (cleanPathname.endsWith(".html") || cleanPathname === "/") {
     if (!text.includes("put.io")) {
       throw new Error(`${pathname} did not include the expected put.io marker`);
     }
 
@@ -8,8 +8,8 @@ This is the `system/` folder inside [`putdotio/putio-design`](https://github.com
 project root/
 └── system/
     ├── index.html           ← redirects to the design-system guide
-    ├── design-system.html   ← dark-mode guide and preview-card index
-    ├── design-system-light.html
+    ├── design-system.html   ← guide and preview-card index
+    ├── design-system-light.html ← legacy redirect to design-system.html?theme=light
     ├── tokens.css           ← generated from ../tokens/**/*.tokens.json
     ├── assets/              ← logos, favicons, retro marks, app icons
     └── preview/             ← atomic review cards for foundations + components + brand + platforms
@@ -49,11 +49,23 @@ For **TV preview cards**, also load `preview/tv-shell.css` — it adds the `.tv`
 
 ## Core rules
 
-- **Yellow `#FDCE45` is sacred.** Never gradient, tint, or replace. Primary CTAs, folder icons, focus rings (at 35% alpha), progress bars.
+- **Yellow `#FDCE45` is sacred.** Never gradient, tint, or replace. Primary CTAs, folder icons, focus rings (at 35% alpha), progress bars. `--yellow-solid` is the brand value; for yellow text on light backgrounds use `--yellow-text-secondary` instead.
 - **Icons: Phosphor-style inline SVG.** No emoji, ever.
-- **Dark is app-default, light is landing-default.** Both are in tokens; toggle with `.dark` on `<html>`.
+- **One design, two modes.** Light and dark are the same markup and components with different token values. Toggle `.dark` on `<html>`; do not fork the page or rebuild a light-specific copy.
 - **Content-agnostic.** put.io doesn't know what the user's files are. Never parse `The.Wire.S03E04.1080p.mkv` into `The Wire`. Raw filenames only. See the root [`DESIGN.md`](../DESIGN.md) for the full principle.
 
+## Theme System
+
+The guide owns the theme toggle. It stores `putio-ds-theme` in `localStorage`,
+updates `html.dark`, and broadcasts the current mode to embedded preview iframes.
+Standalone preview pages read the same storage key before paint. A URL query
+(`?theme=light` or `?theme=dark`) can override the preview mode for screenshots.
+
+Fixed-mode previews opt out with `<html data-theme-lock="dark">`. This is only
+for product mockups whose visual language is intrinsically one mode, such as TV
+and mobile shell specimens. Component previews should stay token-driven and work
+in both modes.
+
 ## Design variants
 
 Four documented type stacks — pick one per surface: