How Thunderbolt Handles Responsive Sizing for Mobile and Desktop Devices

Thunderbolt uses a hybrid approach combining Tailwind CSS utility classes with custom CSS variables that automatically switch values at the 768px breakpoint to optimize touch targets, typography, and spacing across devices.

The thunderbird/thunderbolt repository implements a sophisticated responsive sizing system that bridges the gap between mobile-first design and desktop optimization. By leveraging CSS custom properties defined in the root stylesheet, components automatically adapt their dimensions without requiring duplicate media queries in every file.

The Hybrid Approach to Responsive Sizing

Thunderbolt’s system relies on a dual-layer architecture: CSS variables provide the responsive foundation, while Tailwind utilities offer convenient access to those values. This separation ensures consistent sizing logic across the entire application while maintaining the flexibility of utility-first CSS.

Mobile Defaults in the Root Variables

In src/index.css, the :root selector establishes baseline values optimized for mobile screens (≤ 768 px). These variables define touch-target heights, icon sizes, font sizes, and border radii that meet accessibility guidelines for finger-based interaction.

:root {
  /* Touch-target heights */
  --touch-height-default: 2.75rem;   /* 44 px mobile */
  --touch-height-sm: 2.5rem;        /* 40 px mobile */
  
  /* Icon sizes */
  --icon-size-default: 1.25rem;    /* 20 px mobile */
  
  /* Font sizes */
  --font-size-body: 1rem;          /* 16 px mobile */
  
  /* Border radius */
  --radius-sm: 0.25rem;            /* 4 px mobile */
}

Source: src/index.css lines 49‑70

Desktop Overrides via Media Queries

A single media query at the 768px breakpoint redefines these variables with values appropriate for desktop layouts. Since components reference the variable names rather than static values, the entire UI automatically adjusts when the viewport crosses the threshold.

@media (min-width: 768px) {
  :root {
    --touch-height-default: 2.25rem;   /* 36 px desktop */
    --icon-size-default: 1rem;         /* 16 px desktop */
    --font-size-body: 0.875rem;        /* 14 px desktop */
    --radius-sm: 0.125rem;             /* 2 px desktop */
  }
}

Source: src/index.css lines 82‑104

Integrating Tailwind CSS with Custom Variables

The project documentation in AGENTS.md specifies two methods for accessing these responsive values within the Tailwind framework. This dual approach maximizes developer efficiency while preserving the underlying variable-based responsiveness.

Standard Utility Classes

For properties that map directly to Tailwind’s design system, developers use standard utility classes like rounded-sm, px-2, gap-2, or text-base. The Tailwind configuration maps these utilities to the custom CSS variables, ensuring they inherit the responsive behavior defined in src/index.css.

Source: AGENTS.md section “Responsive Sizing” lines 98‑105

Arbitrary Value Syntax for Custom Dimensions

When Tailwind lacks a built-in utility for specific Thunderbolt dimensions (such as touch heights or icon sizes), the system uses Tailwind’s arbitrary value feature with CSS variable interpolation. This syntax allows direct access to the responsive variables while maintaining the utility-first workflow.

// Button with responsive touch-target height
<button className="
  rounded-md
  bg-primary text-white
  h-[var(--touch-height-default)]
  px-4
  flex items-center justify-center
">
  Click me
</button>

// Icon that scales between mobile (20px) and desktop (16px)
<SvgIcon className="
  size-[var(--icon-size-default)]
  text-muted
" />

// Body text using responsive font sizing
<p className="text-[length:var(--font-size-body)]">
  Responsive typography that shrinks on desktop.
</p>

Source: AGENTS.md lines 106‑110

Practical Implementation Examples

The following patterns demonstrate how Thunderbolt components leverage the responsive sizing system in production code. These examples show the interplay between Tailwind utilities and CSS variables.

Responsive Button Component:

<button className="
  rounded-md
  bg-primary text-white
  h-[var(--touch-height-default)]
  px-4
  flex items-center justify-center
  text-[length:var(--font-size-body)]
">
  Submit
</button>

Adaptive Icon Sizing:

<SvgIcon className="
  size-[var(--icon-size-default)]
  text-muted
" />

Typography Scaling:

<p className="text-[length:var(--font-size-body)]">
  Content automatically adjusts from 16px on mobile to 14px on desktop.
</p>

Summary

• Thunderbolt combines Tailwind CSS with CSS custom properties to achieve responsive sizing across mobile and desktop viewports.
• Mobile defaults are defined in :root within src/index.css, establishing larger touch targets (44px), icons (20px), and fonts (16px) for accessibility.
• Desktop overrides occur at the 768px breakpoint, automatically reducing dimensions to 36px touch heights, 16px icons, and 14px body text.
• Developers can access these values via standard Tailwind utilities or arbitrary value syntax like h-[var(--touch-height-default)].
• Components automatically adapt without media queries in individual files, ensuring consistency across the codebase.

Frequently Asked Questions

What breakpoint does Thunderbolt use for responsive sizing?

Thunderbolt uses a 768px breakpoint (min-width: 768px) to switch between mobile and desktop sizing. This is implemented as a media query in src/index.css that overrides the CSS custom properties defined in the :root selector.

How does Thunderbolt handle touch targets differently on mobile vs desktop?

On mobile, Thunderbolt sets --touch-height-default to 2.75rem (44px) to meet accessibility guidelines for finger-based interaction. On desktop, the same variable reduces to 2.25rem (36px) via the 768px media query, optimizing for mouse precision and denser information display.

Can I use standard Tailwind classes with Thunderbolt's responsive sizing system?

Yes. Thunderbolt encourages using standard Tailwind utilities like rounded-sm, px-2, or gap-2 wherever possible. The Tailwind configuration maps these utilities to the underlying CSS variables, ensuring they inherit the responsive behavior. For custom dimensions not covered by Tailwind, use the arbitrary value syntax with CSS variables.

Where are the responsive sizing variables defined in the codebase?

The responsive sizing variables are defined in src/index.css. Mobile defaults appear in the :root selector (lines 49‑70), while desktop overrides are located in the @media (min-width: 768px) block (lines 82‑104). Documentation for using these variables with Tailwind appears in AGENTS.md (lines 98‑110).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}