Skip to content

CONCEPT Cited by 1 source

Visual-equivalence mapping

Definition

Visual-equivalence mapping is the human-authored correspondence between two UI-component-library attributes that assigns a source value to the target value producing the same rendered appearance — not necessarily the target value with the same name. Two libraries can use the same attribute key (size) and the same value ("medium") to mean visually different things; the mapping encodes the visual semantics a source-code-only transformation cannot see.

The failure mode this concept names

Zalando's iteration-3 experiment handed the LLM an auto-generated attribute mapping and let it emit transforms. Characteristic failure:

"For the button component, LLM created direct size mappings (converting 'medium' sized button to 'medium'), when in reality, a 'medium' button in the original library was visually equivalent to a 'large' button in the new library." (Source: sources/2025-02-19-zalando-llm-powered-migration-of-ui-component-libraries)

The LLM sees size="medium" in both libraries and picks the obvious identity mapping. A human who has rendered both components sees that the new library's "medium" is visually smaller — the correct mapping is "medium" → "large".

The three reasons source code cannot reveal this

Zalando names them explicitly:

  1. "Source code cannot reveal all information, e.g. design intent or visual relationships."
  2. "The LLM couldn't visualize how components are rendered."
  3. "Different libraries implement similar concepts (like 'medium' size) differently."

Reason 1 is general (design intent lives in designer heads, not in the code). Reason 2 is tractable for multi-modal models that can see rendered screenshots (e.g. GPT-4o with image input); Zalando did not use that modality. Reason 3 is the convention mismatch problem — the libraries' naming conventions are superficially compatible but semantically divergent.

The remediation

Human pair programmers + designers produced the mapping. In Zalando's iteration-4 experiment:

"To handle the issues in the above iteration, we included manual verification of the prompts, for example, fixing the size mapping if they were not accurate."

The mapping becomes a frozen, authoritative artefact that rides in the prompt's mapping layer (see concepts/prompt-interface-mapping-examples-composition) and the regression tests. Once authored, it's reusable across every file in the migration.

Where visual equivalence matters beyond size

  • Colours. Tokens named "primary", "accent", "warning" map differently between libraries' palettes.
  • Spacing scales. Libraries with different spacing units (4px grid vs 8px grid) require non-trivial mappings.
  • Grid columns. 12-column → 24-column migrations have no unique mapping; rounding up breaks into two lines, rounding down leaves whitespace. Zalando names this explicitly — it's the class of case where visual equivalence is undefined and human judgement per-site is required.
  • Typography. Size tokens, line-height, font-weight rarely align by name between libraries.

Relation to sibling primitives

  • vs patterns/visual-parity-screenshot-gate: the Zalando's Paparazzi / Instacart visual-parity gate runs after the code transformation to catch visual regressions. Visual-equivalence mapping operates before — encoding the visual correspondence into the prompt itself so the transformation is visually correct by construction rather than caught post-hoc. Complementary: mapping prevents known wrong transforms; screenshot gates catch unknown ones.
  • vs multi-modal LLMs with vision. A VLM could in principle see the rendered components and infer the mapping directly. Zalando did not try this — the mapping was produced by humans. An open question: would VLM-driven mapping inference match human accuracy?
  • vs concepts/source-code-as-agent-feedback-loop: that concept is about the agent learning from merged source code. Visual-equivalence mapping is the dual — information the agent cannot learn from source code and must receive from a different channel (humans with design intent).

Seen in

Last updated · 501 distilled / 1,218 read