Japanese Minimalism / Wabi-Sabi

---
name: japanese-wabi-sabi
description: Apply the Japanese Minimalism / Wabi-Sabi visual design system when building or restyling websites and UI. Use whenever the user asks to build, theme, restyle, or "make it look like" Japanese Minimalism / Wabi-Sabi, mentions wabi-sabi, japanese minimalism, zen minimal, or describes vast negative space (ma), muted natural palette, light 300-weight type — 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
---

# Japanese Minimalism / Wabi-Sabi Design System

Quiet imperfection and vast negative space (ma): washi-paper neutrals, sumi ink, a muted indigo, light-weight Mincho serifs over fine gothic sans, and near-invisible borders. Nothing shouts; the emptiness between elements carries the composition.

Apply this system holistically: colors, type, spacing, radius, borders, shadows, and motion together produce the look. Token values are representative interpretations of the aesthetic, not an official spec. When in doubt, match the reference sites listed at the end.

## When to use

- Building a new page or component that should read as Japanese Minimalism / Wabi-Sabi.
- Restyling existing UI to this aesthetic.
- The user names the style, an alias (wabi-sabi, japanese minimalism, zen minimal, ma design, japandi, ryokan aesthetic), or describes its traits: vast negative space (ma); muted natural palette; light 300-weight type; washi paper texture; hairline warm borders; vertical text accents.

## Design tokens

### Color palette

- Washi paper — warm off-white ground: `#f4f1ea` (--color-bg)
- Slightly lifted panel tone for images and cards: `#faf8f3` (--color-surface)
- Sumi ink — soft near-black, never pure #000: `#2b2b2b` (--color-text)
- Captions, dates, secondary labels: `#66615a` (--color-text-muted)
- Aizome indigo — links and quiet emphasis: `#3b4a6b` (--color-accent)
- Ochre — decorative warmth in illustrations and hover states, never text: `#c19a6b` (--color-accent-2)
- Hairline warm dividers, barely visible: `#e2ddd3` (--color-border)

### Typography

- Display / headings: Shippori Mincho (fallback: Yu Mincho, Hiragino Mincho ProN, Georgia, serif)
- Body: Noto Sans JP (fallback: Hiragino Kaku Gothic ProN, Yu Gothic, sans-serif)
- Type scale: 1.25 ratio, base 16px — computed steps: 16px / 20px / 25px / 31px / 39px / 49px (body / h5 / h4 / h3 / h2 / h1; scale further for display sizes)
- Headings: weight 400, line-height 1.4, letter-spacing 0.02em
- Body: line-height 1.8, letter-spacing 0.01em

### Spacing, radius, border

- Spacing scale (px): 8, 16, 24, 40, 64, 96, 144, 192 — Very airy vertical rhythm; sections are separated by emptiness rather than rules, and margins are far larger than Western minimalism would dare.
- Border radius: none 0px, sm 2px — Corners stay at 0–2px; softness comes from color and texture, not rounding.
- Border treatment: 1px solid #e2ddd3 — Borders are whispers — warm hairlines used only when spacing alone cannot separate. Never dark rules.

### Shadows

- breath: `0 1px 2px rgba(43, 43, 43, 0.05)` — Barely-there lift under images; most surfaces stay perfectly flat

### Layout

- Max content width: 1080px
- Single quiet column with margins wider than the content feels like it needs
- Asymmetric placement — images sit off-center with deliberate imbalance
- Vertical writing-mode (tategaki) labels as compositional accents on section edges
- One idea per viewport; scrolling reveals content one breath at a time

### Effects

- Faint washi paper grain texture on the background (2–3% opacity)
- Occasional enso or ink-brush stroke as a decorative motif
- Vertical text labels via writing-mode: vertical-rl

### Motion

- Easing: cubic-bezier(0.25, 0.1, 0.25, 1); durations 200ms / 450ms / 800ms
- Long, slow opacity fades — elements appear like ink soaking into paper
- No bounce, no spring, no parallax
- Hover states shift color tone gently rather than moving elements

## CSS variables (drop-in)

```css
:root {
  --color-bg: #f4f1ea;
  --color-surface: #faf8f3;
  --color-text: #2b2b2b;
  --color-text-muted: #66615a;
  --color-accent: #3b4a6b;
  --color-accent-2: #c19a6b;
  --color-border: #e2ddd3;
  --radius-none: 0px;
  --radius-sm: 2px;
  --shadow-breath: 0 1px 2px rgba(43, 43, 43, 0.05);
  --border-default: 1px solid #e2ddd3;
  --font-display: "Shippori Mincho", "Yu Mincho", "Hiragino Mincho ProN", Georgia, serif;
  --font-body: "Noto Sans JP", "Hiragino Kaku Gothic ProN", "Yu Gothic", sans-serif;
  --text-base: 16px;
  --leading-heading: 1.4;
  --leading-body: 1.8;
  --tracking-heading: 0.02em;
  --tracking-body: 0.01em;
  --ease: cubic-bezier(0.25, 0.1, 0.25, 1);
  --duration-fast: 200ms;
  --duration-base: 450ms;
  --duration-slow: 800ms;
}
```

Google Fonts: `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Shippori+Mincho:wght@400;500&family=Noto+Sans+JP:wght@300;400&display=swap" rel="stylesheet">`

## Component recipes

- **Nav:** Nearly invisible: small Mincho wordmark top-left, two or three lowercase links far right in 14px light sans, no background, no border until scroll adds a hairline
- **Hero:** A 32–48px light Mincho heading placed in the upper third with a short vertical label beside it; one small photograph offset below; at least half the viewport left empty
- **Card:** Borderless image with 2px radius, generous padding, caption in muted 13px sans below; separation by whitespace, optionally a hairline top border
- **Button (primary):** Indigo text on transparent with a 1px indigo underline offset 6px; fills to indigo bg with washi text only on hover — even primary actions whisper
- **Button (secondary):** Muted text with hairline bottom border that darkens to sumi on hover
- **Form fields:** Bottom hairline only (#e2ddd3), 16px light input text; focus deepens the line to indigo over 400ms

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

A single small element — a vertical tategaki label, an ink-toned kanji, or an off-center photograph — placed in an expanse of warm washi background, with the surrounding emptiness treated as the actual design material. Spend boldness here; keep everything else quiet.

## Do

- Treat empty space as the primary material — if a section feels sparse, it is probably right
- Keep every tone warm and slightly desaturated; never pure white or pure black
- Embrace asymmetry and imperfection — perfectly centered, perfectly balanced layouts break the wabi-sabi spirit
- Use texture grain at whisper opacity to keep large empty areas alive

## Don't

- No loud accent colors, gradients, or saturated fills
- Don't add elements to fill space — restraint is the entire point
- No heavy font weights above 500 anywhere
- Don't use hard shadows or visible elevation; depth reads as clutter here

## Accessibility notes

- The 300-weight body sans must never be used below 16px; bump to 400 for small captions
- Sumi #2b2b2b on washi #f4f1ea passes AAA; indigo #3b4a6b on washi passes AA at all sizes (~7.8:1)
- Ochre #c19a6b is decorative only — it fails contrast for text on washi
- Vertical tategaki text needs proper lang and writing-mode markup so screen readers linearize it correctly

## Reference sites

- Muji: https://www.muji.com
- Kinfolk: https://www.kinfolk.com
- Hoshinoya: https://hoshinoya.com

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

Install this skill

unzip japanese-wabi-sabi.zip -d ~/.claude/skills/

npx shadcn add https://claude-design-skills.convoke.software/r/japanese-wabi-sabi.json

Settings → Capabilities → Skills → Upload skill → japanese-wabi-sabi.zip