Limitations and technical details

Source of truth

The documentation describes the contract, but code remains the ultimate source of truth. When they differ:

1. establish actual behavior;
2. do not change a workaround blindly;
3. correct the code and documentation together in an agreed task.

Identical preset values

WordPress editor may match list items by value, not only by slug. If two presets use the same value string, selecting one may display as selecting the other.

Therefore, the Core contract contains unique aliases:

--_spacing--edge-x: var(--size-fluid300-60px);
--_spacing--base-gap: var(--size-fluid200-16px);

Do not replace an alias with a direct primitive reference merely for “simplification.”

Preset spacing--0

primitives.css declares manually:

--wp--preset--spacing--0: 0;

This is a compatibility workaround for a WordPress behavior change that made None reference this variable. Before removing it, check the target WordPress version and editor behavior.

slug stability

Preset slugs are saved in block attributes and markup. Simply renaming them in code does not update existing saved content.

Before renaming or removing:

• find usage in templates, patterns, and database content;
• design a migration;
• check for visual regression;
• preserve backward compatibility if migration cannot happen immediately.

theme.json collection inheritance

Do not assume adding a child palette entry will always retain the complete parent array as needed. Child themes in the current project list the base roles again when extending the palette.

Always check the final:

• palette;
• gradients;
• duotone;
• shadows;
• font families;
• controls Gutenberg.

Font families

Fonts cannot be defined only through a plain primitive CSS variable with the expectation of full WordPress registration.

Font family and fontFace are declared in child theme.json. WordPress then generates:

• @font-face;
• --wp--preset--font-family--{slug}.

Not all theme.json fields work the same with var()

CSS-variable support depends on the specific field and WordPress version. Do not move a working pattern from palette or spacing into another section without checking the schema and generated output.

Some fields require literal values or WordPress preset syntax.

Duotone

Duotone has separate color-format requirements and must not be automatically based on the assumption that any CSS variable will be handled correctly.

Core theme disables default duotone. The child theme adds it only after verification.

Breakpoint variables

--mobile-bp, --tablet-bp, and --desktop-bp document values, but CSS custom properties cannot be used in ordinary @media (min-width: var(...)).

Current code contains a TODO to replace hardcoded values where possible, particularly in JavaScript. Do not consider this transition complete.

Runtime layout variables

--header-height and --wpadminbar-height are calculated by JavaScript and may change after loading.

They:

• are not design tokens;
• must not be copied into the palette or presets;
• require layout verification before and after JavaScript executes;
• depend on theme infrastructure and the MU plugin.

Core CSS embedded in child bundles

Child theme does not receive automatic updates to already-built CSS after core-fse/assets/css changes.

After a core CSS change:

1. find child themes importing the changed file;
2. run their builds;
3. include generated output in the change;
4. check the frontend and editor.

Generated files

.min.css and source maps are not edited manually. A manual fix will be lost in the next build and create a mismatch with source.

_doc-wp-presets.scss

The file exists for IDE autocomplete and generated-variable documentation. It:

• does not create presets;
• is not a runtime source;
• does not replace theme.json;
• must be updated when the public preset API changes.

The list in this file is an IDE aid and may be less complete than the current theme.json. When they differ, trust theme.json and generated WordPress CSS.

Default WordPress presets

auto-include/fse-settings.php also clears the default palette, gradients, duotone, spacing sizes, and font sizes through wp_theme_json_data_default.

Therefore, looking only at theme.json is insufficient: the actual editor API also depends on parent-theme PHP filters.

Global Styles admin module

The Appearance → Global Styles page saves custom CSS in a site/network option and adds it to the frontend and editor.

This is not part of the design system:

• do not define system tokens there;
• do not use it as a replacement for version-controlled CSS;
• consider it a possible late override when debugging;
• an agent must not change this layer without an explicit request.

Core and custom blocks

Detailed custom-block implementation is outside this documentation’s scope. However, every block must:

• use existing presets and semantic variables;
• not create its own parallel global scale;
• render consistently on the frontend and in the editor when previews are supported.

Technical debt is not a rule

Document TODO comments, compatibility declarations, and helper aliases as limitations rather than turning them into universal architectural patterns.