smooth-shadow-ring

Elevated surfaces: use smooth-shadow-ring, never border + shadow

When this applies

Any element that floats above the page surface: cards, dialogs, modals,

popovers, dropdowns, menus, tooltips, sheets, toasts, command palettes.

The problem

Putting a border-* (or ring-*) and a shadow-* on the same element draws

two stacked edges: the border paints a hard 1px stroke, and the shadow begins

just outside it. The result is a visible double border, a crisp line then a

soft one. It looks heavy, greyed, and cheap.

The rule

If you are about to write a border-* or ring-* class next to any shadow-*

on an elevated surface, use smooth-shadow-ring-{size} instead. It bakes a 1px

hairline ring into the final shadow layer, so the edge dissolves into the shadow

as one continuous stroke.

• border shadow-md → smooth-shadow-ring-md
• ring-1 ring-neutral-200 shadow-lg → smooth-shadow-ring-lg
• Sizes: smooth-shadow-ring-xs, -sm, -md (or bare smooth-shadow-ring), -lg, -xl, -2xl
• Never keep a border or ring on an element that already has

smooth-shadow-ring-*. The ring is already in there; a second edge doubles up.

• If the surface should have no edge stroke at all, use plain

smooth-shadow-{size} (no ring), not a border.

Coloring

The ring and shadow tint independently and compose on the same element:

• shadow-{color} tints the shadow, e.g. shadow-blue-500
• smooth-ring-{color} tints the ring, e.g. smooth-ring-black/10, smooth-ring-blue-500/40

The ring defaults to rgba(0,0,0,0.05) and flips to rgba(255,255,255,0.18)

in dark mode — under a .dark class, data-theme="dark", or (for

OS-preference dark modes) when the page declares color-scheme: light dark.

It never keys off prefers-color-scheme alone, so light-only sites keep the

light ring for every visitor. If the site's dark mode is driven purely by a

prefers-color-scheme media query, make sure it declares

:root { color-scheme: light dark; } so the ring follows.

The dark alpha is much higher than the light one on purpose. The ring paints

outside the surface, so its rendered colour comes from the page behind it, not

from the surface it outlines. A white hairline therefore lightens *toward* a

raised dark surface, and too low an alpha makes the edge land on the surface's

own colour and disappear. If a surface is light enough to sit near the ring

anyway (neutral-700 and up on a dark page), set smooth-ring-* explicitly.

Ring width

The hairline is 1px by default and follows the project's Tailwind ring width

automatically, so a project with @theme { --default-ring-width: 0.5px; } gets

a 0.5px hairline here with no extra setup. Do not hardcode a width to match;

override --smooth-ring-width at any scope only when it must differ from the

project ring width — per element via [--smooth-ring-width:2px].

Overriding

The utilities carry no !important and follow the normal cascade, so a later

utility, an inline style, or a JS animation on box-shadow overrides them

normally. When one has to win against CSS that outranks it — a component

library's own box-shadow, which usually ships unlayered — use Tailwind's

important modifier on that element instead of a global override:

<div class="smooth-shadow-ring-md!">…</div>

Example

<!-- Wrong: border + shadow renders a double edge -->
<div class="rounded-2xl border border-neutral-200 shadow-md">…</div>

<!-- Right: one continuous edge -->
<div class="rounded-2xl smooth-shadow-ring-md">…</div>

<!-- Right: tuned ring + tinted shadow -->
<div class="rounded-2xl smooth-shadow-ring-md smooth-ring-black/10 shadow-blue-500">…</div>