Theming Guide

Learn how to customize colors and implement theming in your Tezos marketing sites using tezosx-ui.

Dynamic Color System

CSS Variables + Tailwind

tezosx-ui uses CSS custom properties (variables) for colors, making it easy to customize for different marketing sites without changing component code.

Key Benefits:

Override colors per marketing site
Automatic dark mode support
No component code changes needed
Runtime theme switching
Full Tailwind CSS integration

Color Tokens

Try toggling dark mode with the button in the header to see how colors adapt!

Primary

Main brand color for CTAs and links

--primary: 220 90% 56%

Secondary

Secondary actions and elements

--secondary: 280 70% 50%

Accent

Highlights and emphasis

--accent: 340 82% 52%

Destructive

Errors and dangerous actions

--destructive: 0 84% 60%

Muted

Subtle backgrounds and disabled states

--muted: 210 40% 96%

Background/Foreground

Page background and text colors

--background / --foreground

Customizing Colors

Override CSS Variables

Each marketing site can override colors in their own `globals.css` file

/* Your marketing site's globals.css */
@import "tezosx-ui/styles";

:root {
  /* Override primary color to blue */
  --primary: 220 90% 56%;
  
  /* Override secondary color to pink */
  --secondary: 340 82% 52%;
  
  /* Override accent color to green */
  --accent: 160 84% 39%;
}

.dark {
  /* Dark mode overrides */
  --primary: 220 80% 60%;
  --secondary: 340 75% 55%;
  --accent: 160 75% 45%;
}

HSL Color Format

Colors use HSL (Hue, Saturation, Lightness) without the wrapping function

Format: H S% L%

Example: --primary: 220 90% 56%

Hue (0-360): Color on the color wheel
Saturation (0-100%): Color intensity
Lightness (0-100%): Light to dark

💡 Tip: Use HSL format for easy color manipulation. Adjust lightness for hover states, saturation for disabled states.

Dark Mode Implementation

Multi-Theme Support

tezosx-ui supports both light and dark themes out of the box

Default Behavior

System preference detection
Theme persistence in localStorage
Manual toggle via ThemeToggle component
Smooth transitions between themes

// In your layout.tsx
import { ThemeProvider } from "@/components/theme-provider";

<ThemeProvider
  attribute="class"
  defaultTheme="system"
  enableSystem
>
  {children}
</ThemeProvider>

Single Theme Mode

Force light or dark mode for your marketing site

// Force light mode only
<ThemeProvider forcedTheme="light">
  {children}
</ThemeProvider>

// Force dark mode only
<ThemeProvider forcedTheme="dark">
  {children}
</ThemeProvider>

Multi-Brand Platform Example

Multiple marketing sites can use the same components with different colors:

Site A - Blue

Finance focused

--primary: 220 90% 56%

Site B - Purple

Gaming focused

--primary: 280 70% 50%

Site C - Green

Sustainability focused

--primary: 160 84% 39%

💡 Same components, different colors! All three sites use the exact same Button component from tezosx-ui, just with different CSS variable values.

Complete Token Reference

Token	Usage	Default (Light)
--primary	Main brand color, CTAs	220 90% 56%
--secondary	Secondary actions	280 70% 50%
--accent	Highlights, emphasis	340 82% 52%
--destructive	Errors, delete actions	0 84% 60%
--background	Page background	0 0% 100%
--foreground	Primary text	222 47% 11%
--muted	Subtle backgrounds	210 40% 96%
--card	Card backgrounds	0 0% 100%
--border	Border color	214 32% 91%
--ring	Focus ring	220 90% 56%

Best Practices

✓Use semantic color names (primary, destructive) instead of specific colors (blue, red)
✓Test your custom colors in both light and dark modes
✓Ensure color contrast meets WCAG AA standards (4.5:1 for text)
✓Keep saturation consistent across your color palette
✓Document your custom color values for your team
✗Don't hardcode color values in components
✗Don't use too many different colors (stick to your palette)