zudo-sg Docs

Type to search...

to open search from anywhere

/CLAUDE.md

CLAUDE.md at /CLAUDE.md

Path: CLAUDE.md

zudo-sg

Documentation site built with zudo-doc — a zfb-based documentation framework with MDX, zudo-wind CSS, and zudo-react islands.

Tech Stack

  • zfb — documentation build framework. The @takazudo/zfb* family is pinned to the stable 5.2.0 release alongside zudo-doc 9.1.2 (Node 24). The engine peers are plain ^<root pin> ranges; the doc 6 / Node 22 window and its fixtures/descriptor-host compat lane were retired with zfb 5 (ADR §13, 2026-10-24).

  • MDX — content format

  • zudo-wind — utility CSS with explicit tokens, breakpoints, and package manifests in zfb.config.ts

  • zudo-react — setup-once interactive islands with signals and activation scopes

  • syntax highlighting — built-in class-mode code highlighting, run by zfb's Rust pipeline at build time: fences render as semantic hi-* token classes under pre.hi-root, mapped to this project's --zd-syntax-* design tokens via @takazudo/zudo-doc/features.css's --zfb-hi-* bridge — no project-owned renderer, theme, or codeHighlight config required. This superseded the old project-owned WCAG-AA base16-ocean tmTheme pair from #169, so syntax colors inherit the site's existing semantic tokens rather than being baked per-span at build time.

Commands

  • pnpm dev — zfb dev server (port 4321)

  • pnpm build — static HTML export to dist/

  • pnpm check — first-party peer-floor gate (pnpm check:peer-floors), then TypeScript type checking

Key Directories

pages/                    # File-based routing (host-owned: /, /docs/versions, /preview/contact)
│                         # zudo-doc's package injects docs, 404, robots (sitemap only when
│                         # settings.sitemap is on — it is off here); @takazudo/zudo-sg
│                         # (packages/styleguide) injects /components, /components/[slug],
│                         # /components/preview and /tokens
src/
├── components/           # JSX + zudo-react components
│   └── content/          # MDX content components (admonitions, code-group, ...)
├── config/               # Settings, color schemes, design token manifests
├── content/
│   └── docs/             # Root overview + the "Architecture" category
│                         # (the styleguide engine, from the reader's side)
├── features/
│   └── styleguide/
│       └── preview-demos/ # Live-demo islands for host preview pages (/preview/contact)
├── styleguide/           # sg-registry.ts (generated by `pnpm gen:sg-registry`) + registry.ts
└── styles/
    └── global.css        # Design tokens & authored styles

There is no src/pages/ or src/layouts/ — routing lives in the root pages/ directory, and page-level chrome (header, footer, doc-route shells) is owned by @takazudo/zudo-doc's package-injected routes (packageOwnedRoutes, see src/config/settings.ts).

The styleguide catalog is dogfooded from the @takazudo/zudo-sg engine (packages/styleguide, contract: docs/adr/styleguide-engine.md), composed in zfb.config.ts via withZudoSg(preset, zudo-sg.config.mjs). Do not add pages/components/* or pages/tokens.tsx — a host page at an engine URL silently shadows the injected route. pages/index.tsx must keep importing pages/lib/_body-end-islands.tsx; it also imports pages/lib/_zudo-sg-islands.ts, kept for @takazudo/zudo-sg/islands API stability (a no-op under the current zfb 5.2.0 floor; injected-route island scanning first landed in 2.18.0 — ADR finding 4 amendment).

The tree above covers only the root host's own src/. packages/demo-ui's component tree and apps/demo's content/route tree are separate workspace packages — see "Monorepo Structure" below.

Root /docs contains the root Overview plus an Architecture category (the three-part model, the engine package, adopting it, tokens/preview CSS, and its relationship to @takazudo/zudo-doc) — a concept-level explanation of the styleguide engine for readers of this site, not the full story-authoring spec. It is self-contained and independent of the separately deployed doc/ workspace — there is no navigation between the two sites and no root build/test/check coupling to doc/ (see doc/ under "Monorepo Structure" below).

Content Conventions

Frontmatter

  • Required: title (string)

  • Optional: description, sidebar_position (number), category

  • Sidebar order is driven by sidebar_position

Admonitions

Available in all MDX files without imports: <Note>, <Tip>, <Info>, <Warning>, <Danger>, <Caution>, <Details> (via :::name directives, registered in zfb.config.ts) — plus <Important> from GitHub-style [!IMPORTANT] blockquote alerts. Each accepts an optional title prop; Details renders as a collapsible section.

Headings

Do NOT use h1 (#) in doc content — the page title from frontmatter is rendered as h1. Start content headings from h2 (##).

Components

  • Default to server-rendered JSX components (.tsx) — zero JS, server-rendered

  • Use zudo-react islands only when client-side interactivity is needed: mark the component module "use client" and mount it via zfb's <Island ssrFallback={...}> wrapper (when="load" or when="idle") — see pages/lib/_body-end-islands.tsx for the pattern. There is no client:load-style directive; that was an Astro-era convention this project no longer uses.

Demo component library

  • Engine vs host. packages/styleguide (published as @takazudo/zudo-sg) is the installable styleguide engine, built the way @takazudo/zudo-doc is built: it owns the story registry/scaffold/token-manifest CLI (zudo-sg), the catalog/detail/preview/tokens routes, the preview iframe app, the code panel, the preview token panel + iframe bridge, and the token dashboards. This root project is the engine's dogfooding host — it owns its component library (packages/demo-ui), its stories, the small zudo-sg.config.mjs, its token CSS, and the zudo-doc site config that composes the engine in via withZudoSg() (zfb.config.ts). Full seam contract: docs/adr/styleguide-engine.md; fixtures/engine-host + scripts/verify-styleguide-install.mjs prove the same install works for a foreign project (packed tarball, non-root base, outside the workspace). packages/create-zudo-sg/templates/default is a generated copy of that fixture; keep it in sync with pnpm sync:create-template and enforce the invariant with pnpm check:create-template rather than editing the template by hand.

  • @zudo-sg/demo-ui is this repo's showcase library, not a shipped provider. It is a components-only package with co-located stories under packages/demo-ui — the recommended structure for a project's own component set adopting the engine. It is not installed by the engine or its scaffold CLI, and it is not consumed by any other product; zudo-composer (Composer/Sitemapper) is a separate repository with no coupling to this one.

  • Route invariant — C2 confirmed that the styleguide-only root build emits 88 HTML routes (zfb reports 89 pages, the 89th being /robots.txt), with no HTML-route delta from the S1 baseline. The four catalog routes are injected by @takazudo/zudo-sg (dist/__zfb/routes.json lists them as pages/components.tsx, pages/components/[slug].tsx, pages/components/preview.tsx, pages/tokens.tsx overlay sources) and none may be shadowed by a host page. The what-is-zudo-sg identity page and the six-page src/content/docs/architecture/ category (index, three-part-model, engine-package, adopting, tokens-and-preview-css, relationship-to-zudo-doc, plus its Architecture header-nav entry) account for the routes beyond the pre-epic 83. Since zudo-doc 5.17.0 the package injects /sitemap.xml only when settings.sitemap is enabled, and this project sets it to false, so no sitemap route is emitted.

See packages/demo-ui/STORIES.md §10 and packages/demo-ui/README.md for the component library's authoring conventions.

Monorepo Structure

This is a pnpm workspace monorepo:

  • Root (.) — the zudo-doc styleguide host and component catalog

  • doc/ (@zudo-sg/doc) — the full docs workspace; owns Claude resource generation and doc-lookup skill setup

  • packages/demo-ui (@zudo-sg/demo-ui) — shared zudo-react component library: ~70 components under src/<category>/<component>/, grouped into 9 category directories (cards/ chrome/ content/ forms/ landing/ media/ news/ search/ shared/)

  • packages/create-zudo-sg (create-zudo-sg) — pnpm-only initializer that scaffolds a private zudo-react + zfb host from the verified engine-host template.

  • apps/demo (@zudo-sg/demo) — multi-page corporate demo site (zudo-wind, server-rendered shell with client islands): a ~70-entry content collection under content/ drives nav/footer/breadcrumbs from frontmatter, plus cross-site search (/search), an SPA-style client router with View Transitions (components/router/), and per-business-line theming (config/lines.ts, styles/lines.css)

@zudo-sg/demo-ui is consumed from source — its exports map points at ./src/* directly and it has no build script, so edits are picked up by consumers immediately; there is no dist step to run.

To build all packages: pnpm install && pnpm build (root only; apps/demo builds with pnpm --filter @zudo-sg/demo build).

Design tokens

@zudo-sg/demo-ui colors follow a grouped three-tier strategy: Tier-1 --palette-{group}-{n} ramps (base, accent, state, plus a line-* ramp per business line) feed Tier-2 semantic :root roles (bg, surface, surface-2, border, fg, muted, accent, accent-hover, on-accent, focus, the rail-* family, and the state colors), defined in packages/demo-ui/styles/colors.css. Components bind only to the Tier-2 semantic utilities (bg-accent, text-fg, border-border, …) — the Tier-1 palette is a plain :root block. Only semantic roles are registered in the wind token map, so no bg-palette-* utility is generated. Full contract: packages/demo-ui/STORIES.md §"Three-tier color system". This is independent of the doc-chrome's own --zd-* token world (src/styles/global.css) — see .claude/skills/zudo-doc-design-system/SKILL.md for how the two worlds relate. The wind token map in packages/demo-ui/styles/wind-tokens.mjs defines the utility vocabulary; root zfb.config.ts adds doc-chrome roles and composes engine sg-* roles and manifests through withZudoSg(). Component replacements use unlayered authored zc-* rules so they can override utilities emitted before authored CSS.

Since zdtp 0.9.0 the engine-owned dashboard adapter mounts zdtp's dashboard through mountTokenDashboard on the host's zudo-react runtime; no package in the repo depends on Preact for it. The root host and demo-ui do not import the adapter directly.

Enabled Features

  • search — Built-in search from zudo-doc (fetch, substring matching, weighting, and ranking); the sidebar also has its own real-time filter input, implemented in the @takazudo/zudo-doc/sidebar-tree-island package island (not a separate toggleable feature)

  • imageEnlarge — Click-to-enlarge images

  • claudeResources — Moved to the doc/ workspace

  • claudeSkills — The doc/ workspace ships zudo-doc-design-system, zudo-doc-translate, zudo-doc-version-bump skills

  • designTokenPanel — OFF. The doc-chrome token panel (the "zdtp" header button) was removed: it was host-only wiring create-zudo-sg never scaffolds, so keeping it made this dogfooding host advertise a feature adopters do not get. The engine's PREVIEW token panel (mounted by pages/lib/_body-end-islands.tsx) and the /tokens dashboard are unaffected, and bundleZdtp: true (verified in the zudo-doc 6 preset declarations) stays in zfb.config.ts so the preview panel still gets the real zdtp loader instead of the throwing stub. The header icon itself came back as an engine feature: withZudoSg()'s headerTokenTrigger option (default true) injects a header button, hidden outside the engine's own routes, that opens the same preview panel as the workbench "Preview tokens" button — see src/content/docs/overview/token-panels.mdx.

  • dynamicPageTransition — SPA client-router page swaps with View Transitions and page-loading overlay

  • sidebarResizer — Draggable sidebar width

  • sidebarToggle — Show/hide desktop sidebar

  • versioning — Multi-version documentation support

  • llmsTxt — Generates llms.txt for LLM consumption

  • skillSymlinker — Moved to the doc/ workspace (pnpm --filter @zudo-sg/doc setup:doc-skill)

  • footerNavGroup — Footer navigation link groups

  • footerCopyright — Footer copyright notice