Sass: @debug Directive

@debug Directive

The @debug rule is useful to see the value of a variable or expression while you're developing your stylesheet.

It's written @debug <expression>, and it prints the value of that expression, along with the filename and line number.

Example:

@mixin inset-divider-offset($offset, $padding) {
  $divider-offset: (2 * $padding) + $offset;
  @debug "divider offset: #{$divider-offset}";

  margin-left: $divider-offset;
  width: calc(100% - #{$divider-offset});
}

The exact format of the debug message varies from implementation to implementation. This is what it looks like in Dart Sass when run from the command line:

DEBUG: divider offset: 48px
    example.scss 3:3   inset-divider-offset()
    example.scss 11:3  root stylesheet

When to use @debug

Use @debug as a development aid to inspect state while writing or troubleshooting styles:

• Trace mixin/function arguments: see what values are actually being passed.
• Inspect computed values: verify calculations before they reach the CSS.
• Check list or map contents: confirm the shape of a data structure.
• Find which branch ran: place @debug in @if/@else branches to see which condition matched.

@mixin flex-grid($columns, $gap) {
  @debug "flex-grid called with columns: #{$columns}, gap: #{$gap}";
  display: flex;
  gap: $gap;
  > * {
    flex: 1;
    min-width: calc((100% - (#{$columns - 1} * #{$gap})) / #{$columns});
  }
}

@debug vs @warn vs @error

• @debug is silent in production and meant for local development only.
• @warn is visible in the build log but still emits CSS.
• @error stops the compiler and prevents any CSS from being generated.

Debugging data structures

@debug is especially helpful for inspecting lists and maps, because it prints their full structure:

$breakpoints: (
  mobile: 480px,
  tablet: 768px,
  desktop: 1024px
);

@debug "Breakpoints: #{$breakpoints}";

$font-stack: Helvetica, Arial, sans-serif;

@debug "Font stack: #{$font-stack}";

Dart Sass output:

DEBUG: Breakpoints: (mobile: 480px, tablet: 768px, desktop: 1024px)
    example.scss 5:9   root stylesheet

DEBUG: Font stack: Helvetica, Arial, sans-serif
    example.scss 9:9   root stylesheet

Practical debugging pattern

A common pattern is to add a temporary debug-only mixin that prints a label plus a value, then remove it when you're done:

/// Temporary helper for debugging mixin internals
@mixin debug($label, $value) {
  @debug "#{$label}: #{$value}";
}

@mixin responsive-padding($size) {
  @debug "responsive-padding", $size;
  padding: if($size == auto, 1em, $size);
}

Summary

• @debug <expression> prints the expression's value, filename, and line number to the build log.
• Use @debug as a development tool to inspect variables, computed values, lists, maps, and branch choices.
• You can pass any Sass value, like strings, numbers, colors, lists, maps, and it will be printed in a readable format.
• Unlike @warn or @error, @debug is purely for debugging and does not affect compilation or the final CSS.
• Clean up @debug statements before committing, or wrap them in a debug-only flag so they can be toggled off in production.