Managing Variables: CSS Custom Properties vs. SCSS

Maintaining a consistent design system across a massive game UI requires variables for colors, typography, and spacing. However, standard web development practices for managing these variables can introduce hidden frame-rate penalties and run into specific engine constraints.

This guide explores the mechanical differences between runtime and build-time variables. We will examine the hidden costs of global CSS Custom Properties , explore advanced SCSS techniques for zero-cost design tokens, and establish the correct architectural pattern for safely scoping dynamic variables.

The Reality of Native CSS Variables

In modern web development, it is common practice to define global design tokens using CSS Custom Properties (variables) attached to the :root pseudo-class. This allows you to update a single variable via JavaScript and instantly change the theme of the entire application.

Here is what a standard web-first implementation looks like:

SolidJS
HTML

import Block from '@components/Layout/Block/Block';
import TextBlock from '@components/Basic/TextBlock/TextBlock';

const HudPanel = () => (
    <Block class="hud-panel">
        <TextBlock class="title">Health</TextBlock>
    </Block>
);

<body>
    <div class="hud-panel">
        <h1 class="title">Health</h1>
    </div>
</body>

/* The standard web approach: defining global variables */
:root {
    --primary-color: #ff0000;
}

.title {
    color: var(--primary-color);
}

Then, updating the variable with JavaScript is as simple as:

SolidJS
Vanilla JS

import { createSignal, createEffect } from 'solid-js';

const [themeColor, setThemeColor] = createSignal('#ff0000');

createEffect(() => {
    document.documentElement.style.setProperty('--primary-color', themeColor());
});

const root = document.documentElement;

function updateThemeColor(newColor) {
    root.style.setProperty('--primary-color', newColor);
}

Or by toggling CSS classes that switch between different variable values:

.light-theme {
    --primary-color: #e62e3a;
}

While this looks clean, it is highly dangerous in a game environment when updated frequently.

Native CSS variables are resolved at runtime. Because the variable is attached to the :root element, the CSS engine assumes that every single element on the page might rely on it. Whenever you update a :root variable, you force the engine to traverse the entire Document Object Model (DOM) and recalculate the styles for every single element, regardless of whether they actually use the variable or not.

Updating a :root variable can trigger a massive global style recalculation . To be highly precise, the variable isn’t inherently slow just because of where it is defined. The true performance bottleneck is determined by how many elements actually reference that variable.

If a root variable is only used by three specific buttons, updating it is relatively fast. However, if a global variable is applied to thousands of UI nodes, changing it forces the engine to recalculate the layout and paint for every single one of those nodes simultaneously.

Crucially, it does not matter how you trigger the update. Whether you use JavaScript (setProperty) or toggle a CSS class on the root element, changing a variable that thousands of nodes rely on will cause severe layout thrashing and destroy your frame rate. For high-frequency updates, always scope your variables as tightly as possible.

Beyond the performance penalty, there are three critical Gameface constraints you must remember when using native CSS variables.

Gameface does not support CSS variables inside of @keyframes definitions, it does not support variable fallback values, and it does not support CSS variables inside shorthand properties — including sub-shorthands.

If you attempt to write animation logic using variables like you would in a standard browser environment, the engine will fail to parse the rules.

/* ❌ AVOID: This will NOT work in Gameface */

/* 1. Fallback values are not supported */
.health-bar {
    background-color: var(--hp-color, #ff0000);
}

/* 2. Variables inside keyframes are not supported */
@keyframes damage-pulse {
    0% {
        background-color: var(--pulse-color);
    }
    100% {
        background-color: transparent;
    }
}

/* 3. Variables inside shorthand properties are not supported */
/*    This applies to true shorthands like border, background, font … */
.card-border {
    border: 2px solid var(--accent-color); /* ❌ shorthand — fails */
}

/*    … and also to sub-shorthands like border-color, border-width, */
/*    background-position, etc.                                       */
.card-border {
    border-color: var(--accent-color); /* ❌ sub-shorthand — also fails */
}

For shorthand properties, always expand to per-side or per-property longhands:

/* ✅ Use individual longhand properties instead */
.card-border {
    border-width: 2px;
    border-style: solid;
    border-color: transparent; /* hardcoded default */
}

/* ✅ Override with a scoped variable on the longhand that accepts it */
.card-border--accented {
    border-left-color: var(--accent-color);
    border-right-color: var(--accent-color);
    border-top-color: var(--accent-color);
    border-bottom-color: var(--accent-color);
}

To create robust animations and reliable default styles, you must rely on hardcoded values or build-time preprocessors.

The Zero-Cost Alternative: SCSS Preprocessing

For static design tokens that do not change during gameplay (such as your game’s core theme, base typography sizes, or margins & padding), you should completely avoid native CSS variables.

Instead, you should use a CSS preprocessor like SASS/SCSS. Because SCSS variables are resolved at build-time , the compiler generates standard CSS with hardcoded values. The layout engine does zero variable resolution math at runtime, costing you zero performance.

At its most basic level, you can define and use an SCSS variable directly within the same stylesheet.

/* Define the SCSS variables locally */
$brand-primary: #ff0000;
$spacing-large: 2rem;

.hud-panel {
    padding: $spacing-large;
}

.title {
    color: $brand-primary;
}

When your UI is built for production, the SCSS compiler strips away the variables entirely. The engine only ever receives and parses the final, hardcoded CSS:

/* The final output the layout engine actually reads */
.hud-panel {
    padding: 2rem;
}

.title {
    color: #ff0000;
}

Scaling to Global Variables

While defining a local variable is useful, a massive game UI requires a centralized design system. You need variables that act globally, similar to how the :root selector is used for CSS variables.

To achieve this global reach in SCSS, there are two primary architectural approaches.

Method 1: Manual Imports

The most standard approach is to extract all your design tokens into a dedicated file and manually import them into every component stylesheet that needs them.

/* Define your central SCSS variables in one master file */
$brand-primary: #ff0000;
$spacing-large: 2rem;

/* Import the variables specifically for this component */
@use "variables" as *;

.hud-panel {
    padding: $spacing-large;
}

.title {
    color: $brand-primary;
}

Method 2: Global Variable Injection (Bundlers)

A common complaint about manual imports is having to write the @use statement at the top of every single component file across a massive project. If you are using a modern frontend bundler like Vite, you can configure it to automatically inject your global variables into every SCSS file.

Here is how you set up Vite to handle your design tokens globally:

import { defineConfig } from 'vite';

export default defineConfig({
  css: {
    preprocessorOptions: {
      scss: {
        // Automatically injects your variables file into every SCSS component
        additionalData: `@use "@/styles/global-variables.scss" as *;`
      }
    }
  }
});

Safe Usage: Tightly Scoped CSS Variables

SCSS is perfect for static values, but game UIs still require dynamic theming. For example, imagine a multiplayer scoreboard where each player’s card needs to be dynamically accented with their specific “Team Color” assigned by the server.

For these dynamic features, you cannot use SCSS because the values are decided at runtime. While you could use standard inline JavaScript styles (element.style.color), that becomes incredibly inefficient if the color needs to affect the card’s background, its borders, and its pseudo-elements all at once (since JavaScript cannot target ::before or ::after directly).

Native CSS variables are the perfect tool here, but they must be architected safely. To avoid the global recalculation penalty discussed earlier, you must tightly scope your CSS variables to the specific UI component that needs them.

By applying the variable directly to the component’s container, you tell the layout engine to only recalculate the styles for that specific container and its internal children, rather than the entire document.

Here is how you safely scope a dynamic CSS variable for a Player Card:

<body>
    <div id="player-1-card" class="player-card">
        <div class="card-bg"></div>
        <div class="card-border"></div>
        <div class="player-name">Player One</div>
    </div>

    <div id="player-2-card" class="player-card">...</div>
</body>

/* 1. We set a safe default directly on the component, not the root */
.player-card {
    --player-accent: #cccccc;
    position: relative;
}

/* 2. Multiple children inherit the same dynamic variable */
.card-bg {
    background-color: var(--player-accent);
    opacity: 0.2;
}

.card-border {
    border-width: 2px;
    border-style: solid;
    border-color: var(--player-accent);
}

/* 3. The variable works on pseudo-elements, which JS cannot easily reach! */
.player-card::after {
    content: "";
    position: absolute;
    box-shadow: 0 0 15px var(--player-accent);
}

const playerCard = document.getElementById('player-1-card');

// When the engine assigns the team color, we update the specific node
function updatePlayerColor(hexColor) {
    // This instantly updates the bg, border, and pseudo-element glow!
    playerCard.style.setProperty('--player-accent', hexColor);
}