Theme & Design Tokens

Patch UI uses a CSS custom property system with the --patch-* namespace for all visual styling. Tokens define colors, radii, shadows, and easings - and they switch automatically between light and dark mode.

Overview

Every component in Patch UI reads its colors, spacing, and motion values from CSS custom properties defined on :root. This means you can customize the entire look of the library by overriding a handful of variables in your own CSS.

The tokens are defined in @patchui/react/theme/tokens.css and imported through your Tailwind CSS file during setup.

Color Tokens

All 14 color tokens with their light and dark mode values:

Token	Light	Dark
`--patch-bg`	`#fafafa`	`#09090b`
`--patch-surface`	`#ffffff`	`#111113`
`--patch-surface-hover`	`#f5f5f5`	`#191919`
`--patch-surface-active`	`#ebebeb`	`#222222`
`--patch-text`	`#171717`	`#ededed`
`--patch-text-secondary`	`#525252`	`#a1a1a1`
`--patch-text-tertiary`	`#737373`	`#858585`
`--patch-text-quaternary`	`#b5b5b5`	`#5a5a5a`
`--patch-border`	`#e5e5e5`	`rgba(255,255,255,0.06)`
`--patch-border-hover`	`#d4d4d4`	`rgba(255,255,255,0.10)`
`--patch-border-active`	`#a3a3a3`	`rgba(255,255,255,0.15)`
`--patch-error`	`#dc2626`	`#f87171`
`--patch-success`	`#16a34a`	`#4ade80`
`--patch-warning`	`#d97706`	`#fbbf24`

Tailwind Bridge

The tokens file includes an @theme inline block that registers each --patch-* token as a Tailwind CSS v4 color. This creates --color-patch-* aliases that enable utility classes:

@theme inline {
  --color-patch-bg: var(--patch-bg);
  --color-patch-surface: var(--patch-surface);
  --color-patch-text: var(--patch-text);
  /* ... all 14 colors */
}

With this bridge in place, you can use Tailwind utilities like:

<div class="bg-patch-surface text-patch-text border-patch-border">
  Token-driven styling via Tailwind utilities
</div>

This works because Tailwind v4 treats --color-* custom properties as first-class color values.

Radius Tokens

Token	Value
`--radius-patch-sm`	`4px`
`--radius-patch-lg`	`6px`

Used via Tailwind utilities: rounded-patch-sm, rounded-patch-lg.

Shadow Tokens

Token	Value
`--shadow-patch-sm`	`0 1px 2px rgba(0,0,0,0.3)`
`--shadow-patch-md`	`0 4px 12px -2px rgba(0,0,0,0.4)`
`--shadow-patch-lg`	`0 8px 24px -4px rgba(0,0,0,0.5)`
`--shadow-patch-overlay`	`0 16px 48px -12px rgba(0,0,0,0.6)`

Used via Tailwind utilities: shadow-patch-sm, shadow-patch-md, shadow-patch-lg, shadow-patch-overlay.

Easing Tokens

Token	Value
`--ease-patch`	`cubic-bezier(0.25, 0.1, 0.25, 1)`
`--ease-patch-out`	`cubic-bezier(0.16, 1, 0.3, 1)`
`--ease-patch-in`	`cubic-bezier(0.7, 0, 0.84, 0)`

Light & Dark Mode

The token system supports light and dark mode automatically. Tokens are defined on :root for light mode and overridden inside a .dark selector for dark mode:

:root {
  --patch-bg: #fafafa;
  --patch-text: #171717;
  /* light values ... */
}
 
.dark {
  --patch-bg: #09090b;
  --patch-text: #ededed;
  /* dark values ... */
}

To switch to dark mode, add the dark class to your <html> element:

<html class="dark">

All components and token-based utilities update instantly - no JavaScript required.

Customization

Override any token in your own CSS to customize the theme. Place your overrides after the Patch UI import:

@import "tailwindcss";
@import "@patchui/react/theme/tokens.css";
@source "../node_modules/@patchui/react/src";
 
/* Custom brand colors */
:root {
  --patch-bg: #fefce8;
  --patch-surface: #fffef5;
  --patch-text: #1a1a1a;
}
 
.dark {
  --patch-bg: #0a0a0f;
  --patch-surface: #12121a;
  --patch-text: #f0f0f0;
}

Because components read from --patch-* properties at runtime, your overrides take effect everywhere - no rebuild needed.