Neumorphism (Soft UI)

---
name: neumorphism
description: Apply the Neumorphism (Soft UI) visual design system when building or restyling websites and UI. Use whenever the user asks to build, theme, restyle, or "make it look like" Neumorphism (Soft UI), mentions soft UI, neomorphism, soft skeuomorphism, or describes paired light/dark shadows, single continuous surface color, extruded and inset elements — even if they don't name the style explicitly. Do NOT use for non-visual tasks or when another named design system is requested.
license: MIT
---

# Neumorphism (Soft UI) Design System

UI elements appear extruded from or pressed into a single continuous surface, modeled by paired light and dark soft shadows on a low-saturation background. Tactile, quiet, and monolithic.

Apply this system holistically: colors, type, spacing, radius, borders, shadows, and motion together produce the look. Token values follow the widely documented recipe for this style. When in doubt, match the reference sites listed at the end.

## When to use

- Building a new page or component that should read as Neumorphism (Soft UI).
- Restyling existing UI to this aesthetic.
- The user names the style, an alias (soft UI, neomorphism, soft skeuomorphism), or describes its traits: paired light/dark shadows; single continuous surface color; extruded and inset elements; very low color contrast; large soft radii.

## Design tokens

### Color palette

- The one surface color — page and elements share it: `#e0e5ec` (--color-bg)
- Identical to bg by design: `#e0e5ec` (--color-surface)
- Primary text, desaturated navy: `#31344b` (--color-text)
- Secondary text and icons: `#9ba3b5` (--color-text-muted)
- Accent for active states and key actions: `#5b5fc7` (--color-accent)
- Dark half of the shadow pair: `#a3b1c6` (--color-shadow-dark)
- Light half of the shadow pair: `#ffffff` (--color-shadow-light)

### Typography

- Display / headings: Nunito (fallback: -apple-system, sans-serif)
- Body: Nunito (fallback: -apple-system, sans-serif)
- Type scale: 1.2 ratio, base 16px — computed steps: 16px / 19px / 23px / 28px / 33px / 40px (body / h5 / h4 / h3 / h2 / h1; scale further for display sizes)
- Headings: weight 800, line-height 1.2, letter-spacing 0
- Body: line-height 1.6, letter-spacing 0

### Spacing, radius, border

- Spacing scale (px): 8, 12, 16, 24, 32, 48, 64 — Elements need wide gaps so their soft shadows never overlap; cramped neumorphism turns to mud.
- Border radius: md 16px, lg 24px, round 50% — Everything is soft; circular buttons are characteristic.
- Border treatment: none — Borders would break the molded-from-one-surface illusion. Shape is defined entirely by shadow.

### Shadows

- raised: `9px 9px 16px #a3b1c6, -9px -9px 16px #ffffff` — Default extruded element
- raised-sm: `5px 5px 10px #a3b1c6, -5px -5px 10px #ffffff` — Small controls
- inset: `inset 6px 6px 12px #a3b1c6, inset -6px -6px 12px #ffffff` — Pressed states, inputs, wells

### Layout

- Max content width: 1100px
- Single-surface canvas — no alternating section backgrounds
- Grouped control clusters (media players, dashboards) rather than long marketing pages
- Consistent global light source: light always from top-left

### Effects

- Toggle states swap raised to inset
- Circular knobs and dials with radial tick marks

### Motion

- Easing: ease-out; durations 150ms / 250ms / 400ms
- Press animates raised-to-inset shadow swap
- Slow, soft transitions; nothing snaps

## CSS variables (drop-in)

```css
:root {
  --color-bg: #e0e5ec;
  --color-surface: #e0e5ec;
  --color-text: #31344b;
  --color-text-muted: #9ba3b5;
  --color-accent: #5b5fc7;
  --color-shadow-dark: #a3b1c6;
  --color-shadow-light: #ffffff;
  --radius-md: 16px;
  --radius-lg: 24px;
  --radius-round: 50%;
  --shadow-raised: 9px 9px 16px #a3b1c6, -9px -9px 16px #ffffff;
  --shadow-raised-sm: 5px 5px 10px #a3b1c6, -5px -5px 10px #ffffff;
  --shadow-inset: inset 6px 6px 12px #a3b1c6, inset -6px -6px 12px #ffffff;
  --border-default: none;
  --font-display: Nunito, -apple-system, sans-serif;
  --font-body: Nunito, -apple-system, sans-serif;
  --text-base: 16px;
  --leading-heading: 1.2;
  --leading-body: 1.6;
  --tracking-heading: 0;
  --tracking-body: 0;
  --ease: ease-out;
  --duration-fast: 150ms;
  --duration-base: 250ms;
  --duration-slow: 400ms;
}
```

Google Fonts: `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Nunito:wght@400;600;800&display=swap" rel="stylesheet">`

## Component recipes

- **Nav:** No bar chrome — a floating raised pill containing icon buttons, or a raised sidebar on the same surface
- **Hero:** App-style: a large raised panel holding the primary control cluster; text set directly on the canvas
- **Card:** Raised shadow, 16–24px radius, same fill as bg, 24px padding
- **Button (primary):** Raised circle or rounded rect; accent color only on the icon/label, not the fill; goes inset when active
- **Button (secondary):** Smaller raised element with muted icon
- **Form fields:** Inset well with 16px radius; placeholder in muted; focus adds a faint accent ring outside the inset shadow

Where this spec is silent (footers, responsive breakpoints, empty states), derive the treatment from the tokens above and the Do/Don't rules — never fall back to generic defaults. Every interactive element needs a visible keyboard focus state consistent with the style (use the accent color or the border treatment, not the browser default).

## Signature element

The dual-shadow extrusion: every element casts a dark shadow toward bottom-right and a white highlight toward top-left from the SAME surface color as the page, so it reads as molded plastic. Spend boldness here; keep everything else quiet.

## Do

- Keep every element the same color as the background — the shadows do all the work
- Maintain one global light source direction across the whole UI
- Use inset shadows to communicate active/pressed/selected
- Reserve the accent color for small, meaningful highlights

## Don't

- Never mix neumorphic elements with flat cards or hard borders on the same surface
- Don't put large body-text blocks on raised elements — this is a control-panel style, not an editorial one
- No dark mode by simple inversion; rebuild the shadow pair for a dark surface (#2d3142 with #262a38/#3a4055 shadows)
- Don't use it for content-heavy or conversion-critical pages

## Accessibility notes

- SEVERE contrast limitations by design: element boundaries are sub-3:1 against the background and invisible to many low-vision users — always add visible focus rings and rely on text/iconography, not shape alone
- Muted text #9ba3b5 on #e0e5ec fails AA (≈2.2:1) — use it only for decorative labels, never information
- This style is best confined to demos, portfolio pieces, and niche control UIs, not general products

## Reference sites

- neumorphism.io generator: https://neumorphism.io
- Michal Malewicz on Neumorphism: https://hype4.academy/articles/design/neumorphism-in-user-interfaces

For the exhaustive machine-readable spec, see references/tokens.md and tokens.json in this skill folder.

Install this skill

unzip neumorphism.zip -d ~/.claude/skills/

npx shadcn add https://claude-design-skills.convoke.software/r/neumorphism.json

Settings → Capabilities → Skills → Upload skill → neumorphism.zip