[wp-block-themes]: document theme.json slug-normaliser bug class (#59)

## Summary

Documents a silent failure in theme.json: WordPress hyphenates
preset/custom slugs before emitting CSS vars, so a handwritten `var()`
reference to the un-normalised slug resolves to nothing and quietly
falls back. No error, layout looks roughly right — invisible without
computed-style inspection.

Examples:

- slug `3xl` → `--wp--preset--font-size--3-xl`
- slug `cardShadow` → `--wp--custom--card-shadow`

Under the hood, `WP_Theme_JSON` runs every slug through
`_wp_to_kebab_case()`, which splits at digit/letter boundaries,
camelCase transitions, and non-alphanumeric characters.

## Changes

- **`skills/wp-block-themes/references/theme-json.md`** — new "Slug
normalisation gotcha" section with the explanation and a grep pattern
for catching un-normalised references.
- **`skills/wp-block-themes/references/debugging.md`** — new bullet
under "Styles not applying" pointing at the gotcha section.

Co-authored-by: mikeyarce <mikeyarce@git.wordpress.org>
Co-authored-by: karmatosed <karmatosed@git.wordpress.org>
Co-authored-by: bgrgicak <berislavgrgicak@git.wordpress.org>

Author: 4 people

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:
 

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.