Content Fields & Sections

The split is the point. Changing the design needs the AI. Changing the content never does.

<!-- template_html -->
<section class="hero">
  <h1>{{title}}</h1>
  <p>{{html_subhead}}</p>
  <img src="{{image_hero}}" alt="{{image_hero_alt}}" loading="lazy" />
  <a class="hero__cta" href="{{cta_url}}">{{cta_label}}</a>
</section>

{
  "title": "Care that starts with listening",
  "html_subhead": "Same-day appointments, <strong>no waiting room</strong>.",
  "image_hero": "https://example.com/wp-content/uploads/hero.jpg",
  "image_hero_alt": "Dentist talking with a patient",
  "cta_url": "/book/",
  "cta_label": "Book a visit"
}

These resolve at render time and need no content field:

{{site_name}} · {{site_url}} · {{site_tagline}} · {{current_year}} · {{wp_menu:location}} · {{business:name}} · {{business:phone}} · {{business:email}} · {{business:address}} · {{business:hours}} · {{business:social:*}}

Template placeholders — {{post_*}}, {{archive_*}}, {{term_*}}, {{search_query}}, {{paged_*}}, {{loop_wc_*}}, {{main_query}} — are covered in Template System.

Navigation that knows where it is

{{is_current:/features/}} in a link's class highlights it on that page (it prints is-active there and nothing anywhere else). {{is_current:/product/*}} keeps a parent item lit across a whole branch. Menus printed with {{wp_menu:location}} already carry WordPress's own current-item classes, so this is for hand-built navigation.

This is the single most important habit, and the plugin enforces it:

When the AI saves a section that is mostly hardcoded text with few or no editable fields, the plugin warns it during the write that Content Mode users won't be able to edit it.

If a section slipped through anyway, its editor shows a notice explaining that its content is hardcoded and pointing at the code editor. The fix is always the same: pull the copy out of template_html and into content_fields.

Already have a page full of hardcoded copy? extract_content_fields pulls it out into labelled fields in one step. It shows a preview first, saves a version so it can be undone, and skips anything already done. Text that contains bold or italic becomes a rich-text field.

Rule of thumb: if a human might ever want to change it, it belongs in a content field.

• Use design tokens — var(--ppd-colors-primary), var(--ppd-spacing-section-y) and so on. Set them once at Design Pages → Design Tokens.
• Never declare --ppd-* variables in page CSS. Tokens are owned by the token system and rendered fresh on every load; declarations in page CSS are stripped on save and on render so a stale hex can't shadow a live token.
• Give every section a uniquely-classed wrapper.
• Section CSS is scoped and minified. calc(), clamp(), min(), max() and var() survive minification intact.

Token groups

Besides colours, fonts, spacing and shape, the tokens cover:

• type: heading weight, case and tracking, body size, line height, and the eyebrow label style (size, weight, case, tracking).
• button: padding, weight, case and tracking.
• shape per component: radius-button, radius-card, radius-input, radius-image, plus border-width and shadow-sm.
• Colours on-primary (text on a primary background), surface and text-muted.

Every change to the design tokens is recorded. get_design_token_history lists earlier sets and restore_design_tokens puts one back.

Use section_js, not a <script> tag in the markup. It runs in an IIFE with section pre-bound:

var btn = section.querySelector('.hero__cta');

Declare libraries in js_dependencies — gsap, scrolltrigger, aos, alpinejs, swiper, splide, plyr, countup, typed, lottie — or pass a full CDN URL. They load only on pages that ask for them.

Prefer CSS. And never use IntersectionObserver on an above-the-fold section — elements already in the viewport on load may never fire the observer and stay stuck at opacity: 0. Use setTimeout for hero entrances.

• AI Best Practices
• Template System
• Third-Party Widgets