WordPress Integration

The design system generates a WordPress-compatible theme.json fragment at build/wordpress/theme-tokens.json. This file bridges the token JSON into the WordPress block editor and the Naluma WordPress theme’s styling pipeline.

Build Pipeline

tokens/primitive/color.json
tokens/primitive/typography.json
        |
  Style Dictionary (css transformGroup + custom format)
        |
  build/wordpress/theme-tokens.json

The custom naluma/wordpress-theme format transforms tokens into the WordPress theme.json v3 schema, populating settings.color.palette and settings.typography.fontFamilies / fontSizes.

Run from the design system repository root:

npm run tokens

Generated File Structure

The output follows the WordPress theme.json v3 spec:

{
  "$schema": "https://schemas.wp.org/wp/6.5/theme.json",
  "version": 3,
  "_generated": "Do not edit — generated by naluma-design-system Style Dictionary build",
  "settings": {
    "color": {
      "palette": [
        { "slug": "warm-white", "color": "#fbfaf1", "name": "Primary light background" },
        { "slug": "pale-wheat", "color": "#f9dfae", "name": "Secondary background, soft accent areas" },
        ...
      ]
    },
    "typography": {
      "fontFamilies": [
        { "slug": "heading", "fontFamily": "'Literata', Georgia, serif", "name": "Headings and display text" },
        { "slug": "body", "fontFamily": "'Plus Jakarta Sans', system-ui, sans-serif", "name": "Body text and UI elements" }
      ],
      "fontSizes": [
        { "slug": "11", "size": "11px", "name": "11px" },
        { "slug": "12", "size": "12px", "name": "12px" },
        ...
      ]
    }
  }
}

All 21 primitive colors, both font families, and 13 font sizes are included. Dark mode tokens are excluded by the Style Dictionary filter (dark mode in WordPress is handled separately via the theme’s SCSS layer).

Sync Workflow

The WordPress theme lives in a separate repository (naluma-theme). The recommended sync workflow:

Manual sync (current)

Run npm run tokens in the design system repo
Copy build/wordpress/theme-tokens.json to the WordPress repo at naluma-theme/theme.json (or merge into the theme’s existing theme.json)
The WordPress theme’s own build pipeline picks up the new values

Merging with existing theme.json

The generated file only contains settings.color and settings.typography. The WordPress theme’s theme.json likely has additional sections (styles, templateParts, customTemplates, settings.layout, etc.). When syncing:

Replace the settings.color.palette array entirely with the generated one
Replace settings.typography.fontFamilies and fontSizes entirely
Do not touch other sections

A merge script or a CI job that performs this selective replacement is the recommended next step.

WordPress Theme SCSS Pipeline

The WordPress theme has its own Style Dictionary + SCSS build that consumes the color palette from theme.json. The typical flow:

theme.json (color palette, font stacks)
      |
  WordPress Block Editor   +   SCSS build
      |                            |
  Block styles in editor      Compiled CSS
      |                            |
      └──────── Consistent styling ────────┘

Using token colors in SCSS

WordPress theme.json colors are available as CSS custom properties:

/* WordPress generates these automatically from theme.json palette */
--wp--preset--color--warm-white: #fbfaf1;
--wp--preset--color--pale-wheat: #f9dfae;
--wp--preset--color--burnt-sienna-deep: #a55838;
/* ... */

In the theme’s SCSS:

.naluma-hero {
  background-color: var(--wp--preset--color--warm-white);
  color: var(--wp--preset--color--warm-dark);
}

.naluma-cta {
  background-color: var(--wp--preset--color--burnt-sienna-deep);
  color: var(--wp--preset--color--white);
  border-radius: 8px; // primitive.radius.md
  padding: 16px 32px; // button.size.lg.web
  font-family: var(--wp--preset--font-family--body);
  font-weight: 600;
  transition: background 150ms ease; // primitive.transition.fast

  &:hover {
    background-color: var(--wp--preset--color--burnt-sienna-deep-hover);
  }
}

Using token typography

.naluma-heading {
  font-family: var(--wp--preset--font-family--heading);
  font-size: var(--wp--preset--font-size--36); // h1
  font-weight: 600;
  line-height: 1.2;
}

.naluma-body {
  font-family: var(--wp--preset--font-family--body);
  font-size: var(--wp--preset--font-size--16);
  line-height: 1.7;
}

Font Loading in WordPress

Both Literata and Plus Jakarta Sans are Google Fonts. In the WordPress theme, enqueue them via functions.php or load them as self-hosted woff2 files for performance:

Option A: Google Fonts CDN

function naluma_enqueue_fonts() {
    wp_enqueue_style(
        'naluma-google-fonts',
        'https://fonts.googleapis.com/css2?family=Literata:wght@300..800&family=Plus+Jakarta+Sans:wght@300..800&display=swap',
        array(),
        null
    );
}
add_action('wp_enqueue_scripts', 'naluma_enqueue_fonts');

Download the font files and place them in naluma-theme/assets/fonts/. Reference them in SCSS:

@font-face {
  font-family: 'Literata';
  src: url('../fonts/Literata-VariableFont.woff2') format('woff2');
  font-weight: 300 800;
  font-display: swap;
}

@font-face {
  font-family: 'Plus Jakarta Sans';
  src: url('../fonts/PlusJakartaSans-VariableFont.woff2') format('woff2');
  font-weight: 300 800;
  font-display: swap;
}

Self-hosting is the recommended approach for a German-market product to avoid GDPR issues with Google Fonts CDN.

What Is Not Synced

The generated theme-tokens.json currently includes:

All primitive colors (light mode)
Font families
Font sizes

It does not include:

Dark mode colors (handled by the theme’s own CSS/SCSS)
Semantic color mappings (the theme maps primitives to roles in its own SCSS)
Spacing, radius, shadow, and motion tokens (applied directly in SCSS using the values documented in this design system)
Component-level tokens (the theme implements components using semantic tokens)

Expanding the Style Dictionary WordPress format to include these additional token layers is a planned improvement.