MelloUI

A React component library built for Atmosphere — soft, squishy, delightful interfaces.

While most UI libraries are built for Enterprise Density, MelloUI is built for creative apps, personal portfolios, music tools, and wellness platforms.

✨ Features

• 🫧 Squishy Physics — Spring animations that feel physical and satisfying
• 🌅 Warm Palettes — Cream, lavender, peach, sage color schemes
• 🎯 Accessible — Full keyboard navigation and WCAG AA contrast
• 🌙 Dark Mode — Beautiful light and dark themes
• ⚡ Lightweight — Tree-shakeable, optimized bundle

📦 Installation

npm install @mello-ui/react framer-motion

🚀 Quick Start

import { MelloProvider, Button } from '@mello-ui/react';
import '@mello-ui/react/styles.css';

function App() {
  return (
    <MelloProvider>
      <Button variant="solid" color="primary">
        Hello Mellow! ✨
      </Button>
    </MelloProvider>
  );
}

🧩 Components

MelloUI includes 45+ components organized into categories:

Buttons & Interactive

| Component | Description | |-----------|-------------| | Button | Squishy buttons with spring physics, 4 variants | | ButtonGroup | Group of connected buttons | | IconButton | Circular icon-only button | | Toggle | Single toggleable button | | ToggleGroup | Single/multi selection toggle group | | FloatingActionButton | FAB with icon-only and extended modes |

Forms

| Component | Description | |-----------|-------------| | Input | Text input with floating label | | Textarea | Multi-line input with auto-resize | | Checkbox | Bouncy checkmark animation | | Switch | Toggle switch with spring physics | | Radio / RadioGroup | Radio buttons with bouncy dot | | Slider | Range input with squishy thumb | | Select | Dropdown with animated options |

Date & Time

| Component | Description | |-----------|-------------| | Calendar | Month display with smooth slide animations | | DatePicker | Input with popup calendar | | DateRangePicker | Two-date selection with range highlighting | | TimePicker | Spinning wheel selector with drag/scroll |

Layout

| Component | Description | |-----------|-------------| | Stack / HStack / VStack | Flex container with spacing | | Grid / GridItem | CSS Grid layout wrapper | | Container | Centered max-width wrapper | | Divider | Visual separator line | | Spacer | Flexible empty space |

Feedback

| Component | Description | |-----------|-------------| | Toast | Notification popups with variants | | Tooltip | Hover information | | Alert | Inline status messages | | Progress | Bar and circular loading indicators | | Skeleton | Loading placeholder with shimmer |

Navigation

| Component | Description | |-----------|-------------| | Tabs | Line/pills/enclosed variants | | Breadcrumb | Path-based navigation | | Pagination | Page navigation controls | | Link | Styled anchor with hover effects |

Data Display

| Component | Description | |-----------|-------------| | Card | Content container with hover lift | | Badge | Status indicators | | Avatar / AvatarGroup | User image with initials fallback | | Table | Data table (striped/hoverable) | | List / ListItem | Styled list with leading/trailing | | Tag | Colored labels/chips | | Kbd | Keyboard shortcut display |

Disclosure

| Component | Description | |-----------|-------------| | Collapsible | Animated expand/collapse | | Accordion | Single/multiple mode with nested context |

Overlay

| Component | Description | |-----------|-------------| | Modal | Dialog with backdrop blur, spring bounce | | Drawer | Slide-out panel from any edge | | Popover | Floating content with arrow | | DropdownMenu | Action menu with icons & shortcuts | | ContextMenu | Right-click triggered menu |

Data Visualization

| Component | Description | Status | |-----------|-------------|--------| | LineChart | Smooth curves, multi-series, gradient | ✅ | | AreaChart | Gradient fills, stacking support | ✅ | | BarChart | Rounded corners, horizontal/vertical, colorful | ✅ | | PieChart | Donut variant, active shape animation | ✅ | | RadarChart | Multi-axis comparison ("spider" chart) | ✅ | | ScatterChart | Point distribution, bubble variant | ✅ | | ComposedChart | Mix of line/bar/area in single chart | ✅ | | GaugeChart | KPI/progress indicator (semicircular) | ✅ | | FunnelChart | Conversion/process flow visualization | ✅ | | TreemapChart | Hierarchical data visualization | ✅ |

Chart Usage

import { Chart, MellowLineChart, MellowBarChart } from '@mellow-ui/react';

// Simple usage
<Chart title="Monthly Revenue">
  <MellowLineChart data={data} xKey="month" yKey="revenue" />
</Chart>

// Multi-series bar chart
<Chart title="Revenue vs Cost">
  <MellowBarChart 
    data={data} 
    xKey="month" 
    yKey={['revenue', 'cost']} 
  />
</Chart>

🎨 Design Tokens

Access design tokens directly:

import { colors, spacing, radii, shadows } from '@mellow-ui/react';

// Use in your custom components
const myStyle = {
  backgroundColor: colors.lavender[500],
  padding: spacing[4],
  borderRadius: radii.lg,
};

🎭 Animation Hooks

Create your own squishy interactions:

import { useSquishy, useHover } from '@mellow-ui/react';

function MyComponent() {
  const { scale, handlers } = useSquishy();
  
  return (
    <motion.div style={{ scale }} {...handlers}>
      Press me!
    </motion.div>
  );
}

🌙 Theme

Control light/dark mode:

import { useTheme } from '@mellow-ui/react';

function ThemeToggle() {
  const { theme, toggleTheme } = useTheme();
  
  return (
    <Button onClick={toggleTheme}>
      {theme === 'dark' ? '☀️' : '🌙'}
    </Button>
  );
}

🎨 Custom Theming

Create a custom color theme to match your brand:

import { MellowProvider, createTheme } from '@mellow-ui/react';

const brandTheme = createTheme({
  name: 'my-brand',
  colors: {
    primary: '#6366F1',
    accent: '#EC4899',
    success: '#10B981',
    warning: '#F59E0B',
    error: '#EF4444',
    backgroundLight: '#F8FAFC',
    backgroundDark: '#0F172A',
  },
});

function App() {
  return (
    <MellowProvider theme={brandTheme}>
      <YourApp />
    </MellowProvider>
  );
}

Pre-built Themes

import { themes } from '@mellow-ui/react';

// themes.mellow  - Default warm (lavender, cream, peach)
// themes.ocean   - Cool blues and cyans
// themes.forest  - Natural greens
// themes.sunset  - Warm oranges and pinks

<MellowProvider theme={themes.ocean}>
  <App />
</MellowProvider>

📚 Documentation

See the docs/ folder for detailed documentation:

• Design Philosophy
• Component Specs

🛠️ Development

# Install dependencies
npm install

# Start Storybook
npm run storybook

# Run tests
npm run test

# Build library
npm run build:lib

📄 License

MIT © MellowUI Team