Context​

The converter already ships a complete entrance-animation surface: every content shortcode registers the Entrance Animation option (Animate.css effect + a shared animation_settings panel with trigger / delay / stagger / easing), and the mapper already knows every node's role (heading, text, button, image, card grid, pricing table). The render reader honours the modern animation.effect + animation_settings shape and hides each element until it scrolls into view.

So the raw capability to sequence reveals is entirely mechanical — the converter can walk the built node tree and assign effects itself. The only thing that genuinely benefits from taste is the choice of effect per element (should the hero CTA slide up last for emphasis? should a testimonial row cascade left-to-right?). The local AI (Ollama / Claude Code / an API key, via the capture service) is good at exactly that semantic judgement — but it is slower, varies run to run, and is only present when the user has a backend configured and the capture service running.

Options considered​

• A — AI drives the animations. The AI decides which elements animate and how, and the converter just applies its output. Rejected: it makes a core feature depend on a slow, optional, non-deterministic component. With the AI off (the common case for an offline .zip upload), the feature would do nothing; with it on, two runs of the same page could differ, and a bad/empty AI response could leave elements stuck hidden (sc-anim-pending with no effect written).
• B — Deterministic only. A role → effect rule table with a per-section stagger. Fast, free, offline, 100% repeatable, and good for ~90% of pages. But it can't tell that this particular element deserves a different treatment.
• C — Deterministic base + AI as an optional refinement layer. The deterministic pass always runs and sets a tasteful base (fade-up for content, soft fade for media, stagger reset per band). When "Refine with AI" is additionally ticked and a backend is reachable, the AI only re-picks the effect/timing per element on top of that base, constrained to the Animate.css entrance vocabulary, with any failure or absence silently falling back to the deterministic result.

Decision​

C. The deterministic converter owns the sequencing; the local AI is an opt-in refinement that only adjusts the per-element effect and delay. The "Add entrance animations" checkbox runs the deterministic pass alone; a secondary "Refine with AI" sub-option layers the AI on top when it's available.

Why​

• Robustness first. A conversion feature must never depend on an optional, variable component to function. Making the deterministic pass the base means the feature works for every path — the offline .zip upload included — and the AI can never break a conversion, only improve it.
• The AI is applied where it actually adds value. Sequencing and staggering are mechanical; effect taste is not. Letting the AI touch only the effect/timing (not whether an element animates, not the hide-until-play plumbing) keeps its blast radius tiny and its output easy to validate against a fixed vocabulary.
• Consistency with the converter's whole philosophy. This mirrors the standing rule that the deterministic path is the source of truth and the AI is a helper on top (the same shape as the always-on local micro-pass that only names sections while Claude/deterministic own the structural mapping). Determinism stays the default; intelligence is additive.
• Graceful degradation is explicit. "Refine with AI" is only offered when a backend + the capture service are present, and any error returns the deterministic base — so there is no state in which turning it on makes the result worse than leaving it off.

Context​

Two bugs surfaced it. First, a converted section-3 card showed the box dropped into the icon_box's Custom CSS with a bare box utility class — no Box Preset selected — so it wasn't reusable, wasn't editable as a preset, and didn't travel like one. Second, and more structural: once a card that contains a nested list is decomposed (icon + heading + description → icon_box, and the list → a native feature_list), a box put on the icon_box alone would only wrap the header and leave the list outside the card.

So there are really two questions: who owns the box, and is it a preset or a class. The owner question needs a rule that's deterministic (same source → same output) and doesn't re-sniff content the converter has already classified.

Options considered​

1. Decide by content type. Inspect the card: icon + title + a single paragraph → icon_box owns it; contains a list or a button → column owns it.

   • For: Matches intuition directly.
   • Against: Re-inspects and re-classifies content the converter already turned into shortcodes; a second heuristic to keep in sync with the recognizers, and fragile at the edges ("is this a list?").

2. Decide by decomposition count. The converter already knows how many shortcodes a card cell becomes. If it collapses to one icon_box, the icon_box owns the box (box_style). If it becomes two or more shortcodes (icon_box + feature_list / button / …), the column owns it (border_preset on the inner wrapper), so the box wraps all of them. N boxed icon_boxes in one column → each owns its own box.

   • For: Uses a signal the pipeline already computes — zero extra heuristic, and it's exactly the content-type rule expressed structurally (a list/button is why the card became 2+ shortcodes).
   • Against: None material; it is the same decision, sourced from data instead of a re-scan.

3. Always the column. Put every card's box on the column.

   • Against: A self-contained single icon_box is more portable when the box is its own (box_style travels with the element on export); forcing it onto the column loses that and over-nests.

Orthogonally, for the skin itself: a Box Preset (registered once, emitted in Theme Settings, referenced by box_style / border_preset) versus a one-off scoped box class + Custom CSS. The preset is reusable, editable in one place, and portable; the class is a per-element dead-end.

Decision​

Own the box by decomposition count, always as a Box Preset. One icon_box → the icon_box owns it via box_style = boxp-<slug>. Two or more shortcodes → the column owns it via border_preset = boxp-<slug> on the inner wrapper, wrapping every child. Multiple boxed icon_boxes in a column → each owns its own preset. In every path the skin is registered (register_box_preset, keyed by a hash of the normalized skin so identical cards share one preset) and emitted as a real Box Preset — never a bare box class + Custom CSS.

This also corrected a latent bug in the other card paths (counter grids, stacked cards, nested grids): they were matching against pre-existing theme presets only (box_preset_slug → the box lookup), so a freshly captured skin fell through to one-off CSS. They now register_box_preset like the primary path, so every captured card box becomes a real, deduped preset.

Why​

The decomposition count is the content-type signal, already computed — a card becomes 2+ shortcodes precisely because it holds a list or a button beyond what one icon_box can represent. Keying the owner off that count means one source of truth and no second heuristic drifting out of sync with the recognizers. The box must enclose everything it enclosed in the source, so a multi-shortcode card has to be boxed at the column; a lone icon_box is most portable owning its own box. And registering a real Box Preset — rather than stamping a one-off class — is what makes the converted box behave like a designed box: reusable across the cards that share it, editable in Theme Settings, and portable on template export. The bug where fresh skins silently degraded to Custom CSS was the same mistake in four other places (match-only lookup instead of register), now fixed uniformly.

Context​

The element-mapping data is a mirror of what the converter code derives — it's generated by classifying each option against the n_* block builders. So “unmapped” means “left at the shortcode default.” Crucially, that is often the correct, faithful result: if a source has no signal for an option (e.g. an accordion that never specifies an icon animation), the default is the accurate reproduction. A conversion's job is faithful reproduction, not maximizing a coverage percentage.

But the single “unmapped” bucket hid an important distinction. Of accordion's 18: about half are options a real source does express and the converter simply doesn't read yet (is_open from aria-expanded, single/multiple-open from data-bs-parent, header background/alignment from computed styles, faq_schema from a FAQPage JSON-LD block, …). The other half have no reliable signal or are UnysonPlus-specific (animation = an Animation Engine effect, css_class, our preset styles, numbering). Lumping both as “unmapped” made the table read as failure and gave no work-list.

Options considered​

• A — Drive unmapped to zero. Wrong target: it would force fabricated or unreliable mappings for options no source expresses, hurting fidelity to chase a vanity metric.
• B — Hand-author “pre-mapping” data. Rejected: the mapping doc mirrors the converter; authoring mappings the code doesn't perform makes the doc lie. The lever is the converter, not the doc.
• C — Split “unmapped” into GAP vs DEFAULT, improve the converter for gaps only. A gap is a derivable option with a real source signal the converter doesn't read yet (a genuine to-do); a default is intentional — no reliable signal, or a UnysonPlus-specific choice — and is correct left unmapped.

Decision​

Option C. We added a fourth design status — ⚠️ Gap — alongside ✅ native / 🟡 via-CSS / ⚪ default, and the element-mapping generator now shows, per shortcode, “N native, M gaps (derivable, not yet), K default.” Each gap row names the source signal the converter could read, so the table becomes a prioritized work-list instead of a wall of ⚪. We then improve the converter to close gaps — never by fabricating mapping data.

On real sites: they're for validation and prioritization, not a prerequisite. Common element patterns (Bootstrap collapse, <details>, FAQ/Elementor/Divi exports, schema.org) are well-known and detectable, so gaps can be closed from the patterns; a small curated set of real captures then confirms the signals and catches edge cases. We do not need a large corpus hand-mapped by the user.

Why​

• Faithful reproduction is the real goal. An option with no source signal is correctly at its default; a metric that punishes that is measuring the wrong thing.
• Honesty + actionability. Separating gaps from defaults turns an alarming “18 unmapped” into “~11 real gaps + 7 intentional defaults”, and every gap carries the signal to derive — a concrete to-do.
• The doc must not diverge from the code. Summaries and mappings live in / reflect the source; hand-authored mappings the converter doesn't perform would reintroduce drift.
• Effort goes where it pays. Prioritize gaps on commonly-converted elements; leave genuine defaults alone.

Status: Accepted — the ⚠️ Gap status ships with the element-mapping generator; accordion is the pilot reclassification, with the remaining shortcodes and the converter improvements to follow.

Context​

Documenting functions inline and publishing a browsable reference is a standard, named practice: docblocks (PHPDoc / PSR-5/19) parsed by doc generators (phpDocumentor, Doxygen; JSDoc, Javadoc, rustdoc elsewhere). WordPress itself ships the Code Reference auto-generated from PHPDoc via phpdoc-parser. In the Diátaxis documentation model (Tutorials / How-to / Reference / Explanation), a function catalogue is squarely Reference — a different axis from our existing how-to Manual, The Theme, and AI Dev Kit sections.

The temptation is to generate a page per symbol for all ~845 functions. That's the classic trap: exhaustive auto-references become dumping grounds nobody reads, they go stale the moment a signature changes, and 90% of the entries are internal helpers meaningless without their surrounding code.

Options considered​

• A — Hand-write a reference. Highest quality per page, but unmaintainable at this scale and guaranteed to drift from the code. Rejected outright.
• B — Auto-generate a page per function for everything (WP-style). Comprehensive, but noisy and low-signal; buries the ~5% that authors actually consume (public helpers + hooks) under internal plumbing. This is the "dumping ground" outcome.
• C — Generate a reference for the public contract only, organized by subsystem. The public helper functions (the fw_ / unysonplus_ / upw_ / sc_ / fw_ext_ families) and — with equal billing — every framework-owned hook, since hooks are the real extensibility surface a framework lives or dies by. Internal closures and WordPress-core hooks are excluded on purpose.

Decision​

Option C. The docs site gets a dedicated, generated API Reference section (/reference), split into Functions and Hooks, each grouped by subsystem. It's produced by a two-step pipeline — scripts/extract-php-api.php (a token_get_all scan that pulls signatures, docblocks, function_exists()-guarded/pluggable flags, and do_action/apply_filters sites) → scripts/gen-php-api.mjs (emits the grouped Markdown). The .md is generated, never hand-authored: you edit the framework docblocks and re-run the two commands.

Implementation stance: the code documents the implementation (via docblocks); the site documents the contract people depend on (public API + hooks).

Why​

• Signal over noise. Authors search for "which function formats an upload path" or "which filter lets me change X" — the public helpers and hooks. Those are exactly what's published; the internal 90% stays where it belongs (in the source, next to the code it explains).
• It can't drift. Because it's extracted from the shipped source every build, the reference always matches the code — the failure mode that kills hand-written and even per-symbol-generated references.
• Hooks are first-class. For a framework, the hook catalogue is the single highest-value reference — it's the supported way to extend without forking. Giving it a peer section to Functions reflects that.
• It slots into the existing IA. As a Diátaxis Reference section it sits cleanly beside the how-to Manual / The Theme / AI Dev Kit rather than competing with them.

Status: Accepted — the generated section ships with the functions + hooks pipeline; future framework changes flow through by re-running the extractor + generator.

Context​

The trigger was a conversion of a mortgage site whose review cards each had a bordered footer: "Total savings" in muted small caps, then the figure in bold brand green. The testimonials shortcode captures rating, quote, avatar, name, role and location — but nothing for that footer, so the deterministic Site Converter was folding the stat into the author's role line (VP Sales, Method Homes · Total savings $14,200). That's lossy and wrong: the stat is a distinct, emphasized element, not part of the role.

So the card needs a real field. The open question was its shape, which drives three things at once: how authors enter it, how it renders, and how faithfully the converter can populate it from a source card.

Options considered​

1. Repeatable {label, value} rows. A small addable list per testimonial; each row is an optional muted label with an emphasized value. Renders as a footer block (label over value). Placed via a new "Extra Texts" slot in Card Rows.

   • For: Matches the observed pattern exactly (label + figure). Handles the common single-stat case and cards with two stats. The muted-label / bold-value styling is intrinsic, so every card reads consistently. Converter mapping is a clean split: leaf label → label, figure → value.
   • Against: Slightly more structure than a single pair; two fields per row.

2. A single {label, value} pair. Exactly one stat per testimonial.

   • For: Simplest field.
   • Against: Can't represent a card with two stats, and the moment one design needs a second line we'd be back here widening it. A repeatable is barely more code and never boxes us in.

3. Freeform rich text. One HTML/text field for the whole footer.

   • For: Maximum authoring flexibility.
   • Against: Loses the consistent muted-label / bold-value typography (each author re-styles by hand), and it's the hardest for the converter to map — it would have to guess where the label ends and the value begins, or dump the raw run and lose the structure. Freeform trades the one thing that makes the stat read as a stat (its two-part styling) for flexibility we don't need.

Decision​

A repeatable list of {label, value} rows, surfaced as an "Extra Texts" slot in Card Rows (defaults to a divider + the rows at the card footer, so it can be positioned like any other slot). Each row renders a muted label above an emphasized value; a value-only row (blank label) is allowed. The slot renders only when a row has content, so plain testimonials are unaffected. The Site Converter maps a source card's bordered footer stat into this field — preferring two distinct leaf texts (label + value), else splitting a single "Label $Figure" run on the figure — and pins Card Rows to surface it, instead of cramming the stat into the role line.

Why​

The shape should follow the data, and the data is a label paired with a figure — sometimes one, sometimes two. A repeatable {label, value} is the tightest fit: it captures exactly that structure, so the styling (muted label / bold value) can be intrinsic and every card looks the same, and the converter maps it deterministically instead of guessing. The single-pair option is a false economy — it saves nothing and caps the feature the first time a design shows two stats. Freeform maximizes authoring freedom but throws away the consistent typography and the clean converter mapping, which is the whole point of making it a first-class field rather than leaving it as prose. Modeling it as a Card Rows slot keeps it consistent with how every other card-like shortcode composes, so it's positionable without a bespoke layout.

Context​

The Site Converter derives Theme Settings from the source. For buttons it emits colour presets and size presets; each converted button then references a size class (btn btn-primary btn-lg). The size preset carries font-size, line-height, padding-x/y, radius and (new) min-height.

The first implementation:

1. Deduped button skins by exact fontSize|px|py|radius.
2. Sorted by font-size descending.
3. Kept the top 3 → named Large / Medium / Small.
4. At map time, re-matched each button to a preset by tolerance (fs ±1, py ±3, px ±4).

Three failures showed up on a real site (modfii, 4 distinct button sizes):

• Dropped sizes. The top-3 cap discarded the 4th size. A button whose size was dropped matched nothing → no .btn-{slug} class → the thin .btn base (the "button stays thin" bug).
• Noise as duplicates. Computed values are noisy (43.99 vs 44px, 31.98 vs 32px), so one design became several near-identical presets, bloating the list and burning the top-3 budget.
• Mis-ranking. Sorting by font-size alone put a 14px / h-11 (44px) button below a 16px / h-9 (36px) one, even though it's physically taller.
• Fixed height lost. A source h-11 (44px, zero vertical padding, flex-centred) was approximated as a guessed Padding-Y instead of a real height.

Options considered​

1. Just raise the cap + relax tolerances. Keeps the fragile re-match; noise still sprawls; ranking still wrong. Rejected — treats symptoms.
2. One preset per exact size, no cap. Fixes dropping but explodes the list on noisy sites (5–6 near-dupes). Rejected.
3. Cluster → rank-by-visual → frequency-name, keep all clusters, closest-match fallback. Chosen.

Decision​

A four-part pipeline, identical in the PHP (build_button_presets) and JS (deriveButtonPresets) paths:

1. Cluster near-identical skins within a tolerance (fs ±1, px/py/height ±3). The representative value per property is the mode (most-common exact value in the cluster), so preset numbers stay clean (44px, not 43.99px). This collapses computed noise into one preset per real design.
2. Rank by visual size — max(fixedHeight, fontBox + 2·paddingY) — the height a reader actually perceives. Ties (same height, different font) break by font-size, then by frequency.
3. Frequency-aware naming — the most-used cluster is tagged the base "(Default)", and it wins ranking ties, so the dominant CTA size reads as the primary.
4. Fixed height → Min Height — a source sized by h-11 populates the preset's new Min Height field (the button centres content via inline-flex), the exact reproduction instead of guessed padding.

Plus a closest-match fallback at assignment: if a button doesn't match a preset exactly, it takes the nearest (weighted to font-size). A real button is never left unassigned/thin.

Why​

Clustering is the key insight: the source's intent is a handful of button sizes, but its computed output is dozens of noisy measurements. Deduping on exact values confuses noise for design; clustering with a mode representative recovers the intent. Ranking by visual size (not font) matches how a human names Large/Medium/Small. Keeping every cluster + a closest-match fallback guarantees no button falls through to the unstyled base — the failure mode that caused the recurring "button stays thin" reports. And a dedicated Min Height option means a fixed-height button is reproduced exactly rather than approximated.

Deferred: responsive size layers (a button that changes size at breakpoints, h-10 md:h-11). That needs the size-preset option itself to become responsive (base/md/lg) plus media-query CSS generation — a separate feature, not a derivation change. The converter currently reproduces the desktop size.

Status: Accepted.

Context​

The source items were Radix accordion cards: <div class="bg-card rounded-xl border border-border"> inside a space-y-4 container. Unmistakably Separated (per-item fill + rounded corners + a border + vertical gaps). The converter emitted Flush.

Two real bugs, not a fuzzy judgment call:

1. The detector read only computed styles (data-sc-cs). On a class-based / raw-HTML source with no stamped computed styles, background-color, border-radius and border-width all read empty → no fill, no edge.
2. space-y-4 sets margin-top on children, which neither the flex gap read nor the first item's margin-bottom can see → the inter-item gap read as 0.

Result: gap < 4, no bg, no edge → the Flush branch.

Options considered​

1. Hand style classification to the local AI companion. The capture service already builds an AI verify pass (d._hint carries the icon markup + item geometry), so extending it to "pick the closest accordion style" is easy.
2. Fix the deterministic classifier — read the Tailwind classes (bg-*, rounded-*, border, space-y-*/gap-*) as a fallback/complement to the computed reads.
3. Both — deterministic first, AI as a last-resort tie-breaker for the ambiguous tail.

Decision​

Deterministic first (option 2), with the AI kept as the existing last-resort verify pass (the tail of option 3). Not AI-primary.

The classifier now falls back to the item card's + container's utility classes: a non-transparent bg-* ⇒ has-fill; rounded-* ⇒ radius (xl→12, 2xl→16…); border/border-* ⇒ an edge; space-y-N/gap-N on the container (or mb-N on the item) ⇒ the inter-item gap; divide-y ⇒ a flush divider list. The FAQ now classifies as Separated with corner_radius: md and item_spacing: mb-[16px]. Both the PHP and JS paths carry the fallback.

Why​

• Reproducibility is the converter's contract. Same source → same output, every run. AI style-picking is non-deterministic; the same accordion could map to different styles across runs, which breaks the one guarantee the deterministic path exists to provide.
• The signal is measurable, not ambiguous. bg-card rounded-xl border in a space-y-4 container is Separated — the CSS/classes encode it exactly. Reaching for an LLM to read a class list is a sledgehammer where a strpos suffices, and it adds a per-widget round-trip plus cost.
• The converter must work with the AI off. The local companion auto-detects a backend (API key → claude CLI → off); a core mapping decision can't depend on a backend that may be absent (headless/cron runs especially).
• AI earns its place on the genuine tail. A bespoke accordion with no clear style signals is where a verify pass helps — and the capture service already emits _hint for exactly that. Deterministic gets it right for the 95% that is measurable; AI confirms/corrects the ambiguous 5%. That division keeps the common case fast, free, and reproducible.

The broader principle: push the deterministic detector as far as the source's measurable signal allows before delegating to AI. Most "the converter guessed wrong" cases are a missing measurement (here, classes + space-y), not a case that needs judgment.

Status: Accepted.

Context​

The trigger was a fidelity bug in the Site Converter. Converting a hero whose grid used gap-10 lg:gap-16 (40px mobile, 64px desktop) produced a 48px gap — because:

• The gap scale stopped at slug 5 (48px), so 64px had nowhere to land and clamped.
• The converter's gap_slug() snapped to the nearest of {4, 8, 16, 24, 48}, so 40px → 48px too.
• Arbitrary gap-[Npx] tokens harvested from the source were being folded into the spacing scale, but the Section's Gap option reads the gap scale — so they never reached it.

The deeper issue is the 24px → 48px cliff shared by both scales: 2rem (32px) and 2.5rem (40px) — the two steps modern designs use most for card/section padding and grid gaps — simply don't exist as named slugs.

The hard constraint: you cannot renumber existing slugs. Every built page, every converted site, and every theme preset references .pt-11, .g-5, section--gap-5, etc. Changing what a slug means silently breaks live content. So any fix has to be purely additive.

Options considered​

1. Redefine the mid-range slugs (make slug 5 = 2rem, shift the rest). Cleanest scale, but renumbers every existing reference — breaks all built/converted content. Rejected outright.
2. Raise the gap cap only (add 4rem, 5rem to the gap scale). Fixes 64/80px gutters but leaves the 32/40px cliff and the snap-to-48px behaviour. Half a fix.
3. Extend the gap scale to mirror the spacing scale, seed the mid-range as bracketed arbitrary steps in both scales, and give the converter a dedicated gap scale with exact [NNpx] output. Chosen.

Decision​

A four-part, entirely additive change:

1. The gap scale now mirrors the spacing scale — slugs 0–12 (0…8rem). g-{slug} ≡ p-{slug} mentally, and 56/64/72/80/96/112/128px gutters become expressible. Slugs 0–5 are byte-for-byte unchanged.
2. The [32px] / [40px] mid-range is seeded into both scale defaults. Bracket-named so they read as exact lengths in the dropdown. The gap generator and the Section view both sanitise [32px] → .section--gap-32px; on the spacing side the bracketed entries render on demand through the per-page arbitrary-spacing handler (.pt-[32px]).
3. The Site Converter gained a dedicated build_gap_scale() (parallel to build_spacing_scale()) that emits the extended base and appends any genuinely off-scale gutter the source uses — a gap-[20px] class or a computed gap:Npx — as an exact [NNpx] entry. Gap tokens no longer pollute the spacing scale.
4. gap_slug() now resolves exactly — an on-scale value returns the clean slug (gap-16 = 64px → 7), an off-scale value returns a lossless [NNpx] slug that build_gap_scale() has registered a preset for. No more snapping.

The PHP (Stitch/Mapper) and JS (to-theme-settings/to-pages) paths carry identical scales and logic.

Why​

The scale's job is to encode a design system's intent as a small, named, editable vocabulary. Bootstrap's $spacers encodes a 2013-era intent; modern component design leans on a denser mid-range and larger section gutters. Because slug numbers are a public contract, the only safe way to modernise is additively: keep 0–12 stable, mirror them across both scales so the mental model is one scale not two, and express everything off-scale as lossless bracketed arbitraries — the same mechanism the converter already used for spacing. The converter change is what makes it faithful: a real site's exact gutter is reproduced, not rounded to the nearest legacy step.

Deliberately not done: redefining the gap cap philosophy as "gaps over 3rem are section spacing." In practice hero and feature grids routinely use 64–80px column gaps; treating those as un-representable was the bug, not a feature.

Status: Accepted.

Context​

Each new option so far got its own hand-written detector (the accordion style/gap reader, the button-size algorithm, the gap snapper, the section padding distillation, …). That's dozens of bespoke functions, each re-discovering the same problems: where the signal lives (class vs computed), how to snap a measured value onto a scale, and — for preset-backed options — the build ordering (presets are assembled in the theme-settings pass, after the page is built). The box-preset bug (assigned boxes silently falling back to raw CSS because the lookup was empty during page build) was that ordering trap, hit again.

The insight: options are two kinds, not one​

A. Preset-backed options — the value references a Theme Settings preset: background_pattern, box preset / border_preset, color presets, section styles, button color/size, icon badges, text styles, the spacing/gap scale. You can't "detect" these into a scalar — the faithful mapping is register a preset and point the option at it.

B. Intrinsic scalars — the value is a direct property: alignment, margins, orientation, columns, corner radius, position, width mode. These are reads; there's nothing to register.

Options considered​

1. A detector per option. Maximum control, but O(N) bespoke functions, each re-solving signal-location + snapping + (for presets) ordering. Doesn't scale; it's how we got here.
2. Hand everything to the local AI. Non-deterministic; breaks the converter's reproducibility contract (see the "deterministic style classification" decision). Rejected as the primary.
3. Two shared frameworks + a data-driven backlog. Chosen.

Decision​

Preset-backed options → one shared registration framework. Capture the skin → register_*() returns a deterministic id (hash of the normalized skin) → the option is set to that id; the theme-settings pass emits the referenced presets. This is the pattern proven twice (Background Patterns, Box Presets). Generalizing it bakes in, once and for all:

• deterministic ids, so assignment and registration agree with no name/order coupling;
• the correct ordering (record during page build, emit during the theme-settings pass);
• reuse — any shortcode that wants a box/color/pattern/badge just registers and assigns.

Intrinsic options → one declarative resolver over a spec table: { source signal (CSS property or class pattern) → option key + value transform }. Adding an option becomes adding a row, not a function; shared value-snappers (spacing scale, gap scale, radius buckets) are called by the table, not re-implemented per option.

What to add next is data-driven. The converter already emits class-coverage.json and conversion-drops.json — ranked lists of source signals it didn't map. Extend the registry/table by frequency, not by guessing. AI stays the last-resort for the genuinely ambiguous tail only.

Why​

A detector-per-option model makes coverage a function of how many functions someone hand-writes — unbounded and error-prone. Splitting on how a value is expressed (a preset reference vs a scalar) yields exactly two reusable mechanisms that cover the whole surface: registration handles everything preset-backed (and fixes the ordering class of bugs structurally), and a declarative table handles the scalars (turning "add an option" into "add a row"). The coverage reports turn the remaining work into a ranked backlog instead of a guessing game, and AI is reserved for the small ambiguous remainder where no measurable signal exists. Reproducibility — the converter's core contract — is preserved throughout, because both mechanisms are deterministic.

Status: Accepted.

Context​

The trigger was a conversion complaint: a source "how it works" section whose steps are boxed cards with icons converted to a flat, borderless number list — the boxed look and the per-step icons were both dropped. Fixing the detection was unambiguous (read the boxed skin from computed styles, capture the icon glyph, match the marker shape/accent). But it surfaced a design question: how much option surface should Steps grow to reproduce designs like this faithfully, and to stay flexible for the future?

Card Rows is the obvious "future-proof" answer — it's the system every other card-like shortcode already shares. The instinct was to give Steps the same treatment.

Options considered​

1. Full Card Rows on Steps now. Add a Card tab with a slot designer (marker/icon, number, title, content), a live card preview, and box_style. Maximally flexible and consistent with the other card shortcodes. Cost: a Steps view rewrite — the view would have to render from rows while still drawing the marker + connector spine, which Card Rows has no concept of. High risk for a shortcode whose value is its connected-flow layouts (horizontal / vertical / alternating / cards).

2. Box Preset (box_style) now, Card Rows later. Add just the shared sc_card_box_style_field + sc_card_box_style_class (the same Box Preset picker icon-box / testimonials use) to the Steps Design tab, stamped as .boxp-{slug} on every .fw-steps__item. Keep the marker/connector engine untouched. Small, shared, immediately useful; the Site Converter can auto-assign a captured box skin. Revisit Card Rows as a scoped, Steps-specific effort once there's a real need.

3. Detection fixes only. Ship the converter improvements (boxed → cards, icon capture, marker shape/accent) and add no new option surface. Faithful conversions, but no new editor control for hand-built steps.

Decision​

Option 2 — add box_style now and defer Card Rows.

Why​

Card Rows models an independent card grid: each item is a self-contained stack of slots (image/title/meta/excerpt) with no relationship to its neighbours. That's a perfect fit for Posts, Testimonials, wc_products and team-member. Steps is not that — it's a connected flow with a marker + connector spine and horizontal/vertical/alternating layouts. Dropping the grid Card Rows onto it would either discard the connector model or fight it, and would force a view rewrite of the one part of the shortcode that carries its identity.

box_style, by contrast, is pure win at low risk: it's the exact Box Preset system the rest of the card-like shortcodes already share, it needs no view rewrite (one class on each step item), and it closes the reported gap directly — a boxed source process now maps to design: cards plus a matching .boxp- preset, while the converter also carries the per-step icon (→ marker: icon), marker shape and accent colour. If a genuine need for per-step slot reordering appears later, it can be built as a Steps-specific Card variant that keeps the connector spine — not a copy of the grid system. Ship the 80% that fits the shortcode's grain; don't retrofit the 20% that doesn't.

Status: Accepted.

Context​

Both doc sets describe the same underlying engine but for different readers. The extension pages (index, convert-from-file, convert-from-url, capture-service, ai-assist, manual-tools, how-it-works) are a product manual for a WordPress user running the plugin in wp-admin. The AI Dev Kit pages are for a developer running Claude Code to drive an agentic conversion and improve the converter.

Two facts complicated a wholesale move:

1. The Site Converter extension is a standalone plugin — fully usable without the kit (its deterministic engine and the capture service need no AI and no Node tooling from the kit).
2. The extension has its own optional "AI assist" — Claude running inside the capture service to refine the mapping only. That is not the same as the kit's full agentic build. So there are three tiers, not two: extension-deterministic, extension-AI-assist, and kit-full-agentic.

Options considered​

• Full consolidation (the original proposal). Move every extension subpage's content into the kit; collapse the extension section to one overview page + a prominent "see the AI Dev Kit" link. Trade-off: a user who just installed the plugin to convert an HTML file gets bounced into developer-kit docs that imply they need Node + Claude — and the extension's light AI-assist gets conflated with the kit's full agentic build. The plugin stops being self-documenting.
• Hybrid. Keep the pure task pages (file/URL) in the extension; move everything conceptual (how-it-works, ai-assist, full-conversion, manual-tools pipeline) to the kit. Trade-off: splits the extension's own manual mid-way — ai-assist and manual-tools are things you do in the plugin, so exiling them reads oddly.
• Consolidate by depth (chosen). Move only the deep architecture + algorithm to the kit as one canonical page; keep the extension's task manual in place; shrink the extension's how-it-works to a short two-engine overview that links to the kit for the full details.

Decision​

Consolidate by depth, not wholesale. A new canonical page — ai-dev-kit/conversion-architecture — now holds the full pipeline (capture → extract → apply → review → build), section detection, chrome-vs-content, the role→shortcode map, the navigation and footer-widget mappers, design-token extraction, the two kept-in-sync implementations, and exactly where AI fits. The extension's how-it-works is reduced to a short two-engine overview (deterministic / capture service / optional AI) that links out to that page. All the extension task pages stay put. Cross-links run both directions.

Why​

The right axis to split on is audience/depth, not location. The deep architecture is shared by both paths, so it belongs in exactly one canonical place — and the kit, whose whole reason for being is "how conversion really works and how to improve it," is the natural home. But the extension is a standalone product; its docs must let a wp-admin user convert a site without ever meeting the kit. Keeping the task manual in the extension preserves that self-sufficiency, while moving the deep reference eliminates the duplication and the "which how-it-works is authoritative?" ambiguity. The plugin's own AI-assist stays documented as a plugin feature, distinct from the kit's agentic build.

Context​

The theme-settings importer replaces the whole border_presets option (it doesn't merge), so whatever the converter emits is the entire library the converted site ships with. That forces an explicit choice — the emitted list has to deliberately contain the defaults, or they're gone. Two things pull in opposite directions:

• The converted presets are the site's design system. On a faithful clone, "Feature Card", "Glass Stat Box", and "Problem Card" ARE the site's boxes; they're what every converted element references (box_style / border_preset = boxp-<slug>), and what a user should reach for first when adding a new card that matches the design.
• The defaults are still useful. A user who later adds an element the source never had (a plain bordered callout, a soft-shadow panel) wants a sensible generic starting point without hand-rolling one. And removing a built-in that some element or template already references would break it.

Options considered​

• Replace the defaults with the converted presets. Cleanest "this is your site" list — no generic noise. Trade-off: destructive. Any element/template pointing at a default .boxp-card / .boxp-outline loses its styling, and a user adding a non-source element has nothing generic to grab. Deleting built-ins that a store REPLACES (not merges) is a one-way loss.
• Keep defaults first, converted appended after (the original behaviour). Non-destructive, but the site-matching presets sit below four generic ones the user has to scroll past — the converted design system reads as secondary to boilerplate.
• Keep defaults, PREPEND the converted presets (chosen). Non-destructive AND the converted design system is primary.

Decision​

Keep the built-in defaults, but put the converted presets ON TOP — array_merge( $derived, $defaults ) (PHP) / derived.concat(DEFAULTS) (JS). The site-derived presets are what the user sees and selects first, and what the converter assigns; the four generic defaults remain available below as a fallback. Same ordering rule applies to the sibling preset families (section styles, buttons, icon badges) so the whole Theme Settings → Components experience is "your site's stuff first, library defaults below".

Why​

The right axis is primacy, not exclusivity. The converted presets earn top billing because they're the actual design system — but removing the defaults trades a real safety property (nothing that references a built-in can break; there's always a generic starting point) for a purely cosmetic tidiness that the ordering already delivers. Prepending gets the "this is your site" feel with none of the destructive risk, and it's the same "your items first, library below" pattern users already know from every other picker in the product. When in doubt between destructive-and-clean vs non-destructive-and-ordered, non-destructive wins — you can always ignore a default, but you can't un-break a reference to a deleted one.

Context​

The single-URL build hard-coded the target as the front page:

$screens[] = array( 'html' => …, 'title' => <page <title>>, 'slug' => '', 'front' => true );

The importer is idempotent by slug (update-if-exists, else create), and front => true writes show_on_front / page_on_front. So converting /services:

• created a new page (slug derived from the messy <title>, e.g. services-noir) — it did NOT overwrite the Home page's content;
• but set that new page as the site's front page — so visiting the site now showed Services. That's the real bug: the homepage pointer was hijacked;
• and re-captured header/footer + rebuilt the child theme — redundant, and destructive when adding a page to an already-converted site (it re-derives chrome over the tuned one).

The converter already receives the source URL (source_url in the build opts), so it has everything it needs to tell an inner page from the homepage — it just wasn't using it.

Options considered​

• Make the user uncheck the boxes. Rely on the human to turn off Create child theme / Capture header / Capture footer for an inner page. Trade-off: easy to forget (the front-page hijack still happens even if they do, because front is hard-coded), and it pushes converter knowledge onto the user for something the URL already tells us.
• Add a "Create new page" checkbox. Trade-off: the importer already creates a new page per slug — the thing actually missing is control over the front-page assignment, not page creation. A "create new page" toggle would be redundant and wouldn't fix the hijack.
• Infer from the URL path + one "Set as homepage" toggle (chosen). Derive slug + front from the source path; flip the chrome/child-theme defaults for inner pages; expose a single explicit override.

Decision​

Infer the target from the source URL path, and expose a "Set as homepage" toggle:

• Root path (/, /index.*, /home) → the homepage: blank slug → home, set as the front page (today's behavior).
• Any inner path (/services) → a new page under the clean path-segment slug (services), front:false — the homepage is left untouched.
• The Convert panel's "Set as homepage" checkbox always wins when the user sets it (threaded as the set_as_homepage build opt); it's auto-ON for a root URL and auto-OFF for an inner URL.
• Typing an inner URL also auto-unchecks Create child theme / Capture header / Capture footer (with a hint) so an inner page imports as content-only into the existing site — any box the user has touched is left as they set it.

Why​

The URL path is an unambiguous, already-available signal for "is this the homepage or an inner page," so making the human re-encode it by hand (and remember to do so) is the wrong layer — especially since the real hazard (the front-page hijack) came from a hard-coded front => true the checkboxes couldn't even fix. A "create new page" checkbox misdiagnoses the gap: creation was never the problem, front-page assignment was. Inferring the defaults from the path and surfacing exactly one override ("Set as homepage") makes the common cases correct with zero clicks — convert the homepage → it's the homepage; convert /services → it's a new page, your site untouched — while keeping the user in full control for the exceptions.

Context​

The Site Converter maps a source's DOM onto native UnysonPlus constructs. A product grid on the source (cards with a title, image, price, and an add-to-cart control) currently falls through to the generic card-grid path and renders as static image_box tiles — frozen content, no cart, no live catalog.

Two facts pull in opposite directions:

1. The source can be detected. A real WooCommerce/e-commerce page carries unambiguous signals in the captured HTML — the woocommerce body/wrapper class, woocommerce-Price-amount, add_to_cart_button, data-product_id, WooCommerce Blocks (wc-block-*), Product JSON-LD, and store-shaped URLs (/product/, /cart, /checkout).
2. Emission can break the target. [wc_products] and friends only render on a site where WooCommerce is active. Emit them on a plain install and the visitor sees raw, unparsed shortcodes — worse than the static cards we replaced. Detection tells us about the source; it says nothing about whether the target can render what we'd emit.

Options considered​

• Auto-detect only (no UI). Detect WooCommerce in the source and map product grids to WooCommerce shortcodes automatically. Trade-off: silently emits broken shortcodes whenever the target lacks WooCommerce, and gives the user no way to opt out (e.g. they're rebuilding the store on a page builder and don't want a live feed there). Detection is necessary but insufficient — it's the wrong single gate.
• Checkbox only (no detection). A plain "Map to WooCommerce" toggle, always available. Trade-off: a user can tick it on a non-store site and get a product feed where the source had a portfolio grid; and it offers no guidance about whether the option is even usable on this install.
• Detect and gate (chosen). A checkbox that is disabled unless class_exists('WooCommerce') (labelled "(WooCommerce not installed)" when off), auto-ticked when the source is detected as a store, and whose emission is gated a second time by the same source detection at build time. Both the target (WooCommerce active) and the source (reads as a store) must agree, and the user stays in control.

Decision​

Detect the store, but gate emission behind a WooCommerce-active checkbox — a double gate.

• FW_Site_Converter_Sources::is_woocommerce_source($html) scores the captured HTML (strong signals worth 2, corroborating ones worth 1; a threshold of 2 avoids a lone "cart" word false-positiving).
• The Convert panel's "Map to WooCommerce" checkbox is disabled unless WooCommerce is active on the install, so it's impossible to request an unrenderable mapping.
• The build reads the option (map_woocommerce), and the mapper only switches product grids to WooCommerce shortcodes when the option is on, WooCommerce is active, and is_woocommerce_source() agrees — so a mistaken tick on a non-store site is a no-op, not a broken feed.

Why​

The core insight is that source detection and target capability are two different questions, and each is a necessary gate for a different failure mode. Detection prevents "portfolio grid became a shop"; the WooCommerce-active gate prevents "raw [wc_products] on a site with no WooCommerce". Neither gate alone is safe, so we require both and let detection auto-tick the option (convenience) while the WooCommerce-active check disables it (safety). The result is a converter that does the smart thing by default on a real store, degrades to the existing static-card behaviour everywhere else, and never emits output the target can't render — with the user always able to override.

Status: Accepted. The detection + gated checkbox + option threading ship first; the product-grid → [wc_products] mapping itself lands next, built and verified against a live WooCommerce source.

Context​

Type was stored as a single desktop value per role (body, h1–h6) and made "responsive" by one generated @media (max-width: 767.98px) block that scaled each size by a tiered percentage. Converting a source site surfaced the failure modes: tablets (≥768px) rendered full desktop sizes, the boundary was a visible jump, small phones still overflowed (one fixed value below 768px), and any size stored as rem/em skipped the px-only scaler entirely.

Options considered​

• Keep the stepped model, add more breakpoints. Familiar, but every breakpoint is still a jump, and it multiplies the values to maintain.
• Add Phone/Tablet/Desktop controls to every typography field. Maximum control, but triples an already-dense tab, still only changes at breakpoints, and most users won't fill three values — so the defaults must be good regardless.
• Fluid clamp() on a modular scale (chosen). One authored value scales smoothly across every viewport. Matches where the ecosystem has landed: WordPress core (theme.json fluid: true), Utopia, Material's role/token scale.

Decision​

Move typography to fluid clamp() built on a modular type-scale engine, with per-device controls kept only as an optional override, and the WCAG 1.4.4 (resize to 200%) constraint designed in: every generated clamp uses a rem + vw preferred value and a rem-anchored max — never vw alone. A tiered mobile floor and a body minimum keep small sizes readable, and a guardrail flags over-steep curves.

Why​

• A vw-only clamp breaks browser zoom. Viewport units don't change when the user zooms, so a vw-based size stays visually fixed at 200% zoom — a direct WCAG 1.4.4 failure. Anchoring both the preferred value and the max in rem means zoom (and the user's font-size preference) still scale the text. This is the single constraint that dictated the whole implementation; bolting fluid on without it is the trap most implementations fall into.
• Fluid removes the real defects. Smooth scaling covers tablets (no more desktop-on-tablet), erases the breakpoint jump, and stops small-phone overflow — the exact problems the stepped model caused.
• A scale beats per-element hand-tuning. A base size × a ratio yields a coherent set of steps that elements reference, so the whole system stays consistent instead of drifting per heading.
• It's the interoperable baseline. WordPress core already ships this model; aligning lets the block editor and the builder agree, and keeps us on the same footing as the major themes/builders.
• The overhaul is the moment to fix font CLS too. Owning how type and fonts are declared let us add font-display: swap (already present) plus metric-matched fallback @font-face rules, so the web-font swap doesn't shift layout.

Status​

Accepted — shipped as Phases 0–4 (fluid clamp foundation, scale engine, authored Type Scale UI, semantic roles + theme.json fluid + fallback metrics). Per-device per-role overrides and the dedicated authored control follow with the v3 option type.

Context​

A conversion maps a source element onto a UnysonPlus construct (a special_heading, an icon_box, a footer section) and emits the source's look as a faithful base. The base is written with :where(selector){…} — deliberately zero specificity, so a user can override any of it later without fighting !important.

That same zero specificity is the trap. A shortcode's own rule (h2.heading-title { font-weight: var(--h2-font-weight, revert) } = specificity 0,1,1) or the parent theme's tag rule (h2 { … } = 0,0,1) both outrank the :where base (0,0,0). When the theme/shortcode default happens to equal the source, everything looks right; when it doesn't, the source loses:

• Heading weight — the shortcode's revert fallback resolves to the UA default for <h2>, which is bold; a source heading at 400 rendered bold.
• Heading casing — the source's CSS-applied text-transform: uppercase (no uppercase class) was dropped, so "OUR SERVICES" became "Our Services".
• Icon colour — an unresolved text-muted-foreground fell through to the icon_box shortcode's default green instead of the source grey.
• Footer text — a stale section rule painted the address rows black on a dark footer.

Read individually these look like four bugs. They are one architectural fact: the base cannot win a specificity battle it was designed to lose.

Options considered​

1. Keep patching per property. Fast each time, but it is whack-a-mole — every new shortcode or theme default is a fresh way for the source to be overruled, and nothing tells us which properties are at risk until a site looks wrong.
2. A separate runtime "overrule detector". Render the converted page, diff every element's computed style against the source, emit corrective CSS. Accurate, but a conversion is imported server-side (PHP) into a site that isn't live yet — there is no rendered page to diff at import time. It would need a headless browser in the import path, which we don't have and don't want there.
3. Deterministic source re-assertion at build time (chosen). For a fixed set of high-overrule-risk properties, always emit the source's computed value at a scoped specificity that wins — the .uHASH .part (0,2,0) selector the mapper already uses for heading_weight_css(). The source is authoritative by construction; no rendering, no diffing, no per-case chase.

Decision​

Re-assert, don't detect. When the converter maps an element it already holds that element's computed style (data-sc-cs); it emits the overrule-prone properties — font-weight, font-family, text-transform, letter-spacing, line-height, colour — as a scoped rule at .uHASH .part specificity (0,2,0), which beats a shortcode's hN.heading-title (0,1,1) and the theme's bare tag rule (0,0,1). The mapper's significant_text_decls() already extracts exactly this set from a computed-style string, so the mechanism is a generalisation of an existing helper rather than a new subsystem.

The first place this landed: heading_weight_css() now recovers the weight from the heading part's own computed style (*_cs) when no explicit weight/class carries it, so a source <h2> at 400 re-asserts font-weight:400 !important scoped to its node and renders regular. Casing was fixed in the same spirit by carrying the heading's text-transform through to a --hN-text-transform token the theme's hN rules consume. The icon-colour case was the same root in a different guise — the admin rebuild path wasn't seeding the semantic-colour config, so text-muted-foreground couldn't resolve and fell to the shortcode default; enriching the config is the "re-assert the real source value" move for colour.

Why​

• Deterministic and offline. It runs in the PHP importer with no browser and no live page — the same constraint that rules out a runtime detector.
• Wins by construction, not by luck. Specificity is chosen so the source outranks the constructs it is mapped onto; we stop depending on the theme default happening to match.
• Bounded, not universal !important soup. Only the small, named set of properties that shortcode and theme defaults actually clobber is re-asserted — the rest of the base stays overridable :where, so users keep the clean override story the base was designed for.
• One concept, many symptoms. Weight, casing, colour and footer text were all the base losing a specificity battle; framing the fix as "re-assert the source at winning specificity" turns a growing list of one-off patches into a single rule with a known property set to extend.

Status: Accepted. Applied to heading parts first; the property set and the .uHASH .part re-assertion pattern are the template for extending it to other converted constructs as new overrule cases surface.

Context​

Typography settings drive every site's rendered type. The overhaul (fluid scale engine, new Type Scale UI, role tokens, font pipeline) changes how sizes are authored and emitted. We had just promoted the former typography-v2 control to be the canonical typography — so we already had a pattern for "prove a new control, then make it the default."

Options considered​

• Edit the canonical control in place. Fewest moving parts, but any regression hits all 13+ installs immediately, and there's no clean rollback while iterating.
• Build a permanent parallel typography-v3 and keep all three. Safe to iterate, but leaves the namespace cluttered with versioned controls forever.
• Stage as typography-v3, then promote it to canonical (chosen). Iterate in isolation, verify, then rename v3 → the canonical typography and retire the old one — exactly the v2→v1 move.

Decision​

Develop the overhaul as an isolated typography-v3 surface. Once verified across installs and the converted test sites, promote it to the canonical typography and demote the current control to a compatibility shim. "v3" is a staging label, not a permanent versioned control.

Why​

• Zero blast radius while building. The live control keeps running untouched, so iteration can't break a production site; rollback is just "don't promote."
• Non-destructive by construction. V3 emits into the same CSS custom properties (--h1-font-size etc.), so when it becomes canonical, built pages don't notice the swap; saved values fold forward.
• A clean long-term namespace. Because the destination is the canonical name — not a permanent v3 — we don't accumulate versioned controls. The number is scaffolding that disappears on promotion.
• A proven pattern. This is the same staged promotion used for v2→v1, so the workflow and its guarantees are already understood.

Status​

Superseded. The dedicated typography-v3 option type was built as a composite (fonts + the scale in one control) and then removed: a single control bundling the whole scale read as bulky and confusing, and it duplicated what the General → Typography tab already does. The correct home for the fluid scale is a group of ordinary options on the Typography tab (the Phase 2 "Type Scale" group), not a bespoke option type. So there is no v3 control to promote — the fluid engine (Phases 0–1), the tab controls (Phase 2), the font-CLS layer (Phase 3) and the role/theme.json work (Phase 4) all stay; only the option-type packaging was dropped. The lesson kept: reach for a new option type only when a control is genuinely reusable across many contexts — not to bundle one tab's settings.

Context​

Reorganising the Header Layout and Mobile & Tablet tabs into type => 'group' boxes gave us ~19 groups. Each group needed a visible heading (and one needed a short note — "a different mobile logo lives under Identity"). The framework's group container had no title concept, so every group led with a throwaday html option:

'grp_toggle' => [
    'type'    => 'group',
    'options' => [
        'toggle_heading' => [ 'type' => 'html', 'label' => false, 'html' => '<h4 …>Hamburger / Toggle</h4>' ],
        // …real options…
    ],
],

That works, but it's wrong on three counts: the heading is a fake option occupying an id in a data array; its markup/inline-styles are duplicated at every call site; and the label lives inside options rather than as an attribute of the group, so grouping and labelling are two disconnected ideas.

Options considered​

• Keep the leading html option. Zero framework change, but the noise multiplies with every group and the styling drifts (each site/tab re-invents the <h4 style=…>).
• A helper closure ($heading() / $section()) per options file. Removes the copy-paste but still emits a fake option, still per-file, still not an attribute of the group.
• Native title (+ desc) on the group container, rendered only when set. One place owns the markup; the label becomes an attribute of the thing it labels; every group across the plugin benefits.

Decision​

Add optional title and desc parameters to FW_Container_Type_Group::_render(). title renders as a small uppercase "eyebrow" section label — deliberately a muted <div class="fw-backend-options-group__title">, not a content <h4>, so it marks a section without competing with the field labels beneath it; desc allows limited inline HTML (wp_kses_post) in a muted <p class="fw-backend-options-group__desc">. Both render only when present, so every existing group in the plugin is untouched. The Header Layout and Mobile & Tablet tabs were then refactored to use title/desc and drop their html heading options (the "mobile logo" note became the Layout group's desc).

Why​

• Back-compat is free — an unset title/desc renders nothing, so the thousands of existing groups are byte-identical in output.
• One owner for the markup — the box heading style lives in the container renderer, not scattered inline styles across option files, so it stays consistent and themeable via two real classes.
• The model reads right — a group's label is now an attribute of the group, mirroring how box/tab already carry a title. Grouping and labelling are one construct, which is exactly what a reader skimming the option array expects.

The options-framework docs (/docs/options) were updated to document the two new parameters.

Context​

header_behavior is one select with five values: static, sticky, sticky-shrink, hide-on-scroll, transparent-overlay. But a header's "behavior" is really four independent things:

• Position / motion — does it pin? does it hide on scroll-down?
• Top transparency — clear over the hero, or a solid bar?
• Scroll transform — shrink the logo / tighten padding when stuck?
• Background chrome — the fill, plus Glass, Border, Shadow.

Forcing those into one mutually-exclusive list means most combinations are unreachable: transparent + shrink, solid + hide-on-scroll, and — the one that started this — clear at the top, frosted glass only on scroll. Glass compounds the problem: it is currently a constant background (frosted at the top and on scroll, by design), so it can't express "frost appears on scroll." Every recent header gap traced back to this one enum.

The converter made the smell obvious. The capture already records the header in two states — header_scroll = { top, scrolled } — and then we throw half of it away trying to collapse both into a single enum value, guessing whether the result should be transparent-overlay or sticky or sticky-shrink.

Options considered​

• Keep one enum, add modifier toggles (Shrink on scroll, Frost on scroll, Solid on scroll). Least disruptive and no migration, but the enum still owns position and transparency, so the toggles can still contradict the mode (e.g. "Frost on scroll" under a static header). It patches symptoms, not the conflation.

• Literal two sub-tabs, "On load" / "On scroll", both always visible. Discoverable and honest about the two states, but it doubles the visible surface for everyone even though most headers never differ between states — and it still needs a separate home for position.

• Two composable appearance states + a slim position axis, with progressive disclosure. Model exactly the two states the header has. Behavior shrinks to position (static / sticky / overlay) plus a hide on scroll toggle. Appearance — At top is always shown. Appearance — On scroll (same fields + shrink) is revealed by one master toggle, "Change appearance on scroll"; off means the scrolled header inherits the at-top look.

Decision​

Adopt the two-state model: a slim Behavior (position + a hide toggle), Appearance — At top, and a toggle-gated Appearance — On scroll (Background, Glass, Border, Shadow, Shrink). The CSS splits today's constant chrome rules into :not(.is-stuck) (at top) and .is-stuck (on scroll) halves keyed off data-attributes, with a second --header-scroll-bg variable; the .is-stuck observer and the hide-on-scroll JS already exist and are reused as-is.

No database migration. The handful of live sites are re-picked by hand once the option shape lands; a small read-side shim derives a missing header_position from any legacy header_behavior so nothing renders broken in the meantime. The converter mapping (fill At-top from the resting snapshot, On-scroll from header_scroll / data-sc-scrolled) and the header presets are deliberately sequenced as follow-ups, so the first pass is options + CSS + JS + docs only.

Why​

The four things the old enum bundled are genuinely orthogonal, so the honest model is orthogonal controls, not a longer list of pre-baked combinations — a list can never cover the whole product of four axes, and every gap becomes a support question. Two states is the complete description of a header (there is no third), so the model is not just more flexible, it's bounded: you can't invent a fifth thing to forget.

It also collapses two hard problems into one. The converter's header_scroll is already two states; giving Theme Settings two states makes the mapping a 1:1 copy instead of the lossy "guess a single behavior" heuristic we kept patching — the OBSIDIAN case (transparent hero, frosted-and-shrunk on scroll) becomes an exact reproduction rather than an approximation.

The cost is real — it spans options, CSS, JS, the converter, and presets — but skipping the DB migration (the riskiest piece) in favor of a read-side shim and hand-fixing a few sites removes most of that risk, and the master "Change appearance on scroll" toggle keeps the panel as light as today's for the common case. Modifier toggles on the old enum were rejected because they leave the core conflation in place; the always-visible two-tab layout was rejected for taxing every user with a split that most headers don't use.

Status: Accepted. Implementation spec: Header-Two-State-Model-Spec.docx. Build order — theme options + CSS/JS + docs first; converter mapping and presets follow.

Context​

The Site-wide UX tab (Page Transitions, Cursor, Preloader, Smooth Scroll, Dark Mode, Scroll Progress, …) pairs an Enable X switch with the feature's controls. For the image-picker features — e.g. Page Transitions with its searchable Fade / Content Fade-Up / Zoom tiles — the picker recently gained a deselect gesture: clicking the selected tile clears it, storing "none". That raised a fair question: if "none" is now a reachable state, isn't the separate enable switch redundant? Deselect the transition → no transition → effectively off.

Options considered​

• Remove the enable switch; treat "no image selected" as off. Fewer controls, one less thing to reason about, and "none" becomes a first-class member of the choice set. But it overloads the picker with two jobs — which variant and whether the feature runs at all — and only works for features that actually have an image to deselect.
• Keep the enable switch as the master on/off; deselect stays a "clear my choice" escape hatch. One extra control per feature, but enablement and variant-choice stay orthogonal, and every feature in the tab toggles the same way.
• Keep the switch, and for features where "none" is genuinely first-class, add an explicit "None" tile rather than leaning on the subtle deselect gesture. Best of both where it applies, without changing the enable model.

Decision​

Keep the enable switches. Deselect is treated as what it's best at — a "none / clear" option within the choice — not as the feature's on/off. Where "none" is a natural first-class member of a picker's set, we prefer adding an explicit None tile over repurposing the deselect gesture, but the master switch stays either way.

Why​

• They answer different questions. The switch is "is this feature active at all?"; the picker is "which variant?" An image-picker with nothing selected means "enabled, but no transition chosen" — an in-between state, not a clean off. The switch says off unambiguously.
• Deselect discards the user's choice. With a switch you can disable Page Transitions while keeping "Zoom" selected, then re-enable later with Zoom intact. If off means "no image selected", disabling wipes the configured variant and re-enabling forces a re-pick. Keeping enablement orthogonal to the choice is the more forgiving model.
• Consistency across the tab. Most Site-wide UX features have an enable switch but no deselectable image — Smooth Scroll (sliders), Dark Mode (a mode select), Scroll Progress (a color). Removing the switch only where there's an image picker splits the tab into two mental models: some features toggle via a switch, others via a "clear the tile" gesture. Uniform switches are easier to learn.
• Discoverability. "Enable page transitions: YES/NO" is obvious at a glance; "clear the image to disable" is a hidden affordance most users won't find. Deselect is a good escape hatch, not a good primary control.
• Default direction. The switch lets a feature ship off by default while still offering a sensible preselected tile (Fade) once enabled. Without the switch you either default the feature on (a tile is preselected) or present an empty, uninviting picker.

Status​

Accepted — no code change; this ratifies the existing pattern and rules out the "deselect replaces the switch" simplification.