l-design-system

Design system reference for the Takazudo Modular website. Use PROACTIVELY when writing or modifying CSS/styling. Provides token names, spacing scales, color semantics, and typography rules. Do NOT inv...

Zudo Design System Reference

Tight token strategy: Tailwind v4 with NO default theme (Approach B — only tailwindcss/preflight + tailwindcss/utilities imported). Only project tokens via @theme in sub-packages/design-system/theme.css. Never use raw pixel/rem values or default Tailwind classes like h-3, w-4, p-4, bg-gray-500 — they don’t exist and will cause build errors.

For full token definitions, read sub-packages/design-system/tokens.css and sub-packages/design-system/theme.css.

Also invoke /css-wisdom <topic> for broader CSS patterns and best practices.

Component-First Rule

Always create components with utility classes. Never create custom CSS class names (.card, .btn-primary) for UI styling. The component is the abstraction. Exception: @utility definitions in the design system package itself.

No CSS Modules

Do not use .module.css files. For complex CSS that can’t be expressed as Tailwind utilities (keyframe animations, clip-paths), use plain CSS files with unique class prefixes imported as side effects:

import './hamster-animation.css'; // side-effect import
<div className="hamster-wheel">   // direct class name, no styles.xxx

Spacing

Two semantic axes. Never use numeric Tailwind classes (p-4, m-8, gap-2).

Horizontal (hgap):

Token	Value	Use
`hgap-2xs`	5px	Tight inline spacing
`hgap-xs`	12px	Small gaps, tag padding
`hgap-sm`	20px	Default horizontal padding
`hgap-md`	40px	Section spacing
`hgap-md-x2`	80px	Large section spacing
`hgap-lg`	60px	Major layout divisions
`hgap-lg-x2`	120px	Extra large divisions
`hgap-xl`	100px	Page margins
`hgap-2xl`	250px	Maximum spacing

Vertical (vgap):

Token	Value	Use
`vgap-2xs`	4px	Minimal gaps
`vgap-xs`	8px	Tight component gaps
`vgap-sm`	20px	Default vertical gaps
`vgap-md`	35px	Section gaps
`vgap-lg`	50px	Large section gaps
`vgap-xl`	65px	Page section gaps
`vgap-2xl`	80px	Major section gaps

Special: 0 (zero), 1px (hairline)

Usage: px-hgap-md, py-vgap-sm, gap-hgap-xs, gap-y-vgap-md, mt-vgap-lg, mx-hgap-sm

Colors

Three-tier architecture: Palette (p0–p15) → Semantic → Component.

Tier 2: Semantic Colors (primary usage)

Token	Use
`bg` / `fg`	Page background / main text
`surface`	Cards, panels, elevated backgrounds
`muted`	Secondary text, disabled elements
`accent` / `accent-hover`	Links, CTAs, interactive elements
`link`	Link color (white — dark theme)
`success` / `danger` / `warning` / `info`	Status colors
`price` / `sold`	Price displays, sold indicators
`code-bg` / `code-fg`	Code blocks

Usage: bg-bg, text-fg, bg-surface, text-muted, bg-accent, text-price

Tier 1: Palette (raw values, for reference)

Token	Role
`p0`	Dark surface (#201f1f)
`p1`	Danger/red
`p2`	Success/green
`p3`	Warning/yellow
`p4`	Info/link (pure white)
`p5`	Accent/primary (orange)
`p6`	Neutral/gray
`p7`	Light text (headings)
`p8`	Muted text
`p9`	Background (dark)
`p10`	Surface (slightly lighter)
`p11`	Text primary (= p7)
`p12`	Price/highlight (yellow)
`p13`	Sold/special
`p14`	Accent hover (darker p5)
`p15`	Secondary text

Usage: bg-p9, text-p7, border-p6

Legacy Colors (still available)

Token	Use
`zd-black`	Dark backgrounds (`rgb(28,25,23)`)
`zd-white`	Light text (`rgb(214,211,209)`)
`zd-link`	Links (`#fff`)
`zd-active`	Active state (`#713f12`)
`zd-gray` / `zd-gray2`	Grays
`zd-notify`	Success (`#22c55e`)
`zd-error`	Error (`#f43f5e`)
`zd-warning`	Warning (`#f59e0b`)
`zd-price`	Price (`#fbbf24`)
`zd-strong`	Emphasis (`#d97706`)
`zd-sold`	Sold status
`zd-outline`	Focus outline (`#ea580c`)
`zd-mercari-corporate`	Mercari brand (`#b91c1c`)

Usage: bg-zd-black, text-zd-white, text-zd-price, border-zd-gray

Status Colors (admin interfaces)

status-pending, status-notified, status-confirmed, status-fulfilled, status-cancelled — available as both color tokens (bg-status-pending) and custom utility classes (status-pending sets both bg and text).

Button Colors (admin interfaces)

btn-success / btn-success-hover, btn-danger / btn-danger-hover, btn-warning / btn-warning-hover, btn-info / btn-info-hover

Typography

Font Sizes (with integrated line heights)

Class	Size	Line Height
`text-xs`	1rem (10px)	1.4
`text-sm`	1.1rem (11px)	1.5
`text-base`	1.4rem (14px)	1.7
`text-lg`	1.6rem (16px)	1.5
`text-xl`	1.9rem (19px)	1.4
`text-2xl`	2.8rem (28px)	1.35
`text-3xl`	3.2rem (32px)	1.3
`text-4xl`	4rem (40px)	1.3
`text-5xl`	4.8rem (48px)	1.3

Fonts

Class	Use
`font-noto`	Noto Sans / Noto Sans JP — Japanese body text
`font-futura`	Futura / Jost — headings, navigation
`font-sans`	Helvetica / Arial — general sans-serif
`font-mono`	Menlo / Monaco — code

Line Heights (standalone override)

leading-none(1), leading-tight(1.4), leading-snug(1.6), leading-normal(1.8), leading-relaxed(1), leading-loose(2.3)

Font Weights

font-thin(100), font-extralight(200), font-light(300), font-normal(400), font-medium(500), font-semibold(600), font-bold(700), font-extrabold(800), font-black(900)

Breakpoints

Prefix	Width
`sm:`	580px
`md:`	740px
`lg:`	980px
`xl:`	1280px
`2xl:`	1630px
`3xl:`	1800px

Border Radius

rounded-xs(0.125rem), rounded-sm(0.25rem), rounded-md(0.375rem), rounded-lg(0.5rem)

Box Shadows

shadow-sm, shadow, shadow-md, shadow-lg, shadow-xl, shadow-2xl, shadow-inner, shadow-none

Custom Utilities

Defined in sub-packages/design-system/utilities.css:

text-shadow-md — text shadow for readability on images
text-shadow-none — remove text shadow
zd-gradient-black-to-transparent — black to transparent gradient
zd-gradient-white-to-transparent — white to transparent gradient
clearfix — clearfix for float layouts
status-* — status badge styles (sets both bg and text color)

Common Patterns

// Page container
px-hgap-sm py-vgap-md

// Card/panel
bg-surface p-hgap-xs rounded-lg

// Product card
bg-zd-gray2 p-hgap-xs

// Grid layout
grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-hgap-xs gap-y-vgap-sm

// Section spacing
mt-vgap-lg mb-vgap-xl

// Price display
text-zd-price text-xl

// Link on dark background
text-zd-link hover:text-zd-strong

SVG Icons

Use explicit width/height attributes — Tailwind size classes (h-N/w-N) don’t exist. Add shrink-0 in flex.

<svg width="16" height="16" className="shrink-0" viewBox="0 0 16 16" fill="currentColor">

Key Source Files

sub-packages/design-system/tokens.css — all --zd-* token definitions
sub-packages/design-system/theme.css — @theme block mapping tokens to Tailwind
sub-packages/design-system/utilities.css — custom @utility definitions