Theme.json configuration with modern Sass (SCSS) features (@use, @forward)

Overview

• theme.json: defines color palette, typography, spacing scale, layout, and custom tokens exposed as CSS variables.
• Sass modules: design system split into settings (tokens) and tools (functions/mixins) using @use/@forward.
• Goal: Create styles with stable design tokens while staying aligned with WordPress Global Styles.

theme.json highlights

• Colors
  • Custom palette (e.g., foreground, background, primary, secondary, etc.).
  • Available in CSS as -wp--preset--color--{$slug} and in SCSS with get-color($slug) function
  • Example use:

@use '~design' as *;

color: get-color('primary');
background: get-color('background');

@use '~design' as *;

color: get-color('primary');
background: get-color('background');

• Typography
  • Fluid font sizes and a curated fontSizes scale (small → huge), exposed as -wp--preset--font-size--{slug} and can be used with SCSS get-font-family($slug) function
  • Custom fontFamilies with local files via file:./assets/fonts/*.woff2:
    • Body: Quicksand (-wp--preset--font-family--body)
  • Example use:

@use '~design' as *;

font-family: get-font-family('body');
font-size: get-font-size('normal');

@use '~design' as *;

font-family: get-font-family('body');
font-size: get-font-size('normal');

• Spacing
  • Custom scale generated via spacingScale and enumerated in spacingSizes.
  • Exposed as -wp--preset--spacing--{slug} and can be used with SCSS get-padding($slug) or get-margin($slug) functions.
• Layout
  • contentSize and wideSiz**e** used by block editor and templates.
• Global styles
  • Base colors, typography, element defaults (links, headings), and block-level spacing rules.
• Blocks
  • Per‑block spacing and gap customizations for core blocks.

How theme.json and Sass connect

• CSS variables from theme.json are globally available (e.g., -wp--custom--gap--medium).
• Sass tools provide ergonomic functions to reference those variables without hardcoding strings.
  • Example:

// src/design/tools/_theme.scss
@function get-padding($key) {
  @return var(--wp--custom--padding--#{$key});
}

// src/design/tools/_theme.scss
@function get-padding($key) {
  @return var(--wp--custom--padding--#{$key});
}

This makes token usage consistent and refactor‑friendly.

• Best practice: Create components using functions/tokens instead of literals:

@use '~design' as *;

.card {
  padding: get-padding('medium');
  color: get-color('foreground');

  @include bp('medium') {
    // bp() is defined in design/tools/_breakpoints.scss
    padding: get-padding('large');
  }
}

@use '~design' as *;

.card {
  padding: get-padding('medium');
  color: get-color('foreground');

  @include bp('medium') {
    // bp() is defined in design/tools/_breakpoints.scss
    padding: get-padding('large');
  }
}

Using @use and @forward

• Importing tools globally in a file:

@use '~design' as *; // forwards all tools

@use '~design' as *; // forwards all tools

• Importing settings explicitly:

@use '../design/settings' as settings;

.grid {
  gap: map.get(settings.$gaps, 'normal');
}

@use '../design/settings' as settings;

.grid {
  gap: map.get(settings.$gaps, 'normal');
}

• Why this matters:
  • @use namespacing avoids variable collisions.
  • @forward centralizes what a consumer needs (you import design once, not every tool file).
  • Clear separation between tokens (settings) and behaviors (tools).

Using @use and @forward (Sass modules) — short guide

• @use: imports a Sass module once and namespaces its members (variables, mixins, functions).

Basic:

@use '../design/tools';      // access as tools.$var, tools.fn(), tools.mixin()
@use '../design/tools' as *; // flatten into current scope (be careful with naming)
@use '../design/tools' as t; // custom namespace

@use '../design/tools';      // access as tools.$var, tools.fn(), tools.mixin()
@use '../design/tools' as *; // flatten into current scope (be careful with naming)
@use '../design/tools' as t; // custom namespace

With configuration (override module variables at load time):

@use '../design/settings' with (
  $root-font-size: 18px
);

@use '../design/settings' with (
  $root-font-size: 18px
);

• @forward: re-exports members from another module to build a public API.

In the theme, src/design/_index.scss.This means consumers can just:

@forward 'tools';

@forward 'tools';

@use '../design' as *; // gets everything forwarded by tools/_index.scss

@use '../design' as *; // gets everything forwarded by tools/_index.scss

You can curate exports in a tools/_index.scss:

// src/design/tools/_index.scss
@forward 'breakpoints';
@forward 'px-to-rem';
@forward 'theme';
// etc.

// src/design/tools/_index.scss
@forward 'breakpoints';
@forward 'px-to-rem';
@forward 'theme';
// etc.

• Why modules (vs @import):
  • Single evaluation, no duplication.
  • Namespacing avoids collisions.
  • Clear, composable public API via @forward.