surfaces
The Visual Plane
Every boundary between two surfaces gets exactly one separation device: a hairline, a shadow, or a step in background lightness. Never two. Default to the hairline — it is the cheapest, it survives every background behind it, and it is what most "flat" UI actually needed. Promote to a shadow only when the element is meant to read as lifted and has to travel across mixed or image backgrounds. Promote to translucency only when content genuinely passes underneath. Interfaces that look cheap are rarely under-decorated; they are decorated twice, with a border and a shadow and a background tint all arguing the same point.
This skill owns the elevation ladder within one theme. Expressing that ladder as lightness when shadows stop reading against dark backgrounds belongs to dark-mode, which never picks a shadow recipe; this skill never derives a second theme. The choice between a border and a hairline is here; the hairline's exact grey and its device-pixel rendering are ui-polish's.
Read the project's depth system before adding to it. Find where shadows and radii already live — a Tailwind @theme block, :root custom properties, a generated token file, a styled-components theme object — and add a step to that ladder rather than writing a one-off box-shadow at the call site. A codebase with four hand-written shadows has no elevation system; a codebase with four named tokens does. Never introduce a second mechanism to fix one card.
Quick Reference
| You need | Open |
|---|---|
| The exact token values for a tier, or which tier a component gets | references/shadow-recipes.md — load it whenever you are about to write a literal box-shadow or assign elevation to a specific component. |
| Blur, translucency, noise, sheen, and the reduced-transparency fallbacks | references/materials.md — load it the moment backdrop-filter enters the diff, or when a surface is meant to read as a physical material. |
Core Principles
- One separation device per boundary. A card with a
1pxborder and a drop shadow and a lighter background states the same thing three times, and the three disagree at every zoom level. Pick one and delete the others. The single exception is a translucent surface, where the blur and the1pxtop-edge sheen are one material, not two devices.