Beyond Responsive Design: My Journey into Tamagui

For years, the promise of "Write Once, Run Anywhere" felt like a recurring fever dream. We’ve all been there: you build a beautiful UI in React Native for mobile, then spend the next three weeks fighting CSS media queries and DOM-specific behaviors to make it look decent on a 27-inch monitor using Next.js.

I’ve tried them all—NativeWind, styled-components, plain old StyleSheet. Each had a breaking point. NativeWind gets you close, but the DX often feels like fighting the tool rather than building the product. Then I found Tamagui.

If you're building in the Expo and Next.js ecosystem, Tamagui isn't just another UI kit; it’s a paradigm shift in how we handle the unified design system. Here is what I’ve learned about mastering it.

The Problem: The "Lowest Common Denominator" Trap

In the past, sharing styles between Expo (Native) and Next.js (Web) meant either:

1. Over-relying on JavaScript styles, which kills web performance (no SSR-friendly CSS).
2. Maintaining two separate UI libraries, which kills developer productivity.

Tamagui solves this by being a compiler first. It takes your high-level styling code and transforms it into optimized atomic CSS for the web, while keeping it as high-performance JSI-based styles for native.

1. The Power of Shorthands and Tokens

One of my biggest breakthroughs was realizing how much cognitive load is reduced when your design system is baked into the props. In my setup, I define a strict token system for spacing, colors, and sizing.

// tamagui.config.ts snippet
const tokens = createTokens({
  size: { sm: 30, md: 50, lg: 80 },
  space: { sm: 10, md: 20, lg: 40 },
  color: {
    primary: '#0070f3',
    background: '#ffffff',
  },
  // ...
})

Once this is set, I can stop thinking about pixels. I’m thinking in systems. The Shorthands feature allows me to write px="$md" instead of paddingHorizontal: 20. It sounds small, but in a large-scale project, this consistency is what prevents "UI drift."

2. Real-World Adaptive Components

Responsive design is usually just about layout (Flexbox wrapping). Unified design is about behavior. Take a Modal, for example. On a mobile device (Expo), you probably want a bottom-sheet. On a desktop (Next.js), you want a centered dialog.

Tamagui’s Adapt component is the secret sauce. I’ve used it to build complex navigation that feels native to each platform without writing a single if (Platform.OS === 'web') block.

import { Sheet, Dialog, Adapt } from 'tamagui'

export const MyAdaptiveDialog = () => (
  <Dialog modal>
    <Dialog.Trigger>Open UI</Dialog.Trigger>
    
    {/* On small screens, turn this dialog into a Sheet! */}
    <Adapt when="sm" platform="touch">
      <Sheet dismissOnSnapToBottom>
        <Sheet.Frame>
          <Sheet.Contents />
        </Sheet.Frame>
      </Sheet>
    </Adapt>

    <Dialog.Portal>
       <Dialog.Content>
          <Dialog.Title>Settings</Dialog.Title>
          {/* Content */}
       </Dialog.Content>
    </Dialog.Portal>
  </Dialog>
)

3. Mastering the Compiler for Next.js

One of the biggest hurdles I faced initially was getting the Next.js performance right. Tamagui's @tamagui/next-plugin is essential here. It extracts your styles into static CSS files during the build process.

In my experience, the mistake most devs make is not enabling the compiler in development. While it's slower to hot-reload, it ensures that what you see in the browser is exactly what will be shipped in the optimized production CSS. This eliminates the dreaded "Hydration Mismatch" errors that plague many React Native Web implementations.

4. The Performance Edge: Static Extraction

Why does this matter? On the web, Tamagui transforms this:

<Stack padding="$4" backgroundColor="$primary" hoverStyle={{ scale: 1.1 }} />

Into this (roughly):

<div class="_pd_16px _bg_blue _hover_scale_1_1"></div>

There is zero runtime overhead for those styles. On the mobile side, it stays as optimized View props. This is the first time I’ve felt like I’m not trading off web Lighthouse scores for mobile fluidity.

Lessons from the Trenches

If you're just starting with Tamagui in an Expo/Next.js monorepo (like Solito), here are my three golden rules:

1. Strict Typing is your friend. Use the TamaguiCustomConfig to ensure your components only accept your defined tokens. It stops the team from using "magic numbers."
2. Lean into the Themes. Tamagui’s nesting themes allow you to change an entire section of your app from light to dark or corporate to playful by wrapping it in a single <Theme name="dark"> provider.
3. Don't over-abstract. I spent too much time trying to wrap Tamagui components into my own custom wrappers. Tamagui is your design system foundation. Use it directly and only abstract when you have repeated complex logic.

Final Thoughts

Moving beyond simple responsive design means building apps that respect the medium they live in. By leveraging Tamagui with Expo and Next.js, we finally have the tools to build a unified design system that doesn't feel like a compromise. It’s technical, it has a learning curve, but the result—a single source of truth for your UI—is worth every hour spent in the config file.

Happy coding, colleagues. Let’s build something performant.