How to Inspect and Trace CSS Custom Properties and Variables in Safari Web Inspector

Modern responsive web design systems and UI component libraries rely extensively on CSS custom properties (commonly referred to as CSS variables) to manage colour palettes, typographic scales, spacing systems, and dynamic dark-mode themes. Because CSS variables participate fully in the cascade and inherit values down through the DOM hierarchy, values defined on :root or global selectors can be scoped, redefined, or overwritten at any container boundary. When an element displays an incorrect theme color or fallback value, tracing the exact declaration origin through multiple layers of specificity can be difficult. Apple Safari Web Inspector provides specialized tools to inspect CSS custom properties, trace variable values, and edit tokens in real time.

Understanding CSS Custom Property Inheritance and Scope

CSS custom properties are declared with a double-dash prefix (e.g., --brand-color: #0071e3;) and consumed via the var() function:

.button {
  background-color: var(--brand-color, #005bb5);
}

Unlike preprocessor variables (such as Sass or Less variables) which compile into static values at build time, CSS custom properties are dynamic runtime values maintained in the browser engine. They inherit from parent elements down through child nodes. An element can override a variable locally (e.g., within a .dark-card container), which re-evaluates all descendant elements referencing that variable without affecting sibling elements.

Opening Safari Web Inspector and Selecting Elements

To inspect CSS variables on macOS:

1. Ensure Developer features are enabled in Safari > Settings > Advanced > Show features for web developers.
2. Navigate to the target webpage in Safari.
3. Right-click the element consuming or defining custom properties and select Inspect Element (or press Option + Command + I).
4. The Web Inspector opens to the Elements tab with your chosen DOM node highlighted.

Tracing Variable Declarations in the Styles Sidebar

When you select an element that references a custom property via var(--variable-name):

1. Look at the Styles panel located in the right-hand inspection sidebar.
2. Locate the rule consuming the custom property (for example, color: var(--text-primary);).
3. Notice that Safari Web Inspector renders a small, interactive token badge around the variable name.
4. Hovering your mouse over the var(--text-primary) token displays a tooltip revealing the computed value (e.g., rgb(29, 29, 31)) and a preview swatch if it represents a colour.

Clicking directly on the variable token badge in Safari Web Inspector automatically scrolls the Styles panel to the exact rule where --text-primary was declared—whether on an ancestor class, an ID selector, or the global :root pseudo-class.

Inspecting Inherited and Scoped Custom Properties

If an element is located inside a nested container that overrides a variable, the Styles panel displays the complete cascade:

• Active Local Scope: The overriding rule (for example, .dark-card { --text-primary: #f5f5f7; }) appears active and uncrossed at the top of the matching rules list.
• Overridden Global Scope: The global definition on :root { --text-primary: #1d1d1f; } appears lower down in the cascade with strikethrough styling, confirming that the local container rule successfully eclipsed the global default.

If an undefined custom property is referenced, Safari renders the variable token with a dashed outline or warning icon, indicating that the browser has fallen back to the secondary fallback parameter declared inside var(--undefined-var, fallback).

Editing and Overriding Variables in Real Time

Safari Web Inspector allows live experimentation with design tokens directly in the DOM tree:

1. To test a global colour change across the entire website, select the <html> root element in the DOM tree.
2. In the Styles panel under the :root selector, locate the target variable (e.g., --accent-color).
3. Click the value string or double-click the colour swatch icon.
4. Select a new colour using the integrated colour picker or type a new hex/RGB value.

Every element across the page referencing var(--accent-color) updates immediately in real time, allowing you to audit accessibility contrast and visual consistency across desktop and responsive mobile layouts.

Inspecting Registered Custom Properties (@property)

Modern WebKit engines support the CSS @property rule, which allows developers to register typed custom properties with explicit syntax checking, inheritance control, and initial fallback values:

@property --progress-percentage {
  syntax: '<percentage>';
  inherits: false;
  initial-value: 0%;
}

Safari Web Inspector identifies registered typed custom properties in the Styles pane, displaying their declared syntax rules (such as <color>, <length>, or <percentage>). If an invalid value is assigned (e.g., assigning a string to a <length> variable), Safari flags the declaration as invalid, helping you debug typed animation transitions.

Evaluating Custom Properties in the Console

To programmatically inspect the computed value of any CSS variable on a selected element:

1. Select an element in the DOM tree (binding it to $0).
2. Open the Console drawer (press Escape).
3. Run:

   getComputedStyle($0).getPropertyValue("--brand-color").trim()

4. The console returns the exact evaluated color or dimension string resolved by the layout engine.