Related PR: #19921

That PR was closed because this is a significant API addition and should be discussed before implementation. Opening this discussion to agree on the right shape before sending another PR.

Problem

Tailwind has great primitives for spacing, inset positioning, scroll padding/margin, and modern viewport units like dvh/svh/lvh, but it does not currently have a first-class way to use the platform safe-area insets:

env(safe-area-inset-top)
env(safe-area-inset-right)
env(safe-area-inset-bottom)
env(safe-area-inset-left)

Those values are necessary when a web UI is allowed to use the full device viewport. This affects:

• installed PWAs using display: fullscreen or app-like standalone display modes
• iOS/Safari layouts using viewport-fit=cover
• Capacitor, Cordova, Ionic, and other native shells where the WebView can render under the status bar, navigation bar, notch, camera cutout, or home indicator
• Android edge-to-edge apps where system bars overlay the WebView

Without safe-area utilities, Tailwind users have to repeatedly write custom CSS or install a larger UI library/plugin only to get a small set of layout primitives. Libraries like Ionic/Konsta-style mobile UI kits commonly include safe-area helpers because the problem is not component-specific; it is a viewport layout primitive.

Why this matters in practice

In a fullscreen WebView or PWA, regular Tailwind utilities can place UI behind unsafe screen areas:

<header class="fixed top-0 inset-x-0 h-14 px-4">
  ...
</header>

<main class="h-dvh overflow-y-auto">
  ...
</main>

<footer class="fixed bottom-0 inset-x-0 h-16 px-4">
  ...
</footer>

On devices with notches, rounded corners, system gesture areas, or overlaid status/navigation bars, this often needs extra CSS:

.pt-safe {
  padding-top: env(safe-area-inset-top);
}

.pb-safe {
  padding-bottom: env(safe-area-inset-bottom);
}

.h-dvh-safe {
  height: calc(100dvh - (env(safe-area-inset-top) + env(safe-area-inset-bottom)));
}

The need is even stronger when an element already has design spacing and also needs the safe inset:

<header class="pt-safe-4 px-safe-4">
  ...
</header>

Expected output could be:

.pt-safe-4 {
  padding-top: calc(env(safe-area-inset-top) + var(--spacing-4));
}

.px-safe-4 {
  padding-left: calc(env(safe-area-inset-left) + var(--spacing-4));
  padding-right: calc(env(safe-area-inset-right) + var(--spacing-4));
}

This is awkward to maintain manually across padding, margin, inset, scroll-padding, scroll-margin, height, and width utilities.

Existing demand

This has come up several times already:

• Built in support for safe-area-inset env variables #5396
• "safe" modifier safe-area-inset-* for iOS and other non-rectangular devices #12536
• Built in safe-area utilities #16938
• Add margin, padding and inset safe area utilities #6366
• Add safe area utilities for mobile app usage #19921

The web platform also treats this as a standard CSS environment value, not a framework-specific workaround:

• MDN env() / safe-area inset docs: https://developer.mozilla.org/en-US/docs/Web/CSS/env
• WebKit viewport-fit=cover / safe-area guidance: https://webkit.org/blog/7929/designing-websites-for-iphone-x/
• MDN PWA display modes: https://developer.mozilla.org/docs/Web/Progressive_web_apps/Manifest/Reference/display
• Capacitor status bar / WebView overlay behavior: https://capacitorjs.com/docs/apis/status-bar

Possible API

I am not attached to the exact naming from the PR, but this is the shape I think would cover the real use cases while staying Tailwind-like.

Direct safe-area spacing

<div class="pt-safe pb-safe px-safe">
<div class="m-safe mt-safe mb-safe">
<div class="scroll-pt-safe scroll-pb-safe">

These would map directly to the relevant env(safe-area-inset-*) value.

Safe-area plus theme spacing

<div class="pt-safe-4 pb-safe-6 px-safe-4">

This would mean "safe inset plus the normal Tailwind spacing value", for example:

padding-top: calc(env(safe-area-inset-top) + var(--spacing-4));

This is the most common app-shell case: preserve normal design spacing, then add the device inset only when it exists.

Safe viewport sizes

<main class="h-dvh-safe min-h-dvh-safe">
<aside class="w-dvw-safe">

Vertical safe sizes subtract top/bottom safe areas. Width variants are useful in landscape where safe areas are on the left/right edges:

height: calc(100dvh - (env(safe-area-inset-top) + env(safe-area-inset-bottom)));
width: calc(100dvw - (env(safe-area-inset-left) + env(safe-area-inset-right)));

Optional reset/scope utilities

If the implementation uses internal custom properties, reset utilities could make component subtrees easier to control:

<div class="safe-none">
<div class="safe-x-none">
<div class="safe-b-none">

This part is optional, but it helps when a root app shell consumes the safe area and nested components should not double-apply it.

Questions for maintainers

1. Is this feature appropriate for core, given that Tailwind already includes viewport-unit utilities and scroll padding/margin utilities?
2. Should the API be direct utilities like pt-safe / pt-safe-4, or a modifier-like shape such as safe:pt-4?
3. For combined spacing, should the math be calc(env(...) + spacing) by default, or should there also be a max(env(...), spacing) form?
4. Should the first version be limited to padding/inset/viewport sizes to keep scope small, then expand to margin and scroll utilities later?
5. How should Tailwind handle physical vs logical axes here? The platform exposes physical safe-area values (left/right), but Tailwind also has logical spacing utilities (ps/pe).

If maintainers agree on the API direction, I am happy to adapt the closed implementation from #19921 into a smaller PR that matches the chosen shape.