From 7fe9685fd84270dd239dd8b906bf7326189d0fd3 Mon Sep 17 00:00:00 2001
From: Mikey Arce <mikey.arce@principalwp.com>
Date: Mon, 1 Jun 2026 12:31:22 -0400
Subject: [PATCH] wp-block-themes: document theme.json slug-normaliser bug
 class
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

WordPress passes every preset/custom slug through _wp_to_kebab_case() before
emitting its CSS var, hyphenating at digit/letter boundaries and camelCase
transitions. Handwritten references to the un-normalised form silently fall
back, making the failure invisible without computed-style inspection.

Adds a "Slug normalisation gotcha" section to theme-json.md (with a grep
pattern for catching un-normalised references) and a cross-referenced bullet
under debugging.md § "Styles not applying".

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 skills/wp-block-themes/references/debugging.md  |  1 +
 skills/wp-block-themes/references/theme-json.md | 14 ++++++++++++++
 2 files changed, 15 insertions(+)

diff --git a/skills/wp-block-themes/references/debugging.md b/skills/wp-block-themes/references/debugging.md
index 5475e20..9414a16 100644
--- a/skills/wp-block-themes/references/debugging.md
+++ b/skills/wp-block-themes/references/debugging.md
@@ -7,6 +7,7 @@ Fast checks:
 1. Confirm you edited the active theme (Site Editor → theme).
 2. Check if user customizations exist (they override theme defaults).
 3. Validate `theme.json` structure (typos can prevent styles from applying).
+4. If a `var(--wp--preset--*)` / `var(--wp--custom--*)` reference is silently using its fallback, the slug is likely un-normalised — WordPress hyphenates digit/letter boundaries and camelCase transitions before emitting the CSS var. See `theme-json.md` § "Slug normalisation gotcha".
 
 Remember the hierarchy:
 
diff --git a/skills/wp-block-themes/references/theme-json.md b/skills/wp-block-themes/references/theme-json.md
index fa25bc4..45049e0 100644
--- a/skills/wp-block-themes/references/theme-json.md
+++ b/skills/wp-block-themes/references/theme-json.md
@@ -57,3 +57,17 @@ References:
 
 - Border radius presets: https://make.wordpress.org/core/2025/11/12/theme-json-border-radius-presets-support-in-wordpress-6-9/
 - Form element styling: https://developer.wordpress.org/news/2025/11/how-wordpress-6-9-gives-forms-a-theme-json-makeover/
+
+## Slug normalisation gotcha
+
+> **Slug normaliser trap (silent failure).** WordPress inserts hyphens inside preset/custom slugs before emitting CSS vars: slug `3xl` becomes `--wp--preset--font-size--3-xl`; slug `cardShadow` becomes `--wp--custom--card-shadow`. A handwritten reference to the *un-normalised* form (e.g. `var(--wp--preset--font-size--3xl)`) resolves to nothing and silently falls back to the second `var()` argument.
+
+Before assembling the variable name, `WP_Theme_JSON` passes each preset/custom slug through `_wp_to_kebab_case()`, which splits it into word tokens — at digit/letter boundaries, camelCase transitions, and non-alphanumeric characters — lowercases them, and joins with `-`. Reference the emitted form, not the slug you typed.
+
+Grep pattern to catch un-normalised references in CSS/SCSS/PHP/JS:
+
+```
+var\(\s*--wp--(?:preset|custom)--[a-z-]+--\d+[a-z]
+```
+
+This matches a digit immediately followed by a letter inside the variable name (`3xl`, `2xs`, `4x-large`) — every emitted form keeps the hyphen (`3-xl`, `2-xs`, `4-x-large`) and is correctly not flagged.