# 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:

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

## Example

```html
<!-- 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>
```