Design System

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

zudo-doc uses a tight token strategy — instead of importing the full Tailwind framework, only preflight and utilities are loaded, skipping the default theme entirely. The package then supplies a small, intentional set of design tokens. This page covers the full system: spacing, typography, colors, border radius, breakpoints, and layering.

Tight Token Strategy

Tailwind CSS ships with hundreds of built-in values — colors, spacing scales, font sizes, and more. In a themeable project, these defaults cause problems: hardcoded values ignore theme changes and create inconsistency.

The scaffold's src/styles/global.css imports only Tailwind's preflight (reset) and utilities (functional classes), then imports the package's token stylesheet. The default Tailwind theme layer is deliberately skipped:

@layer zd-preflight, zd-flow;
@import "tailwindcss/preflight" layer(zd-preflight);
@import "tailwindcss/utilities";
@import "@takazudo/zudo-doc/theme.css";
@import "@takazudo/zudo-doc/safelist.css";
@import "@takazudo/zudo-doc/content.css";
@import "@takazudo/zudo-doc/page-loading.css";
@import "@takazudo/zudo-doc/features.css";

/* Override package defaults here when the project needs to. */
@theme {
  /* e.g. --color-accent: oklch(0.6 0.2 250); */
}

@takazudo/zudo-doc/theme.css ships the default @theme tokens. Its package source, packages/zudo-doc/src/theme.css, is the source of truth; the scaffold's later, empty @theme block is an override point. The shipped block opens with --color-*: initial to wipe Tailwind's default palette before adding back project color tokens.

What Tailwind vocabulary you have

The tight token strategy does not remove Tailwind's utility syntax. It narrows which token-backed utilities have values. Use the project vocabulary below when writing MDX or components.

The scaffold scans MDX content, src/components/, src/chrome-bindings.tsx, and pages/ through its @source coverage and Tailwind's automatic detection. A class used in a location that is not scanned is emitted as unstyled markup, so add an @source directive when you introduce a new source location.

To re-enable a default Tailwind vocabulary, import tailwindcss/theme, or define the specific tokens you need in the project's @theme override block. Prefer a local semantic token when the value is part of the project's design language.

For examples of using this vocabulary in MDX components, see Custom Components.

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>

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

Tailwind v4 merges every @theme block reached from the stylesheet entry into one variable set. When a key appears more than once, the last declaration wins. CSS reports no error for a duplicate or for the resulting overwrite.

zudo-doc reserves 23 bare --color-* alias names and the --color-zd-* prefix. The bare aliases have these suffixes:

bg, fg, sel-bg, sel-fg, surface, muted, accent, accent-hover, code-bg, code-fg, success, danger, warning, info, overlay, image-overlay-bg, image-overlay-fg, chat-user-bg, chat-user-text, chat-assistant-bg, chat-assistant-text, matched-keyword-bg, matched-keyword-fg.

Other names, such as --color-acme-*, are yours. The package chrome consumes the bare aliases through bg-bg, text-fg, border-muted, var(--color-muted), and similar references. A second design system's @theme that defines any of these reserved names is unsupported: whichever declaration is imported last wins silently. This is separate from intentionally overriding zudo-doc's own theme for your project.

The --color-*: initial guardrail clears every --color-* declaration before it, from any file, not just Tailwind's defaults. Import @takazudo/zudo-doc/theme.css before your own @theme block, as the scaffold already does.

If the host stylesheet cannot be reordered after zudo-doc's import, use @takazudo/zudo-doc/theme-no-reset.css in place of theme.css. It has identical tokens and rules, with only the color reset removed. Under zfb's split imports (tailwindcss/preflight + tailwindcss/utilities), the default palette never exists: the variant loses nothing there, and the reset in theme.css is a defensive guardrail. A host that imports tailwindcss/theme (or uses a non-zfb @import "tailwindcss" entry) keeps the whole default palette with the variant; theme.css clears that palette when it is declared before the reset.

The --color-zd-* aliases provide one namespaced counterpart per bare alias, with the same default value. Another design system can consume zudo-doc colors through bg-zd-*, text-zd-*, and border-zd-* utilities without using the bare tier. The aliases are declared in @theme static, so their variables are always present in :root, even when your Tailwind scan uses none of them. The utilities themselves are generated only for classes your own scan sees.

For example, give the host design system an acme namespace and import its tokens after zudo-doc:

@theme {
  --color-acme-bg: oklch(0.97 0.01 250);
  --color-acme-fg: oklch(0.25 0.02 250);
}

@layer zd-preflight, zd-flow;
@import "tailwindcss/preflight" layer(zd-preflight);
@import "tailwindcss/utilities";
@import "@takazudo/zudo-doc/theme.css";
@import "./consumer.css";
@import "@takazudo/zudo-doc/safelist.css";
@import "@takazudo/zudo-doc/content.css";
@import "@takazudo/zudo-doc/page-loading.css";
@import "@takazudo/zudo-doc/features.css";

What you get with this entry:

Keep the two spellings distinct: the raw --zd-* tier is prefix-first, outside @theme, and injected by ColorSchemeProvider; the semantic --color-zd-* tier is category-first, inside @theme. Never insert color- after the raw --zd- prefix: that third spelling connects to neither tier. Check the built CSS as well as the source to confirm that the utilities you use were emitted and reference the intended tokens.

Moving the package chrome to the namespaced tier is explicitly outside this contract. Package and showcase code keep using the bare tier; a host design system that also defines the bare names remains unsupported, including with theme-no-reset.css.

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.