Skip to main content

Search rules

Search all UI Guides rules by name, category, or source

designimpeccable

Hairline Border or Soft Shadow, Not Both

NEVER

NEVER: Pair a visible hairline border with a wide, diffuse shadow — it is a generated-UI signature. The two make contradictory claims: the hairline says the surface has a crisp edge in the plane, the soft shadow says it is floating above the plane with light wrapping its edge, so the border kills the lift and the shadow kills the line. Commit to one — a defined EDGE (crisp hairline, no shadow) or a soft ELEVATION (shadow, no border). The detector fires on >=2 sides at <=1.5px with border alpha >=0.28 while a shadow layer of alpha >=0.12 has blur >=16px: `border shadow-lg` fires, `border shadow-xs` does not. A single layered shadow that INCLUDES its ring (`0 0 0 1px …`, 0 blur) is not this pattern — see `design-layered-shadows`.

Commit a card to a defined edge or to a soft elevation — pairing a 1px border with a wide diffuse shadow is the "every card style I know" tell

Bad

Good

Why it matters

The detector is precise about what counts: at least two sides carrying a VISIBLE hairline (width <= 1.5px with border-color alpha >= 0.28) while the element also has a box-shadow whose largest blur radius is >= 16px, measured only across shadow layers with alpha >= 0.12. So `border shadow-lg` on a card fires it; `border shadow-xs` does not, and neither does a shadow built entirely from near-invisible layers.

The reason it reads as cheap is that the two devices make contradictory claims. A hairline says "this surface has a crisp, defined boundary and sits in the plane." A wide diffuse shadow says "this surface is floating above the plane, and its edge is soft because light wraps around it." Ship both and the edge fights the lift: the border stops the shadow from selling elevation, and the shadow stops the border from reading as a deliberate line.

Pick one and mean it — a crisp hairline with no shadow (flat, precise, editorial), or a soft shadow with no border (lifted, tactile). Note the one legitimate exception, which is not this pattern: a shadow that INCLUDES its hairline as a 0-blur ring layer (`0 0 0 1px …`) is a single layered shadow, not a border plus a shadow — see design-layered-shadows.

Built by Gleb Stroganov, design engineer at Evil Martians.

The rules come from other people's skills and guidelines — Vercel, Rauno Freiberg, @Ibelick, impeccable, Emil Kowalski, Tailwind, RAMS — each one credited on the Sources page. The work here is extraction and wiring: every rule is pulled into one corpus, given a good and a bad example you can operate, a MUST/SHOULD/NEVER rule an agent can paste, and a link back to where it came from.