Shizen (自然) means nature, naturalness — the effortless quality at the heart of Japanese aesthetics. This specification defines a design system built on Japanese aesthetic principles: named token palettes, spacing rooted in ma (negative space), typography and motion vocabulary, and AI-ready prompt templates. The goal is to give developers and AI agents a shared, precise language for Japanese-style UI.
Each aesthetic pack defines a set of semantic color tokens. Common names:
| Token | Purpose |
|---|---|
bg | Background / paper |
text | Primary text |
accent | Links, buttons, key emphasis |
muted | Secondary text, captions |
border | Borders, dividers |
Packs may add tokens (e.g. gold, ink, warm). Values are hex. Use CSS custom properties with a --shizen- prefix for implementation.
Ma (間) is the intentional use of negative space — pause, breath, balance. Shizen spacing scales are named (e.g. ma-ratio, ceremonial scale) and defined as a small set of values (e.g. 4, 8, 16, 32, 64px). Use these for margin, padding, and gap so layout has consistent rhythm.
Each pack specifies a ratio (e.g. 1.618), weight (e.g. light, regular), and a short note. Prefer restrained weight and clear hierarchy. Japanese typography often emphasizes vertical rhythm and clarity; adapt these ideas for Latin type with line-height and scale.
Shizen motion is subtle and purposeful:
Terms from the system: en (subtle, fate-like transition), nagare (flowing state change), shizuka (stillness-first animation).
Token names are lowercase, semantic, and English. Use --shizen-<token> in CSS. In prompts, spell out the token and hex so AI and humans get the same result (e.g. “bg #F5F0E8, text #2C2C2C”).
A Shizen prompt embeds the chosen palette and rules in one block. Example structure:
Use [aesthetic] palette: [token list with hex]. Spacing scale: [scale] ([name]). Typography: [ratio] ratio, [weight] weight. Transitions: [duration] [easing], [style]. Style: [short style rule].
Optional modifiers: season (e.g. spring, winter), mood (e.g. calm, minimal). Platform-specific prompts can prefix with “For [Platform]:”.
Five core packs are defined: Wabi-Sabi Neutral, Shinto Ceremonial, Edo Ink, Sakura Season, Yoru (Night). Each has tokens, spacing, typography, motion, style description, and a prompt template. See the Prompt Builder and the free Wabi-Sabi pack for full detail.
This is the Shizen Design System specification v1.0. The specification and associated design tokens, prompts, and documentation are licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You may share and adapt with attribution. See the license (text).
Every day, one teaching. One moment of stillness.
Kanji, meaning, and a quiet reflection — rooted in the philosophy
behind Japan's forests, seasons, and sacred silences.