inspira-ui

What this skill does

# Inspira UI - Animated Vue/Nuxt Component Library

Inspira UI is a collection of 120+ reusable, animated components powered by TailwindCSS v4, motion-v, GSAP, and Three.js — crafted to help ship beautiful Vue and Nuxt applications faster.

## Table of Contents

- [When to Use](#when-to-use-this-skill)
- [Quick Start](#quick-start)
- [Component Selection](#component-selection-workflow)
- [Core Patterns](#core-usage-patterns)
- [Critical Pitfalls](#critical-pitfalls-to-avoid)
- [Detailed References](#detailed-documentation)

## When to Use This Skill

Use Inspira UI when building:
- **Animated landing pages** with hero sections, testimonials, and effects
- **Modern web applications** requiring 3D visualizations and interactive elements
- **Marketing sites** with eye-catching backgrounds and text animations
- **Portfolio sites** with image galleries, carousels, and showcase effects
- **Interactive experiences** with custom cursors, special effects, and particle systems
- **Vue 3 or Nuxt 4 projects** requiring production-ready animated components

**Key Benefits**:
- 120+ copy-paste components (not a traditional npm library)
- Full TypeScript support with Vue 3 Composition API
- TailwindCSS v4 with OkLch color space
- Responsive and mobile-optimized
- Free and open source (MIT license)

## Quick Start

### 1. Install Core Dependencies

```bash
# Required for all components
bun add -d clsx tailwind-merge class-variance-authority tw-animate-css
bun add @vueuse/core motion-v

# Optional: For 3D components (Globe, Cosmic Portal, etc.)
bun add three @types/three

# Optional: For WebGL components (Fluid Cursor, Neural Background, etc.)
bun add ogl
```

### 2. Setup CN Utility

Create `lib/utils.ts`:

```typescript
import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}
```

### 3. Configure CSS Variables

Add to your `main.css`. See [references/SETUP.md](references/SETUP.md) for complete CSS configuration with OkLch colors.

### 4. Verify Setup

```bash
./scripts/verify-setup.sh
```

### 5. Copy Components

Browse [inspira-ui.com/components](https://inspira-ui.com/components), copy what you need into `components/ui/`.

## Secure Installation

This installs 6+ packages including 3D libraries (`three`, `ogl`) with large dependency trees. Before installing, follow supply chain security best practices:

- **Block post-install scripts** — `npm config set ignore-scripts true` (or Bun: disabled by default)
- **Cooldown period** — Wait 7 days for new package versions to be vetted by the community
- **Audit before installing** — Run `socket package score npm <pkg>` or use `socket npm install <pkg>` to check packages

Load the `dependency-upgrade` skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.

## Component Selection Workflow

**What type of effect do you need?**

1. **Background Effects** → Aurora, Cosmic Portal, Particles, Neural Background
   - See: [references/components-list.md#backgrounds](references/components-list.md#-backgrounds-24)

2. **Text Animations** → Morphing Text, Glitch, Hyper Text, Sparkles Text
   - See: [references/components-list.md#text-animations](references/components-list.md#-text-animations-24)

3. **3D Visualizations** → Globe, 3D Carousel, Icon Cloud, World Map
   - Dependencies: `bun add three @types/three`
   - See: [references/components-list.md#visualization](references/components-list.md#-visualization-21)

4. **Interactive Cursors** → Fluid Cursor, Tailed Cursor, Smooth Cursor
   - Dependencies: `bun add ogl` (for WebGL cursors)
   - See: [references/components-list.md#cursors](references/components-list.md#%EF%B8%8F-cursors-5)

5. **Animated Buttons** → Shimmer, Ripple, Rainbow, Gradient
   - No extra dependencies
   - See: [references/components-list.md#buttons](references/components-list.md#-buttons-5)

6. **Special Effects** → Confetti, Meteors, Neon Border, Glow Border
   - See: [references/components-list.md#special-effects](references/components-list.md#-special-effects-12)

**For complete implementation details** (props, full code, installation):
Fetch https://inspira-ui.com/docs/llms-full.txt - LLM-optimized documentation with structured props tables and working code examples.

## Core Usage Patterns

### Pattern 1: Animated Landing Page

```vue
<template>
  <AuroraBackground>
    <Motion
      :initial="{ opacity: 0, y: 40, filter: 'blur(10px)' }"
      :while-in-view="{ opacity: 1, y: 0, filter: 'blur(0px)' }"
      :transition="{ delay: 0.3, duration: 0.8, ease: 'easeInOut' }"
      class="relative flex flex-col items-center gap-4 px-4"
    >
      <div class="text-center text-3xl font-bold md:text-7xl">
        Your amazing headline
      </div>
      <ShimmerButton>Get Started</ShimmerButton>
    </Motion>
  </AuroraBackground>
</template>

<script setup lang="ts">
import { Motion } from "motion-v";
import AuroraBackground from "~/components/ui/AuroraBackground.vue";
import ShimmerButton from "~/components/ui/ShimmerButton.vue";
</script>
```

### Pattern 2: Props with TypeScript Interfaces

```vue
<script setup lang="ts">
// ALWAYS use interface-based props
interface Props {
  title: string;
  count?: number;
  variant?: "primary" | "secondary";
}

const props = withDefaults(defineProps<Props>(), {
  count: 0,
  variant: "primary",
});
</script>
```

### Pattern 3: Explicit Imports (Critical for Vue.js Compatibility)

```vue
<script setup lang="ts">
// ALWAYS include explicit imports even with Nuxt auto-imports
import { ref, onMounted, computed } from "vue";
import { useWindowSize } from "@vueuse/core";

const { width } = useWindowSize();
</script>
```

### Pattern 4: WebGL Component Cleanup

```vue
<script setup lang="ts">
import { onUnmounted } from "vue";

let animationFrame: number;
let renderer: any;

onUnmounted(() => {
  // CRITICAL: Clean up WebGL resources to prevent memory leaks
  if (animationFrame) cancelAnimationFrame(animationFrame);
  if (renderer) renderer.dispose();
});
</script>
```

### Pattern 5: Client-Only Wrapper (Nuxt)

```vue
<template>
  <ClientOnly>
    <FluidCursor />
  </ClientOnly>
</template>
```

## Critical Pitfalls to Avoid

### 1. Accessibility Bug (CRITICAL)

The original Inspira UI docs have `--destructive-foreground` set to the same color as `--destructive`, making text invisible. Use the corrected value:

```css
:root {
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.985 0 0); /* CORRECTED */
}
```

### 2. Missing CSS Imports

```css
/* REQUIRED in main.css */
@import "tailwindcss";
@import "tw-animate-css";  /* Often forgotten! */
```

### 3. Wrong Props Syntax

```typescript
// DON'T: Object syntax
const props = defineProps({ title: { type: String } });

// DO: Interface syntax
interface Props { title: string; }
const props = defineProps<Props>();
```

### 4. Three.js Without ClientOnly (Nuxt)

```vue
<!-- WRONG: Will fail during SSR -->
<GithubGlobe :markers="markers" />

<!-- CORRECT -->
<ClientOnly>
  <GithubGlobe :markers="markers" />
</ClientOnly>
```

### 5. Using Enums Instead of `as const`

```typescript
// DON'T: TypeScript enums
enum ButtonVariant { Primary = "primary" }

// DO: as const objects
const ButtonVariants = { Primary: "primary" } as const;
```

## Token Efficiency

**Average Token Savings**: ~65%
- Without skill: ~15k tokens (trial-and-error with setup)
- With skill: ~5k tokens (direct implementation)

**Errors Prevented**: 13+ common issues including:
1. Critical accessibility bug (destructive-foreground)
2. TailwindCSS v4 CSS variables misconfiguration
3. Missing `@import "tw-animate-css"`
4. Motion-V setup issues
5. Three.js/OGL without ClientOnly
6. Props typed with object syntax instead of interfaces
7. Missing explicit imports

## Detailed Documentation

**For complete setup with all CSS variables**: [references/SETUP.md](refe