Theming

Learn how to customize Hummingbird UI with Tailwind CSS v4 theme variables, override tokens, and support multiple themes and dark mode.

Overview

Hummingbird UI is built on Tailwind CSS v4 and exposes a set of theme variables (design tokens) for colors, typography, shadows, and more. You can:

Use our theme variables (like --color-primary and --shadow-md) via standard Tailwind utilities (for example bg-primary, text-primary, shadow-md).
Override any theme variables globally by redefining it in an @theme { ... } block after importing our CSS.
Create multiple themes (e.g. light/dark/forest) by overriding the theme variables within a theme scope like @variant dark{}, or [data-theme="dark"]{}.

Hummingbird Theme Variables

Hummingbird UI provides a small, consistent set of semantic tokens as Tailwind theme variables. These variables create utilities and can be overridden later to change the look and feel without changing your HTML.

@theme {
  /* Background colors */
  --background-color-subtle: var(--color-gray-50);
  --background-color-muted: var(--color-gray-100);
  --background-color-default: var(--color-white);
  --background-color-highlight: var(--color-gray-200);
  --background-color-emphasis: var(--color-gray-300);
  /* Text colors */
  --text-color-subtle: var(--color-gray-400);
  --text-color-muted: var(--color-gray-600);
  --text-color-default: var(--color-gray-800);
  --text-color-highlight: var(--color-gray-900);
  --text-color-emphasis: var(--color-gray-950);
  /* neutral */
  --color-light: var(--color-gray-100);
  --color-dark: var(--color-gray-950);
  --color-contrast: var(--color-white);
  /* primary */
  --color-primary-lighter: var(--color-blue-50);
  --color-primary-light: var(--color-blue-400);
  --color-primary: var(--color-blue-500);
  --color-primary-dark: var(--color-blue-600);
  --color-primary-darker: var(--color-blue-900);
  /* secondary */
  --color-secondary-lighter: var(--color-purple-50);
  --color-secondary-light: var(--color-purple-300);
  --color-secondary: var(--color-purple-500);
  --color-secondary-dark: var(--color-purple-700);
  --color-secondary-darker: var(--color-purple-900);
  /* danger */
  --color-danger-lighter: var(--color-red-50);
  --color-danger-light: var(--color-red-300);
  --color-danger: var(--color-red-500);
  --color-danger-dark: var(--color-red-600);
  --color-danger-darker: var(--color-red-900);
  /* warning */
  --color-warning-lighter: var(--color-orange-50);
  --color-warning-light: var(--color-orange-400);
  --color-warning: var(--color-orange-500);
  --color-warning-dark: var(--color-orange-700);
  --color-warning-darker: var(--color-orange-900);
  /* success */
  --color-success-lighter: var(--color-green-50);
  --color-success-light: var(--color-green-400);
  --color-success: var(--color-green-500);
  --color-success-dark: var(--color-green-700);
  --color-success-darker: var(--color-green-900);
  /* info */
  --color-info-lighter: var(--color-sky-50);
  --color-info-light: var(--color-sky-300);
  --color-info: var(--color-sky-500);
  --color-info-dark: var(--color-sky-700);
  --color-info-darker: var(--color-sky-900);
  /* borders */
  --border-color-light: --alpha(var(--color-gray-300) / 60%);
  --border-color-base: var(--color-gray-300);
  --border-color-dark: var(--color-gray-600);
  /* actions */
  --color-active: var(--color-gray-500);
  --color-hover: var(--color-gray-100);
  --color-selected: var(--color-gray-100);
  --color-disabled-color: var(--color-gray-400);
  --color-disabled: var(--color-gray-200);
  --color-focus: var(--color-gray-300);
  /* font family */
  --font-sans: 'Figtree', ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
  /* Shadows */
  --shadow-2xs: 2px 2px 10px 0px rgba(0, 0, 0, 0.09), 0px 1px 1px 0px rgba(0, 0, 0, 0.03);
  --shadow-xs: 2px 9px 11px 0px rgba(0, 0, 0, 0.04), 1px 3.92px 5.79px 0px rgba(0, 0, 0, 0.04), 0px 1.36px 2.867px 0px rgba(0, 0, 0, 0.03), 0px 0.286px 1.134px 0px rgba(0, 0, 0, 0.02);
  --shadow-sm: 4px 0px 18px 0px rgba(0, 0, 0, 0.04), 0px 6.147px 9.475px 0px rgba(0, 0, 0, 0.03), 0px 2.258px 4.692px 0px rgba(0, 0, 0, 0.02), 0px -2.46px 3.86px 0px rgba(0, 0, 0, 0.02);
  --shadow-md: 3px 24px 42px 0px rgba(0, 0, 0, 0.07), 1px 10.271px 9.478px 0px rgba(0, 0, 0, 0.03), 0px 5.695px 3.531px 0px rgba(0, 0, 0, 0.01), 0px -1px 3.15px 0px rgba(0, 0, 0, 0.02);
  --shadow-lg: 4px 38px 47px 0px rgba(0, 0, 0, 0.07), 0px 20px 17.48px 0px rgba(0, 0, 0, 0.03), 1px 10px 10px 0px rgba(0, 0, 0, 0.01), 0px -2px 6px 0px rgba(0, 0, 0, 0.03);
  --shadow-xl: 6px 33px 46px 0px rgba(0, 0, 0, 0.07), 1px 20px 19px 0px rgba(0, 0, 0, 0.03), 2px 10px 10px x rgba(0, 0, 0, 0.01), 0px -2px 6px 0px rgba(0, 0, 0, 0.03);
  --shadow-2xl: 16px 39px 67px 0px rgba(0, 0, 0, 0.11), 1px 20px 65px 0px rgba(0, 0, 0, 0.02), 2px 10px 10px 0px rgba(0, 0, 0, 0.01), 0px -2px 6px 0px rgba(0, 0, 0, 0.03);
}

Customizing theme

Redefine any theme variables by declaring it in @theme after you import Hummingbird UI:

@import "tailwindcss";
@import "@hummingbirdui/hummingbird";

@theme {
--color-primary: #0074e6;
--font-sans: "Figtree", ui-sans-serif, system-ui, sans-serif;
}

Spacing

Customize spacing scale by overriding --spacing-* variables:

@theme {
  --spacing-1: 4px;
  --spacing-2: 8px;
  --spacing-3: 12px;
}

Breakpoints

Customize and add new responsive breakpoints by overriding --breakpoint-* variables:

@theme {
  --breakpoint-sm: 40rem;
  --breakpoint-md: 48rem;
  --breakpoint-lg: 64rem;
  --breakpoint-xl: 80rem;
  --breakpoint-2xl: 96rem;
  /* new */
  --breakpoint-3xl: 120rem;
}

Multiple themes

We use a small set of theme variables. By overriding these variables inside a new theme scope, you can create multiple themes.

@theme {
  --color-primary: var(--color-blue-500);
  --color-secondary: var(--color-purple-500);
}

@variant dark {
  --color-primary: var(--color-blue-400);
  --color-secondary: var(--color-purple-400);
}

@variant forest {
  --color-primary: var(--color-blue-600);
  --color-secondary: var(--color-purple-600);
}

Tailwind theme variable namespaces

Tailwind Theme variables are defined in namespaces and each namespace corresponds to one or more utility class or variant APIs.

Defining new theme variables in these namespaces will make new corresponding utilities and variants available in your project:

Namespace	Utility classes
`--color-*`	Color utilities like `bg-primary-light`, `text-primary-dark`, and many more
`--text-color-*`	Text color utilities like `text-default`, `text-subtle`, and many more
`--background-color-*`	Background color utilities like `bg-highlight`, `bg-emphasis`, and many more
`--border-color-*`	Border color utilities like `border-base`, `border-light`, and many more
`--font-*`	Font family utilities like ‘font-serif’
`--text-*`	Font size utilities like `text-xl`
`--font-weight-*`	Font weight utilities like ‘font-bold’
`--tracking-*`	Letter spacing utilities like ‘tracking-wide’
`--leading-*`	Line height utilities like `leading-tight`
`--breakpoint-*`	Responsive breakpoint variants like `sm:*`
`--container-*`	Container query variants like `@sm:*` and size utilities like `max-w-md`
`--spacing-*`	Spacing and sizing utilities like `px-4`, `max-h-16`, and many more
`--radius-*`	Border radius utilities like `rounded-sm`
`--shadow-*`	Box shadow utilities like `shadow-md`
`--inset-shadow-*`	Inset box shadow utilities like `inset-shadow-xs`
`--drop-shadow-*`	Drop shadow filter utilities like `drop-shadow-md`
`--blur-*`	Blur filter utilities like `blur-md`
`--perspective-*`	Perspective utilities like `perspective-near`
`--aspect-*`	Aspect ratio utilities like `aspect-video`
`--ease-*`	Transition timing function utilities like `ease-out`
`--animate-*`	Animation utilities like `animate-spin`

Follow the Official Tailwind CSS docs for more details

hummingbird

Getting Started

Integration guides

Customize

Layout

Forms

Components