create-forte-ui 1.0.0-alpha.5 → 1.0.0-alpha.7

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

@@ -27,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  --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  --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,6 +51,7 @@ 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" },
@@ -94,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);
     }
@@ -149,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

@@ -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,

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

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/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.5",
+  "version": "1.0.0-alpha.7",
   "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",
@@ -24,13 +24,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsc -p tsconfig.json --watch",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "smoke": "node scripts/smoke.mjs",
-    "clean": "rm -rf dist .turbo"
-  },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
     "picocolors": "^1.1.1"
@@ -41,5 +34,12 @@
   "engines": {
     "node": ">=20"
   },
-  "homepage": "https://forte-ui.com"
-}
+  "homepage": "https://forte-ui.com",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "smoke": "node scripts/smoke.mjs",
+    "clean": "rm -rf dist .turbo"
+  }
+}