How to Inspect and Debug CSS @property Registrations in Safari Web Inspector

Standard CSS Custom Properties (CSS variables such as --primary-color) are treated by browser rendering engines as untyped textual tokens. Because the browser has no semantic understanding of whether a variable represents a colour, length, angle, or percentage, animating or transitioning CSS variables directly\u2014such as smoothly rotating a gradient angle or tweening numeric values in a custom counter\u2014is impossible with traditional variables. To give CSS variables explicit types, default fallback values, and inheritance controls, the CSS Properties and Values API (part of CSS Houdini) provides the at-rule @property. In Safari on macOS, inspecting registered custom properties and validating syntax types is supported directly inside Safari Web Inspector.

Understanding the CSS @property Rule Structure

The @property at-rule registers a custom property with the browser\u2019s style engine:

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

The rule requires three mandatory descriptors:

  • syntax: Defines the data type expected by the property. Supported types include "<color>", "<length>", "<percentage>", "<angle>", "<number>", and "<integer>". If an author assigns an invalid value, the browser automatically reverts to the initial value.
  • inherits: A boolean (true or false) controlling whether child DOM elements inherit this custom property from ancestral nodes.
  • initial-value: The fallback value used when the property is not explicitly declared. Required for any syntax except the universal type ("*").

Opening Safari Web Inspector and Selecting Styled Elements

To inspect elements utilizing registered custom properties in Safari:

  1. Open Safari on macOS.
  2. Ensure developer tools are enabled in Safari > Settings > Advanced > Show features for web developers.
  3. Right-click the animated component (such as an animated conic-gradient card or circular progress ring) and choose Inspect Element (or press Option + Command + I).
  4. In the Elements DOM tree, select the target element.
  5. In the right-hand sidebar, switch to the Styles panel.

Inspecting Registered Properties in the Styles Sidebar

When you select an element whose style sheet defines an @property rule, Web Inspector presents the definition directly within the cascade view:

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

.animated-card {
  --gradient-angle: 45deg;
  background: conic-gradient(from var(--gradient-angle), #ff4500, #ff8c00, #ff4500);
  transition: --gradient-angle 0.5s ease-in-out;
}

Web Inspector validates the declaration:

  • Syntax Badge: Displays the recognized data type (<angle>).
  • Type Mismatch Warnings: If you accidentally declare an invalid unit (such as --gradient-angle: 45px;), Web Inspector flags the property with an invalid syntax icon and strikes it out, showing that the browser safely applied initial-value: 0deg instead of breaking rendering.

Debugging Animated CSS Variables and Transitions

Because registered custom properties possess concrete data types, they can be animated smoothly via CSS keyframes or transitions:

@keyframes rotateGradient {
  0% {
    --gradient-angle: 0deg;
  }
  100% {
    --gradient-angle: 360deg;
  }
}

.spinner {
  animation: rotateGradient 3s linear infinite;
}

To debug the animation inside Safari Web Inspector:

  1. In the Styles panel, switch to the Computed tab.
  2. Filter for --gradient-angle.
  3. Watch the live computed value update continuously from 0deg through 360deg in real time.
  4. If the variable jumps abruptly between 0deg and 360deg without smooth intermediate interpolation, check whether the @property rule was omitted or if syntax: "<angle>" contains a typographical error.

Testing Inheritance Isolation

One of the primary benefits of @property over standard CSS variables is preventing unwanted variable pollution down the DOM tree:

@property --theme-padding {
  syntax: "<length>";
  inherits: false;
  initial-value: 16px;
}

When inherits: false is set, child elements within .container will not inherit --theme-padding unless explicitly specified. You can verify this inside Web Inspector by inspecting child elements in the DOM tree and checking whether --theme-padding appears under Inherited from .container (it will be absent).

Get the best tech tips delivered straight to your inbox.

Join thousands of readers mastering Apple, Google, Microsoft, and Linux.