Mochi UI 🍡

A Claymorphism Design System built with Astro, React, and Motion — featuring spring physics, tactile haptic feedback, and Figma-native compatibility.

✨ Philosophy

If it looks like clay, animates like clay, it must feel like clay.

Mochi UI implements the complete tactile web playbook:

• Pastel Psychology — Reduced cognitive load through curated tints
• Shadow Matrix — 4-layer depth system (Base → Lift → Volume → Reflection)
• Spring Physics — Bounce + Perceptual Duration parameters (no Mass/Stiffness/Damping)
• Haptic Synchronization — Device hardware feedback mapped to visual states
• Bento Grids — Japanese bento-inspired compartmentalization

🚀 Quick Start

# Clone and install
npm install

# Start dev server
npm run dev

# Build for production
npm run build

# Export design tokens to Figma
npm run tokens

🎨 Design Tokens (W3C Format)

All tokens follow the W3C Design Tokens Format for universal compatibility:

{
  "mochi.color.rainbow.mint": { "$type": "color", "$value": "#A3E635" },
  "mochi.shadow.lift.md": { "$type": "shadow", "$value": { ... } },
  "mochi.motion.spring.bounce": { "$type": "number", "$value": 0.4 }
}

Figma Integration

Export Format	Use Case
tokens-studio.json	Tokens Studio plugin
figma-variables.json	Native Figma Variables API
variables.css	CSS custom properties import
component-specs.json	Component anatomy documentation

🧱 Component Library

Clay Primitives

Component	Features	Physics
ClayButton	Triple-shadow, 6 colorways, 3 sizes	Compression → Overshoot → Settle
ClayCard	4-layer shadow, 3D tilt on hover, shine effect	Floating parallax
ClayToggle	Spring knob, track recess, haptic tick	Elastic snap
ClaySlider	Tactile knob, granular feedback, fill animation	Drag + release
ClayInput	Inset recess, glow focus, validation	Scale pulse
ClayChartBar	3D cylinder, volumetric shadow, tooltip	Grow from bottom
ClayBadge	Pulse animation, micro-float	Scale bounce
ClayAvatar	Status indicator, rotation on hover	Tilt + scale

Animation Systems

System	Purpose
SpringPhysics	Bounce + Duration configuration
ClayRebound	3-phase animation (Compression → Overshoot → Settle)
FloatingContainer	Ambient breathing animation
FloatingGroup	Staggered floating elements
ParallaxLayer	Mouse-driven depth

🎯 Physics Presets

import { physicsPresets, PhysicsProvider } from 'mochi-ui';

// Available presets
const presets = {
  jelly:       { bounce: 0.8, duration: 500 },  // Maximum elasticity
  clay:        { bounce: 0.4, duration: 300 },  // Standard (default)
  firm:        { bounce: 0.15, duration: 200 }, // Minimal bounce
  snappy:      { bounce: 0.2, duration: 150 },  // Quick response
  luxurious:   { bounce: 0.5, duration: 600 },   // Slow elegance
  bouncy:      { bounce: 0.9, duration: 400 },  // Playful
};

// Apply to entire app
<PhysicsProvider config={physicsPresets.jelly}>
  <App />
</PhysicsProvider>

📐 Shadow Matrix

The 4-layer CSS shadow system creates physical depth:

.clay-surface {
  /* Layer 1: Base color */
  background: hsl(120deg 35% 82%);

  /* Layer 2: Lift — floating depth */
  box-shadow: 0 8px 16px rgba(0,0,0,0.1);

  /* Layer 3: Volume — 3D inflation */
  box-shadow: inset -10px -10px 20px rgba(0,0,0,0.05);

  /* Layer 4: Reflection — light source */
  box-shadow: inset 10px 10px 20px rgba(255,255,255,0.8);
}

🌗 Dark Mode

// Never use pure black — always elevated darks
document.documentElement.setAttribute('data-theme', 'dark');

Mode	Base	Surface	Card
Light	#F5E6D3	#FFF8F0	#FFFFFF
Dark	#1E1E2E	#2D2D44	#252538

🎭 State Lifecycle

Every interactive component follows the 3-state tactile lifecycle:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   DEFAULT   │ →  │    HOVER    │ →  │    ACTIVE   │
│   Floating  │    │   Lifted    │    │  Compressed │
│  (shadow↑)  │    │ (shadow↑↑)  │    │ (inset↓)    │
└─────────────┘    └─────────────┘    └─────────────┘

📱 Haptic Feedback

import { triggerHaptic } from 'mochi-ui';

// Mapped to UI components
triggerHaptic({ enabled: true, intensity: 'soft' });   // Button press
triggerHaptic({ enabled: true, intensity: 'medium' });   // Toggle
triggerHaptic({ enabled: true, intensity: 'firm' });    // Deep press

🏗️ Architecture

mochi-ui/
├── src/
│   ├── components/
│   │   ├── clay/           # 8 primitive components
│   │   ├── animations/     # Physics & motion systems
│   │   ├── layout/         # BentoGrid, containers
│   │   └── ShowcasePage.tsx # Interactive demo
│   ├── styles/
│   │   ├── tokens.css      # CSS custom properties
│   │   └── clay.css        # Component styles
│   ├── tokens/
│   │   └── tokens.json     # W3C format tokens
│   └── pages/
│       └── index.astro     # Main entry
├── figma-export/           # Generated Figma assets
├── scripts/
│   └── build-tokens.js     # Token transformation
└── package.json

🎨 Color Palettes

Theme	Mood	Colors
Rainbow	Whimsical	Mint, Baby Blue, Lavender, Peach
Pink & Red	Romantic	Blush Pink, Soft Rose
Blue	Serene	Powder Blue, Sky Blue
Green	Natural	Sage, Mint Green
Neutrals	Sophisticated	Ivory, Soft Taupe

📄 License

MIT © 2026 Mochi UI