The element registry is a shared library of 18 UI component definitions. Every block that uses components like headings, buttons, or descriptions draws its styling controls and defaults from this shared library. This means a site owner can set their preferred heading style once in the wpTruss admin and have it apply consistently across every block on the site, without touching any block code.

This system has two sides: a JavaScript runtime (the cascade resolver and element definition files) and a PHP class (class-wpt-element-registry.php) that registers the JS files with WordPress, manages user defaults in the database, and handles the REST API for saving changes.

---

The 18 Elements

Element name	Script handle	Type
heading	wpt-element-heading	Variant
description	wpt-element-description	Flat
button	wpt-element-button	Variant
badge	wpt-element-badge	Flat
list	wpt-element-list	Flat
card	wpt-element-card	Flat
image	wpt-element-image	Flat
icon	wpt-element-icon	Flat
stat	wpt-element-stat	Flat
testimonial	wpt-element-testimonial	Flat
accordion	wpt-element-accordion	Flat
video	wpt-element-video	Flat
formField	wpt-element-form-field	Flat
pricingTier	wpt-element-pricing-tier	Flat
logo	wpt-element-logo	Flat
step	wpt-element-step	Flat
tag	wpt-element-tag	Flat
divider	wpt-element-divider	Flat

Variant elements have controls nested under named variants. The heading element has variants h1 through h6, each level has its own control set and defaults (for example, h1 defaults to 5xl font size; h3 defaults to 2xl). The button element has primary and secondary variants.

Flat elements have their controls at the root. The description element, for example, has controls directly: color, fontSize, fontWeight, textAlign, lineHeight, spacingBottom.

---

What an Element Definition File Contains

Each element lives in src/elements/{name}.js. The file registers itself on window.wptElementDefs using an IIFE (no build step, no ES module syntax). Here is the structure for a variant element:

// src/elements/heading.js (simplified)
window.wptElementDefs = window.wptElementDefs || {};
window.wptElementDefs.heading = {
    h2: {
        controls: {
            color: {
                type:    'select',
                label:   'Text Color',
                panel:   2,
                options: [
                    { label: 'Default', value: 'text'    },
                    { label: 'Primary', value: 'primary' },
                    { label: 'Dark',    value: 'dark'    },
                    { label: 'Light',   value: 'light'   },
                    { label: 'Muted',   value: 'muted'   },
                ],
                default: 'text',
            },
            fontSize: {
                type:    'select',
                label:   'Font Size',
                panel:   2,
                options: [
                    { label: '2XL — 24px', value: '2xl' },
                    { label: '3XL — 30px', value: '3xl' },
                    { label: '4XL — 36px', value: '4xl' },
                ],
                default: '3xl',
            },
            // ... more controls
        },
        inlineStyles: [
            { name: 'wpt-accent', title: 'Accent', className: 'wpt-text--accent' },
            // ... more text styles
        ],
    },
    // h1, h3, h4, h5, h6 each have their own controls object
};

---

Custom Token Integration, A Key Benefit

Element definition files are the place where design token values are referenced as option values. If you define a custom design token in wpTruss Brand Settings, you update the relevant element file to add it as an option. Every block that uses that element then inherits the new option automatically, without any block code changes.

For example, if you create a custom token --wpt-color-brand-alt and want it available as a heading colour option, you add one entry to heading.js:

color: {
    options: [
        { label: 'Default',   value: 'text'      },
        { label: 'Primary',   value: 'primary'   },
        { label: 'Brand Alt', value: 'brand-alt' },  // ← added once here
        // ...
    ],
    default: 'text',
},

Now every heading in every block across the entire site gains the “Brand Alt” colour option. That is the power of the element registry, a single file edit propagates to all blocks that declare wpt-element-heading as a dependency.

---

The Four-Layer Cascade

When a block renders a heading, the element registry resolves the correct styling values through a four-layer cascade. The top layer always wins.

Layer 1 — Block instance override   Set by the editor on this specific block only.
Layer 2 — User defaults             Set by the site owner in wpTruss element settings.
Layer 3 — System default            The element definition file's built-in default value.
Layer 4 — CSS fallback              Hardcoded fallback in your block's style.css.

Practical example: The site owner sets all headings to semibold weight as a user default (Layer 2). Every block’s heading uses semibold. But one specific block’s editor sets that block’s heading weight to bold as an instance override (Layer 1). That block uses bold, Layer 1 wins. The CSS fallback in Layer 4 only activates if all three JS layers fail to return a value.

---