create-zudo-sg 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to `create-zudo-sg` are documented in this file.
 
 The format is based on Keep a Changelog.
 
+## [0.1.2] - 2026-09-20
+
+Gives fresh starter projects a styled homepage and usable default navigation.
+
+### Fixed
+
+- Style the host-owned homepage with token-based typography, spacing, and
+  clearly visible links to Components and Design Tokens after Tailwind preflight.
+- Verify the packed starter's homepage markup and generated utility CSS.
+
+### Changed
+
+- Update the starter engine range to `@takazudo/zudo-sg ^0.2.2`, which supplies
+  default header navigation and search controls for minimally configured hosts.
+
+## [0.1.1] - 2026-09-20
+
+Hardens fresh starter projects and aligns them with `@takazudo/zudo-sg 0.2.1`.
+
+### Fixed
+
+- Include the complete host stylesheet needed by the catalog, detail
+  workbench, token dashboard, and responsive sidebar.
+- Ignore generated zfb cache and temporary build artifacts while continuing to
+  track the generated lockfile.
+- Exempt the starter's exact shipped zfb, zudo-doc, zdtp, and zudo-sg versions
+  from pnpm's minimum-release-age policy, including zfb platform binaries.
+- Let the first `gen-registry` run create its output instead of requiring a
+  marker-only seed file.
+
+### Changed
+
+- Update the starter engine range to `@takazudo/zudo-sg ^0.2.1`.
+- Verify generated lockfiles with a clean frozen install before release.
+
 ## [0.1.0] - 2026-09-20
 
 Initial release of the pnpm-only `create-zudo-sg` initializer.

package/README.md

@@ -16,13 +16,12 @@ 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.
+Commit the generated `pnpm-lock.yaml` so the host's dependency resolution is
+reproducible.
 
 ## Usage
 
@@ -57,13 +56,14 @@ contains:
   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/styleguide/sg-registry.ts`, generated from the three example stories.
+  Run `pnpm gen-registry` after changing stories; the CLI also bootstraps a
+  missing or whitespace-only output.
 - `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`.
+- `src/styles/global.css`, the automatically discovered host stylesheet, plus
+  `src/styles/preview-entry.css` for standalone previews and
+  `src/styles/ui-tokens.css`, the token source used by `pnpm gen-token-manifest`.
 - `tsconfig.json` and `pnpm-workspace.yaml`, a workspace policy suitable for a
   fresh host.
 
@@ -72,6 +72,48 @@ renames the package-safe `_gitignore` to `.gitignore`. The token manifest is
 generated after installation; it is intentionally not checked into the
 template seed.
 
+## Styles
+
+zfb discovers `src/styles/global.css` automatically; no page import or config
+entry is needed. Keep its imports in this order:
+
+1. Declare `@layer zd-preflight, zd-flow`, then import
+   `tailwindcss/preflight` in `layer(zd-preflight)` and unlayered
+   `tailwindcss/utilities`.
+2. Import `@takazudo/zudo-doc/theme.css`, then `./ui-tokens.css` and any
+   component package stylesheet. The theme supplies the framework tokens and
+   resets the color-token namespace; preflight is the only element reset.
+3. Import zudo-doc's `safelist.css`, `content.css`, `features.css`, and
+   `page-loading.css`, in that order.
+4. Import `@takazudo/zdtp/dashboard/styles.css` after content styles so the
+   `/tokens` dashboard wins ties with prose rules, then
+   `@takazudo/zudo-sg/styles.css` and `@takazudo/zudo-sg/safelist.css`.
+5. Keep the `@source` globs for `pages/`, `ui/`, and `src/content/`; add your
+   component package's source glob alongside them. zfb resolves these
+   global-entry paths from the project root.
+
+Keep the engine styles and Tailwind utilities unlayered: utility margins must
+outrank `zd-flow`, while engine chrome overrides must compete with utilities.
+Do not add the full `tailwindcss` import or a second preflight. If an existing
+host defines consumer-only color tokens before zudo-doc's theme, replace
+`theme.css` with `theme-no-reset.css` to preserve them. That variant only
+omits the color-token reset; tokens defined by both stylesheets still follow
+source order.
+
+The preview document uses `src/styles/preview-entry.css` independently. Add
+your component package's styles and source scan there too when previews need
+them; its `@source` paths are relative to that stylesheet. Keep dashboard and
+catalog chrome imports in the host's global entry.
+
+## Release-age exemptions
+
+The generated `pnpm-workspace.yaml` exempts only the exact versions shipped by
+this starter: zfb, its runtime and wasm packages, zudo-doc, zdtp, the engine,
+and zfb's platform binaries. Later dependency upgrades are not covered by
+these entries and follow the consumer's normal `minimumReleaseAge` policy.
+The platform binaries have their own entries because the package resolver
+checks each optional package independently.
+
 ## Host requirements and caveats
 
 The starter targets Preact + zfb hosts. Keep these dependencies in a host

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-sg",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Create a new zudo-sg styleguide project",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/default/_gitignore

@@ -1,4 +1,7 @@
 node_modules
 dist
 .zfb-build
-pnpm-lock.yaml
+.zfb/
+.zfb-esbuild-entry-*.tsx
+.zfb-islands-tsconfig-*.json
+.zfb-virtual-*.mjs

package/templates/default/package.json

@@ -13,11 +13,11 @@
   },
   "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",
+    "@takazudo/zfb": "2.20.0",
+    "@takazudo/zfb-md-wasm": "2.20.0",
+    "@takazudo/zfb-runtime": "2.20.0",
+    "@takazudo/zudo-doc": "5.26.2",
+    "@takazudo/zudo-sg": "^0.2.2",
     "diff": "^8.0.4",
     "katex": "^0.16.38",
     "preact": "^10.29.1",

package/templates/default/pages/index.tsx

@@ -12,11 +12,28 @@ export default function IndexPage(): JSX.Element {
     <html lang="en">
       <head>
         <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
         <title>Styleguide starter</title>
       </head>
-      <body>
-        <h1 data-host-index>Styleguide starter</h1>
-        <a href="/components">Components</a>
+      <body class="min-h-screen bg-bg font-sans text-base leading-normal text-fg">
+        <main class="mx-auto flex max-w-[48rem] flex-col gap-vsp-lg px-hsp-lg py-vsp-2xl">
+          <h1 data-host-index class="text-2xl font-bold leading-tight">Styleguide starter</h1>
+          <p class="text-muted">Explore your components, their stories, and the design tokens that bring them together.</p>
+          <nav aria-label="Styleguide" class="flex flex-wrap gap-hsp-md">
+            <a
+              href="/components"
+              class="inline-flex px-hsp-sm py-vsp-sm font-semibold text-accent underline hover:text-accent-hover focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus"
+            >
+              Components
+            </a>
+            <a
+              href="/tokens"
+              class="inline-flex px-hsp-sm py-vsp-sm font-semibold text-accent underline hover:text-accent-hover focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus"
+            >
+              Design Tokens
+            </a>
+          </nav>
+        </main>
       </body>
     </html>
   );

package/templates/default/pnpm-workspace.yaml

@@ -2,8 +2,14 @@ packages: []
 allowBuilds:
   esbuild: true
 minimumReleaseAgeExclude:
-  - "@takazudo/zfb"
-  - "@takazudo/zfb-runtime"
-  - "@takazudo/zfb-md-wasm"
-  - "@takazudo/zudo-doc"
-  - "@takazudo/zdtp"
+  - "@takazudo/zdtp@0.8.0"
+  - "@takazudo/zfb-darwin-arm64@2.20.0"
+  - "@takazudo/zfb-darwin-x64@2.20.0"
+  - "@takazudo/zfb-linux-arm64-gnu@2.20.0"
+  - "@takazudo/zfb-linux-x64-gnu@2.20.0"
+  - "@takazudo/zfb-md-wasm@2.20.0"
+  - "@takazudo/zfb-runtime@2.20.0"
+  - "@takazudo/zfb-win32-x64-msvc@2.20.0"
+  - "@takazudo/zfb@2.20.0"
+  - "@takazudo/zudo-doc@5.26.2"
+  - "@takazudo/zudo-sg@0.2.2"

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

@@ -1,10 +1,38 @@
-// 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`.
+// GENERATED by `zudo-sg gen-registry`.
+// Run `zudo-sg gen-registry` after changing stories; the command rewrites the
+// block below from `ui/*.stories.tsx`. Missing or whitespace-only output is
+// bootstrapped automatically; non-empty output must contain both markers.
+// GENERATED:SG_REGISTRY_BEGIN — do not hand-edit; run `zudo-sg gen-registry`.
 import type { StoryModule } from "@takazudo/zudo-sg/stories";
 
-export const storyModules: Record<string, StoryModule> = {};
+import * as button from "../../ui/button/button.stories.tsx";
+import * as card from "../../ui/card/card.stories.tsx";
+import * as counter from "../../ui/counter/counter.stories.tsx";
 
-export const storyExportOrder: Record<string, string[]> = {};
+/**
+ * Path → story module map. Keys are glob-relative (e.g.
+ * `./ui/src/button/button.stories.tsx`). Each module is
+ * `{ default: meta, ...named Story exports }`.
+ */
+export const storyModules: Record<string, StoryModule> = {
+  "./ui/button/button.stories.tsx": button as unknown as StoryModule,
+  "./ui/card/card.stories.tsx": card as unknown as StoryModule,
+  "./ui/counter/counter.stories.tsx": counter as unknown as StoryModule,
+};
+
+/**
+ * Per-story named-export declaration order (SOURCE order), keyed by the
+ * same path as `storyModules`. registry.ts sorts each story's variants
+ * by this so tabs render in authored order (and the default tab is the
+ * first-authored story) instead of the alphabetical key-enumeration order
+ * of the `import * as` namespace. Captured at codegen time because the
+ * runtime namespace cannot recover source order (#128 / #174). Superset:
+ * lists every `export const`, so registry.ts uses it only to SORT the
+ * `isStory()`-filtered variants, never to gate membership.
+ */
+export const storyExportOrder: Record<string, string[]> = {
+  "./ui/button/button.stories.tsx": ["Primary", "Plain"],
+  "./ui/card/card.stories.tsx": ["Basic"],
+  "./ui/counter/counter.stories.tsx": ["Basic"],
+};
 // GENERATED:SG_REGISTRY_END

package/templates/default/src/styles/global.css

@@ -0,0 +1,28 @@
+/* zfb discovers this entry automatically. Flow spacing beats preflight;
+ * unlayered utilities can still override the zd-flow layer. */
+@layer zd-preflight, zd-flow;
+/* The only element reset is preflight; theme.css below resets color tokens only. */
+@import "tailwindcss/preflight" layer(zd-preflight);
+@import "tailwindcss/utilities";
+
+/* Framework defaults first, then the starter's own token values. */
+@import "@takazudo/zudo-doc/theme.css";
+@import "./ui-tokens.css";
+/* Add your component package's stylesheet here, after the theme's color reset. */
+
+@import "@takazudo/zudo-doc/safelist.css";
+@import "@takazudo/zudo-doc/content.css";
+@import "@takazudo/zudo-doc/features.css";
+@import "@takazudo/zudo-doc/page-loading.css";
+
+/* Dashboard rules follow content CSS so they win ties with prose styling. */
+@import "@takazudo/zdtp/dashboard/styles.css";
+/* Keep engine styles unlayered alongside utilities so chrome overrides work. */
+@import "@takazudo/zudo-sg/styles.css";
+@import "@takazudo/zudo-sg/safelist.css";
+
+/* zfb resolves these global-entry globs from the project root.
+ * Add your component package's @source here; package chrome uses the safelists. */
+@source "pages/**/*.{tsx,ts,jsx,js}";
+@source "ui/**/*.{tsx,ts,jsx,js,mdx,md}";
+@source "src/content/**/*.{mdx,md}";

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

@@ -5,16 +5,15 @@
 // 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.
+// relative import. This host has no separate provider package, so it omits
+// `uiPackageName`; generated usage snippets use each component's own relative
+// module path instead.
 
 /** @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: {