create-forte-ui 1.0.0-alpha.4 → 1.0.0-alpha.6

package/README.md

@@ -10,7 +10,7 @@ npm create forte-ui@latest my-app
 
 Four questions get you to a running app (name, framework, Tailwind, accent
 color); everything else — secondary color, neutral tint, radius, density,
-motion, fonts — hides behind one "customize further?" gate. Every prompt has a
+motion, light/dark, fonts — hides behind one "customize further?" gate. Every prompt has a
 flag twin, so the [Theme Studio](https://forte-ui.com/theme/) can hand you a
 complete command line and `--yes` runs without a single question:
 

package/dist/args.d.ts

@@ -6,8 +6,19 @@ export type CliOptions = {
     framework?: Framework;
     tailwind?: boolean;
     pm?: PackageManager;
+    /** Version spec for `@forte-ui/react` — exact ("1.0.0-alpha.4"), dist-tag
+     *  ("alpha"), or range. Deliberately NOT validated here: the package
+     *  manager understands every legal form (tags, ranges, `file:`…) and
+     *  rejects a wrong one at install with a better error than any regex
+     *  would give. Undefined = the registry's `latest`. Dev/CI knob only —
+     *  no prompt, and the studio dialog knows nothing about it. */
+    library?: string;
     yes: boolean;
     install: boolean;
+    /** Install the forte-ui agent skill (skills.sh) into the project. On by
+     *  default; `--no-skill` opts out, and `--no-install` skips it with
+     *  everything else. */
+    skill: boolean;
     help: boolean;
     version: boolean;
     /** Only the keys given as flags — presence is what suppresses the prompt. */
@@ -16,4 +27,4 @@ export type CliOptions = {
 export declare class UsageError extends Error {
 }
 export declare function parseCliArgs(argv: string[]): CliOptions;
-export declare const HELP = "create-forte-ui \u2014 scaffold a new app wired up with forte-ui\n\nUsage\n  pnpm create forte-ui [name] [flags]\n  npm create forte-ui@latest [name] -- [flags]\n\nEvery flag has a prompt twin; a passed flag suppresses its prompt. With no\nflags you get the questionnaire, with --yes you get a Next.js + Tailwind app\non the library's default theme.\n\nProject\n  [name]                 project directory (prompted if omitted)\n  -f, --framework        next | vite\n  --tailwind             wire the Tailwind v4 bridge (default yes)\n  --no-tailwind          plain CSS setup\n  --pm                   npm | pnpm | yarn | bun (default: whoever invoked us)\n  --no-install           write files only; skip installing dependencies\n  -y, --yes              accept the defaults for everything not passed\n\nTheme \u2014 every skipped value keeps the library default and writes NOTHING,\nso the app keeps following the library when defaults are tuned.\n  --seed, --accent       accent seed, hex (\"#6d43d4\")\n  --secondary            secondary seed, hex\n  --tint                 neutral tint, 0 (pure grey) to 1 (default)\n  --radius               none | soft | pill\n  --density              compact | spacious\n  --motion               system (default) | reduce | full\n                         \"full\" overrides the OS reduced-motion preference\n                         for everyone \u2014 prefer leaving it unset.\n  --font-sans            a catalogue name (\"Inter\", \"DM Sans\", ...)\n  --font-mono            a catalogue name (\"JetBrains Mono\", ...)\n\nDesign the theme visually instead: https://forte-ui.com/theme\n";
+export declare const HELP = "create-forte-ui \u2014 scaffold a new app wired up with forte-ui\n\nUsage\n  pnpm create forte-ui [name] [flags]\n  npm create forte-ui@latest [name] -- [flags]\n\nEvery flag has a prompt twin; a passed flag suppresses its prompt. With no\nflags you get the questionnaire, with --yes you get a Next.js + Tailwind app\non the library's default theme.\n\nProject\n  [name]                 project directory (prompted if omitted)\n  -f, --framework        next | vite\n  --tailwind             wire the Tailwind v4 bridge (default yes)\n  --no-tailwind          plain CSS setup\n  --pm                   npm | pnpm | yarn | bun (default: whoever invoked us)\n  --library              version spec for @forte-ui/react \u2014 exact\n                         (\"1.0.0-alpha.4\"), a dist-tag (\"alpha\"), or a range.\n                         Default: latest.\n  --no-install           write files only; skip installing dependencies\n                         and the agent skill\n  --no-skill             skip installing the forte-ui agent skill\n                         (skills.sh \u2014 .agents/skills plus .claude/skills)\n  -y, --yes              accept the defaults for everything not passed\n\nTheme \u2014 every skipped value keeps the library default and writes NOTHING,\nso the app keeps following the library when defaults are tuned.\n  --seed, --accent       accent seed, hex (\"#6d43d4\")\n  --secondary            secondary seed, hex\n  --tint                 neutral tint, 0 (pure grey) to 1 (default)\n  --radius               none | soft | pill\n  --density              compact | spacious\n  --motion               system (default) | reduce | full\n                         \"full\" overrides the OS reduced-motion preference\n                         for everyone \u2014 prefer leaving it unset.\n  --scheme               system (default) | light | dark\n                         \"light\" / \"dark\" pin one palette on <html> and\n                         leave the theme toggle and its replay script out.\n  --font-sans           a catalogue name (\"Inter\", \"DM Sans\", ...)\n  --font-mono            a catalogue name (\"JetBrains Mono\", ...)\n\nDesign the theme visually instead: https://forte-ui.com/theme\n";

package/dist/args.js

@@ -11,7 +11,7 @@
 import { parseArgs } from "node:util";
 import { SANS_FONTS, MONO_FONTS } from "./fonts.js";
 import { hexToOklch } from "./color.js";
-import { RADIUS, DENSITY, MOTION } from "./theme.js";
+import { RADIUS, DENSITY, MOTION, SCHEME } from "./theme.js";
 import { PACKAGE_MANAGERS } from "./scaffold.js";
 export class UsageError extends Error {
 }
@@ -51,11 +51,14 @@ export function parseCliArgs(argv) {
             radius: { type: "string" },
             density: { type: "string" },
             motion: { type: "string" },
+            scheme: { type: "string" },
             "font-sans": { type: "string" },
             "font-mono": { type: "string" },
+            library: { type: "string" },
             pm: { type: "string" },
             yes: { type: "boolean", short: "y" },
             "no-install": { type: "boolean" },
+            "no-skill": { type: "boolean" },
             help: { type: "boolean", short: "h" },
             version: { type: "boolean", short: "v" },
         },
@@ -92,6 +95,8 @@ export function parseCliArgs(argv) {
         answers.motion =
             values.motion.toLowerCase() === "system" ? "default" : oneOf("motion", values.motion, MOTION);
     }
+    if (values.scheme !== undefined)
+        answers.scheme = oneOf("scheme", values.scheme, SCHEME);
     if (values["font-sans"] !== undefined) {
         answers.fontSans = fontByName("font-sans", values["font-sans"], SANS_FONTS);
     }
@@ -103,8 +108,10 @@ export function parseCliArgs(argv) {
         framework: values.framework === undefined ? undefined : oneOf("framework", values.framework, ["next", "vite"]),
         tailwind: values.tailwind ? true : values["no-tailwind"] ? false : undefined,
         pm: values.pm === undefined ? undefined : oneOf("pm", values.pm, PACKAGE_MANAGERS),
+        library: values.library,
         yes: values.yes ?? false,
         install: !(values["no-install"] ?? false),
+        skill: !(values["no-skill"] ?? false),
         help: values.help ?? false,
         version: values.version ?? false,
         answers,
@@ -126,7 +133,13 @@ Project
   --tailwind             wire the Tailwind v4 bridge (default yes)
   --no-tailwind          plain CSS setup
   --pm                   npm | pnpm | yarn | bun (default: whoever invoked us)
+  --library              version spec for @forte-ui/react — exact
+                         ("1.0.0-alpha.4"), a dist-tag ("alpha"), or a range.
+                         Default: latest.
   --no-install           write files only; skip installing dependencies
+                         and the agent skill
+  --no-skill             skip installing the forte-ui agent skill
+                         (skills.sh — .agents/skills plus .claude/skills)
   -y, --yes              accept the defaults for everything not passed
 
 Theme — every skipped value keeps the library default and writes NOTHING,
@@ -139,7 +152,10 @@ so the app keeps following the library when defaults are tuned.
   --motion               system (default) | reduce | full
                          "full" overrides the OS reduced-motion preference
                          for everyone — prefer leaving it unset.
-  --font-sans            a catalogue name ("Inter", "DM Sans", ...)
+  --scheme               system (default) | light | dark
+                         "light" / "dark" pin one palette on <html> and
+                         leave the theme toggle and its replay script out.
+  --font-sans           a catalogue name ("Inter", "DM Sans", ...)
   --font-mono            a catalogue name ("JetBrains Mono", ...)
 
 Design the theme visually instead: https://forte-ui.com/theme

package/dist/index.js

@@ -15,8 +15,8 @@ import pc from "picocolors";
 import { parseCliArgs, UsageError, HELP } from "./args.js";
 import { collectPlan } from "./prompts.js";
 import { hexToOklch, validateSeed } from "./color.js";
-import { applyOverlay, dependenciesFor, recordDependencies } from "./overlay.js";
-import { detectPackageManager, runScaffolder, addDependencies, devCommand, installCommand, } from "./scaffold.js";
+import { applyOverlay, dependenciesFor, recordDependencies, toAddSpecs, } from "./overlay.js";
+import { detectPackageManager, runScaffolder, addDependencies, installSkill, devCommand, installCommand, } from "./scaffold.js";
 function ownVersion() {
     const pkgPath = path.join(fileURLToPath(import.meta.url), "../../package.json");
     return JSON.parse(fs.readFileSync(pkgPath, "utf8")).version;
@@ -41,7 +41,19 @@ function warnAboutSeeds(plan) {
 }
 function scaffold(plan, pm) {
     if (plan.framework === "vite") {
-        return runScaffolder(pm, "create-vite@latest", [plan.name, "--template", "react-ts"], process.cwd());
+        return runScaffolder(pm, "create-vite@latest", [
+            plan.name,
+            "--template",
+            "react-ts",
+            /* create-vite 9 goes interactive whenever stdin is a TTY, template
+             * or not: it asks which linter to use and then "Install and start
+             * now?". A yes to that starts the dev server INSIDE our child
+             * process, so control never comes back and the overlay is never
+             * applied — the user ends up with a stock Vite app and no forte-ui.
+             * Non-interactive takes its defaults (Oxlint, no install), and the
+             * one install happens at the end with the library included. */
+            "--no-interactive",
+        ], process.cwd());
     }
     return runScaffolder(pm, "create-next-app@latest", [
         plan.name,
@@ -109,17 +121,35 @@ async function main() {
         process.exit(1);
     }
     p.log.success(`Wired up forte-ui: ${written.join(", ")}`);
-    const deps = dependenciesFor(plan);
+    const deps = dependenciesFor(plan, opts.library);
+    const specs = toAddSpecs(deps);
     if (opts.install) {
-        p.log.step(`Installing ${deps.join(", ")} with ${pm}…`);
-        if (!addDependencies(pm, deps, plan.dir)) {
-            p.cancel(`${pm} failed to install — run ${pc.bold(`${installCommand(pm)}`)} in ./${plan.name} yourself.`);
+        p.log.step(`Installing ${specs.join(", ")} with ${pm}…`);
+        if (!addDependencies(pm, specs, plan.dir)) {
+            /* A `--library` spec is validated only here, by the registry itself —
+             * so on failure say which spec died rather than suggesting a re-run
+             * that would resolve the exact same thing. */
+            p.cancel(opts.library
+                ? `${pm} could not install @forte-ui/react@${opts.library} — see its output above. ` +
+                    `Check that the --library spec exists on the registry.`
+                : `${pm} failed to install — run ${pc.bold(`${installCommand(pm)}`)} in ./${plan.name} yourself.`);
             process.exit(1);
         }
     }
     else {
         recordDependencies(plan.dir, deps);
-        p.log.info(`Skipped install; added ${deps.join(", ")} to package.json.`);
+        p.log.info(`Skipped install; added ${specs.join(", ")} to package.json.`);
+    }
+    /* The agent skill, so AI tooling in the new project starts past the
+     * library's silent traps. Gated on `install` too: `--no-install` means
+     * "write files, run nothing". Failure is a warning, not an exit — the app
+     * is complete without it, and the guide's one-liner recovers it. */
+    if (opts.install && opts.skill) {
+        p.log.step("Installing the forte-ui agent skill…");
+        if (!installSkill(pm, plan.dir)) {
+            p.log.warn("Skill install failed — the app is unaffected. " +
+                `Run ${pc.bold("npx skills add arsen/forte-ui -s forte-ui")} in ./${plan.name} to retry.`);
+        }
     }
     const steps = [
         `cd ${plan.name}`,

package/dist/overlay.d.ts

@@ -9,8 +9,16 @@ export type ProjectPlan = {
 };
 /** Returns the files it wrote (project-relative), for the summary. */
 export declare function applyOverlay(plan: ProjectPlan): string[];
+export type Dependency = {
+    name: string;
+    spec: string;
+};
 /** The `--no-install` fallback: record the dependencies so the user's own
- *  install resolves them. "latest" is a dist-tag, which every manager
- *  accepts and replaces with a real range on first install. */
-export declare function recordDependencies(dir: string, deps: string[]): void;
-export declare function dependenciesFor(plan: ProjectPlan): string[];
+ *  install resolves them. The default spec is the "latest" dist-tag, which
+ *  every manager accepts and replaces with a real range on first install —
+ *  and so is anything `--library` put there instead, tag, range or exact. */
+export declare function recordDependencies(dir: string, deps: Dependency[]): void;
+/** `pm add` arguments: the bare name resolves `latest` exactly as before, so
+ *  only a `--library` spec changes what gets asked of the registry. */
+export declare function toAddSpecs(deps: Dependency[]): string[];
+export declare function dependenciesFor(plan: ProjectPlan, library?: string): Dependency[];

package/dist/overlay.js

@@ -24,7 +24,7 @@ function applyVite({ name, dir, tailwind, answers }) {
     written.push("src/index.css");
     write(dir, "src/main.tsx", viteMainTsx(tailwind));
     written.push("src/main.tsx");
-    write(dir, "src/App.tsx", viteAppTsx(name, tailwind));
+    write(dir, "src/App.tsx", viteAppTsx(name, tailwind, answers.scheme === "system"));
     written.push("src/App.tsx");
     /* The guide's warning covers App.css too: its rules are unlayered and the
      * new App.tsx no longer imports it. Delete rather than empty, so nobody
@@ -47,6 +47,28 @@ function applyVite({ name, dir, tailwind, answers }) {
             `the create-vite template may have changed; add the attribute(s) by hand.`);
     }
     html = anchored.replace(/<title>[^<]*<\/title>/, `<title>${name}</title>`);
+    /* Replay a stored light/dark choice before first paint — the guides'
+     * "Light and dark" step. A bundled component cannot run before the bundle,
+     * so on Vite the script lives in the document itself; the string must stay
+     * byte-identical to `themeInitScript` in @forte-ui/react, which is the
+     * other writer of the same localStorage key.
+     *
+     * Not when a scheme is pinned: `data-theme` is then static in the markup
+     * above, and the script would OVERRIDE it with any `forte-theme` record on
+     * the origin — which on localhost is shared by every project, so a toggle
+     * pressed in another app would flip this one's pinned palette. */
+    if (answers.scheme === "system") {
+        const themeReplay = "    <!-- Replays a stored light/dark choice before first paint\n" +
+            "         (themeInitScript from @forte-ui/react). -->\n" +
+            '    <script>(function(){try{var t=localStorage.getItem("forte-theme");if(t==="light"||t==="dark")document.documentElement.setAttribute("data-theme",t)}catch(e){}})();</script>\n';
+        const replayed = html.replace(/[ \t]*<\/head>/, `${themeReplay}  </head>`);
+        if (replayed === html) {
+            throw new Error("could not find '</head>' in index.html to add the theme replay script — " +
+                "the create-vite template may have changed; copy the snippet from the " +
+                "guide's 'Light and dark' step into <head> by hand.");
+        }
+        html = replayed;
+    }
     /* Tailwind only: pin the cascade-layer order in the DOCUMENT, not the
      * stylesheet. The bridge's own `@layer theme, base, forte, components,
      * utilities;` statement is supposed to do this, but Vite's CSS pipeline
@@ -88,20 +110,28 @@ function applyNext({ name, dir, tailwind, answers }) {
     return written;
 }
 /** The `--no-install` fallback: record the dependencies so the user's own
- *  install resolves them. "latest" is a dist-tag, which every manager
- *  accepts and replaces with a real range on first install. */
+ *  install resolves them. The default spec is the "latest" dist-tag, which
+ *  every manager accepts and replaces with a real range on first install —
+ *  and so is anything `--library` put there instead, tag, range or exact. */
 export function recordDependencies(dir, deps) {
     const pkgPath = path.join(dir, "package.json");
     const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
     pkg.dependencies ??= {};
     for (const dep of deps)
-        pkg.dependencies[dep] = "latest";
+        pkg.dependencies[dep.name] = dep.spec;
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
-export function dependenciesFor(plan) {
-    /* create-next-app's --tailwind scaffold already carries tailwindcss v4;
-     * on Vite the guide installs it alongside the library, plus the plugin. */
+/** `pm add` arguments: the bare name resolves `latest` exactly as before, so
+ *  only a `--library` spec changes what gets asked of the registry. */
+export function toAddSpecs(deps) {
+    return deps.map((d) => (d.spec === "latest" ? d.name : `${d.name}@${d.spec}`));
+}
+export function dependenciesFor(plan, library) {
+    /* `--library` steers ONLY the library. The Vite Tailwind extras stay on
+     * latest — the templates target current Tailwind v4 regardless of which
+     * forte-ui build is being tried out. */
+    const lib = { name: "@forte-ui/react", spec: library ?? "latest" };
     return plan.framework === "vite" && plan.tailwind
-        ? ["@forte-ui/react", "tailwindcss", "@tailwindcss/vite"]
-        : ["@forte-ui/react"];
+        ? [lib, { name: "tailwindcss", spec: "latest" }, { name: "@tailwindcss/vite", spec: "latest" }]
+        : [lib];
 }

package/dist/prompts.js

@@ -95,12 +95,12 @@ export async function collectPlan(opts) {
     if (!opts.yes && !flagged.has("seed")) {
         answers.seed = await hexPrompt("Accent color — your brand's hex, the whole palette derives from it")();
     }
-    const advancedKeys = ["secondary", "tint", "radius", "density", "motion", "fontSans", "fontMono"];
+    const advancedKeys = ["secondary", "tint", "radius", "density", "motion", "scheme", "fontSans", "fontMono"];
     const remaining = advancedKeys.filter((k) => !flagged.has(k));
     const customize = !opts.yes &&
         remaining.length > 0 &&
         accept(await p.confirm({
-            message: "Customize further? (secondary, neutrals, radius, density, motion, fonts)",
+            message: "Customize further? (secondary, neutrals, radius, density, motion, light/dark, fonts)",
             initialValue: false,
         }));
     if (customize) {
@@ -155,6 +155,17 @@ export async function collectPlan(opts) {
                 ],
             }));
         }
+        if (remaining.includes("scheme")) {
+            answers.scheme = accept(await p.select({
+                message: "Light and dark",
+                initialValue: "system",
+                options: [
+                    { value: "system", label: "Both", hint: "follows the OS, with a toggle" },
+                    { value: "light", label: "Light only" },
+                    { value: "dark", label: "Dark only" },
+                ],
+            }));
+        }
         if (remaining.includes("fontSans")) {
             answers.fontSans = await fontPrompt("Sans font", SANS_FONTS);
         }

package/dist/scaffold.d.ts

@@ -12,6 +12,13 @@ export declare function runScaffolder(pm: PackageManager, pkg: string, args: str
 /** `pm add <deps>` in the project — resolves "latest" into a real caret range
  *  in package.json and performs the full install in one pass. */
 export declare function addDependencies(pm: PackageManager, deps: string[], cwd: string): boolean;
+/** Install the forte-ui agent skill into the project via skills.sh, the
+ *  same command the AI-agents guide documents. `-s forte-ui` is load-bearing:
+ *  the repository also carries internal skills (release-prep) that must not
+ *  reach consumers. `-y` writes the universal `.agents/skills` copy plus the
+ *  per-agent links — `.claude/skills` for Claude Code among them — without
+ *  prompting. */
+export declare function installSkill(pm: PackageManager, cwd: string): boolean;
 /** The dev-server line for the outro, in the user's own manager. */
 export declare function devCommand(pm: PackageManager): string;
 export declare function installCommand(pm: PackageManager): string;

package/dist/scaffold.js

@@ -46,6 +46,15 @@ export function addDependencies(pm, deps, cwd) {
     const sub = pm === "npm" ? "install" : "add";
     return run(pm, [sub, ...deps], cwd);
 }
+/** Install the forte-ui agent skill into the project via skills.sh, the
+ *  same command the AI-agents guide documents. `-s forte-ui` is load-bearing:
+ *  the repository also carries internal skills (release-prep) that must not
+ *  reach consumers. `-y` writes the universal `.agents/skills` copy plus the
+ *  per-agent links — `.claude/skills` for Claude Code among them — without
+ *  prompting. */
+export function installSkill(pm, cwd) {
+    return runScaffolder(pm, "skills@latest", ["add", "arsen/forte-ui", "-s", "forte-ui", "-y"], cwd);
+}
 /** The dev-server line for the outro, in the user's own manager. */
 export function devCommand(pm) {
     return pm === "npm" ? "npm run dev" : `${pm} dev`;

package/dist/templates.d.ts

@@ -1,7 +1,11 @@
 import { type ThemeAnswers } from "./theme.js";
 export declare function viteIndexCss(a: ThemeAnswers, tailwind: boolean): string;
 export declare function viteMainTsx(tailwind: boolean): string;
-export declare function viteAppTsx(name: string, tailwind: boolean): string;
+/** `toggle` is false when the answers pinned a colour scheme: `data-theme`
+ *  then sits statically on `<html>` and a toggle would be a button whose one
+ *  job is to fight it. The import goes with the element, so the starter
+ *  still compiles clean under `noUnusedLocals`. */
+export declare function viteAppTsx(name: string, tailwind: boolean, toggle: boolean): string;
 export declare const VITE_CONFIG_TW = "import { defineConfig } from \"vite\";\nimport react from \"@vitejs/plugin-react\";\nimport tailwindcss from \"@tailwindcss/vite\";\n\nexport default defineConfig({\n  plugins: [react(), tailwindcss()],\n});\n";
 export declare function nextGlobalsCss(a: ThemeAnswers, tailwind: boolean): string;
 export declare function nextLayoutTsx(name: string, a: ThemeAnswers, tailwind: boolean): string;

package/dist/templates.js

@@ -18,6 +18,28 @@ const BODY_RULE = `body {
 function joinBlocks(...blocks) {
     return blocks.filter(Boolean).join("\n") + "\n";
 }
+/* The starter's one piece of chrome, and the working half of the guides'
+ * "Light and dark" step: the theme the questionnaire just seeded can be
+ * flipped without writing a line. Two spellings of the same corner, because
+ * the Tailwind paths have utilities and the plain ones do not.
+ *
+ * `fixed` rather than in flow, so the page still centres the component it is
+ * there to demonstrate — and the offsets are space tokens rather than `1rem`,
+ * because this file is the first thing a new app is copied out of and a
+ * hardcoded value here is the habit it teaches. */
+const TOGGLE_TW = `<ThemeToggle className="fixed top-4 right-4" />`;
+const TOGGLE_STYLE = `<ThemeToggle
+  style={{ position: "fixed", top: "var(--forte-space-4)", right: "var(--forte-space-4)" }}
+/>`;
+/** `TOGGLE_STYLE` re-indented to sit at `indent` spaces (its first line is
+ *  placed by the caller, the continuation lines by this). */
+function indented(block, indent) {
+    const pad = " ".repeat(indent);
+    return block
+        .split("\n")
+        .map((line, i) => (i === 0 ? line : pad + line))
+        .join("\n");
+}
 /* -------------------------------------------------------------------------
  * Vite
  * ---------------------------------------------------------------------- */
@@ -56,14 +78,19 @@ createRoot(document.getElementById("root")!).render(
 );
 `;
 }
-export function viteAppTsx(name, tailwind) {
+/** `toggle` is false when the answers pinned a colour scheme: `data-theme`
+ *  then sits statically on `<html>` and a toggle would be a button whose one
+ *  job is to fight it. The import goes with the element, so the starter
+ *  still compiles clean under `noUnusedLocals`. */
+export function viteAppTsx(name, tailwind, toggle) {
     if (tailwind) {
-        return `import { Button, Card } from "@forte-ui/react";
+        const toggleLine = toggle ? `      ${TOGGLE_TW}\n` : "";
+        return `import { Button, Card${toggle ? ", ThemeToggle" : ""} } from "@forte-ui/react";
 
 export default function App() {
   return (
     <main className="grid min-h-dvh place-items-center bg-background text-foreground">
-      <Card.Root variant="elevated" className="items-start gap-5">
+${toggleLine}      <Card.Root variant="elevated" className="items-start gap-5">
         <h1 className="text-5 font-semibold">${name}</h1>
         <p className="text-2 text-foreground-muted">
           Utilities and components, one theme.
@@ -75,12 +102,13 @@ export default function App() {
 }
 `;
     }
-    return `import { Button } from "@forte-ui/react";
+    const toggleLine = toggle ? `      ${indented(TOGGLE_STYLE, 6)}\n` : "";
+    return `import { Button${toggle ? ", ThemeToggle" : ""} } from "@forte-ui/react";
 
 export default function App() {
   return (
     <main style={{ display: "grid", placeItems: "center", minHeight: "100dvh" }}>
-      <Button>It works</Button>
+${toggleLine}      <Button>It works</Button>
     </main>
   );
 }
@@ -113,8 +141,28 @@ export function nextLayoutTsx(name, a, tailwind) {
      * globals.css imports it after the bridge (see the guide's ordering note),
      * and a second import here would pin the `forte` layer before `base`. */
     const themeImport = tailwind ? "" : `import "@forte-ui/react/theme.css";\n`;
+    /* ThemeScript + suppressHydrationWarning are the guides' "Light and dark"
+     * step: the script replays a stored light/dark choice onto <html> before
+     * first paint, and the suppression covers the attribute it legitimately
+     * adds. Harmless with nothing stored — the page just follows the OS. */
+    /* The toggle that writes what the script replays. It goes in the LAYOUT,
+     * not the page, because it is chrome: it then survives every route the app
+     * grows, and the page stays the one file a reader edits first. Being a flat
+     * export it needs no `"use client"` here — the boundary the compound
+     * components force on `page.tsx` does not reach the layout. */
+    /* A pinned scheme drops all three. The attribute is static, so there is
+     * nothing for the script to replay and nothing for the suppression to
+     * cover — and the script is actively wrong here, not merely idle: it
+     * replays whatever `forte-theme` record is on the origin, and on
+     * localhost every project shares one origin, so a toggle pressed in some
+     * OTHER app would flip this one's pinned palette on load. */
+    const pinned = a.scheme !== "system";
+    const toggle = tailwind ? TOGGLE_TW : indented(TOGGLE_STYLE, 8);
+    const libImport = pinned ? "" : `import { ThemeScript, ThemeToggle } from "@forte-ui/react";\n`;
+    const head = pinned ? "" : `      <head>\n        <ThemeScript />\n      </head>\n`;
+    const toggleLine = pinned ? "" : `        ${toggle}\n`;
     return `import type { Metadata } from "next";
-${font.importLine ? font.importLine + "\n" : ""}${themeImport}import "./globals.css";
+${libImport}${font.importLine ? font.importLine + "\n" : ""}${themeImport}import "./globals.css";
 
 ${font.consts ? font.consts + "\n\n" : ""}export const metadata: Metadata = {
   title: "${name}",
@@ -127,8 +175,10 @@ export default function RootLayout({
   children: React.ReactNode;
 }>) {
   return (
-    <html lang="en"${htmlAttrs(a)}${font.htmlClassAttr}>
-      <body>{children}</body>
+    <html lang="en"${htmlAttrs(a)}${font.htmlClassAttr}${pinned ? "" : " suppressHydrationWarning"}>
+${head}      <body>
+${toggleLine}        {children}
+      </body>
     </html>
   );
 }

package/dist/theme.d.ts

@@ -1,9 +1,11 @@
 export declare const RADIUS: readonly ["none", "default", "soft", "pill"];
 export declare const DENSITY: readonly ["compact", "default", "spacious"];
 export declare const MOTION: readonly ["full", "default", "reduce"];
+export declare const SCHEME: readonly ["system", "light", "dark"];
 export type Radius = (typeof RADIUS)[number];
 export type Density = (typeof DENSITY)[number];
 export type Motion = (typeof MOTION)[number];
+export type Scheme = (typeof SCHEME)[number];
 export type ThemeAnswers = {
     /** Accent seed hex, or null to keep the library default (write nothing). */
     seed: string | null;
@@ -13,6 +15,9 @@ export type ThemeAnswers = {
     radius: Radius;
     density: Density;
     motion: Motion;
+    /** "system" follows the OS and scaffolds the toggle; "light" / "dark" pin
+     *  one palette on `<html>` and leave the toggle and its replay script out. */
+    scheme: Scheme;
     /** Catalogue names. "System" writes nothing. */
     fontSans: string;
     fontMono: string;
@@ -33,7 +38,7 @@ export declare function rootBlock(a: ThemeAnswers, fontMode: FontMode): string;
 export declare function fontImports(a: ThemeAnswers): string[];
 /** ` data-forte-radius="pill" ...` — leading space included, "" when all
  *  defaults. Default modes stay UNSET so the app keeps following the OS
- *  (motion) and the library's own defaults. */
+ *  (motion, colour scheme) and the library's own defaults. */
 export declare function htmlAttrs(a: ThemeAnswers): string;
 export type NextFontSetup = {
     /** `import { Inter, JetBrains_Mono } from "next/font/google";` or "". */

package/dist/theme.js

@@ -14,6 +14,13 @@ import { hexToOklch, bestOnColor } from "./color.js";
 export const RADIUS = ["none", "default", "soft", "pill"];
 export const DENSITY = ["compact", "default", "spacious"];
 export const MOTION = ["full", "default", "reduce"];
+/* "system" is spelled out rather than being the "default" the other presets
+ * use, because it is also the flag value and the studio's strip label: the
+ * one mode that is not a mode. Pinning one writes `data-theme` on `<html>`,
+ * and that ATTRIBUTE is the whole mechanism — the stylesheet resolves every
+ * `light-dark()` through the `color-scheme` it sets, so a pinned app ships
+ * both palettes and simply never shows the other one. */
+export const SCHEME = ["system", "light", "dark"];
 export const DEFAULT_ANSWERS = {
     seed: null,
     secondary: null,
@@ -21,6 +28,7 @@ export const DEFAULT_ANSWERS = {
     radius: "default",
     density: "default",
     motion: "default",
+    scheme: "system",
     fontSans: "System",
     fontMono: "System",
 };
@@ -80,12 +88,13 @@ export function fontImports(a) {
 }
 /** ` data-forte-radius="pill" ...` — leading space included, "" when all
  *  defaults. Default modes stay UNSET so the app keeps following the OS
- *  (motion) and the library's own defaults. */
+ *  (motion, colour scheme) and the library's own defaults. */
 export function htmlAttrs(a) {
     const attrs = [
         a.radius !== "default" && `data-forte-radius="${a.radius}"`,
         a.density !== "default" && `data-forte-density="${a.density}"`,
         a.motion !== "default" && `data-forte-motion="${a.motion}"`,
+        a.scheme !== "system" && `data-theme="${a.scheme}"`,
     ].filter(Boolean);
     return attrs.length ? " " + attrs.join(" ") : "";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-forte-ui",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.6",
   "description": "Scaffold a new app wired up with forte-ui — Vite or Next.js, with or without Tailwind, themed from your answers.",
   "license": "MIT",
   "type": "module",