Your Cross-Platform UI Isn’t “Parity”—It’s Drift With Matching Pixels

Most cross-platform “component parity” efforts fail in the same boring way: the visuals match, the behavior doesn’t. The web version blocks double-submits, keyboard interaction is clean, and screen readers announce the right state. The native version looks identical but still fires while “disabled,” announces nothing when it enters a busy state, and has focus behavior that feels like an improvised jazz solo (and not the good kind). This isn’t because people are careless. It’s because the team accidentally agreed on the wrong unit of truth. If the “spec” for a component is basically “here are the props,” you have not specified a component. You’ve specified a shape and left the meaning to each implementation. Meaning is where drift lives. shape meaning Contract-first components fix that by treating a component as a small, testable system with guarantees: API, events, state transitions, invariants, accessibility semantics, i18n behavior, and performance constraints. You write those down, test them, and then let each platform adapter translate inputs/outputs without inventing new behavior. TL;DR Props-only design drifts because critical behavior lives in event semantics, state transitions, focus rules, and accessibility—not in prop types.A component contract defines: API, events, state model, invariants, accessibility guarantees, i18n rules, and performance expectations.Implement the contract once in a platform-agnostic core (state machine + semantics), then render via thin adapters.Test contracts with state-machine tests (transitions + invariants) plus accessibility assertions (role/name/state/focus guarantees).Adapters translate IO and semantics to platform primitives; they must not re-implement behavior.Version the contract: breaking changes include behavior, event ordering, defaults, and accessibility guarantees—not just type changes. Props-only design drifts because critical behavior lives in event semantics, state transitions, focus rules, and accessibility—not in prop types. A component contract defines: API, events, state model, invariants, accessibility guarantees, i18n rules, and performance expectations. Implement the contract once in a platform-agnostic core (state machine + semantics), then render via thin adapters. Test contracts with state-machine tests (transitions + invariants) plus accessibility assertions (role/name/state/focus guarantees). Adapters translate IO and semantics to platform primitives; they must not re-implement behavior. Version the contract: breaking changes include behavior, event ordering, defaults, and accessibility guarantees—not just type changes. 1. Why “Props-Only” Thinking Creates Drift Across Platforms Props are inputs. Real components are interactive systems. Even a “simple” button has: Event semantics: When does activation happen? Pointer up or down? Key down or key up? What about long-press, repeat, or gesture cancellation?State: Idle, pressed, focused, pending, error, success, toggled, expanded…Invariants: “Disabled means inert,” “busy means no duplicate commits,” “focus must be visible with keyboard/remote.”Accessibility semantics: role, accessible name, disabled/busy/expanded state exposure, announcements, focus order, and interaction modalities.i18n behavior: RTL layout, long labels, truncation rules, pluralization and formatting ownership.Performance constraints: measurement frequency, layout thrash avoidance, stable renders, bounded expensive work. Event semantics: When does activation happen? Pointer up or down? Key down or key up? What about long-press, repeat, or gesture cancellation? Event semantics: State: Idle, pressed, focused, pending, error, success, toggled, expanded… State: Invariants: “Disabled means inert,” “busy means no duplicate commits,” “focus must be visible with keyboard/remote.” Invariants: Accessibility semantics: role, accessible name, disabled/busy/expanded state exposure, announcements, focus order, and interaction modalities. Accessibility semantics: i18n behavior: RTL layout, long labels, truncation rules, pluralization and formatting ownership. i18n behavior: Performance constraints: measurement frequency, layout thrash avoidance, stable renders, bounded expensive work. Performance constraints: If you only define props, you’ve defined a configuration surface, not a behavioral contract. Each platform team fills in the blanks differently, often reasonably, and the component slowly becomes multiple incompatible components that happen to share a name. configuration surface behavioral contract Drift doesn’t show up as a compile error. It shows up as: “It works on web but not on native.”“It’s accessible on desktop but not on TV.”“It’s fine until latency is high.”“It breaks in RTL.”“It double-submits if you tap fast.” “It works on web but not on native.” “It’s accessible on desktop but not on TV.” “It’s fine until latency is high.” “It breaks in RTL.” “It double-submits if you tap fast.” Contract-first is how you stop debugging the same conceptual component multiple times. 2. What a Component Contract Actually Is A component contract is a written and testable description of what the component means and what it guarantees, independent of how it renders on any specific platform. component contract means guarantees Think of it like an API contract for UI behavior. The contract should cover: API (Inputs): props, slots/children, theming hooks, optional imperative methods (with strict constraints).Events (Outputs): event names, payloads, ordering, exactly when they fire, and when they must never fire.State model: states, transitions, derived flags, and how async influences state.Invariants: rules that must always hold (including timing rules like “single-fire per gesture”).Accessibility guarantees: role, accessible name computation, states exposed (disabled/busy/expanded/checked), focusability rules, and announcements.i18n rules: text ownership, formatting boundaries, RTL expectations, truncation/wrapping behavior.Performance expectations: render stability, measurement frequency, and “no expensive work on hot paths” constraints.Adapter boundary: what platform adapters are responsible for and what they are forbidden from doing.Versioning rules: what counts as breaking, including behavioral and accessibility changes. API (Inputs): props, slots/children, theming hooks, optional imperative methods (with strict constraints). API (Inputs): Events (Outputs): event names, payloads, ordering, exactly when they fire, and when they must never fire. Events (Outputs): never State model: states, transitions, derived flags, and how async influences state. State model: Invariants: rules that must always hold (including timing rules like “single-fire per gesture”). Invariants: Accessibility guarantees: role, accessible name computation, states exposed (disabled/busy/expanded/checked), focusability rules, and announcements. Accessibility guarantees: i18n rules: text ownership, formatting boundaries, RTL expectations, truncation/wrapping behavior. i18n rules: Performance expectations: render stability, measurement frequency, and “no expensive work on hot paths” constraints. Performance expectations: Adapter boundary: what platform adapters are responsible for and what they are forbidden from doing. Adapter boundary: Versioning rules: what counts as breaking, including behavioral and accessibility changes. Versioning rules: If you can’t test it, it’s not a guarantee. It might still be a goal, but label it honestly. 3. The Contract Template (A Reusable Spec You Can Paste Into a Repo) A contract only works if it’s easy to write and hard to misinterpret. Here’s a template you can reuse verbatim for any interactive component: +----------------------------------------------------------------------------------+ | COMPONENT CONTRACT: | +----------------------------------------------------------------------------------+ | Purpose | | - Primary user problem it solves | | - Non-goals (what it explicitly does NOT do) | | | | API (Inputs) | | - Props: | | - Children/slots: | | - Imperative handle (optional): | | | | Events (Outputs) | | - onX(payload): when it fires, ordering guarantees, dedupe/idempotency rules | | - Must NOT fire when: | | | | State Model | | - States: | | - Transitions: next state> | | - Derived flags: | | | | Invariants | | - Always-true rules (e.g., "disabled => no activation") | | - Timing rules (e.g., "single-fire per gesture") | | - Consistency rules (e.g., "busy => exposed as busy to assistive tech") | | | | Accessibility Guarantees | | - Role: | | - Accessible name: | | - States exposed: | | - Focus: | | - Announcements: | | | | i18n Guarantees | | - Text ownership boundaries (no string concatenation inside component) | | - RTL rules, truncation, wrapping behavior | | | | Performance Expectations | | - Render stability expectations (memoization boundaries) | | - Measurement/layout constraints (when measurement is allowed) | | | | Adapters | | - Responsible for: IO translation, semantics mapping, pixels/layout | | - Must NOT: re-implement state transitions or business rules | | | | Versioning Notes | | - Breaking vs non-breaking changes for this contract | +----------------------------------------------------------------------------------+ A contract only works if it’s easy to write and hard to misinterpret. Here’s a template you can reuse verbatim for any interactive component: +----------------------------------------------------------------------------------+ | COMPONENT CONTRACT: | +----------------------------------------------------------------------------------+ | Purpose | | - Primary user problem it solves | | - Non-goals (what it explicitly does NOT do) | | | | API (Inputs) | | - Props: | | - Children/slots: | | - Imperative handle (optional): | | | | Events (Outputs) | | - onX(payload): when it fires, ordering guarantees, dedupe/idempotency rules | | - Must NOT fire when: | | | | State Model | | - States: | | - Transitions: next state> | | - Derived flags: | | | | Invariants | | - Always-true rules (e.g., "disabled => no activation") | | - Timing rules (e.g., "single-fire per gesture") | | - Consistency rules (e.g., "busy => exposed as busy to assistive tech") | | | | Accessibility Guarantees | | - Role: | | - Accessible name: | | - States exposed: | | - Focus: | | - Announcements: | | | | i18n Guarantees | | - Text ownership boundaries (no string concatenation inside component) | | - RTL rules, truncation, wrapping behavior | | | | Performance Expectations | | - Render stability expectations (memoization boundaries) | | - Measurement/layout constraints (when measurement is allowed) | | | | Adapters | | - Responsible for: IO translation, semantics mapping, pixels/layout | | - Must NOT: re-implement state transitions or business rules | | | | Versioning Notes | | - Breaking vs non-breaking changes for this contract | +----------------------------------------------------------------------------------+ This is not “extra documentation.” This is the thing you can point to when a platform diverges and someone says, “But it’s not in the API.” 4. Core vs Adapter: One Behavioral Truth, Many Renderers Once you commit to a contract, the architecture becomes clearer and calmer. The core implements the contract’s behavior: state transitions, invariants, and the semantic model (including accessibility semantics).The adapter renders pixels and translates platform-specific inputs/outputs to/from the core. The core implements the contract’s behavior: state transitions, invariants, and the semantic model (including accessibility semantics). core The adapter renders pixels and translates platform-specific inputs/outputs to/from the core. adapter If adapters decide behavior (“native needs a special rule”), drift comes back immediately. The core must be the only place where behavioral truth lives. Here’s the split: Platform IO Contract Core Platform UI +---------------------+ +------------------------------+ +---------------------+ | pointer / touch | events | state machine + invariants | viewModel | DOM / Native views | | keyboard / remote +---------->| event ordering + dedupe rules |---------->| layout + styling | | assistive tech | | semantics: role/name/state | | platform a11y props | +---------------------+ +------------------------------+ +---------------------+ ^ | | | | NO platform APIs | NO pixels/layout | NO direct DOM/native refs | Adapter translates: - input events -> contract events - contract semantics -> platform attributes/props - pixels/layout -> platform primitives Platform IO Contract Core Platform UI +---------------------+ +------------------------------+ +---------------------+ | pointer / touch | events | state machine + invariants | viewModel | DOM / Native views | | keyboard / remote +---------->| event ordering + dedupe rules |---------->| layout + styling | | assistive tech | | semantics: role/name/state | | platform a11y props | +---------------------+ +------------------------------+ +---------------------+ ^ | | | | NO platform APIs | NO pixels/layout | NO direct DOM/native refs | Adapter translates: - input events -> contract events - contract semantics -> platform attributes/props - pixels/layout -> platform primitives A useful mantra for code reviews: Core decides behavior. Adapter decides pixels. Core decides behavior. Adapter decides pixels. If someone adds a behavioral “if” statement in an adapter, it should feel suspicious by default. 5. Designing the Core: State Model, Events, and Invariants Contracts become real when you encode them as a state machine (or reducer) plus a semantic view model. Even if you don’t use a state-machine library, you can implement the same discipline with a pure transition function. A common drift magnet is an async action component (submit, save, purchase, follow, etc.). Contracts for these typically want: Disabled means inert (no activation, no async start).Pending means deduped (single-fire) and exposed as busy.Errors are surfaced consistently and accessibly.Event ordering is deterministic. Disabled means inert (no activation, no async start). Pending means deduped (single-fire) and exposed as busy. Errors are surfaced consistently and accessibly. Event ordering is deterministic. Here’s a minimal contract-first core with tests for transitions, invariants, and accessibility semantics: // Contract types (portable) type PressSource = "pointer" | "keyboard" | "assistive";

type ActionState = | { tag: "idle" } | { tag: "pending"; startedAt: number } | { tag: "success"; settledAt: number } | { tag: "error"; message: string; settledAt: number };

type ActionEvent = | { type: "PRESS"; source: PressSource; now: number } | { type: "RESOLVE"; now: number } | { type: "REJECT"; message: string; now: number } | { type: "RESET" };

type ActionProps = { label: string; // accessible name source disabled?: boolean; // invariant: disabled => ignore PRESS onCommit: () => Promise ; // adapter initiates side-effect based on core transition announceOnError?: boolean; };

// Semantic output for adapters to map to platform a11y + UI type ViewModel = { label: string; isDisabled: boolean; isBusy: boolean; a11y: { role: "button"; name: string; disabled: boolean; busy: boolean; liveMessage?: string; // optional: polite announcement text }; };

function computeViewModel(state: ActionState, props: ActionProps): ViewModel { const isBusy = state.tag === "pending"; const isDisabled = !!props.disabled || isBusy; // contract choice: busy implies disabled

return { label: props.label, isDisabled, isBusy, a11y: { role: "button", name: props.label, disabled: isDisabled, busy: isBusy, liveMessage: props.announceOnError && state.tag === "error" ? state.message : undefined, }, }; }

// Pure transition function: behavioral truth lives here. function transition(state: ActionState, event: ActionEvent, props: ActionProps): ActionState { const blocked = !!props.disabled || state.tag === "pending";

// Invariant: disabled or pending => ignore PRESS (no activation, no duplicates) if (event.type === "PRESS" && blocked) return state;

switch (state.tag) { case "idle": if (event.type === "PRESS") return { tag: "pending", startedAt: event.now }; return state;

case "pending": if (event.type === "RESOLVE") return { tag: "success", settledAt: event.now }; if (event.type === "REJECT") return { tag: "error", message: event.message, settledAt: event.now }; return state;

case "success": case "error": if (event.type === "RESET") return { tag: "idle" }; return state; } }

// Contract tests: transitions + invariants + a11y semantics describe("ActionButton contract", () => { const base: ActionProps = { label: "Save", onCommit: async () => {} };

it("ignores PRESS when disabled", () => { const props = { ...base, disabled: true }; const s0: ActionState = { tag: "idle" }; const s1 = transition(s0, { type: "PRESS", source: "pointer", now: 1 }, props); expect(s1).toEqual(s0); });

it("dedupes PRESS while pending", () => { const props = base; const s0: ActionState = { tag: "idle" }; const s1 = transition(s0, { type: "PRESS", source: "keyboard", now: 1 }, props); expect(s1.tag).toBe("pending");

const s2 = transition(s1, { type: "PRESS", source: "pointer", now: 2 }, props); expect(s2).toBe(s1); });

it("exposes busy + disabled semantics while pending", () => { const props = base; const pending: ActionState = { tag: "pending", startedAt: 10 }; const vm = computeViewModel(pending, props);

expect(vm.a11y.role).toBe("button"); expect(vm.a11y.name).toBe("Save"); expect(vm.a11y.busy).toBe(true); expect(vm.a11y.disabled).toBe(true); }); }); // Contract types (portable) type PressSource = "pointer" | "keyboard" | "assistive";