Preview fidelity
Preview fidelity means that the design environment and generated application interpret the same model decisions. It does not require them to share every rendering implementation, but meaningful differences must be treated as defects or declared limitations.
The fidelity contract
Section titled “The fidelity contract”For a given revision, preview and generation should agree on:
- surfaces, shell, navigation, and home view;
- view pattern and composition;
- visible fields and their order;
- available actions and their placement;
- actor-specific visibility;
- design tokens and component character;
- empty, loading, denied, and failure states.
The generated application adds real API, persistence, and runtime behavior. A schematic preview may use representative data, but it cannot invent a different product structure.
Sources of drift
Section titled “Sources of drift”Common causes include:
- duplicate pattern catalogs in preview and generator;
- design tokens resolved independently;
- preview reading canvas-local data instead of the model;
- generated routes inferred from names while preview uses explicit bindings;
- unsupported pattern details silently falling back;
- a stale experience blueprint rendered as current.
Verification
Section titled “Verification”Test fidelity using semantic fixtures that exercise each pattern and action shape. Compare observable decisions, not brittle pixels alone:
- same route and navigation order;
- same columns, slots, and field labels;
- same permission-conditioned actions;
- same token values;
- same empty and error intent.
Visual regression tests can then protect renderer details.
When a target cannot match
Section titled “When a target cannot match”If a generator target does not support a modeled construct, target preflight should block or clearly report the degradation before delivery. Silent substitution weakens the model’s authority.
Preview data
Section titled “Preview data”Use representative data shapes and volumes. A table with three perfect rows will not reveal pagination, overflow, long labels, localization, or performance behavior. Include empty, sparse, dense, invalid, and permission-limited cases.
Preview is strongest when it lets a stakeholder validate product decisions before promotion—not when it merely makes generation feel complete.
Continue with Preview and deliver or Health and validation.