Learn

Building Gradient Tokens for Design Systems

Gradients without tokens drift. Every team member ends up with their own version of 'the purple gradient'. Here's how to nail down your gradient system.

Why gradient tokens matter

In a design system, tokens are the source of truth for visual decisions. Colors, spacing, typography — all benefit from being named and centralized. Gradients are no different.

Without tokens, you end up with:

  • Slightly different gradients on different components ("is this the same purple gradient as the hero?")
  • Copy-pasted CSS that breaks when the brand palette changes.
  • No way to switch themes without updating dozens of gradient declarations.

Naming strategy

Name gradients by their semantic role, not their visual appearance. A gradient named gradient-hero survives a rebrand. A gradient named gradient-blue-to-purple does not.

/* Semantic naming — role-based */
--gradient-hero: linear-gradient(135deg, #6366f1 0%, #a855f7 100%);
--gradient-cta: linear-gradient(90deg, #f97316 0%, #ef4444 100%);
--gradient-surface-elevated: linear-gradient(180deg, var(--color-surface-2) 0%, var(--color-surface-1) 100%);
--gradient-scrim: linear-gradient(to bottom, transparent 0%, rgba(0,0,0,0.7) 100%);

/* Palette-level (reference tokens — use sparingly) */
--gradient-violet: linear-gradient(135deg, #6366f1, #a855f7);
--gradient-sunset: linear-gradient(135deg, #f97316, #ef4444);

CSS custom properties

CSS custom properties (variables) are the most straightforward way to define gradient tokens. Define them on :root (or a theme wrapper) and reference them anywhere:

:root {
  --gradient-brand-primary: linear-gradient(135deg, #6366f1 0%, #a855f7 100%);
  --gradient-brand-secondary: linear-gradient(135deg, #0ea5e9 0%, #6366f1 100%);
  --gradient-neutral-scrim: linear-gradient(to bottom, transparent 0%, rgba(0,0,0,0.6) 100%);
}

/* Usage */
.hero {
  background: var(--gradient-brand-primary);
}

.image-caption {
  background: var(--gradient-neutral-scrim);
}

Theme overrides

Gradient tokens can be overridden per theme just like color tokens:

:root {
  --gradient-brand-primary: linear-gradient(135deg, #6366f1 0%, #a855f7 100%);
}

[data-theme="dark"] {
  --gradient-brand-primary: linear-gradient(135deg, #4f46e5 0%, #9333ea 100%);
}

[data-theme="high-contrast"] {
  --gradient-brand-primary: linear-gradient(135deg, #000 0%, #000 100%);
}

Tailwind: extending the config

Tailwind doesn't have first-class gradient token support, but you can add named gradients to backgroundImage in your config:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      backgroundImage: {
        'brand-primary': 'linear-gradient(135deg, #6366f1 0%, #a855f7 100%)',
        'brand-secondary': 'linear-gradient(135deg, #0ea5e9 0%, #6366f1 100%)',
        'neutral-scrim': 'linear-gradient(to bottom, transparent 0%, rgba(0,0,0,0.6) 100%)',
      }
    }
  }
}

// Usage in templates
<div class="bg-brand-primary">…</div>

Style Dictionary / Token Studio

For large teams, define gradient tokens in a token file and transform them to any output format using Style Dictionary:

// tokens/gradient.json
{
  "gradient": {
    "brand": {
      "primary": {
        "value": "linear-gradient(135deg, {color.violet.600} 0%, {color.purple.500} 100%)",
        "type": "gradient"
      }
    }
  }
}

Token Studio for Figma can read these files, keeping design and code in sync.

Figma: gradient styles

In Figma, define gradients as fill styles. Use the same semantic names as your CSS tokens. When exporting or handing off to developers, the gradient code should match your CSS token values exactly.

  • Create a Gradients section in your Figma styles panel.
  • Name styles using slash notation: Gradient/Brand/Primary.
  • Document the CSS equivalent in the style description field.

Gradient token tiers

A good token architecture has two tiers:

  • Reference tokens (palette-level) — raw values like --gradient-violet. Don't use these directly in components.
  • Semantic tokens (role-level) — contextual names like --gradient-hero. These reference the palette tokens and are what components actually use.

This two-tier system means you can change the brand palette by updating only the reference tokens, and all semantic tokens (and the components that use them) update automatically.