@takazudo/zudo-doc 2.0.0 → 2.1.0

package/dist/config/component-tokens.js

@@ -0,0 +1,262 @@
+const COMPONENT_TOKENS = [
+  {
+    cssVar: "--zdc-doc-title-font",
+    selector: "h1.text-heading",
+    property: "font-family",
+    default: "inherit",
+    component: "doc-title",
+    surface: "content",
+    category: "typography",
+    description: "Font family of the doc-page title <h1> (and the other page-title h1s that share `text-heading`). Defaults to `inherit` so the title keeps the host's brand heading font; redefine in :root to rebrand."
+  },
+  {
+    cssVar: "--zdc-doc-title-weight",
+    selector: "h1.text-heading",
+    property: "font-weight",
+    default: "var(--font-weight-bold)",
+    component: "doc-title",
+    surface: "content",
+    category: "typography",
+    description: "Font weight of the doc-page title <h1> (and the other page-title h1s that share `text-heading`). Defaults to the `--font-weight-bold` token (matching the original `font-bold` utility)."
+  },
+  // `--tracking-normal: normal` (S2 scale token) — letter-spacing chains to the
+  // global scale so a consumer can override the entire scale in one place.
+  // Byte-identical because `normal` is the browser default for letter-spacing.
+  {
+    cssVar: "--zdc-doc-title-tracking",
+    selector: "h1.text-heading",
+    property: "letter-spacing",
+    default: "var(--tracking-normal)",
+    component: "doc-title",
+    surface: "content",
+    category: "typography",
+    description: "Letter spacing of the doc-page title <h1> (and the other page-title h1s that share `text-heading`). Defaults to `var(--tracking-normal)` (resolves to `normal` \u2014 byte-identical to the browser default); redefine in :root or tighten via `--tracking-tight`."
+  },
+  // ── Content heading h2 (HeadingH2 component, selector census: #2449) ───────
+  // `h2.text-title` matches every h2 with the `text-title` size role in the
+  // package: HeadingH2 content override (primary target), plus tag-section
+  // headings on index/locale-index pages, versions-page section headers, and
+  // modal headings (ai-chat, color-tweak-export). All share identical
+  // `text-title font-bold` styling — a semantically-consistent superset
+  // analogous to `h1.text-heading`. Byte-identical defaults produce zero
+  // computed change; a `:root` override rebrands all consistently.
+  {
+    cssVar: "--zdc-doc-h2-font",
+    selector: "h2.text-title",
+    property: "font-family",
+    default: "inherit",
+    component: "heading-h2",
+    surface: "content",
+    category: "typography",
+    description: "Font family of content h2 headings (HeadingH2 component and other h2s sharing `text-title`). Defaults to `inherit` so the heading keeps the host's brand font; redefine in :root to rebrand."
+  },
+  {
+    cssVar: "--zdc-doc-h2-weight",
+    selector: "h2.text-title",
+    property: "font-weight",
+    default: "var(--font-weight-bold)",
+    component: "heading-h2",
+    surface: "content",
+    category: "typography",
+    description: "Font weight of content h2 headings (HeadingH2 component and other h2s sharing `text-title`). Defaults to the `--font-weight-bold` token (matching the original `font-bold` utility)."
+  },
+  {
+    cssVar: "--zdc-doc-h2-tracking",
+    selector: "h2.text-title",
+    property: "letter-spacing",
+    default: "var(--tracking-normal)",
+    component: "heading-h2",
+    surface: "content",
+    category: "typography",
+    description: "Letter spacing of content h2 headings (HeadingH2 component and other h2s sharing `text-title`). Defaults to `var(--tracking-normal)` (byte-identical to the browser default); redefine in :root to tighten or widen."
+  },
+  // ── Content heading h3 (HeadingH3 component, selector census: #2449) ───────
+  // `h3.text-body.font-bold` is unique to the HeadingH3 component — no other
+  // h3 in the package emits both `text-body` and `font-bold`.
+  {
+    cssVar: "--zdc-doc-h3-weight",
+    selector: "h3.text-body.font-bold",
+    property: "font-weight",
+    default: "var(--font-weight-bold)",
+    component: "heading-h3",
+    surface: "content",
+    category: "typography",
+    description: "Font weight of content h3 headings (HeadingH3 component). Defaults to the `--font-weight-bold` token (matching the original `font-bold` utility)."
+  },
+  // ── Content heading h4 (HeadingH4 component, selector census: #2449) ───────
+  // `h4.text-body.font-semibold` is unique to the HeadingH4 component — no
+  // other h4 in the package emits both `text-body` and `font-semibold`.
+  {
+    cssVar: "--zdc-doc-h4-weight",
+    selector: "h4.text-body.font-semibold",
+    property: "font-weight",
+    default: "var(--font-weight-semibold)",
+    component: "heading-h4",
+    surface: "content",
+    category: "typography",
+    description: "Font weight of content h4 headings (HeadingH4 component). Defaults to the `--font-weight-semibold` token (matching the original `font-semibold` utility)."
+  },
+  // ── Content prose font (.zd-content, #2460) ────────────────────────────────
+  // Sets font-family on the content root so every element inside inherits it by
+  // default. The headings whose `--zdc-doc-*-font` default to `inherit` will
+  // inherit this value — safe because the current computed heading family already
+  // resolves to `var(--font-sans)` (Tailwind preflight sets it on `html`).
+  // Byte-identical: `.zd-content` currently carries no explicit font-family, so
+  // setting it to `var(--font-sans)` produces the same computed value.
+  {
+    cssVar: "--zdc-doc-prose-font",
+    selector: ".zd-content",
+    property: "font-family",
+    default: "var(--font-sans)",
+    component: "doc-prose",
+    surface: "content",
+    category: "typography",
+    description: "Font family of the prose content area (.zd-content). Defaults to `var(--font-sans)` (the inherited font \u2014 byte-identical); redefine in :root to use a distinct body font for doc content. Headings with `--zdc-doc-*-font: inherit` inherit this value."
+  },
+  // ── Content link (ContentLink component, styled path, #2460) ─────────────
+  // ContentLink returns early (unstyled) for `block` and `hash-link` classes;
+  // the styled path emits `text-accent underline hover:text-accent-hover`.
+  // Selector `a.text-accent.underline` (specificity 0,2,1) beats the `.underline`
+  // utility (0,1,0) and only matches the styled anchor — not block or hash-link
+  // variants. Default `underline` is a CSS keyword literal: no text-decoration
+  // token exists in the scale (documented exception to the prefer-var-() rule).
+  {
+    cssVar: "--zdc-doc-link-decoration",
+    selector: "a.text-accent.underline",
+    property: "text-decoration",
+    default: "underline",
+    component: "content-link",
+    surface: "content",
+    category: "typography",
+    description: "Text decoration of styled content links (the `text-accent underline` path in ContentLink; excludes block and hash-link variants). Defaults to `underline` (byte-identical to the current utility). Set to `none` to remove underlines from content links."
+  },
+  // ── Admonition block ([data-admonition], content-admonition.tsx, #2460) ───
+  // The base `[data-admonition]` rule in content.css has:
+  //   border-left: 4px solid var(--color-muted);
+  //   border-radius: 0 var(--radius-DEFAULT) var(--radius-DEFAULT) 0;
+  // Both properties are tokenized below. The token rules land in the BEGIN/END
+  // block (after the base rule in source order), so at equal specificity the
+  // token defaults override the originals — byte-identical because the defaults
+  // ARE the original values.
+  // Exception: `4px` is a bare literal — no border-width scale token exists.
+  {
+    cssVar: "--zdc-admonition-radius",
+    selector: "[data-admonition]",
+    property: "border-radius",
+    default: "0 var(--radius-DEFAULT) var(--radius-DEFAULT) 0",
+    component: "admonition",
+    surface: "content",
+    category: "shape",
+    description: "Border radius of the admonition/callout block. Defaults to the current value (0 on the left edges, `--radius-DEFAULT` on the right \u2014 preserving the flush-left accent look); redefine to round all corners or square them off."
+  },
+  {
+    cssVar: "--zdc-admonition-border-width",
+    selector: "[data-admonition]",
+    property: "border-left-width",
+    default: "4px",
+    component: "admonition",
+    surface: "content",
+    category: "shape",
+    description: "Width of the admonition left accent border. Defaults to `4px` (byte-identical to the current `border-left: 4px solid` rule). No border-width scale token exists \u2014 bare literal is the documented exception."
+  },
+  // ── Card radius (nav-indexing card grids, chrome, #2461) ──────────────────
+  // Selector census: `a.group.block` also appears in search-widget-script
+  // (search result link: `class="group block px-hsp-lg py-vsp-sm ..."`).
+  // Adding `.rounded` (present on all three card anchors — doc-card-grid,
+  // nav-card-grid, category-nav — and absent from the search result link)
+  // makes the selector unique to cards. `a.group.block.rounded` specificity
+  // 0,3,1 beats `.rounded` utility (0,1,0); unlayered beats layered (@layer
+  // utilities). No JSX change needed — cards already emit `rounded`.
+  // `--zdc-surface-radius` is a consumer meta-knob: NOT a registry entry
+  // (no single backing selector); it lives only in this default chain so a
+  // consumer can set `--zdc-surface-radius` in :root to round all surfaces.
+  {
+    cssVar: "--zdc-card-radius",
+    selector: "a.group.block.rounded",
+    property: "border-radius",
+    default: "var(--zdc-surface-radius, var(--radius-DEFAULT))",
+    component: "card-grid",
+    surface: "chrome",
+    category: "shape",
+    description: "Border radius of the nav/doc card anchor (doc-card-grid, nav-card-grid, category-nav). Defaults to `var(--zdc-surface-radius, var(--radius-DEFAULT))` \u2014 chains through the meta-knob so setting `--zdc-surface-radius` in :root rounds all surfaces at once."
+  },
+  // ── Content band max-width (.zd-doc-content-band, chrome, #2461) ──────────
+  // Two widths exist in doc-layout.tsx:
+  //   • showSidebar=true:  max-w-[clamp(50rem,75vw,90rem)] → tokenized here
+  //   • showSidebar=false: max-w-[80rem] → replaced by `data-zd-nosidebar`
+  //     attr on the band div + `.zd-doc-content-band[data-zd-nosidebar]` rule
+  //     in features.css (unlayered, specificity 0,2,0 > token rule 0,1,0).
+  // Token rule is unlayered and beats the Tailwind utility (layered). The
+  // `max-w-[clamp(50rem,75vw,90rem)]` JSX class is removed from the sidebar
+  // branch; default value is the transcribed literal — byte-identical.
+  // JS-toggle (html[data-sidebar-hidden]) remains covered by the existing
+  // `html[data-sidebar-hidden] .zd-doc-content-band` rule (specificity 0,2,1).
+  // Exception: `clamp(50rem,75vw,90rem)` is a bare CSS function expression —
+  // no equivalent design token exists (documented exception to the prefer-var()).
+  {
+    cssVar: "--zdc-content-max-width",
+    selector: ".zd-doc-content-band",
+    property: "max-width",
+    default: "clamp(50rem,75vw,90rem)",
+    component: "doc-content-band",
+    surface: "chrome",
+    category: "layout",
+    description: "Max width of the doc reading column (sidebar-present case). Defaults to `clamp(50rem,75vw,90rem)` (byte-identical to the current utility). The hide_sidebar 80rem variant is handled by `.zd-doc-content-band[data-zd-nosidebar]` in features.css; the JS-toggle variant by `html[data-sidebar-hidden] .zd-doc-content-band`."
+  },
+  // ── TOC width (nav[data-zd-toc], chrome, #2461) ───────────────────────────
+  // `nav[aria-label="Table of contents"]` has inner quotes so the parseTokens
+  // regex (which matches double-quoted strings) cannot handle it as a bare
+  // double-quoted field. `data-zd-toc` is added to the nav element in
+  // toc.tsx instead, making the selector parser-safe and an explicit anchor.
+  // Specificity 0,1,1 (element + attribute) beats `w-[280px]` (0,1,0);
+  // unlayered beats layered (@layer utilities).
+  // Exception: `280px` is a bare pixel literal — no fixed-width token exists
+  // (documented exception to the prefer-var-() rule).
+  {
+    cssVar: "--zdc-toc-width",
+    selector: "nav[data-zd-toc]",
+    property: "width",
+    default: "280px",
+    component: "toc",
+    surface: "chrome",
+    category: "layout",
+    description: "Width of the desktop Table of Contents right rail. Defaults to `280px` (byte-identical to the current `w-[280px]` utility in toc.tsx). No fixed-width design token exists \u2014 bare literal is the documented exception."
+  },
+  // ── Sidebar nav active item (a[data-nav-active], chrome, #2462) ───────────
+  // Targets non-root leaf active links in the SSR sidebar-tree island.
+  // `data-nav-active=""` is emitted on the `<a>` when `isActive && !isRoot`
+  // (sidebar-tree-island/index.tsx LeafNode). Root-level and category active
+  // items retain their unconditional `font-semibold` class (not conditional
+  // on active state) — targeting those with a single weight default would
+  // break byte-identity. Non-root leaf active is the canonical "current page"
+  // link: the most brand-identifying nav detail (#2462).
+  //
+  // Selector `a[data-nav-active]` specificity 0,1,1 beats the Tailwind
+  // utilities `bg-fg` (0,1,0) and `font-medium` (0,1,0); unlayered beats
+  // layered (@layer utilities). Defaults match the current classes exactly:
+  //   `bg-fg`      → background-color: var(--color-fg)  (byte-identical)
+  //   `font-medium`→ font-weight: var(--font-weight-medium)  (byte-identical)
+  {
+    cssVar: "--zdc-nav-active-indicator-color",
+    selector: "a[data-nav-active]",
+    property: "background-color",
+    default: "var(--color-fg)",
+    component: "nav-active",
+    surface: "chrome",
+    category: "typography",
+    description: "Background color of the active sidebar nav link (non-root leaf, the current page). Defaults to `var(--color-fg)` (byte-identical to the current `bg-fg` utility \u2014 the inversion fill that marks the active item). Redefine in :root to use an accent stripe or custom fill instead."
+  },
+  {
+    cssVar: "--zdc-nav-active-weight",
+    selector: "a[data-nav-active]",
+    property: "font-weight",
+    default: "var(--font-weight-medium)",
+    component: "nav-active",
+    surface: "chrome",
+    category: "typography",
+    description: "Font weight of the active sidebar nav link (non-root leaf, the current page). Defaults to `var(--font-weight-medium)` (byte-identical to the current `font-medium` utility). Redefine in :root to use semibold or bold for stronger active emphasis."
+  }
+];
+export {
+  COMPONENT_TOKENS
+};

package/dist/content.css

@@ -462,3 +462,59 @@
 .zd-content .mermaid foreignObject {
   overflow: visible;
 }
+
+/* ============================================================================
+ * Component tokens (`--zdc-*`) — epic zudolab/zudo-doc#2446
+ *
+ * Token-backed rules on EXISTING, component-anchored selectors. Each rule
+ * targets the classes the component already emits (NO JSX/class change) with
+ * specificity that beats the consumer's UNLAYERED Tailwind utilities, and is
+ * itself kept UNLAYERED (NOT in `@layer zd-flow`). Defaults chain to existing
+ * tokens / `inherit` (never literals) so the rendered default is byte-identical
+ * to the pre-token output — the #2425 route-injection byte-hash gate stays
+ * green — and consumer `@theme` overrides keep flowing through.
+ *
+ * Single source of truth: `src/config/component-tokens.ts`. Wave 2 (#2448) adds
+ * the `gen-component-tokens` generator that owns the BEGIN/END block below
+ * (mirroring `gen-z-index`); until then the block is maintained by hand to
+ * match what the generator will emit. Consumers rebrand a knob by redefining
+ * its `--zdc-*` custom property in `:root` — no specificity fight, reaches
+ * every route.
+ * ========================================================================== */
+
+/* BEGIN --zdc-* component tokens (generated by gen-component-tokens; do not edit by hand) */
+
+h1.text-heading {
+  font-family: var(--zdc-doc-title-font, inherit);
+  font-weight: var(--zdc-doc-title-weight, var(--font-weight-bold));
+  letter-spacing: var(--zdc-doc-title-tracking, var(--tracking-normal));
+}
+
+h2.text-title {
+  font-family: var(--zdc-doc-h2-font, inherit);
+  font-weight: var(--zdc-doc-h2-weight, var(--font-weight-bold));
+  letter-spacing: var(--zdc-doc-h2-tracking, var(--tracking-normal));
+}
+
+h3.text-body.font-bold {
+  font-weight: var(--zdc-doc-h3-weight, var(--font-weight-bold));
+}
+
+h4.text-body.font-semibold {
+  font-weight: var(--zdc-doc-h4-weight, var(--font-weight-semibold));
+}
+
+.zd-content {
+  font-family: var(--zdc-doc-prose-font, var(--font-sans));
+}
+
+a.text-accent.underline {
+  text-decoration: var(--zdc-doc-link-decoration, underline);
+}
+
+[data-admonition] {
+  border-radius: var(--zdc-admonition-radius, 0 var(--radius-DEFAULT) var(--radius-DEFAULT) 0);
+  border-left-width: var(--zdc-admonition-border-width, 4px);
+}
+
+/* END --zdc-* component tokens */

package/dist/doc-body-end/index.js

@@ -1,7 +1,9 @@
 import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
 import { SidebarResizerInit } from "../sidebar-resizer/index.js";
 import { deriveBodyEndIslands } from "../chrome/derive.js";
+import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createDocBodyEnd(ctx) {
+  assertChromeContext(ctx, "createDocBodyEnd");
   const settings = ctx.settings;
   const BodyEndIslands = deriveBodyEndIslands(ctx);
   function DocBodyEnd() {

package/dist/doc-content-header/index.js

@@ -2,7 +2,9 @@ import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
 import { FrontmatterPreview } from "../metainfo/index.js";
 import { createDocMetainfoArea } from "../doc-metainfo-area/index.js";
 import { createDocTagsArea } from "../doc-tags-area/index.js";
+import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createDocContentHeader(ctx) {
+  assertChromeContext(ctx, "createDocContentHeader");
   const t = ctx.t;
   const buildFrontmatterPreviewEntries = ctx.hostBindings.buildFrontmatterPreviewEntries ?? (() => []);
   const frontmatterRenderers = ctx.hostBindings.frontmatterRenderers ?? {};

package/dist/doc-history-area/index.js

@@ -4,7 +4,9 @@ import { BodyFootUtilArea } from "../body-foot-util/index.js";
 import { toHistorySlug } from "../slug/index.js";
 import { buildGitHubSourceUrl as buildGitHubSourceUrlBase } from "../github-helpers/index.js";
 import { deriveDocHistorySlot } from "../chrome/derive.js";
+import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createDocHistoryArea(ctx) {
+  assertChromeContext(ctx, "createDocHistoryArea");
   const settings = ctx.settings;
   const defaultLocale = ctx.defaultLocale;
   const docHistoryMeta = ctx.hostBindings.docHistoryMeta ?? {};

package/dist/doc-metainfo-area/index.js

@@ -1,6 +1,7 @@
 import { jsx } from "preact/jsx-runtime";
 import { DocMetainfo } from "../metainfo/index.js";
 import { toHistorySlug } from "../slug/index.js";
+import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 const LOCALE_TO_BCP47 = {
   en: "en-US",
   ja: "ja-JP",
@@ -16,6 +17,7 @@ function formatDate(isoDate, locale) {
   });
 }
 function createDocMetainfoArea(ctx) {
+  assertChromeContext(ctx, "createDocMetainfoArea");
   const settings = ctx.settings;
   const defaultLocale = ctx.defaultLocale;
   const docHistoryMeta = ctx.hostBindings.docHistoryMeta ?? {};

package/dist/doc-page-renderer/index.js

@@ -4,7 +4,9 @@ import { createDocContentHeader } from "../doc-content-header/index.js";
 import { createDocMetainfoArea } from "../doc-metainfo-area/index.js";
 import { createDocHistoryArea } from "../doc-history-area/index.js";
 import { deriveMdxComponents, deriveInlineVersionSwitcher } from "../chrome/derive.js";
+import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createRenderDocPage(ctx) {
+  assertChromeContext(ctx, "createRenderDocPage");
   const docsUrl = ctx.docsUrl;
   const versionedDocsUrl = ctx.versionedDocsUrl;
   const absoluteUrl = ctx.absoluteUrl;

package/dist/doc-page-shell/index.js

@@ -12,7 +12,9 @@ import { createFooterWithDefaults } from "../footer-with-defaults/index.js";
 import { createDocBodyEnd } from "../doc-body-end/index.js";
 import { createDocPager } from "../doc-pager/index.js";
 import { deriveComposeMetaTitle } from "../chrome/derive.js";
+import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createDocPageShell(ctx) {
+  assertChromeContext(ctx, "createDocPageShell");
   const settings = ctx.settings;
   const composeMetaTitle = deriveComposeMetaTitle(ctx);
   const HeadWithDefaults = createHeadWithDefaults(ctx);

package/dist/doc-pager/index.js

@@ -1,6 +1,8 @@
 import { jsx, jsxs } from "preact/jsx-runtime";
 import { ChevronLeft, ChevronRight } from "../icons/index.js";
+import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createDocPager(ctx) {
+  assertChromeContext(ctx, "createDocPager");
   const t = ctx.t;
   function DocPager({ prev, next, locale }) {
     return /* @__PURE__ */ jsxs("nav", { class: "mt-vsp-2xl grid grid-cols-2 gap-hsp-xl", children: [

package/dist/doc-tags-area/index.js

@@ -1,7 +1,9 @@
 import { jsx } from "preact/jsx-runtime";
 import { DocTags } from "../metainfo/index.js";
 import { resolvePageTags } from "../tag-helpers/index.js";
+import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createDocTagsArea(ctx) {
+  assertChromeContext(ctx, "createDocTagsArea");
   const settings = ctx.settings;
   const defaultLocale = ctx.defaultLocale;
   const withBase = ctx.withBase;

package/dist/doclayout/doc-layout.js

@@ -70,7 +70,8 @@ function DocLayout(props) {
             /* @__PURE__ */ jsx("div", { class: "flex min-h-[calc(100vh-3.5rem)] justify-center", children: /* @__PURE__ */ jsxs(
               "div",
               {
-                class: `zd-doc-content-band flex w-full gap-[clamp(1.5rem,3vw,4rem)] ${showSidebar ? "max-w-[clamp(50rem,75vw,90rem)]" : "max-w-[80rem]"}`,
+                class: "zd-doc-content-band flex w-full gap-[clamp(1.5rem,3vw,4rem)]",
+                ...!showSidebar ? { "data-zd-nosidebar": "" } : {},
                 children: [
                   /* @__PURE__ */ jsxs("main", { class: "flex-1 min-w-0 px-hsp-xl py-vsp-xl lg:px-hsp-2xl lg:py-vsp-2xl", children: [
                     breadcrumb,

package/dist/features.css

@@ -309,12 +309,13 @@ pre[class^="syntect-"] .line .highlighted-word {
     margin-left: 0;
   }
 
-  /* When hidden via the toggle, narrow the content band to the
-   * hide_sidebar frontmatter width so it centers (the flex parent already
+  /* When the sidebar is hidden via the JS toggle, narrow the content band
+   * to the hide_sidebar width so it centers (the flex parent already
    * applies justify-content: center) instead of leaving a dead gap where
-   * the sidebar was. 80rem must match the `max-w-[80rem]` hide_sidebar
-   * branch in doc-layout.tsx. These rules are unlayered, so they win over
-   * the Tailwind `max-w-[clamp(...)]` utility (utilities layer). (#2002) */
+   * the sidebar was. The 80rem value mirrors the static hide_sidebar band
+   * width (see `.zd-doc-content-band[data-zd-nosidebar]` below and in the
+   * --zdc-content-max-width chrome token). These rules are unlayered, so
+   * they win over the Tailwind utilities layer. (#2002) */
   .zd-doc-content-band {
     transition: max-width var(--zd-transition-slow) ease-in-out;
   }
@@ -324,6 +325,16 @@ pre[class^="syntect-"] .line .highlighted-word {
   }
 }
 
+/* hide_sidebar band width — applies when doc-layout.tsx sets showSidebar=false
+ * (hide_sidebar frontmatter). The `max-w-[80rem]` JSX utility was replaced by a
+ * data-zd-nosidebar attr + this rule when --zdc-content-max-width was added (#2461).
+ * Specificity 0,2,0 (class + attr) beats the generated token rule (0,1,0) so
+ * hide_sidebar pages keep their narrower 80rem reading column. All-screen (not
+ * inside @media) because the band element exists at every breakpoint. */
+.zd-doc-content-band[data-zd-nosidebar] {
+  max-width: 80rem;
+}
+
 /* Sidebar toggle button — left position uses CSS variable, needs global rule */
 @media (min-width: 1024px) {
   .zd-desktop-sidebar-toggle {
@@ -880,3 +891,41 @@ dialog.zd-mermaid-dialog::backdrop {
 .diff-line-empty {
   background-color: color-mix(in oklch, var(--color-muted) 8%, transparent);
 }
+
+/* ============================================================================
+ * Chrome component tokens (`--zdc-*`) — epic zudolab/zudo-doc#2446
+ *
+ * The CHROME-surface counterpart of the content-surface `--zdc-*` block in
+ * `src/content.css`. Token-backed rules on EXISTING, component-anchored
+ * selectors for the app shell (header/footer/sidebar/toc/cards). Each rule
+ * targets the classes the component already emits (NO JSX/class change) with
+ * specificity that beats the consumer's UNLAYERED Tailwind utilities, and is
+ * itself kept UNLAYERED (mirroring the content block) so a consumer rebrands a
+ * knob by redefining its `--zdc-*` custom property in `:root`.
+ *
+ * Single source of truth: `src/config/component-tokens.ts` (tokens with
+ * `surface: "chrome"`). The `gen-component-tokens` generator owns the BEGIN/END
+ * block below — never hand-edit between the markers. Seeded empty: no chrome
+ * tokens exist yet (S1, #2458 added only the routing mechanism).
+ * ========================================================================== */
+
+/* BEGIN --zdc-* chrome component tokens (generated by gen-component-tokens; do not edit by hand) */
+
+a.group.block.rounded {
+  border-radius: var(--zdc-card-radius, var(--zdc-surface-radius, var(--radius-DEFAULT)));
+}
+
+.zd-doc-content-band {
+  max-width: var(--zdc-content-max-width, clamp(50rem,75vw,90rem));
+}
+
+nav[data-zd-toc] {
+  width: var(--zdc-toc-width, 280px);
+}
+
+a[data-nav-active] {
+  background-color: var(--zdc-nav-active-indicator-color, var(--color-fg));
+  font-weight: var(--zdc-nav-active-weight, var(--font-weight-medium));
+}
+
+/* END --zdc-* chrome component tokens */

package/dist/footer-with-defaults/index.js

@@ -1,6 +1,8 @@
 import { jsx } from "preact/jsx-runtime";
 import { Footer } from "../footer/index.js";
+import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createFooterWithDefaults(ctx) {
+  assertChromeContext(ctx, "createFooterWithDefaults");
   const settings = ctx.settings;
   const defaultLocale = ctx.defaultLocale;
   const tagVocabulary = ctx.hostBindings.tagVocabulary ?? [];

package/dist/head/types.d.ts

@@ -79,3 +79,42 @@ export interface HeadProps {
         crossorigin?: "anonymous" | "use-credentials";
     }>;
 }
+/** Stylesheet link descriptor for {@link SiteHeadConfig}. */
+export interface HeadStylesheet {
+    href: string;
+    crossorigin?: "anonymous" | "use-credentials";
+    /** CSS media attribute applied to the `<link media>` attribute. */
+    media?: string;
+    /**
+     * When `true`, loads the stylesheet non-render-blocking via the
+     * `media="print" + onload="this.media='all'"` pattern, plus a
+     * `<noscript><link rel="stylesheet" href>` fallback.
+     * Plain (absent or `false`) emits a normal `<link rel="stylesheet">`.
+     */
+    async?: boolean;
+}
+/** Preconnect hint descriptor for {@link SiteHeadConfig}. */
+export interface HeadPreconnect {
+    href: string;
+    crossorigin?: "anonymous" | "use-credentials";
+}
+/** Preload hint descriptor for {@link SiteHeadConfig}. */
+export interface HeadPreload {
+    href: string;
+    as: string;
+    type?: string;
+    crossorigin?: "anonymous" | "use-credentials";
+}
+/** Meta tag descriptor for {@link SiteHeadConfig}. */
+export interface HeadMeta {
+    name?: string;
+    property?: string;
+    content: string;
+}
+/** Alternate link descriptor for {@link SiteHeadConfig}. */
+export interface HeadAlternateLink {
+    rel: string;
+    href: string;
+    type?: string;
+    title?: string;
+}