create-zudo-sg 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to `create-zudo-sg` are documented in this file.
+
+The format is based on Keep a Changelog.
+
+## [0.1.0] - 2026-09-20
+
+Initial release of the pnpm-only `create-zudo-sg` initializer.
+
+### Added
+
+- Scaffold a private Preact + zfb host from the bundled starter template.
+- Support project-directory prompts, npm package-name validation, `--name`,
+  `--install` / `--no-install`, `--yes`, `--help`, and `--version`.
+- Include the working `@takazudo/zudo-sg` host configuration, example stories,
+  token CSS, generated-registry seed, and preview stylesheet entry.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takeshi Takatsudo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# create-zudo-sg
+
+`create-zudo-sg` is the pnpm-only initializer for a new
+[`@takazudo/zudo-sg`](https://github.com/Takazudo/zudo-sg/tree/main/packages/styleguide)
+styleguide host. It copies a small, working Preact + zfb project into a new
+directory; the generated project is private and is ready to customize.
+
+## Quick start
+
+```sh
+pnpm create zudo-sg@latest my-styleguide
+cd my-styleguide
+pnpm install
+pnpm gen-registry
+pnpm gen-token-manifest
+pnpm dev
+```
+
+The initializer is available from its first npm release; nothing is published
+by this epic.
+
+The command defaults to no dependency installation and prints the five
+commands after it creates the project. Pass `--install` when the initializer
+should run `pnpm install` for you. The generated `package.json` pins the
+package manager to pnpm, and this release has no npm, yarn, or `--pm` mode.
+
+## Usage
+
+```txt
+create-zudo-sg [project-dir] [options]
+```
+
+| Option | Description |
+| --- | --- |
+| `[project-dir]` | Directory to create. If omitted, the CLI prompts when it has a TTY. |
+| `--name <pkg-name>` | Package name written to the generated `package.json`; defaults to the directory basename. |
+| `--install` | Run `pnpm install` after copying the template. |
+| `--no-install` | Do not install dependencies (the default). |
+| `--yes` | Do not prompt. A project directory is required with this flag. |
+| `--help` | Print usage and options. |
+| `--version` | Print the initializer version. |
+
+The target directory must be empty or not exist. The package name must follow
+npm's lowercase package-name rules; scoped names are accepted with
+`--name @scope/project`. The initializer does not add feature prompts or
+overwrite an existing project.
+
+## What the scaffold contains
+
+The template is a minimal host, not a copy of this repository's full site. It
+contains:
+
+- `zfb.config.ts` composing `zudoDoc()` and `withZudoSg()` with a root base.
+- `zudo-sg.config.mjs` with a local `ui/` components root, registry output,
+  preview stylesheet, category order, and token-manifest inputs.
+- `pages/index.tsx` and an optional `pages/lib/_zudo-sg-islands.ts` import
+  shim for the host page.
+- Three small Preact examples under `ui/`: Button, Card, and Counter, with
+  co-located stories and a Button MDX document.
+- `src/styleguide/sg-registry.ts`, an empty generated seed. Run
+  `pnpm gen-registry` after changing stories.
+- `src/content/docs/getting-started.mdx`, a seed page for the generated host's
+  documentation route.
+- `src/styles/preview-entry.css` and `src/styles/ui-tokens.css`, which provide
+  the standalone preview stylesheet and the token source used by
+  `pnpm gen-token-manifest`.
+- `tsconfig.json` and `pnpm-workspace.yaml`, a workspace policy suitable for a
+  fresh host.
+
+The initializer replaces the package-name placeholder in the template and
+renames the package-safe `_gitignore` to `.gitignore`. The token manifest is
+generated after installation; it is intentionally not checked into the
+template seed.
+
+## Host requirements and caveats
+
+The starter targets Preact + zfb hosts. Keep these dependencies in a host
+that adopts the engine:
+
+- `@takazudo/zdtp` is required by the injected `/tokens` route at build time.
+- `diff` and `katex` are required by the published zudo-doc route dist that
+  the host loads, even when the corresponding optional features are disabled.
+
+Keep the `tokens` block in `zudo-sg.config.mjs` as well. The initializer's
+configuration is typed with `tokens` required, and `gen-token-manifest` needs
+its two CSS paths and `manifestOut`; removing it makes the printed setup step
+fail and leaves the token dashboards without their manifest.
+
+For a host that already exists, use the manual composition and dependency
+steps in the [`@takazudo/zudo-sg` installation guide](https://github.com/Takazudo/zudo-sg/tree/main/packages/styleguide#installation)
+instead of copying this template by hand.
+
+## License
+
+MIT

package/bin/create-zudo-sg.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { main } from "../dist/cli.js";
+
+const exitCode = await main();
+if (exitCode !== 0) process.exitCode = exitCode;

package/dist/cli.d.ts

@@ -0,0 +1,44 @@
+export declare const VERSION = "0.1.0";
+export interface CliArgs {
+    destination?: string;
+    name?: string;
+    install?: boolean;
+    yes?: boolean;
+    help?: boolean;
+    version?: boolean;
+}
+export declare class CliUsageError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse the small public CLI surface. `node:util` owns option parsing; the
+ * tiny normalization step only provides the conventional `--no-install`,
+ * `-h`, `-v`, and `-y` spellings that parseArgs does not expand itself.
+ */
+export declare function parseArgs(argv?: string[]): CliArgs;
+export declare function formatNextSteps(projectDir: string): string;
+export declare function printNextSteps(projectDir: string, output?: (message: string) => void): void;
+export declare function printHelp(output?: (message: string) => void): void;
+export declare function validateArgs(args: CliArgs): string | null;
+export interface RunOptions {
+    argv?: string[];
+    /** Override the template for tests or another embedded template. */
+    templateDir?: string;
+    /** Resolve relative project paths from this directory. */
+    cwd?: string;
+    /** Output callback, kept injectable for unit tests. */
+    output?: (message: string) => void;
+    /** Input/output streams used by the missing-directory prompt. */
+    input?: NodeJS.ReadableStream;
+    outputStream?: NodeJS.WritableStream;
+    /** Tests may explicitly enable the prompt without relying on TTY state. */
+    interactive?: boolean;
+    /** Override installation for tests. */
+    install?: (targetDir: string) => void | Promise<void>;
+}
+/** Execute the initializer and return the absolute generated directory. */
+export declare function run(options?: RunOptions): Promise<string | undefined>;
+export declare function promptForProjectDirectory(input?: NodeJS.ReadableStream, outputStream?: NodeJS.WritableStream): Promise<string>;
+export declare function installDependencies(targetDir: string): void;
+/** CLI entry point used by bin/create-zudo-sg.js. */
+export declare function main(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,207 @@
+import { execFileSync } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { basename, resolve } from "node:path";
+import { stdin, stdout } from "node:process";
+import { parseArgs as parseNodeArgs } from "node:util";
+import { DEFAULT_TEMPLATE_DIR, scaffold, validateProjectName, } from "./scaffold.js";
+export const VERSION = "0.1.0";
+export class CliUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CliUsageError";
+    }
+}
+/**
+ * Parse the small public CLI surface. `node:util` owns option parsing; the
+ * tiny normalization step only provides the conventional `--no-install`,
+ * `-h`, `-v`, and `-y` spellings that parseArgs does not expand itself.
+ */
+export function parseArgs(argv = process.argv.slice(2)) {
+    const normalizedArgv = normalizeAliases(argv);
+    const parsed = parseNodeArgs({
+        args: normalizedArgv,
+        options: {
+            help: { type: "boolean" },
+            install: { type: "boolean" },
+            name: { type: "string" },
+            noInstall: { type: "boolean" },
+            version: { type: "boolean" },
+            yes: { type: "boolean" },
+        },
+        allowPositionals: true,
+        strict: true,
+    });
+    if (parsed.positionals.length > 1) {
+        throw new CliUsageError(`Expected at most one project directory, received ${parsed.positionals.length}`);
+    }
+    const values = parsed.values;
+    const args = {};
+    const [destination] = parsed.positionals;
+    if (destination !== undefined)
+        args.destination = destination;
+    if (typeof values.name === "string")
+        args.name = values.name;
+    if (values.help === true)
+        args.help = true;
+    if (values.version === true)
+        args.version = true;
+    if (values.yes === true)
+        args.yes = true;
+    // Keep the last install spelling when both are supplied. This mirrors the
+    // way most command-line tools handle repeated switches and makes the
+    // explicit `--no-install` contract unambiguous.
+    let install;
+    let afterTerminator = false;
+    for (const arg of argv) {
+        if (arg === "--") {
+            afterTerminator = true;
+            continue;
+        }
+        if (afterTerminator)
+            continue;
+        if (arg === "--install")
+            install = true;
+        if (arg === "--no-install")
+            install = false;
+    }
+    if (install !== undefined)
+        args.install = install;
+    return args;
+}
+function normalizeAliases(argv) {
+    let afterTerminator = false;
+    return argv.map((arg) => {
+        if (arg === "--") {
+            afterTerminator = true;
+            return arg;
+        }
+        if (afterTerminator)
+            return arg;
+        if (arg === "--no-install")
+            return "--noInstall";
+        if (arg === "-h")
+            return "--help";
+        if (arg === "-v")
+            return "--version";
+        if (arg === "-y")
+            return "--yes";
+        return arg;
+    });
+}
+export function formatNextSteps(projectDir) {
+    return [
+        `cd ${shellEscapePath(projectDir)}`,
+        "pnpm install",
+        "pnpm gen-registry",
+        "pnpm gen-token-manifest",
+        "pnpm dev",
+    ].join("\n");
+}
+function shellEscapePath(projectDir) {
+    if (!/[\s'"`$\\]/.test(projectDir))
+        return projectDir;
+    return `'${projectDir.replaceAll("'", "'\\''")}'`;
+}
+export function printNextSteps(projectDir, output = console.log) {
+    output(formatNextSteps(projectDir));
+}
+export function printHelp(output = console.log) {
+    output(`Usage: create-zudo-sg [project-dir] [options]
+
+Create a new pnpm-based zudo-sg styleguide project.
+
+Options:
+  --name <pkg-name>  Package name written to package.json
+  --install          Run pnpm install after scaffolding
+  --no-install       Do not install dependencies (the default)
+  --yes              Do not prompt for a missing project directory
+  --help             Show this help message
+  --version          Show the package version
+`);
+}
+export function validateArgs(args) {
+    if (args.name !== undefined)
+        return validateProjectName(args.name);
+    return null;
+}
+/** Execute the initializer and return the absolute generated directory. */
+export async function run(options = {}) {
+    const args = parseArgs(options.argv);
+    const output = options.output ?? console.log;
+    if (args.help) {
+        printHelp(output);
+        return undefined;
+    }
+    if (args.version) {
+        output(VERSION);
+        return undefined;
+    }
+    const input = options.input ?? stdin;
+    const outputStream = options.outputStream ?? stdout;
+    let displayDestination = args.destination?.trim();
+    if (!displayDestination) {
+        const interactive = options.interactive ?? Boolean(hasTTY(input) && hasTTY(outputStream));
+        if (args.yes) {
+            throw new CliUsageError("A project directory is required when --yes is provided");
+        }
+        if (!interactive) {
+            throw new CliUsageError("A project directory is required in non-interactive mode");
+        }
+        displayDestination = await promptForProjectDirectory(input, outputStream);
+        if (!displayDestination) {
+            throw new CliUsageError("A project directory is required");
+        }
+    }
+    const targetDir = resolve(options.cwd ?? process.cwd(), displayDestination);
+    const projectName = args.name ?? basename(targetDir);
+    const nameError = validateArgs({ ...args, name: projectName });
+    if (nameError)
+        throw new CliUsageError(`Invalid project name: ${nameError}`);
+    const scaffoldOptions = {
+        targetDir,
+        projectName,
+        templateDir: options.templateDir ?? DEFAULT_TEMPLATE_DIR,
+    };
+    await scaffold(scaffoldOptions);
+    if (args.install === true) {
+        if (options.install) {
+            await options.install(targetDir);
+        }
+        else {
+            installDependencies(targetDir);
+        }
+    }
+    output(`Created ${displayDestination}`);
+    printNextSteps(displayDestination, output);
+    return targetDir;
+}
+export async function promptForProjectDirectory(input = stdin, outputStream = stdout) {
+    const readline = createInterface({ input, output: outputStream });
+    try {
+        return (await readline.question("Project directory: ")).trim();
+    }
+    finally {
+        readline.close();
+    }
+}
+export function installDependencies(targetDir) {
+    execFileSync("pnpm", ["install"], {
+        cwd: targetDir,
+        stdio: "inherit",
+    });
+}
+function hasTTY(stream) {
+    return "isTTY" in stream && stream.isTTY === true;
+}
+/** CLI entry point used by bin/create-zudo-sg.js. */
+export async function main(argv = process.argv.slice(2)) {
+    try {
+        await run({ argv });
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Error: ${message}`);
+        return 1;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_TEMPLATE_DIR, isValidPackageName, scaffold, validatePackageName, validateProjectName, type ScaffoldOptions, } from "./scaffold.js";
+export { VERSION, formatNextSteps, installDependencies, main, parseArgs, printHelp, printNextSteps, promptForProjectDirectory, run, validateArgs, type CliArgs, type RunOptions, } from "./cli.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { DEFAULT_TEMPLATE_DIR, isValidPackageName, scaffold, validatePackageName, validateProjectName, } from "./scaffold.js";
+export { VERSION, formatNextSteps, installDependencies, main, parseArgs, printHelp, printNextSteps, promptForProjectDirectory, run, validateArgs, } from "./cli.js";

package/dist/scaffold.d.ts

@@ -0,0 +1,30 @@
+/** The package template shipped by create-zudo-sg. */
+export declare const DEFAULT_TEMPLATE_DIR: string;
+export interface ScaffoldOptions {
+    /** Directory to write the generated project into. */
+    targetDir: string;
+    /** Package name written to the generated package.json. */
+    projectName: string;
+    /** Template directory. Defaults to the package's templates/default tree. */
+    templateDir?: string;
+}
+/**
+ * Validate a package name using npm's lowercase package-name grammar.
+ *
+ * The initializer accepts scoped names for `--name`, while a directory's
+ * basename normally produces an unscoped name. Returning an error string
+ * keeps validation useful from both the CLI and the programmatic API.
+ */
+export declare function validateProjectName(name: string): string | null;
+export declare function isValidPackageName(name: string): boolean;
+/** Compatibility-friendly name for callers that think in npm terms. */
+export declare const validatePackageName: typeof validateProjectName;
+/**
+ * Scaffold a project from a template directory.
+ *
+ * The explicit template parameter is intentional: unit tests can supply a
+ * tiny fixture and remain independent of the separately synchronized
+ * templates/default tree.
+ */
+export declare function scaffold(options: ScaffoldOptions): Promise<string>;
+export declare function scaffold(targetDir: string, projectName: string, templateDir?: string): Promise<string>;

package/dist/scaffold.js

@@ -0,0 +1,142 @@
+import { copyFile, mkdir, readFile, readdir, readlink, stat, symlink, writeFile, } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const PROJECT_NAME_MAX = 214;
+const PACKAGE_NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
+const SCOPED_PACKAGE_NAME_RE = /^@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*$/;
+/** The package template shipped by create-zudo-sg. */
+export const DEFAULT_TEMPLATE_DIR = resolveTemplateDirectory();
+function resolveTemplateDirectory() {
+    const templateUrl = new URL("../templates/default/", import.meta.url);
+    if (templateUrl.protocol === "file:")
+        return fileURLToPath(templateUrl);
+    // Vite's root test runner rewrites import.meta.url to an HTTP URL. The
+    // package itself always runs from a file URL, but keeping this fallback
+    // makes the exported constant safe for the root vitest config too.
+    const pathname = decodeURIComponent(templateUrl.pathname).replace(/^\/\@fs\//, "/");
+    // In the monorepo's root Vite runner, module URLs are rooted at
+    // `/packages/...` rather than the filesystem root.
+    return pathname.startsWith("/packages/")
+        ? resolve(process.cwd(), pathname.slice(1))
+        : pathname;
+}
+/**
+ * Validate a package name using npm's lowercase package-name grammar.
+ *
+ * The initializer accepts scoped names for `--name`, while a directory's
+ * basename normally produces an unscoped name. Returning an error string
+ * keeps validation useful from both the CLI and the programmatic API.
+ */
+export function validateProjectName(name) {
+    if (name.length === 0)
+        return "Project name is required";
+    if (name.length > PROJECT_NAME_MAX) {
+        return `Project name must be ${PROJECT_NAME_MAX} characters or fewer`;
+    }
+    const valid = name.startsWith("@")
+        ? SCOPED_PACKAGE_NAME_RE.test(name)
+        : PACKAGE_NAME_RE.test(name);
+    if (!valid || name === "node_modules") {
+        return ("Project name must be a valid npm package name: start with a lowercase " +
+            "letter or digit (or use @scope/name), and contain only lowercase " +
+            "letters, digits, dots, underscores, and hyphens");
+    }
+    return null;
+}
+export function isValidPackageName(name) {
+    return validateProjectName(name) === null;
+}
+/** Compatibility-friendly name for callers that think in npm terms. */
+export const validatePackageName = validateProjectName;
+async function assertEmptyTarget(targetDir) {
+    try {
+        const targetStats = await stat(targetDir);
+        if (!targetStats.isDirectory()) {
+            throw new Error(`Target path "${targetDir}" is not a directory`);
+        }
+        const entries = await readdir(targetDir);
+        if (entries.length > 0) {
+            throw new Error(`Directory "${targetDir}" already exists and is not empty`);
+        }
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return;
+        throw error;
+    }
+}
+async function assertDirectory(directory, label) {
+    let directoryStats;
+    try {
+        directoryStats = await stat(directory);
+    }
+    catch (error) {
+        if (isMissingPathError(error)) {
+            throw new Error(`${label} does not exist: "${directory}"`);
+        }
+        throw error;
+    }
+    if (!directoryStats.isDirectory()) {
+        throw new Error(`${label} is not a directory: "${directory}"`);
+    }
+}
+function isMissingPathError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+/**
+ * Copy a template tree while translating `_gitignore` to `.gitignore`.
+ *
+ * npm omits `.gitignore` from published package tarballs, so the committed
+ * template uses `_gitignore` and the rename happens only while scaffolding.
+ */
+async function copyTemplateTree(sourceDir, targetDir) {
+    await mkdir(targetDir, { recursive: true });
+    const entries = await readdir(sourceDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const sourcePath = join(sourceDir, entry.name);
+        const targetName = entry.name === "_gitignore" ? ".gitignore" : entry.name;
+        const targetPath = join(targetDir, targetName);
+        if (entry.isDirectory()) {
+            await copyTemplateTree(sourcePath, targetPath);
+        }
+        else if (entry.isSymbolicLink()) {
+            await symlink(await readlink(sourcePath), targetPath);
+        }
+        else if (entry.isFile()) {
+            await copyFile(sourcePath, targetPath);
+        }
+        else {
+            throw new Error(`Unsupported template entry: "${sourcePath}"`);
+        }
+    }
+}
+export async function scaffold(optionsOrTargetDir, projectName, templateDir = DEFAULT_TEMPLATE_DIR) {
+    const options = typeof optionsOrTargetDir === "string"
+        ? {
+            targetDir: optionsOrTargetDir,
+            projectName: projectName ?? basename(resolve(optionsOrTargetDir)),
+            templateDir,
+        }
+        : optionsOrTargetDir;
+    const nameError = validateProjectName(options.projectName);
+    if (nameError)
+        throw new Error(`Invalid project name: ${nameError}`);
+    const targetDir = resolve(options.targetDir);
+    const sourceDir = resolve(options.templateDir ?? DEFAULT_TEMPLATE_DIR);
+    await assertDirectory(sourceDir, "Template directory");
+    // Validate the source before creating a target, so a malformed package
+    // cannot leave a partially generated project behind.
+    const sourcePackageJson = await readFile(join(sourceDir, "package.json"), "utf8");
+    await assertEmptyTarget(targetDir);
+    await mkdir(targetDir, { recursive: true });
+    await copyTemplateTree(sourceDir, targetDir);
+    const targetPackageJson = join(targetDir, "package.json");
+    // Preserve the template's formatting and any comments-like spacing while
+    // replacing every occurrence of the one scaffold token.
+    const packageJson = sourcePackageJson.replaceAll("__PROJECT_NAME__", options.projectName);
+    await writeFile(targetPackageJson, packageJson);
+    return targetDir;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "create-zudo-sg",
+  "version": "0.1.0",
+  "description": "Create a new zudo-sg styleguide project",
+  "license": "MIT",
+  "author": "Takeshi Takatsudo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Takazudo/zudo-sg.git",
+    "directory": "packages/create-zudo-sg"
+  },
+  "bugs": {
+    "url": "https://github.com/Takazudo/zudo-sg/issues"
+  },
+  "keywords": [
+    "create",
+    "scaffold",
+    "styleguide",
+    "zudo-sg",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "bin": {
+    "create-zudo-sg": "bin/create-zudo-sg.js"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "!dist/__tests__",
+    "CHANGELOG.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "pnpm clean && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "pnpm typecheck && pnpm build && pnpm test"
+  }
+}

package/templates/default/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.zfb-build
+pnpm-lock.yaml

package/templates/default/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@11.5.2",
+  "scripts": {
+    "dev": "zfb dev",
+    "build": "zfb build",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "gen-registry": "zudo-sg gen-registry",
+    "gen-token-manifest": "zudo-sg gen-token-manifest"
+  },
+  "dependencies": {
+    "@takazudo/zdtp": "0.8.0",
+    "@takazudo/zfb": "2.19.0",
+    "@takazudo/zfb-md-wasm": "2.19.0",
+    "@takazudo/zfb-runtime": "2.19.0",
+    "@takazudo/zudo-doc": "5.26.0",
+    "@takazudo/zudo-sg": "^0.2.0",
+    "diff": "^8.0.4",
+    "katex": "^0.16.38",
+    "preact": "^10.29.1",
+    "preact-render-to-string": "^6.6.6",
+    "tailwindcss": "^4.2.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.0"
+  }
+}

package/templates/default/pages/index.tsx

@@ -0,0 +1,23 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// The root page stays host-owned so it can import site-wide islands.
+import type { JSX } from "preact";
+// Optional islands seed; see pages/lib/_zudo-sg-islands.ts.
+import "./lib/_zudo-sg-islands";
+
+export const frontmatter = { title: "Styleguide starter" };
+
+export default function IndexPage(): JSX.Element {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <title>Styleguide starter</title>
+      </head>
+      <body>
+        <h1 data-host-index>Styleguide starter</h1>
+        <a href="/components">Components</a>
+      </body>
+    </html>
+  );
+}

package/templates/default/pages/lib/_zudo-sg-islands.ts

@@ -0,0 +1,3 @@
+// Optional islands seed for applications that import engine islands from a
+// host-owned page.
+import "@takazudo/zudo-sg/islands";

package/templates/default/pnpm-workspace.yaml

@@ -0,0 +1,9 @@
+packages: []
+allowBuilds:
+  esbuild: true
+minimumReleaseAgeExclude:
+  - "@takazudo/zfb"
+  - "@takazudo/zfb-runtime"
+  - "@takazudo/zfb-md-wasm"
+  - "@takazudo/zudo-doc"
+  - "@takazudo/zdtp"

package/templates/default/src/content/docs/getting-started.mdx

@@ -0,0 +1,5 @@
+---
+title: Getting started
+---
+
+This starter shows a minimal host application using `@takazudo/zudo-sg`.

package/templates/default/src/styleguide/sg-registry.ts

@@ -0,0 +1,10 @@
+// GENERATED by `zudo-sg gen-registry` — seed file. Run `pnpm gen-registry`
+// after changing stories; the command rewrites the block below from
+// ui/*.stories.tsx. This seed only needs the BEGIN/END markers present once.
+// GENERATED:SG_REGISTRY_BEGIN — do not hand-edit; run `pnpm gen-registry`.
+import type { StoryModule } from "@takazudo/zudo-sg/stories";
+
+export const storyModules: Record<string, StoryModule> = {};
+
+export const storyExportOrder: Record<string, string[]> = {};
+// GENERATED:SG_REGISTRY_END

package/templates/default/src/styles/preview-entry.css

@@ -0,0 +1,7 @@
+/* Host `previewStyles` entry — compiled standalone by
+   @takazudo/zudo-sg/plugins/preview-css. Preflight + utilities + this
+   project's own token sheet + an @source for the ui/ corpus. */
+@import "tailwindcss/preflight";
+@import "tailwindcss/utilities";
+@import "./ui-tokens.css";
+@source "../../ui";

package/templates/default/src/styles/ui-tokens.css

@@ -0,0 +1,113 @@
+/* Self-contained input for the packed gen-token-manifest CLI. The current
+ * generator requires this complete vocabulary; none comes from demo-ui or
+ * the workspace. The Button/Card still use only the original five tokens. */
+:root {
+  --palette-neutral-0: #ffffff;
+  --palette-neutral-1: #e2e8f0;
+  --palette-neutral-2: #475569;
+  --palette-neutral-3: #0f172a;
+  --palette-accent-0: #dbeafe;
+  --palette-accent-1: #93c5fd;
+  --palette-accent-2: #2563eb;
+  --palette-accent-3: #1e40af;
+  --palette-state-danger: #dc2626;
+  --palette-state-danger-dark: #f87171;
+  --palette-state-success: #15803d;
+  --palette-state-success-dark: #4ade80;
+  --palette-state-warning: #a16207;
+  --palette-state-warning-dark: #facc15;
+  --palette-state-info: #0369a1;
+  --palette-state-info-dark: #38bdf8;
+  --palette-line-vacuum-accent: #2563eb;
+  --palette-line-vacuum-accent-dark: #93c5fd;
+  --palette-line-vacuum-hover: #1e40af;
+  --palette-line-vacuum-hover-dark: #dbeafe;
+  --palette-line-process-accent: #2563eb;
+  --palette-line-process-accent-dark: #93c5fd;
+  --palette-line-process-hover: #1e40af;
+  --palette-line-process-hover-dark: #dbeafe;
+  --palette-line-laser-accent: #2563eb;
+  --palette-line-laser-accent-dark: #93c5fd;
+  --palette-line-laser-hover: #1e40af;
+  --palette-line-laser-hover-dark: #dbeafe;
+  --palette-line-meeting-accent: #2563eb;
+  --palette-line-meeting-accent-dark: #93c5fd;
+  --palette-line-meeting-hover: #1e40af;
+  --palette-line-meeting-hover-dark: #dbeafe;
+  --palette-line-beauty-accent: #2563eb;
+  --palette-line-beauty-accent-dark: #93c5fd;
+  --palette-line-beauty-hover: #1e40af;
+  --palette-line-beauty-hover-dark: #dbeafe;
+}
+
+@theme {
+  --color-accent: #2563eb;
+  --color-fg: #0f172a;
+  --color-bg: #ffffff;
+  --color-surface: light-dark(#ffffff, #0f172a);
+  --color-surface-2: light-dark(#e2e8f0, #475569);
+  --color-border: #475569;
+  --color-loading-scrim: #ffffff80;
+  --color-muted: #475569;
+  --color-accent-hover: #1e40af;
+  --color-on-accent: #ffffff;
+  --color-focus: #2563eb;
+  --color-rail-bg: #0f172a;
+  --color-rail-bg-strong: #0f172a;
+  --color-rail-fg: #ffffff;
+  --color-rail-muted: #e2e8f0;
+  --color-rail-border: #475569;
+  --color-rail-hover-bg: #475569;
+  --color-success: #15803d;
+  --color-danger: #dc2626;
+  --color-warning: #a16207;
+  --color-info: #0369a1;
+
+  --spacing-hsp-2xs: 0.125rem;
+  --spacing-hsp-xs: 0.25rem;
+  --spacing-hsp-sm: 0.5rem;
+  --spacing-hsp-md: 1rem;
+  --spacing-hsp-lg: 1.5rem;
+  --spacing-hsp-xl: 2rem;
+  --spacing-hsp-2xl: 3rem;
+  --spacing-vsp-3xs: 0.0625rem;
+  --spacing-vsp-2xs: 0.125rem;
+  --spacing-vsp-xs: 0.25rem;
+  --spacing-vsp-sm: 0.5rem;
+  --spacing-vsp-md: 1rem;
+  --spacing-vsp-lg: 1.5rem;
+  --spacing-vsp-xl: 2rem;
+  --spacing-vsp-2xl: 3rem;
+
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+  --text-xs--line-height: 1.5;
+  --text-sm--line-height: 1.5;
+  --text-base--line-height: 1.5;
+  --text-lg--line-height: 1.5;
+  --text-xl--line-height: 1.5;
+  --text-2xl--line-height: 1.5;
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+  --leading-tight: 1.25;
+  --leading-snug: 1.375;
+  --leading-normal: 1.5;
+  --leading-relaxed: 1.625;
+  --font-sans: sans-serif;
+  --font-mono: monospace;
+
+  --radius-DEFAULT: 0.25rem;
+  --radius-sm: 0.25rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 1rem;
+  --radius-full: 9999px;
+  --shadow-card: 0 1px 2px #0000001a;
+  --shadow-raised: 0 2px 4px #0000001a;
+  --shadow-overlay: 0 4px 8px #0000001a;
+}

package/templates/default/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "allowJs": true,
+    "checkJs": true,
+    "noEmit": true,
+    "strict": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "preact",
+    "skipLibCheck": false
+  },
+  "include": ["pages", "src", "ui", "zfb.config.ts", "zudo-sg.config.mjs"]
+}

package/templates/default/ui/button/button.mdx

@@ -0,0 +1,8 @@
+---
+title: Button
+---
+
+## Button usage notes
+
+This co-located component doc is rendered on the Button detail page from the
+`componentDocs` collection rooted at this project's `ui/` components root.

package/templates/default/ui/button/button.stories.tsx

@@ -0,0 +1,22 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { Story, StoryMeta } from "@takazudo/zudo-sg/stories";
+import { Button } from "./button.tsx";
+
+const meta: StoryMeta = {
+  title: "Button",
+  category: "Actions",
+  description: "A component rendered through the styleguide engine.",
+  usage: `import { Button } from "./ui/button/button";\n\n<Button>Primary action</Button>`,
+};
+export default meta;
+
+export const Primary: Story = {
+  name: "Primary",
+  render: () => <Button>Primary action</Button>,
+};
+
+export const Plain: Story = {
+  name: "Plain",
+  render: () => <Button tone="plain">Plain action</Button>,
+};

package/templates/default/ui/button/button.tsx

@@ -0,0 +1,16 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { ComponentChildren, JSX } from "preact";
+
+export function Button(props: { children: ComponentChildren; tone?: "accent" | "plain" }): JSX.Element {
+  const tone = props.tone ?? "accent";
+  return (
+    <button
+      type="button"
+      data-ui-button={tone}
+      class={tone === "accent" ? "bg-accent text-bg px-hsp-md py-vsp-sm" : "text-fg px-hsp-md"}
+    >
+      {props.children}
+    </button>
+  );
+}

package/templates/default/ui/card/card.stories.tsx

@@ -0,0 +1,17 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { Story, StoryMeta } from "@takazudo/zudo-sg/stories";
+import { Card } from "./card.tsx";
+
+const meta: StoryMeta = {
+  title: "Card",
+  category: "Layout",
+  description: "A second real component, proving the registry discovers more than one story file.",
+  usage: `import { Card } from "./ui/card/card";\n\n<Card title="Example">Body</Card>`,
+};
+export default meta;
+
+export const Basic: Story = {
+  name: "Basic",
+  render: () => <Card title="Example">Body content</Card>,
+};

package/templates/default/ui/card/card.tsx

@@ -0,0 +1,12 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { ComponentChildren, JSX } from "preact";
+
+export function Card(props: { title: string; children: ComponentChildren }): JSX.Element {
+  return (
+    <div data-ui-card class="border border-fg/20 rounded-md p-hsp-md">
+      <h3 class="font-bold mb-vsp-sm">{props.title}</h3>
+      {props.children}
+    </div>
+  );
+}

package/templates/default/ui/counter/counter.stories.tsx

@@ -0,0 +1,17 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { Story, StoryMeta } from "@takazudo/zudo-sg/stories";
+import Counter from "./counter.tsx";
+
+const meta: StoryMeta = {
+  title: "Counter",
+  category: "Actions",
+  description: "A `\"use client\"` island reached through the generated registry.",
+  usage: `import Counter from "./ui/counter/counter";\n\n<Counter start={3} />`,
+};
+export default meta;
+
+export const Basic: Story = {
+  name: "Basic",
+  render: () => <Counter start={3} />,
+};

package/templates/default/ui/counter/counter.tsx

@@ -0,0 +1,19 @@
+"use client";
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+
+// Real `"use client"` island reached through the generated registry. It is
+// intentionally not statically imported by a host `pages/` file.
+
+import { useState } from "preact/hooks";
+
+export default function Counter(props: { start?: number }) {
+  const [count, setCount] = useState(props.start ?? 0);
+  return (
+    <button type="button" data-counter onClick={() => setCount((c) => c + 1)}>
+      count: {count}
+    </button>
+  );
+}
+
+Counter.displayName = "Counter";

package/templates/default/zfb.config.ts

@@ -0,0 +1,26 @@
+// zfb.config.ts — styleguide starter configuration.
+//
+// This minimal zudo-doc site demonstrates a host application. `withZudoSg`
+// appends the engine's plugins and collections after `zudoDoc()`'s own — the
+// routes plugin requires `packageOwnedRoutes: true`, which `zudoDoc()`
+// defaults on.
+import { defineConfig } from "@takazudo/zfb/config";
+import { zudoDoc } from "@takazudo/zudo-doc/config";
+import { withZudoSg } from "@takazudo/zudo-sg/config";
+import zudoSgConfig from "./zudo-sg.config.mjs";
+
+export default defineConfig(
+  withZudoSg(
+    zudoDoc({
+      siteName: "Styleguide Starter",
+      base: "/",
+      port: 4397,
+      // No mermaid diagrams anywhere in this starter's one seed doc; turned
+      // off rather than leaving the default on to keep the dependency set
+      // minimal (see package.json).
+      mermaid: false,
+      strictContentBridge: true,
+    }),
+    zudoSgConfig,
+  ),
+);

package/templates/default/zudo-sg.config.mjs

@@ -0,0 +1,24 @@
+// zudo-sg.config.mjs — styleguide starter configuration.
+//
+// `componentsRoots[0].importBase` is a RELATIVE path ("../../ui", from this
+// config's registryOut directory `src/styleguide/` back up to the project
+// root's `ui/`) rather than a package name: this starter has no installed UI
+// provider package, only its own `ui/` corpus, so the generated registry's
+// `import * as … from "../../ui/<slug>.stories.tsx"` resolves as a plain
+// relative import. `uiPackageName` points at the engine's own `stories`
+// subpath (the actual origin of `StoryModule`) since there is no separate
+// provider package to attribute stories to.
+
+/** @satisfies {import("@takazudo/zudo-sg/config").ZudoSgComposeOptions} */
+export default {
+  componentsRoots: [{ dir: "ui", importBase: "../../ui" }],
+  registryOut: "./src/styleguide/sg-registry.ts",
+  categoryOrder: ["Actions", "Layout"],
+  uiPackageName: "@takazudo/zudo-sg/stories",
+  barrelIndex: null,
+  previewStyles: "./src/styles/preview-entry.css",
+  tokens: {
+    cssFiles: ["./src/styles/ui-tokens.css", "./src/styles/ui-tokens.css"],
+    manifestOut: "./src/styleguide/token-manifest.ts",
+  },
+};