ui-aesthetic-utils/README.md

A lightweight utility library for modern UI aesthetics including glassmorphism, neumorphism, glow effects, and soft shadows

# ui-aesthetic-utils

**A lightweight utility library for modern UI aesthetics** 

ui-aesthetic-utils provides ready-to-use CSS utilities and React/Vue components for modern design aesthetics including glassmorphism, neumorphism, glow effects, and elegant shadows. Perfect for developers who want to quickly apply polished aesthetics with minimal configuration.

## Features

🎨 **Multiple Aesthetic Effects**
- **Glassmorphism** - Frosted glass effects with customizable blur and opacity
- **Neumorphism** - Soft, tactile UI elements with inset/outset shadows  
- **Glow Effects** - Customizable lighting and neon effects
- **Shadow System** - Elegant elevation with multiple softness levels

⚡ **Framework Agnostic**
- Pure CSS utility classes for any framework
- React components with hooks
- Vue 3 components with Composition API
- TypeScript-first with comprehensive type definitions

🔧 **Highly Configurable**
- Central `aesthetic.config.js` for design tokens
- CSS custom properties for runtime theming
- Tree-shakeable ESM and CJS bundles
- Cross-browser compatible

## Installation

```bash
npm install ui-aesthetic-utils
# or
yarn add ui-aesthetic-utils
# or
pnpm add ui-aesthetic-utils
```

## Quick Start

### CSS Utilities (Framework Agnostic)

```css
/* Import the CSS utilities */
@import 'ui-aesthetic-utils/css';
```

```html
<!-- Glassmorphism -->
<div class="glass-md">
  <p>Frosted glass panel</p>
</div>

<!-- Neumorphism -->
<button class="neuro-flat-lg">
  Neumorphic Button
</button>

<!-- Glow Effects -->
<div class="glow-medium">
  <p>Glowing container</p>
</div>

<!-- Shadows -->
<div class="shadow-lg-soft">
  <p>Elevated card</p>
</div>
```

### React Components

```jsx
import { 
  GlassPanel, 
  NeumorphicButton, 
  GlowBox, 
  ShadowCard,
  useGlass,
  useGlow 
} from 'ui-aesthetic-utils/react';
import 'ui-aesthetic-utils/css';

function App() {
  // Using hooks for custom styling
  const { styles } = useGlass({ blur: 'lg', opacity: 0.8 });
  const { styles: glowStyles } = useGlow({ color: '#ff6b6b', intensity: 'strong' });

  return (
    <div>
      {/* Components */}
      <GlassPanel blur="md" opacity={0.7}>
        <h2>Glassmorphism Panel</h2>
        <p>Beautiful frosted glass effect</p>
      </GlassPanel>

      <NeumorphicButton 
        depth="lg" 
        shape="convex"
        onClick={() => console.log('Clicked!')}
      >
        Neumorphic Button
      </NeumorphicButton>

      <GlowBox color="#3b82f6" intensity="medium" animate>
        <p>Animated glow effect</p>
      </GlowBox>

      <ShadowCard elevation="xl" hoverElevation>
        <p>Elevated card with hover effect</p>
      </ShadowCard>

      {/* Using hooks */}
      <div style={styles}>
        <p>Custom glass effect with hooks</p>
      </div>

      <div style={glowStyles}>
        <p>Custom glow effect</p>
      </div>
    </div>
  );
}
```

### Vue 3 Components

```vue
<template>
  <div>
    <GlassPanel :blur="'md'" :opacity="0.7">
      <h2>Glassmorphism Panel</h2>
      <p>Beautiful frosted glass effect</p>
    </GlassPanel>

    <NeumorphicButton 
      depth="lg" 
      shape="convex"
      @click="handleClick"
    >
      Neumorphic Button
    </NeumorphicButton>

    <GlowBox color="#3b82f6" intensity="medium" :animate="true">
      <p>Animated glow effect</p>
    </GlowBox>

    <ShadowContainer elevation="xl">
      <p>Elevated container</p>
    </ShadowContainer>
  </div>
</template>

<script>
import { 
  GlassPanel, 
  NeumorphicButton, 
  GlowBox, 
  ShadowContainer 
} from 'ui-aesthetic-utils/vue';

export default {
  components: {
    GlassPanel,
    NeumorphicButton,
    GlowBox,
    ShadowContainer
  },
  methods: {
    handleClick() {
      console.log('Button clicked!');
    }
  }
};
</script>

<style>
@import 'ui-aesthetic-utils/css';
</style>
```

## Configuration

### Custom Configuration

Create an `aesthetic.config.js` file in your project root:

```javascript
module.exports = {
  blur: {
    sm: "6px",
    md: "12px", 
    lg: "20px",
    xl: "30px"
  },
  
  shadow: {
    soft: "0 4px 20px rgba(0, 0, 0, 0.08)",
    medium: "0 8px 30px rgba(0, 0, 0, 0.12)", 
    hard: "0 12px 40px rgba(0, 0, 0, 0.2)"
  },
  
  glow: {
    primary: "0 0 20px #3b82f6",
    secondary: "0 0 20px #8b5cf6", 
    accent: "0 0 20px #f59e0b",
    neon: "0 0 30px #00ff88"
  },
  
  neumorphic: {
    baseColor: "#f0f0f0",
    darkShadow: "rgba(170, 170, 170, 0.5)",
    lightShadow: "rgba(255, 255, 255, 0.9)"
  },
  
  colors: {
    primary: {
      500: "#3b82f6",
      600: "#2563eb"
    }
  }
};
```

### Runtime Configuration

```javascript
import { setupGlobalConfig, applyAestheticTokens } from 'ui-aesthetic-utils';

// Setup custom configuration
const config = setupGlobalConfig({
  blur: { md: '18px' },
  glow: { primary: '0 0 25px #ff6b6b' }
});

// Apply CSS variables
config.applyCSSVariables();
```

## API Reference

### CSS Utility Classes

#### Glassmorphism
- `.glass-sm` - Small blur (8px)
- `.glass-md` - Medium blur (15px) 
- `.glass-lg` - Large blur (25px)
- `.glass-xl` - Extra large blur (40px)

#### Neumorphism
- `.neuro-flat-{size}` - Flat neumorphic effect
- `.neuro-concave-{size}` - Inset neumorphic effect
- `.neuro-convex-{size}` - Raised neumorphic effect

Sizes: `sm`, `md`, `lg`, `xl`

#### Glow Effects
- `.glow-subtle` - Gentle glow
- `.glow-medium` - Standard glow
- `.glow-strong` - Intense glow 
- `.glow-neon` - Neon effect with border

#### Shadows
- `.shadow-{size}-{type}` - Configurable shadows

Sizes: `sm`, `md`, `lg`, `xl`, `xxl`
Types: `soft`, `medium`, `hard`

### React Components

#### GlassPanel
```tsx
interface GlassPanelProps {
  blur?: 'sm' | 'md' | 'lg' | 'xl' | string;
  opacity?: number;
  border?: string;
  borderRadius?: string;
  background?: string;
  children: ReactNode;
}
```

#### NeumorphicButton
```tsx
interface NeumorphicButtonProps {
  depth?: 'sm' | 'md' | 'lg' | 'xl';
  shape?: 'flat' | 'concave' | 'convex';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  variant?: 'primary' | 'secondary' | 'accent';
  onClick?: () => void;
}
```

#### GlowBox
```tsx
interface GlowBoxProps {
  color?: string;
  intensity?: 'subtle' | 'medium' | 'strong' | 'neon';
  spread?: number;
  blur?: number;
  animate?: boolean;
  hoverEffect?: boolean;
}
```

### React Hooks

#### useGlass
```tsx
const { styles, className } = useGlass({
  blur: 'lg',
  opacity: 0.8,
  background: 'rgba(255, 255, 255, 0.1)'
});
```

#### useNeumorphic
```tsx
const { styles, className, hoverStyles, activeStyles } = useNeumorphic({
  depth: 'lg',
  shape: 'convex'
});
```

#### useGlow
```tsx
const { styles, className, hoverStyles, animatedStyles } = useGlow({
  color: '#3b82f6',
  intensity: 'strong'
});
```

#### useShadow
```tsx
const { styles, className, hoverStyles } = useShadow({
  elevation: 'lg',
  softness: 'soft'
});
```

<!-- ## Examples

- **[React Demo](examples/react-demo/)** - Complete React implementation
- **[Vue Demo](examples/vue-demo/)** - Vue 3 with Composition API
- **[Vanilla HTML](examples/vanilla-demo/)** - Pure CSS utilities -->

## Browser Support

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

**Note:** `backdrop-filter` requires modern browsers. Graceful degradation is provided for unsupported browsers.

## Performance

- **Bundle Size:** ~15KB minified + gzipped
- **Tree Shakeable:** Import only what you need
- **CSS-first:** Minimal JavaScript overhead
- **Hardware Accelerated:** GPU-optimized effects

## TypeScript

Fully typed with comprehensive TypeScript definitions included.

```tsx
import type { 
  GlassPanelProps, 
  NeumorphicButtonProps, 
  GlowBoxProps,
  AestheticConfig 
} from 'ui-aesthetic-utils';
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`) 
5. Open a Pull Request

## Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Build for production
npm run build

# Run Storybook
npm run storybook
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

---