Skip to main content

A converter option is “unmapped” — is that a bug to fix or a default to keep?

· 3 min read
Jon-Michael Lastimosa
Jon-Michael Lastimosa
Senior Web Developer

The question: The Element Mapping tables classify every shortcode option as native / via-CSS / unmapped. Accordion showed 18 unmapped — which looks like the converter is failing. Is a high unmapped count a problem to drive to zero? Should we hand-author “pre-mapping” data, or do we need a pile of real sites to map everything properly?

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.