Component Tokens

The --zdc-* override seams — a public rebrand API for component styling (typography, shape, layout) you cannot reach by editing the component.

zudo-doc ships its layout and content components from the @takazudo/zudo-doc package. Those components hardcode their Tailwind utility classes — the doc-page title is literally <h1 class="text-heading font-bold">. That is the right call for a shipped component (see Component First Strategy), but it leaves consumers a question: how do you re-style a component you do not own?

The --zdc-* component tokens are the answer. They are a small, curated set of CSS custom properties that the package exposes as supported override seams — redefine one in your own :root and the matching component restyles across every route, with no !important and no eject.

The component-library ownership inversion

The usual component-first guidance is: the component is the abstraction, so if you want a different look, change the component. That works when the component is yours. Here it is not — it lives in node_modules/@takazudo/zudo-doc. Editing it means forking or ejecting the whole component, and trying to override it from the outside means fighting unlayered Tailwind-utility specificity with !important. Both are bad doors.

So the conclusion inverts. When you cannot edit the component file, the component token becomes your scope. Instead of reaching into the component, you redefine a value the component already reads. The component-first rule still holds inside the package; the --zdc-* surface is simply the seam it exposes outward.

The one-line override

Every --zdc-* token is redefined the same way: declare it on :root. There is no API to import, no component to wrap, and no build step to run.

:root {
  --zdc-doc-title-font: "Georgia", serif;
  --zdc-doc-title-weight: 800;
}

That single block rebrands the page-title <h1> on every page — doc pages, the home page, tag pages, the versions page — because :root is global and the backing rule is unlayered with enough specificity to beat the component's own utility class. No !important is needed, and you never touch the package source.

The defaults are deliberately invisible. Each token falls back to an existing design token or inherit (for example --zdc-doc-title-weight defaults to var(--font-weight-bold), matching the original font-bold utility), so a project that overrides nothing renders byte-for-byte as before. You only opt in to the tokens you actually want to change.

How it fits the three-tier token story

zudo-doc's tokens are organized into three tiers, each referencing only the tier above it: raw palette values (Tier 1) flow into semantic tokens (Tier 2), which feed component tokens (Tier 3). See Design System and Color for the full model.

--zdc-* tokens are Tier 3 — component-scoped. But unlike the internal Tier-3 color variables inside .zd-content (which are private implementation details you should not reference), --zdc-* tokens are published as a public API: stable, documented names you are meant to redefine. They extend the same proven pattern the color system already uses, where redefining a --zd-* palette token in :root re-themes the whole site. --zdc-* brings that one-line :root override model to component typography.

Token reference

The tables below list every --zdc-* token. They are sourced directly from the registry, so they always match what the package ships.

Tokens are split by rendering surface. Content tokens target the .zd-content prose area (shipped in @takazudo/zudo-doc/content.css). Chrome tokens target the app shell — sidebar navigation, TOC, and card grids (shipped in @takazudo/zudo-doc/features.css).

Content tokens

Chrome tokens

The --zdc-surface-radius meta-knob

--zdc-surface-radius is not a registry entry — it has no backing CSS rule of its own. It exists as a link in the default chain of --zdc-card-radius:

var(--zdc-card-radius, var(--zdc-surface-radius, var(--radius-DEFAULT)))

Set --zdc-surface-radius in :root and every surface that opts into the chain rounds together — without overriding each token individually:

:root {
  --zdc-surface-radius: 0.75rem; /* rounds all surfaces at once */
}

This is the "round everything at once" knob. Individual surfaces can still break out by setting their own --zdc-card-radius (or future surface tokens) directly; the meta-knob only wins when the per-surface token is unset.

Not editable in the Design Token Panel

These are source-level override seams, not live-tweakable values.

Discovering the full set

The registry that backs the table above is the typed source of truth. It is exported from the package as @takazudo/zudo-doc/component-tokens (the COMPONENT_TOKENS array), so the complete, current list — token name, component, default, and description — is discoverable and type-checked in code, not just in this page. When the package adds a new component token, it appears in that export, and this reference is regenerated from it.