CSS Custom Properties (Variables) Website Markup

Website markup using CSS Custom Properties (variables)

CSS Custom Properties are not just "CSS variables." They are cascadable, inheritable, changeable from JavaScript values that live in the DOM. Design systems, theming, dynamic adaptive styles without a single line of JS, and animations of values that cannot be animated directly are all built on them.

Design token architecture

A professional approach — three-level token system:

/* Level 1: Primitives (not used directly in components) */
:root {
  --color-blue-50: #eff6ff;
  --color-blue-500: #3b82f6;
  --color-blue-600: #2563eb;
  --color-blue-700: #1d4ed8;

  --color-gray-50: #f9fafb;
  --color-gray-100: #f3f4f6;
  --color-gray-900: #111827;

  --space-1: 0.25rem;   /* 4px */
  --space-2: 0.5rem;    /* 8px */
  --space-4: 1rem;      /* 16px */
  --space-8: 2rem;      /* 32px */

  --radius-sm: 4px;
  --radius-md: 8px;
  --radius-lg: 12px;
  --radius-full: 9999px;

  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;
  --font-size-2xl: 1.5rem;

  --shadow-sm: 0 1px 2px rgb(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
}

/* Level 2: Semantic tokens (theme) */
:root {
  --color-bg-primary: var(--color-gray-50);
  --color-bg-surface: #ffffff;
  --color-text-primary: var(--color-gray-900);
  --color-text-secondary: #6b7280;
  --color-text-muted: #9ca3af;
  --color-border: var(--color-gray-100);
  --color-accent: var(--color-blue-600);
  --color-accent-hover: var(--color-blue-700);
}

/* Dark theme — only redefine semantic level */
[data-theme="dark"] {
  --color-bg-primary: #0f172a;
  --color-bg-surface: #1e293b;
  --color-text-primary: #f8fafc;
  --color-text-secondary: #94a3b8;
  --color-text-muted: #64748b;
  --color-border: #1e293b;
  --color-accent: var(--color-blue-500);
  --color-accent-hover: #60a5fa;
}

/* Level 3: Component variables */
.button {
  --btn-bg: var(--color-accent);
  --btn-bg-hover: var(--color-accent-hover);
  --btn-text: #ffffff;
  --btn-radius: var(--radius-md);
  --btn-padding-x: var(--space-4);
  --btn-padding-y: var(--space-2);

  background-color: var(--btn-bg);
  color: var(--btn-text);
  border-radius: var(--btn-radius);
  padding: var(--btn-padding-y) var(--btn-padding-x);
  transition: background-color 150ms ease;
}

.button:hover {
  background-color: var(--btn-bg-hover);
}

/* Button variant — only redefine component variables */
.button--ghost {
  --btn-bg: transparent;
  --btn-bg-hover: var(--color-bg-primary);
  --btn-text: var(--color-text-primary);
}

Change from JavaScript

Custom Properties are accessible from JS — a bridge between logic and styles:

// Set variable on :root
document.documentElement.style.setProperty('--color-accent', '#8b5cf6');

// Read current value
const accent = getComputedStyle(document.documentElement)
  .getPropertyValue('--color-accent')
  .trim();

// Apply to specific element
const card = document.querySelector('.card');
card.style.setProperty('--card-elevation', '3');

// Dynamic parallax via scroll
window.addEventListener('scroll', () => {
  const progress = window.scrollY / document.body.scrollHeight;
  document.documentElement.style.setProperty('--scroll-progress', progress.toString());
});

/* Usage in CSS */
.progress-bar {
  transform: scaleX(var(--scroll-progress, 0));
  transform-origin: left;
}

Responsive values without media queries

Custom Properties with clamp() for fluid typography:

:root {
  /* Font smoothly scales from 320px to 1280px viewport */
  --font-size-h1: clamp(1.75rem, 4vw + 0.5rem, 3.5rem);
  --font-size-h2: clamp(1.375rem, 3vw + 0.25rem, 2.25rem);
  --font-size-h3: clamp(1.125rem, 2vw + 0.25rem, 1.5rem);
  --font-size-body: clamp(0.9375rem, 1vw + 0.75rem, 1.0625rem);

  /* Spacing */
  --section-padding: clamp(3rem, 8vw, 8rem);
  --container-padding: clamp(1rem, 5vw, 3rem);
}

Inheritance and scope

Custom Properties are inherited via DOM — a component can redefine them within its scope:

/* Global card */
.card {
  --card-bg: var(--color-bg-surface);
  --card-padding: var(--space-4);
  background: var(--card-bg);
  padding: var(--card-padding);
}

/* In sidebar cards are more compact */
.sidebar .card {
  --card-padding: var(--space-2);
}

/* In hero — with different background */
.hero-section .card {
  --card-bg: rgb(255 255 255 / 0.1);
}

CSS Houdini and @property

To animate numeric values of custom properties, the browser must be explicitly given the type:

/* Without @property animation doesn't work — browser doesn't know type */
@property --progress {
  syntax: '<number>';
  initial-value: 0;
  inherits: false;
}

@property --gradient-angle {
  syntax: '<angle>';
  initial-value: 0deg;
  inherits: false;
}

.animated-border {
  --gradient-angle: 0deg;
  background: conic-gradient(
    from var(--gradient-angle),
    #6366f1, #8b5cf6, #a855f7, #6366f1
  );
  animation: rotate-gradient 3s linear infinite;
}

@keyframes rotate-gradient {
  to { --gradient-angle: 360deg; }
}

Tool integration

PostCSS Custom Properties (for IE11)

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-custom-properties')({
      preserve: true, // Keep native variables for modern browsers
    }),
  ],
};

Export tokens from Figma

Figma Variables → Style Dictionary → CSS Custom Properties. Format for Style Dictionary:

{
  "color": {
    "accent": {
      "$value": "#2563eb",
      "$type": "color"
    }
  }
}

// style-dictionary.config.mjs
export default {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      files: [{
        destination: 'src/styles/tokens.css',
        format: 'css/variables',
        options: { selector: ':root' },
      }],
    },
  },
};

Timeline

Initial token system setup (primitives + semantics + light/dark theming): 4–6 hours. Migrating ready project with hardcoded values to custom properties: 1–2 days depending on CSS volume. Supporting token updates from Figma via Style Dictionary — configured once, then automatic.