Neumorphism in CSS: Soft UI Shadows That Work

Neumorphism — soft UI — makes a control look as though it has been pressed up out of the surface behind it, or pushed down into it. Unlike most shadow styles, the element and its background are the same colour. Nothing is layered on top of anything; the form comes entirely from light.

The whole technique is one rule applied twice:

• A dark shadow offset in the direction light travels away from the source.
• A light shadow offset in the exact opposite direction, by the same distance.

.soft {
  background: #e0e5ec;
  border-radius: 18px;
  box-shadow:
    9px 9px 18px #bcc1c8,
    -9px -9px 18px #ffffff;
}

That is a raised surface. Move both shadows inside with the inset keyword and the same element appears pressed in:

.soft--pressed {
  box-shadow:
    inset 9px 9px 18px #bcc1c8,
    inset -9px -9px 18px #ffffff;
}

The two states share a background, a radius and a shadow distance. Only inset differs, which is why neumorphic toggles animate so cleanly between states.

The most frequent mistake in soft UI is picking shadow colours by eye. They are not free parameters — they are functions of the background, and getting them wrong is what makes an interface look dirty rather than soft.

Both shadows must be the surface colour, darkened and lightened by the same amount. If the surface is #e0e5ec, the shadows are roughly #bcc1c8 (about 15% darker) and #ffffff (about 15% lighter, clamped at white). Using a generic grey, or worse rgba(0,0,0,0.2), introduces a hue that is not present in the surface and the result reads as smudged rather than sculpted.

Two consequences follow:

Neumorphism requires a mid-tone background. The light shadow needs headroom above the surface colour and the dark shadow needs headroom below it. On a white background there is nowhere to go lighter, so only the dark shadow renders and the effect collapses into an ordinary drop shadow. On pure black the reverse happens. The technique works in a band roughly from #d0d0d8 to #eef0f4 in light themes, and around #2a2d35 to #363a45 in dark ones.

The surface and its container must match exactly. A neumorphic card on a background one shade off looks like a mistake, because the eye reads the seam before it reads the shadow. In practice this means the surface colour belongs in a single custom property that both the container and every soft control read from:

:root {
  --surface: #e0e5ec;
  --shadow-dark: #bcc1c8;
  --shadow-light: #ffffff;
}

Three numbers control how the material reads, and they are not independent.

Offset distance sets the apparent height. Small offsets of 4–6px suggest a surface barely lifted; 12–20px suggests a thick, cushioned block. Both shadows must use the same magnitude with opposite signs — asymmetric offsets read as a lighting error rather than a design choice.

Blur radius is conventionally about twice the offset. At 9px offset, an 18px blur gives the diffuse, matte falloff that defines the style. Reduce the blur below the offset and the surface hardens into something closer to a bevel; raise it far above and the form dissolves into a haze.

Border radius determines how much of the shadow is visible at all. Soft UI depends on curvature: on a sharp-cornered rectangle, the two shadows meet at a hard diagonal at each corner and the illusion breaks. A radius of at least 12px, and ideally closer to half the element's height for pills and buttons, keeps the transition continuous.

A rule of thumb that holds up well: offset : blur : radius ≈ 1 : 2 : 2. At a 9px offset that gives an 18px blur and an 18px radius, which is why so many published examples converge on those figures.

Neumorphism spends its entire visual budget on one distinction — raised versus pressed — and interfaces need more states than that.

A button typically needs rest, hover, active, focus-visible and disabled. Soft UI gives you raised and inset. The remaining three have to come from somewhere else, and the usual answers are weak: reducing the offset slightly for hover is nearly invisible, and tinting the surface breaks the rule that surface and background must match.

Practical resolutions, in order of how well they work:

1. Use the offset for pressed only. Rest is raised, active is inset. Do not spend it on hover.
2. Give hover a change of blur, not distance. Tightening the blur from 18px to 14px reads as the surface firming up under the cursor without altering its apparent height.
3. Give focus a real, visible ring. This is not optional. A focus indicator must be perceivable, and a subtly different shadow is not. Use an outline in an accent colour with an offset:

.soft:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: 3px;
}

4. Give disabled a flat surface. Removing both shadows entirely is the clearest possible signal that a control is inert, and it costs nothing from the palette.

This is the honest constraint, and it is the reason soft UI never displaced conventional interface styling.

WCAG requires a contrast ratio of at least 3:1 between a control's visual boundary and the surrounding background, so that people with low vision can tell where a control begins and ends. Neumorphism defines boundaries with a shadow whose colour is, by construction, a few percent away from the background. The measured contrast between a neumorphic button and its container is frequently below 1.2:1.

There is no parameter adjustment that resolves this. Increasing the shadow contrast far enough to pass is the same as abandoning the style.

What this means in practice:

• Acceptable: decorative surfaces, cards and containers whose boundary is not load-bearing, and secondary controls that sit beside a clearly-marked primary action.
• Not acceptable: a form's only submit button, a toggle whose state carries meaning, or any control a user must find unaided.

A workable compromise is to keep the soft surface and add a conventional boundary to controls that need one — a 1px border at sufficient contrast, or a filled accent for primary actions. The page keeps its material, and the controls that must be findable remain findable.

Soft UI does work in dark themes, but the numbers are not a simple inversion. Human perception of lightness is non-linear, and a dark shadow that reads correctly on #e0e5ec is far too subtle on #2b2f38.

In dark themes the light shadow should be weaker and the dark shadow stronger than their light-theme counterparts, because there is less headroom above the surface than below it:

```css :root { --surface: #e0e5ec; --shadow-dark: #bcc1c8; --shadow-light: #ffffff; }

@media (prefers-color-scheme: dark) { :root { --surface: #2b2f38; --shadow-dark: #1e2128; --shadow-light: #383d48; } }

.soft { background: var(--surface); box-shadow: 9px 9px 18px var(--shadow-dark), -9px -9px 18px var(--shadow-light); } ```

Routing every value through custom properties is what makes the style maintainable. The shadow colours are derived from the surface, the surface appears in exactly one place per theme, and a theme change is three values rather than an audit of every component.

Finally, respect prefers-reduced-motion if you animate between raised and pressed. The transition is short and subtle, but it is still motion, and the setting exists to be honoured.

The neumorphism studio derives both shadow colours from the surface you choose, which is the step most hand-written soft UI gets wrong. If the surface needs to animate between raised and pressed, see the CSS animation generator.