Spike: PoC Tamagui as the combined primitives + styling choice for #578/#591

[gaidheal1]

Summary

#591 (styling spike) and #579 (primitives spike, #578) were coordinated but answered somewhat independently: #579 recommended @rn-primitives specifically because it's style-agnostic and doesn't force #591's hand. Revisiting that: Tamagui and Gluestack UI are broader kits that solve primitives and styling together, and #591 explicitly says a kit choice in the #578 spike "likely decides this too."

This issue tests Tamagui as that combined choice. A companion spike for Gluestack should follow the same shape before a final decision, since the two kits push the styling answer in different directions (Tamagui ≈ #591's "runtime/compiled style objects with theme" option; Gluestack, being built on NativeWind, ≈ #591's "utility/atomic CSS" option). Scope of #578 and #591 may be merged or resized based on the outcome — that's an accepted possibility, not a scope violation.

Why Tamagui specifically needs its own verification pass

Docs research surfaced numbers and claims that don't fully agree with each other or with #579's own findings, and #579 already caught one research-vs-reality gap (web bundle cost from @rn-primitives, assumed negligible, measured at +84 kB raw). Don't trust the following without a real PoC against this repo's Vite toolchain:

• Bundle size: cited anywhere from ~20 kB gzipped (core, compiler active) to ~180 kB (likely uncompiled/naive import). The gap depends entirely on whether Tamagui's Babel compiler is actually wired into and running in this Vite build — the same class of assumption Spike: choose the cross-platform primitive strategy (and resolve the ds-entry contract) #579's PoC had to correct for react-native-web.
• Accessibility parity: Tamagui's Dialog/Popover are Tamagui's own implementations (credits Radix and Floating UI as influences, uses a shared FocusScope), not literally @radix-ui/react-* on web the way @rn-primitives is. This is a real, unverified parity gap against the current Radix-based app and against Spike: choose the cross-platform primitive strategy (and resolve the ds-entry contract) #579's PoC, which found exact parity by construction.
• Requirement fit: Tamagui's token system (space/size/color/radius/zIndex) and variants API look like a strong match for this app's existing token work (Consolidate the two parallel spacing/variable systems into one token source #590) and apply-button-variant/apply-list-variant, but "looks like a match on paper" is exactly the kind of claim Spike: choose the cross-platform primitive strategy (and resolve the ds-entry contract) #579 disproved once already (the controlled-open-prop assumption).

Scope of the PoC

1. Confirm the Tamagui compiler is actually active in the build (not just the package installed) — inspect the emitted output, not just docs claims.
2. Measure the real production bundle delta (raw + gzip), same methodology Spike: choose the cross-platform primitive strategy (and resolve the ds-entry contract) #579 used: before/after on the index chunk.
3. Port two components, matching Spike: choose the cross-platform styling approach #591's own acceptance criteria:
   • One trivial component (styling only)
   • One exercising apply-text-style + a variant mixin + a breakpoint — the hard case, not the easy one
4. Also swap the underlying primitive on at least one of them — ideally Tooltip again, so this PoC is a direct, apples-to-apples comparison against Spike: choose the cross-platform primitive strategy (and resolve the ds-entry contract) #579's existing @rn-primitives/tooltip PoC (branch claude/rn-primitives-library-4ny4sa) rather than a fresh, unrelated data point.
5. Run the existing Tooltip test suite (5 cases covering click/tap-to-toggle per Unify tap/click tooltip behaviour #568, hover suppression, focus, escape-to-close, aria-describedby) against the Tamagui version and report pass/fail — don't assume parity, verify it.
6. Confirm visual parity against current output (per Spike: choose the cross-platform styling approach #591's acceptance criteria).

Acceptance criteria

• Written findings recorded in .claude/plans/ (matching the format of .claude/plans/issue-579-rn-primitives-library-exploration.md)
• Verified (not cited) bundle size delta for this toolchain, with the compiler confirmed active
• Two components ported end to end per the PoC scope above, on a real branch
• Tooltip test suite run against the Tamagui swap with results reported explicitly (pass/fail per case, not just "tests pass")
• Visual parity confirmed against current output
• Explicit recommendation on whether this supersedes Spike: choose the cross-platform primitive strategy (and resolve the ds-entry contract) #579's @rn-primitives recommendation, and what that means for Epic: Replace Radix UI with cross-platform primitives (RN/Expo migration prep) #578's and Spike: choose the cross-platform styling approach #591's remaining sub-issues (kept separate, merged, or resized)
• Note on whether a companion Gluestack PoC is still warranted given the findings here

Notes

Related: #578, #579, #588, #590, #591. Timebox it the same way #579 and #591 were timeboxed — this is still a spike, not a commitment to adopt Tamagui.

[gaidheal1]

PoC complete on claude/issue-629-fhmqx2. Full writeup in .claude/plans/issue-629-tamagui-poc.md. Summary:

• Confirmed Tamagui's compiler is actually active (not just installed).
• Measured real bundle deltas: wiring the provider alone costs +383 kB raw / +102 kB gzip before any component is ported — roughly 4.5x @rn-primitives' equivalent floor (Spike: choose the cross-platform primitive strategy (and resolve the ds-entry contract) #579). The two ported components + Tooltip swap add only +122 kB/+42 kB more on top.
• Ported OnlineCountBadge (trivial) and Button (hard case: apply-text-style + apply-button-variant + breakpoint). The variant-mixin port held up; the breakpoint did not — the custom media key is present in the compiled config but doesn't apply at runtime for Button, verified against a real production build at two viewport widths, not assumed.
• Swapped Tooltip's primitive to Tamagui's own Tooltip (not Radix) and ran this branch's actual 3-case test suite against it: hover passes; focus-to-open and Escape-to-close both fail (same root cause — focus never opens the tooltip here, even with the documented opt-in set).
• Found a second a11y gap: Tamagui's Button doesn't set the native disabled attribute on disabled, only aria-disabled.
• Visual parity confirmed via an actual rendered screenshot, not inspection alone — colors/shape match closely, corners render very slightly less rounded.

Recommendation: this does not supersede #579's @rn-primitives recommendation — heavier bundle floor, an unresolved breakpoint gap, and two verified a11y gaps outweigh the one real advantage (Tamagui's Tooltip has a controlled open prop natively, unlike @rn-primitives'). A companion Gluestack PoC is still worth doing, since its NativeWind/@react-native-aria architecture is a different bet than either of these.

---

Generated by Claude Code

[gaidheal1]

Follow-up on this PoC's Tooltip focus-to-open finding: dug further per discussion, and it's confirmed as a real upstream bug rather than a test-environment artifact (unlike the earlier $mdUp breakpoint finding, which turned out to be a bug in my own verification, not Tamagui — corrected in the findings doc).

Traced to source: Tamagui's Tooltip builds a focus-aware floating context via useFloatingContext(), but @tamagui/popper's Popper primitive builds its own separate, purely-positional useFloating() instance and resets FloatingOverrideContext to null for its own children — discarding the focus-aware context before it can attach onFocus/onBlur handlers to the trigger. Confirmed by instrumenting the handler directly (never fires on Tab, in a real Chromium browser) and by reading @tamagui/popper's own source: it imports FloatingOverrideContext and writes to it, but never reads it via useContext() anywhere in the file, despite a comment describing that it should.

Filed upstream: tamagui/tamagui#4152, with the full root-cause trace included in the report.

.claude/plans/issue-629-tamagui-poc.md updated with both corrections (breakpoint bug fixed, Tooltip bug confirmed + linked).

---

Generated by Claude Code

[gaidheal1]

Final decision: Tamagui adopted (full — primitives + styling)

Following the follow-up investigations on this PoC (breakpoint false-negative corrected, Tooltip focus bug confirmed and filed as tamagui/tamagui#4152) and a fourth comparison PoC (@shopify/restyle, .claude/plans/issue-restyle-poc.md), the team has decided to adopt full Tamagui — its own primitives and styling system together — as the answer to both #578 and #591.

Decision recorded on #591: #591 (comment)
Coordination notes posted on #578/#579 since this supersedes the earlier @rn-primitives recommendation.

Known open item carried forward: Tooltip's keyboard-focus-to-open gap (#4152) needs a decision (accept/workaround/wait) before that specific sub-issue (#583) can close its a11y criterion.

---

Generated by Claude Code