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. A small, intentional set of design tokens is defined from scratch. This page covers the full system: spacing, typography, colors, border radius, and breakpoints.

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.

zudo-doc solves this with selective imports in src/styles/global.css — only preflight (reset) and utilities (functional classes) are imported, while the default theme layer is skipped entirely:

@import "tailwindcss/preflight";
@import "tailwindcss/utilities";

@theme {
  /* Only define what we need — no resets necessary */
  --color-bg: var(--zd-bg);
  --color-fg: var(--zd-fg);
  /* ... */
}

Because the default theme is never loaded, no --*: initial reset block is needed. Only explicitly defined tokens in @theme work. Using an undefined token (like p-4 or bg-gray-500) produces no effect — the value simply doesn’t exist. This gives you a guarantee: invalid tokens cause build errors or missing styles, not visual bugs.

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>

Typography

Font Sizes

Font Weights

Line Heights

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>

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.

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-subheading 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>

All tokens are defined in src/styles/global.css. That file is the single source of truth for the design system.

Interaction Rules

hover

on 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: src/components/header.astro, src/components/site-tree-nav.tsx, src/components/footer.astro.

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.