Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Dark Mode and Theming

Custom Colors, Fonts and Spacing

Build a brand palette with OKLCH, add custom fonts and a type scale, tune spacing and radius, and extend Tailwind CSS v4 without losing the defaults.

A design system is mostly three things: a palette, type and spacing. In The @theme Directive you learned how tokens become utilities. This lesson uses that knowledge to build a small but realistic brand theme, step by step: color scales with oklch, font families and sizes, spacing and radius, and the "extend or replace" decision.

Colors: a scale from one hue

Tailwind's own colors have steps from 50 (very light) to 950 (very dark). You can make your own scale the same way: one variable per step. Naming them --color-brand-50 ... --color-brand-900 gives you bg-brand-500, text-brand-700 and so on.

The modern way to write the values is oklch(lightness chroma hue). Keep the hue and roughly the chroma constant and only walk the lightness from high to low. The result is a scale that feels consistent, and because OKLCH is perceptually uniform, equal lightness steps look like equal brightness steps.

A generated brand scale

You can also use hex, rgb() or hsl(). If you use OKLCH colors on older browsers, Tailwind v4 relies on modern CSS (it targets Safari 16.4+, Chrome 111+, Firefox 128+). If you must support older browsers, stay on Tailwind v3.4.

Semantic names

Besides palette steps, give colors a role: --color-surface, --color-ink, --color-accent. When roles are used in templates, a rebrand changes one line. Roles are also how you implement dark mode and multiple themes (see Multiple Themes with CSS Variables).

CSS
@theme {
  --color-accent: var(--color-brand-500);
  --color-surface: white;
  --color-ink: var(--color-slate-900);
}

Because the right side refers to other variables, @theme inline is the safe choice when the referenced variable is not declared in the same block.

Opacity and mixing

Every color utility accepts an opacity modifier: bg-brand-500/20, text-ink/70, border-white/10. Tailwind v4 implements it with color-mix(in oklab, ...), so it works even for colors defined with variables. For a one-off color with no theme entry, use an arbitrary value: bg-[#0ea5e9] or bg-[oklch(0.7_0.15_200)] (underscores stand for spaces).

Fonts

Fonts have two parts: loading the font file, and mapping it to a utility.

  1. Loading is plain CSS or HTML: a <link> to a font service or an @font-face rule. Self-hosting avoids third-party requests.
  2. Mapping uses the --font-* namespace.
CSS
@import "tailwindcss";

@font-face {
  font-family: "Inter";
  src: url("/fonts/inter-variable.woff2") format("woff2");
  font-weight: 100 900;
  font-display: swap;
}

@theme {
  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-display: "Fraunces", Georgia, serif;
  --font-mono: "JetBrains Mono", ui-monospace, monospace;
}

Redefining --font-sans changes the default body font (Tailwind's base styles use it on html). A new name such as --font-display creates font-display. Remember the fallbacks; they are what shows while the web font loads.

Display and body fonts

The suffixes --text-hero--line-height and --text-hero--letter-spacing attach defaults to a font-size token, so text-hero sets all three at once.

Spacing, sizes and radius

Most projects keep the default spacing scale. When you change it, change the single base variable, not each step.

CSS
@theme {
  --spacing: 0.25rem;            /* default; every number multiplies it */
  --radius-card: 1rem;           /* rounded-card */
  --radius-pill: 9999px;         /* rounded-pill */
  --container-prose-narrow: 38rem;  /* max-w-prose-narrow */
}

Named tokens such as rounded-card beat magic numbers in templates: when the designer asks for softer corners, you edit one token.

Radius and spacing tokens at work

Extend or replace?

Goal How
Keep every default and add a few tokens Declare only the new names
Change one default value Redeclare that exact name
Use only your own palette --color-*: initial; then declare yours
Start from a blank slate --*: initial;

A team that wants consistency often resets colors, because designers rarely want 22 default hues. Beginners are better served by keeping the defaults and adding brand colors, which is what the examples above do.

Where does this CSS live?

In a real project all of this sits in one file, usually app.css, next to @import "tailwindcss";. You never need a separate config file. If you are migrating a v3 project that still has tailwind.config.js, you can load it with @config "./tailwind.config.js";, covered in Build Tools and Upgrading.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which tokens produce the utilities bg-brand-500 and text-brand-700?

    Each step is its own --color-* variable; the part after --color- becomes the utility suffix.
  2. 2. Why build a color scale in OKLCH?

    OKLCH is perceptually uniform; walking lightness while keeping hue gives predictable scales.
  3. 3. How do you attach a default line height to the size token --text-hero?

    The double-dash suffix --line-height makes text-hero set the line height too.
  4. 4. What is the quickest way to scale all spacing utilities?

    Spacing utilities are calc(var(--spacing) * N), so changing the base scales them all.

Summary

  • Build color scales as --color-name-STEP variables, ideally in OKLCH; add semantic roles such as --color-accent on top.
  • Load fonts with @font-face or a <link>, and map them with --font-*; give custom size tokens line height and tracking through suffixes.
  • --spacing, --radius-* and --container-* tokens replace magic numbers.
  • Extend by adding names, override by redeclaring, replace by resetting a namespace to initial.

Next: Multiple Themes with CSS Variables