Theming

Customize the look and feel of your components using Tailwind CSS v4 design tokens.

CxFul UI is built with Tailwind CSS v4, which embraces a CSS-first approach to configuration. Instead of a traditional tailwind.config.js, we use design tokens defined directly in CSS variables.

The Theme File

All design tokens—including colors, typography, and spacing—are defined in: @cxful/tokens/tailwind.theme.css

This file uses the @layer theme and @theme directives to integrate seamlessly with Tailwind’s engine.

Color System

We use a multi-layered color system that provides both primitive scales and semantic tokens.

Primitive Colors

We provide full scales for neutral, brand, accent, success, warning, and error.

/* Example from tailwind.theme.css */
--color-brand-500: #168bff;
--color-brand-600: #006dcc;

Semantic Tokens

To keep designs consistent and maintainable, we use semantic tokens for backgrounds, borders, and foregrounds.

  • Surface (--color-sf-*): For page backgrounds and card surfaces.
  • Layer (--color-layer-*): For elements sitting on top of surfaces.
  • Fill (--color-fill-*): For interactive elements like buttons and inputs.
  • Foreground (--color-fg-*): For text and icons.
  • Border (--color-border-*): For dividers and outlines.

Example usage in your components:

<div class="bg-sf-base text-fg-main border-border-subtle">
  <button class="bg-fill-brand-main text-fg-white">
    Click Me
  </button>
</div>

Typography

Typography is managed through custom CSS utilities defined in the theme. These utilities handle font-family, weight, and fluid sizing (using clamp).

Commonly used typography utilities:

  • .display-2xl, .display-xl, etc.
  • .body-xl-medium, .body-md-regular, etc.
  • .code-md-regular for monospace text.
<h1 class="display-xl text-fg-solid">Welcome</h1>
<p class="body-md-regular text-fg-weak">This is a themed paragraph.</p>

Dark Mode

Our theme is dark-mode ready by default. We use the [data-theme="dark"] selector to toggle between light and dark modes.

<!-- Light Mode -->
<html data-theme="light"> ... </html>

<!-- Dark Mode -->
<html data-theme="dark"> ... </html>

The tokens automatically switch their values when the theme changes. For example, --color-sf-page resolves to white in light mode and black in dark mode.

Customizing the Theme

To customize the theme for your own project, you can:

  1. Modify Variables: Update the CSS variables in your global CSS file within a @theme block.
  2. Add New Tokens: Define new variables following the Tailwind v4 syntax.
@theme {
  --color-brand-500: #your-custom-color;
  --font-inter: "Your Custom Font", sans-serif;
}

Since Tailwind v4 is CSS-native, you don’t need to restart your dev server for most theme changes!