Design System

zudo-doc's tight token strategy — spacing, typography, colors, and more.

zudo-doc uses a tight token strategy with zfb's zudo-wind compiler. Authored CSS custom properties hold the values; the package preset registers the supported utility tokens. This reference targets the aligned zfb 4.3.3 family.

Tight Token Strategy

The scaffold imports public package stylesheets and overrides values with ordinary CSS:

@layer zw-reset, zd-flow;
@import "@takazudo/zudo-doc/theme.css";
@import "@takazudo/zudo-doc/content.css";
@import "@takazudo/zudo-doc/page-loading.css";
@import "@takazudo/zudo-doc/features.css";

:root {
  --font-sans: "Inter", system-ui, sans-serif;
}

theme.css owns the custom properties and an authored @layer base reset patch. The preset selects reset: "owned-v1"; this is a zudo-wind reset plus the package patch, not identical Tailwind reset bytes. There are no Tailwind imports, @source directives, safelist stylesheet, or @theme token registration in this entry.

What utility vocabulary you have

Use named project tokens such as text-caption, bg-accent, px-hsp-md, w-icon-sm, and z-modal. Structural utilities such as flex, hidden, and grid-cols-3 and supported explicit lengths such as m-[13px] remain available. Not every Tailwind spelling is supported by zudo-wind.

The preset intentionally omits spacingUnit: nonzero numeric spacing such as p-4 does not acquire an implicit quarter-rem scale. Use named spacing or explicit bracket lengths. Zero and px remain available. Default palette names such as bg-blue-500 are not registered. Named group/peer variants, peer-checked, rings, and animations require authored CSS rather than an assumed utility.

Package classes are declared through the public @takazudo/zudo-doc/wind.json manifest. Project classes must be detectable by zfb's scanner. Add new semantic utility tokens through zudoDoc({ wind }); defining a custom property alone does not register a new utility:

import { defineConfig } from "@takazudo/zfb/config";
import { zudoDoc } from "@takazudo/zudo-doc/config";

export default defineConfig(
  zudoDoc({
    siteName: "My Docs",
    wind: {
      tokens: {
        colors: { brand: "var(--project-brand)" },
      },
    },
  }),
);

:root {
  --project-brand: var(--zd-accent);
}

zfb deep-merges this override over the preset, retaining the other package tokens. wind: false explicitly disables generation. The theme continues to use html[data-theme] and custom properties with dark: false; it does not add a separate dark-utility theme.

Run pnpm exec zfb wind audit --project-root . --fail-on error. The flag makes error diagnostics fail the command. A clean audit does not prove every conditional class was discovered or every intended rule was emitted: also check pnpm check:package-wind-manifest in this repository and inspect generated CSS and computed values on representative pages.

Spacing

zudo-doc separates spacing into two axes: horizontal (hsp) and vertical (vsp). They serve different purposes in layout — horizontal spacing controls inline rhythm and gutters, while vertical spacing controls content flow and section separation. The vertical scale is stretched at larger sizes to give content more breathing room.

Horizontal Spacing (hsp)

Vertical Spacing (vsp)

Both axes also include 0 (0px) and px (1px) utility values.

<!-- Horizontal padding + vertical padding -->
<div class="px-hsp-lg py-vsp-md">Content with asymmetric spacing</div>

<!-- Grid with dual-axis gaps -->
<div class="grid gap-x-hsp-md gap-y-vsp-lg">Grid items</div>

Element Sizes

Icon Sizes

Elevation

Only one shadow token is defined.

Typography

Font Sizes

Each semantic role references an abstract scale step (--text-scale-*); the values below are the resolved sizes.

Font Weights

Line Heights

Letter Spacing

Four steps from negative to open. Use tracking-tight on large headings to keep them optically tight; tracking-normal resets to the browser default; tracking-wide/tracking-wider suit labels and small-caps text.

Font Families

<h1 class="text-heading font-bold leading-tight">Page Title</h1>
<p class="text-body font-normal leading-normal">Body text</p>
<code class="text-small font-mono">inline code</code>

Border Radius

<button class="rounded bg-accent text-bg">Default radius</button>
<div class="rounded-lg bg-surface">Card with larger radius</div>
<span class="rounded-full bg-muted">Pill badge</span>

Breakpoints

<div class="px-hsp-sm sm:px-hsp-md lg:px-hsp-lg xl:px-hsp-xl">
  Responsive horizontal padding
</div>

max-sm, max-lg, and max-xl use a strict width less than the configured pixel value. No md or 2xl breakpoint is configured.

Z-index Tiers

Use semantic z-index tiers instead of arbitrary stack values.

Colors

Colors use a three-tier strategy: raw palette values (Tier 1) flow into semantic tokens (Tier 2), which feed into component-scoped tokens (Tier 3). Each tier only references the tier above it, so swapping a color scheme updates the entire site at once.

See the Color reference for full details on the color token system, color schemes, and customization.

Coexisting with another @theme

A host's separate Tailwind build may still use @theme, but zudo-doc's entry uses ordinary :root properties and zudo-wind token configuration. Keep the host namespace separate. zudo-doc reserves its 23 bare --color-* aliases and the --color-zd-* prefix; redefining a reserved property affects package chrome regardless of which compiler produced the stylesheet.

Import @takazudo/zudo-doc/theme.css before project overrides. There is no palette reset or theme-no-reset.css variant to choose. Existing --color-zd-* aliases remain available and are registered as wind color tokens; raw --zd-* properties belong to the color-scheme provider. Check emitted rules and the winning declaration when multiple stylesheets share a page.

Usage Rules

Do

<!-- Semantic color tokens -->
<p class="text-fg">Primary text</p>
<div class="bg-surface border border-muted">Panel</div>
<a class="text-accent hover:text-accent-hover">Link</a>

<!-- Spacing tokens -->
<div class="px-hsp-lg py-vsp-md">Proper spacing</div>
<div class="gap-x-hsp-sm gap-y-vsp-md">Grid gaps</div>

<!-- Typography tokens -->
<h2 class="text-title font-semibold leading-tight">Heading</h2>

Don't

<!-- DON'T: Tailwind defaults — not defined and produce nothing -->
<div class="p-4 bg-gray-500 text-sm">Broken</div>

<!-- DON'T: Hardcoded hex — breaks theming -->
<div class="bg-[#1e1e2e] text-[#f8f8f2]">Breaks on theme switch</div>

Default tokens ship from @takazudo/zudo-doc/theme.css; packages/zudo-doc/src/theme.css is their source of truth. The scaffold's src/styles/global.css imports those defaults and provides the project override point.

Interaction Rules

Hover-state underline for link-like elements

Elements that navigate (rendered as <a href> or behave as a link) must show an underline on hover and on keyboard focus. Buttons, toggles, and controls do not — they use a border/background change instead.

Do (navigational links):

<a class="text-accent hover:underline focus-visible:underline">Link</a>
<a class="text-fg hover:text-accent hover:underline focus-visible:underline">Sidebar item</a>

Don't (missing focus-visible parity):

<!-- DON'T: mouse users get an underline, keyboard users don't -->
<a class="text-fg hover:underline">Inaccessible to keyboard focus</a>

Don't (controls):

<!-- DON'T: buttons use border/bg hover, not underline -->
<button class="hover:underline">Use hover:bg-accent/10 instead</button>

The pair hover:underline focus-visible:underline is the canonical form — always add both, never one without the other. Precedents: packages/zudo-doc/src/header/header.tsx, src/components/site-tree-nav.tsx, packages/zudo-doc/src/footer/footer.tsx.

For the broader reasoning (light-mode / dark-mode contrast, when an underline is sufficient vs when a color shift is also needed), consult the /css-wisdom skill locally — its light-mode/dark-mode and three-tier token strategy sections cover the trade-offs.