zudo-sg Docs

Type to search...

to open search from anywhere

Monorepo Layout

The workspace areas and how the root styleguide, shared UI package, demo app, and docs site relate.

Workspace shape

zudo-sg is a pnpm workspace. The root package is the styleguide host, packages/styleguide is the installable styleguide engine the host dogfoods, packages/demo-ui is the component source package every site consumes, apps/demo is a static consumer app, and doc is the documentation site you are reading now.

.
|-- pages/
|-- src/
|-- packages/styleguide/
|-- packages/demo-ui/
|-- apps/demo/
`-- doc/

The root host is built with zfb, zudo-doc, MDX, zudo-wind utility CSS, and zudo-react. It owns its own site-identity pages such as / and /docs/versions; package-injected zudo-doc routes own the general docs chrome, 404, and robots behavior (plus the sitemap when settings.sitemap is enabled, which the root host leaves off); package-injected @takazudo/zudo-sg routes own the component catalog (/components, /components/[slug], /components/preview, /tokens). See Component Catalog Pipeline for how the engine is composed into the host build.

The styleguide engine (packages/styleguide)

packages/styleguide is @takazudo/zudo-sg, an installable zfb/zudo-doc plugin package built the same way @takazudo/zudo-doc itself is built: a tsup dist/ build, route entrypoints shipped as .tsx source under routes-src/ (zfb extracts a route's paths() export by AST, so a compiled .js route does not work), and a zudo-sg CLI (bin/zudo-sg.js). It owns the story registry/scaffold/token-manifest CLI commands, the catalog/detail/preview/tokens routes, the preview iframe app, the code panel, the preview token panel, and the token dashboards — everything that used to be hand-copied host application code. The full seam contract (virtual modules, staging, the host-path option channel, the now-optional islands seed) is recorded in docs/adr/styleguide-engine.md at the repository root.

Root styleguide host

The root host is deployed as zudo-sg at https://zudo-sg.takazudomodular.com/. It is the engine's dogfooding host — the same install a foreign project would perform, proven against a packed tarball by fixtures/engine-host (see Quality Gates). Its key directories are:

  • pages/: file-based routes owned by the host (/, /docs/versions, /preview/contact; the four catalog routes above are package-injected, not host files).

  • src/components/: server-rendered JSX components and content components.

  • src/config/: settings, color schemes, token manifests, and navigation config.

  • src/styleguide/: the generated story registry (sg-registry.ts) plus the thin registry.ts/nav-nodes.ts instances built with the engine's @takazudo/zudo-sg/registry.

  • zudo-sg.config.mjs: the host-level config the zudo-sg CLI and the withZudoSg() plugin composition both read (components roots, category order, token CSS files, the preview stylesheet entry).

  • src/styles/global.css: root design tokens and authored styles; the wind token map and package manifests live in zfb.config.ts.

Use server-rendered JSX by default in this host. Add zudo-react islands only when a feature needs client-side behavior, reached through a static import chain from a host pages/ file — pages/index.tsx also keeps a small pages/lib/_zudo-sg-islands.ts shim (import "@takazudo/zudo-sg/islands";); since zfb 2.18.0 the dev server seeds its island scanner from the injected routes itself, so the shim is a no-op kept for the subpath's API stability.

Shared UI package

packages/demo-ui publishes @zudo-sg/demo-ui inside the workspace. It has no build step: its package exports point directly at source files, so consumers transpile .ts and .tsx through their own zfb or Vite pipeline.

That source-consumption contract has two important consequences:

  • There is no dist/ output to compile before using UI components.

  • Consumers must register the package's wind manifest (and token map from @zudo-sg/demo-ui/styles/wind-tokens.mjs) so zfb's CSS pipeline emits the component utility classes.

The package also exports @zudo-sg/demo-ui/styles/tokens.css and @zudo-sg/demo-ui/styles/colors.css. Those CSS files are the shared token contract for consumers.

Components live under packages/demo-ui/src/<category>/<component>/, grouped into nine category directories (cards/, chrome/, content/, forms/, landing/, media/, news/, search/, shared/). The package barrel (src/index.ts) exports the full set, organized into sections that follow the story catalog's own (larger) StoryCategory taxonomy rather than the on-disk directories. See Component Catalog Pipeline for how stories are discovered and grouped.

Demo app and docs site

apps/demo is a multi-page corporate demo site deployed at https://zudo-sg-demo-site.takazudomodular.com/. Its content collection drives navigation, footer, and breadcrumbs from frontmatter; it adds cross-site search, an SPA-style client router with View Transitions, and per-business-line theming on top of @zudo-sg/demo-ui components — validating that the package works as a full site dependency, not only inside the styleguide catalog.

doc is a separate zudo-doc site deployed for contributor documentation. It should explain how zudo-sg works; it should not duplicate the styleguide catalog or become the operating manual for every styleguide panel.

The docs workspace intentionally stays close to the zudo-doc 5 scaffold: zfb.config.ts holds the site choices, pages/index.tsx re-exports the package home route, pages/docs/[[...slug]].tsx is the required self-contained development/build catch-all, and src/styles/global.css imports package-owned styling. Doc chrome, navigation, schemas, translations, and feature islands are package responsibilities rather than local copies.

Related pages

Read Component Catalog Pipeline for the story discovery flow and Design Tokens for the two token systems.