Inspira Ui

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
• Quick Start
• Component Selection
• Core Patterns
• Critical Pitfalls
• Detailed References

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

# 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:

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 for complete CSS configuration with OkLch colors.

4. Verify Setup

./scripts/verify-setup.sh

5. Copy Components

Browse 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

2. Text Animations → Morphing Text, Glitch, Hyper Text, Sparkles Text

• See: references/components-list.md#text-animations

3. 3D Visualizations → Globe, 3D Carousel, Icon Cloud, World Map

• Dependencies: bun add three @types/three
• See: references/components-list.md#visualization

4. Interactive Cursors → Fluid Cursor, Tailed Cursor, Smooth Cursor

• Dependencies: bun add ogl (for WebGL cursors)
• See: references/components-list.md#cursors

5. Animated Buttons → Shimmer, Ripple, Rainbow, Gradient

• No extra dependencies
• See: references/components-list.md#buttons

6. Special Effects → Confetti, Meteors, Neon Border, Glow Border

• See: references/components-list.md#special-effects

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

<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

<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)

<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

<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)

<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:

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

2. Missing CSS Imports

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

3. Wrong Props Syntax

// 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)

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

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

5. Using Enums Instead of as const

// 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

For all 120+ components with dependencies: references/components-list.md

For troubleshooting common issues: references/TROUBLESHOOTING.md

For TypeScript patterns and conventions: references/CODE_PATTERNS.md

Keywords

Frameworks: Vue, Vue 3, Nuxt, Nuxt 4, Composition API, script setup

Styling: TailwindCSS v4, OkLch, CSS variables, dark mode

Animation: motion-v, GSAP, Three.js, WebGL, OGL, canvas

Components: aurora background, shimmer button, morphing text, 3D globe, fluid cursor, confetti, neon border, icon cloud, flip card, particles

Use Cases: landing pages, hero sections, animated backgrounds, interactive UI, marketing sites, portfolios, 3D websites

Problems Solved: Vue animations, Nuxt animations, animated components, 3D effects, particle effects, modern UI effects

Resources

• Official Documentation: https://inspira-ui.com/docs
• LLM-Optimized Docs: https://inspira-ui.com/docs/llms-full.txt (complete props, code examples, installation)
• Component Gallery: https://inspira-ui.com/components
• GitHub Repository: https://github.com/unovue/inspira-ui
• Discord Community: https://discord.gg/Xbh5DwJRc9

---

Production Status: ✅ Production-Ready Token Efficiency: ✅ ~65% savings Error Prevention: ✅ 13+ common issues prevented Last Updated: 2025-11-12

Inspira UI Code Patterns & Best Practices

This guide covers TypeScript patterns, Vue 3 Composition API conventions, and best practices for working with Inspira UI components.

Component File Structure

Standard structure for all Inspira UI components:

<template>
  <!-- Template code -->
</template>

<script setup lang="ts">
// 1. Imports (explicit, always)
import { ref, computed, onMounted, onUnmounted } from "vue";

// 2. Props interface
interface Props {
  title: string;
  count?: number;
  isActive?: boolean;
}

// 3. Props definition with defaults
const props = withDefaults(defineProps<Props>(), {
  count: 0,
  isActive: false,
});

// 4. Emits
const emit = defineEmits<{
  click: [value: string];
  update: [count: number];
}>();

// 5. Component logic
const state = ref(0);
const computed = computed(() => props.count * 2);

// 6. Lifecycle hooks
onMounted(() => {
  // Setup
});

onUnmounted(() => {
  // Cleanup
});
</script>

<style scoped>
/* Scoped styles if needed */
</style>

---

Props Definition

DO: Interface-Based Props

<script setup lang="ts">
interface Props {
  title: string;
  count?: number;
  variant?: "primary" | "secondary" | "destructive";
  items?: string[];
}

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

DON'T: Object Syntax Props

<script setup lang="ts">
// AVOID THIS - less type-safe, more verbose
const props = defineProps({
  title: { type: String, required: true },
  count: { type: Number, default: 0 },
  variant: {
    type: String,
    default: "primary",
    validator: (v) => ["primary", "secondary", "destructive"].includes(v),
  },
});
</script>

---

Explicit Imports

Always include explicit imports, even in Nuxt with auto-imports:

<script setup lang="ts">
// ALWAYS DO THIS for Vue.js compatibility
import { ref, onMounted, computed, watch } from "vue";
import { useWindowSize, useMouse, useIntersectionObserver } from "@vueuse/core";
import { Motion } from "motion-v";

// This ensures components work in both Vue and Nuxt
// and makes dependencies clear
</script>

---

Constants Naming

Use CAPS_SNAKE_CASE for constants, with component prefix:

// Component-specific constants
const AURORA_GRADIENT_COLORS = ["#ff0000", "#00ff00", "#0000ff"] as const;
const BUTTON_ANIMATION_DURATION = 300;
const PARTICLE_DEFAULT_COUNT = 100;
const GLOBE_ROTATION_SPEED = 0.005;

// Configuration objects
const SHIMMER_BUTTON_CONFIG = {
  duration: 300,
  easing: "ease-in-out",
  colors: ["#3b82f6", "#8b5cf6"],
} as const;

---

Avoid Enums - Use as const Objects

DO: Use as const Objects

export const ButtonVariants = {
  Primary: "primary",
  Secondary: "secondary",
  Destructive: "destructive",
  Ghost: "ghost",
} as const;

export type ButtonVariant = (typeof ButtonVariants)[keyof typeof ButtonVariants];

// Usage
const variant: ButtonVariant = ButtonVariants.Primary;

DON'T: Use TypeScript Enums

// AVOID - Enums have runtime overhead and tree-shaking issues
enum ButtonVariants {
  Primary = "primary",
  Secondary = "secondary",
  Destructive = "destructive",
}

---

Motion-V Animation Patterns

Basic Animation

<template>
  <Motion
    :initial="{ opacity: 0, y: 20 }"
    :animate="{ opacity: 1, y: 0 }"
    :transition="{ duration: 0.5, ease: 'easeOut' }"
  >
    <div>Animated content</div>
  </Motion>
</template>

<script setup lang="ts">
import { Motion } from "motion-v";
</script>

While In View Animation

<template>
  <Motion
    :initial="{ opacity: 0, scale: 0.8 }"
    :while-in-view="{ opacity: 1, scale: 1 }"
    :transition="{ delay: 0.3, duration: 0.8 }"
  >
    <div>Animates when scrolled into view</div>
  </Motion>
</template>

Hover Animation

<template>
  <Motion
    :initial="{ scale: 1 }"
    :while-hover="{ scale: 1.05 }"
    :transition="{ type: 'spring', stiffness: 300 }"
  >
    <button>Hover me</button>
  </Motion>
</template>

---

VueUse Composables Pattern

<script setup lang="ts">
import { ref, computed } from "vue";
import {
  useWindowSize,
  useMouse,
  useIntersectionObserver,
  useElementSize,
  useThrottleFn,
} from "@vueuse/core";

// Window dimensions
const { width: windowWidth, height: windowHeight } = useWindowSize();

// Mouse position
const { x: mouseX, y: mouseY } = useMouse();

// Element intersection
const target = ref<HTMLElement | null>(null);
const isVisible = ref(false);

useIntersectionObserver(target, ([{ isIntersecting }]) => {
  isVisible.value = isIntersecting;
});

// Throttled handler for performance
const handleScroll = useThrottleFn(() => {
  // Heavy computation
}, 100);
</script>

---

Responsive Design Patterns

Tailwind Responsive Classes

<template>
  <div class="text-2xl md:text-4xl lg:text-6xl xl:text-8xl">
    Responsive Text
  </div>

  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
    <!-- Responsive grid -->
  </div>

  <div class="hidden md:block">
    <!-- Desktop only -->
  </div>

  <div class="block md:hidden">
    <!-- Mobile only -->
  </div>
</template>

Programmatic Responsiveness

<script setup lang="ts">
import { computed } from "vue";
import { useWindowSize } from "@vueuse/core";

const { width } = useWindowSize();

const isMobile = computed(() => width.value < 768);
const isTablet = computed(() => width.value >= 768 && width.value < 1024);
const isDesktop = computed(() => width.value >= 1024);

const particleCount = computed(() => {
  if (isMobile.value) return 50;
  if (isTablet.value) return 100;
  return 200;
});
</script>

---

Dark Mode Patterns

CSS Variables Approach

<template>
  <div class="bg-background text-foreground">
    <!-- Automatically switches with dark mode -->
  </div>

  <button class="bg-primary text-primary-foreground hover:bg-primary/90">
    Primary Button
  </button>

  <div class="border border-border bg-card text-card-foreground">
    Card content
  </div>
</template>

Conditional Styling

<template>
  <div
    :class="[
      'transition-colors duration-200',
      isDark ? 'bg-gray-900' : 'bg-white',
    ]"
  >
    Content
  </div>
</template>

<script setup lang="ts">
import { useDark } from "@vueuse/core";

const isDark = useDark();
</script>

---

WebGL/Canvas Cleanup Pattern

Critical for preventing memory leaks:

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from "vue";
import * as THREE from "three";

const containerRef = ref<HTMLElement | null>(null);
let renderer: THREE.WebGLRenderer | null = null;
let scene: THREE.Scene | null = null;
let camera: THREE.PerspectiveCamera | null = null;
let animationId: number | null = null;

onMounted(() => {
  if (!containerRef.value) return;

  // Initialize Three.js
  scene = new THREE.Scene();
  camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight);
  renderer = new THREE.WebGLRenderer({ antialias: true });

  containerRef.value.appendChild(renderer.domElement);

  // Animation loop
  const animate = () => {
    animationId = requestAnimationFrame(animate);
    renderer?.render(scene!, camera!);
  };
  animate();
});

onUnmounted(() => {
  // CRITICAL: Clean up WebGL resources
  if (animationId) cancelAnimationFrame(animationId);

  if (renderer) {
    renderer.dispose();
    renderer.forceContextLoss();
    renderer.domElement.remove();
    renderer = null;
  }

  if (scene) {
    scene.traverse((object) => {
      if (object instanceof THREE.Mesh) {
        object.geometry.dispose();
        if (Array.isArray(object.material)) {
          object.material.forEach((m) => m.dispose());
        } else {
          object.material.dispose();
        }
      }
    });
    scene = null;
  }

  camera = null;
});
</script>

---

Client-Only Pattern (Nuxt)

For browser-only components:

<template>
  <ClientOnly>
    <FluidCursor />
    <template #fallback>
      <div class="h-full w-full animate-pulse bg-muted" />
    </template>
  </ClientOnly>
</template>

<script setup lang="ts">
// No special imports needed for ClientOnly in Nuxt
</script>

---

Event Handling Pattern

<script setup lang="ts">
const emit = defineEmits<{
  click: [event: MouseEvent];
  update: [value: string];
  change: [oldValue: string, newValue: string];
}>();

const handleClick = (event: MouseEvent) => {
  // Process event
  emit("click", event);
};

const updateValue = (newValue: string) => {
  const oldValue = currentValue.value;
  currentValue.value = newValue;
  emit("change", oldValue, newValue);
};
</script>

---

Performance Optimization Patterns

Computed Properties

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

// Cache expensive calculations
const filteredItems = computed(() => {
  return props.items.filter((item) => item.active);
});

const sortedAndFiltered = computed(() => {
  return filteredItems.value.sort((a, b) => a.priority - b.priority);
});
</script>

Watch with Debounce

<script setup lang="ts">
import { ref, watch } from "vue";
import { useDebounceFn } from "@vueuse/core";

const searchQuery = ref("");

const performSearch = useDebounceFn((query: string) => {
  // API call or heavy operation
}, 300);

watch(searchQuery, (newQuery) => {
  performSearch(newQuery);
});
</script>

Conditional Rendering

<template>
  <!-- Use v-show for frequent toggles (keeps DOM) -->
  <div v-show="isVisible">Frequently toggled</div>

  <!-- Use v-if for rare toggles (removes DOM) -->
  <HeavyComponent v-if="shouldLoad" />
</template>

---

Slot Patterns

<!-- Component definition -->
<template>
  <div class="wrapper">
    <slot name="header" :title="title">
      <!-- Default header -->
      <h2>{{ title }}</h2>
    </slot>

    <slot>
      <!-- Default content -->
    </slot>

    <slot name="footer" :actions="actions">
      <!-- Default footer -->
    </slot>
  </div>
</template>

<!-- Usage -->
<MyComponent title="Hello">
  <template #header="{ title }">
    <h1>Custom: {{ title }}</h1>
  </template>

  <p>Main content</p>

  <template #footer="{ actions }">
    <button v-for="action in actions" :key="action.id">
      {{ action.label }}
    </button>
  </template>
</MyComponent>

---

Error Boundary Pattern

<script setup lang="ts">
import { onErrorCaptured, ref } from "vue";

const error = ref<Error | null>(null);

onErrorCaptured((err) => {
  error.value = err;
  // Return false to prevent error from propagating
  return false;
});
</script>

<template>
  <div v-if="error" class="error-boundary">
    <p>Something went wrong: {{ error.message }}</p>
    <button @click="error = null">Retry</button>
  </div>
  <slot v-else />
</template>

---

Summary: Key Conventions

1. Always use interface-based props with defineProps<Props>() 2. Include explicit imports for Vue composables 3. Use `as const` objects instead of enums 4. Name constants with CAPS_SNAKE_CASE and component prefix 5. Clean up WebGL/Canvas resources in onUnmounted 6. Wrap browser-only components in <ClientOnly> for Nuxt 7. Use VueUse composables for reactive utilities 8. Leverage Motion-V for declarative animations 9. Follow CSS variable patterns for theming 10. Optimize performance with computed properties and throttling

---

Last Updated: 2025-11-12

Inspira UI Components Quick Reference

Complete list of all 120+ components organized by category.

💡 Need complete implementation details? For full props documentation, code examples, and installation instructions, fetch:

https://inspira-ui.com/docs/llms-full.txt (LLM-optimized documentation)

🌌 Backgrounds (24)

🔘 Buttons (5)

🃏 Cards (6)

🖱️ Cursors (5)

📱 Device Mocks (2)

✏️ Input and Forms (5)

🎨 Miscellaneous (24)

✨ Special Effects (12)

📝 Text Animations (24)

📊 Visualization (21)

🧱 Blocks (2)

Dependencies Summary

Core (Required)

• @vueuse/core - Vue composition utilities
• motion-v - Vue animation library
• clsx - Class name utility
• tailwind-merge - Tailwind class merging
• class-variance-authority - Variant utilities
• tw-animate-css - Tailwind animation utilities

Optional (Component-Specific)

• three & @types/three - For 3D components (Globe, Cosmic Portal, etc.)
• ogl - For WebGL/shader components (Fluid Cursor, Liquid Background, etc.)
• gsap - For advanced animations (select components)
• canvas-confetti - For Confetti component
• spline - For Spline component

Usage Pattern

1. Browse: Visit https://inspira-ui.com/components 2. Copy: Copy the component code you need 3. Paste: Add to your components/ui/ directory 4. Install: Install component-specific dependencies if needed 5. Customize: Modify colors, sizes, animations to fit your design

Component Files Location

When copying components, typical structure:

your-project/
├── components/
│   └── ui/
│       ├── AuroraBackground.vue
│       ├── ShimmerButton.vue
│       ├── FlipCard.vue
│       └── ...
├── lib/
│   └── utils.ts (cn utility)
└── assets/
    └── main.css (CSS variables)

Quick Links

• Component Gallery: https://inspira-ui.com/components
• Installation Guide: https://inspira-ui.com/docs/getting-started/installation
• GitHub: https://github.com/unovue/inspira-ui
• Discord: https://discord.gg/Xbh5DwJRc9

---

Last Updated: 2025-11-12 Total Components: 120+ Blocks: 2

Inspira UI Complete Setup Guide

This guide contains the complete setup instructions for integrating Inspira UI into your Vue 3 or Nuxt 4 project.

Prerequisites

Before starting, ensure you have:

• Vue 3 or Nuxt 4 project
• TailwindCSS v4 (required - for v3, use Inspira UI v1)
• Node.js 18+
• Bun (recommended) or npm/pnpm

Step 1: Install TailwindCSS v4

Follow the official TailwindCSS installation guide.

Step 2: Install Core Dependencies

Install utility libraries and TailwindCSS animation utilities:

bun add -d clsx tailwind-merge class-variance-authority tw-animate-css

Install VueUse and Motion-V for animations:

bun add @vueuse/core motion-v

Follow the Motion-V Vue/Nuxt setup guide to configure motion-v in your project.

Step 3: Configure CSS Variables

Add the following to your main.css or global CSS file:

@import "tailwindcss";
@import "tw-animate-css";

@custom-variant dark (&:is(.dark *));

:root {
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.141 0.005 285.823);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.141 0.005 285.823);
  --primary: oklch(0.21 0.006 285.885);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.967 0.001 286.375);
  --secondary-foreground: oklch(0.21 0.006 285.885);
  --muted: oklch(0.967 0.001 286.375);
  --muted-foreground: oklch(0.552 0.016 285.938);
  --accent: oklch(0.967 0.001 286.375);
  --accent-foreground: oklch(0.21 0.006 285.885);
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.985 0 0);
  --border: oklch(0.92 0.004 286.32);
  --input: oklch(0.92 0.004 286.32);
  --ring: oklch(0.705 0.015 286.067);
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.141 0.005 285.823);
}

.dark {
  --background: oklch(0.141 0.005 285.823);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.141 0.005 285.823);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.141 0.005 285.823);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --primary-foreground: oklch(0.21 0.006 285.885);
  --secondary: oklch(0.274 0.006 286.033);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.274 0.006 286.033);
  --muted-foreground: oklch(0.705 0.015 286.067);
  --accent: oklch(0.274 0.006 286.033);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.396 0.141 25.723);
  --destructive-foreground: oklch(0.637 0.237 25.331);
  --border: oklch(0.274 0.006 286.033);
  --input: oklch(0.274 0.006 286.033);
  --ring: oklch(0.442 0.017 285.786);
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-destructive-foreground: var(--destructive-foreground);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);

  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  body {
    @apply bg-background text-foreground;
  }
}

html {
  color-scheme: light dark;
}
html.dark {
  color-scheme: dark;
}
html.light {
  color-scheme: light;
}

CRITICAL BUG FIX: The CSS variables above have been corrected from the original Inspira UI documentation. The original docs have an accessibility bug where --destructive-foreground in light mode is set to the same value as --destructive (both oklch(0.577 0.245 27.325)), making destructive text invisible. This version uses oklch(0.985 0 0) for proper contrast.

Step 4: Setup CN Utility

Create lib/utils.ts (or appropriate location in your project):

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

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

export type ObjectValues<T> = T[keyof T];

Step 5: Optional Icon Support

Many components use icons. Install Iconify Vue for optimal experience:

Follow the Iconify Vue guide for installation.

Step 6: Optional Dependencies

Install based on the components you need:

For 3D Components (Globe, Cosmic Portal, 3D Carousel, etc.)

bun add three @types/three

For OGL/WebGL Components (Fluid Cursor, Liquid Background, Neural Background, etc.)

bun add ogl

For GSAP Animations (certain advanced animations)

bun add gsap

For Confetti Effect

bun add canvas-confetti

Verification Checklist

After setup, verify:

• [ ] TailwindCSS v4 is installed and configured
• [ ] @import "tailwindcss" is in your CSS
• [ ] @import "tw-animate-css" is in your CSS
• [ ] CSS variables are defined in :root and .dark
• [ ] @theme inline block is present
• [ ] cn() utility is created and accessible
• [ ] Motion-V is configured per their docs
• [ ] Optional dependencies installed for your components

Quick Verification Command

After setup, run the verification script:

./scripts/verify-setup.sh

This will check that all required dependencies are installed and configured correctly.

Nuxt-Specific Setup

For Nuxt 4 projects, additional configuration:

nuxt.config.ts

export default defineNuxtConfig({
  // Enable TypeScript
  typescript: {
    strict: true,
  },

  // Configure motion-v if using as module
  modules: [
    // Add any Nuxt modules needed
  ],

  // Tailwind v4 is auto-configured in Nuxt 4
});

ClientOnly Wrapper

For browser-only components (WebGL, Canvas, etc.):

<template>
  <ClientOnly>
    <FluidCursor />
  </ClientOnly>
</template>

Project Structure

Recommended file organization after setup:

your-project/
├── assets/
│   └── main.css                 # CSS variables and imports
├── components/
│   └── ui/                      # Inspira UI components
│       ├── AuroraBackground.vue
│       ├── ShimmerButton.vue
│       └── ...
├── lib/
│   └── utils.ts                 # cn() utility
└── package.json                 # Dependencies

Using Components

Inspira UI is a copy-paste library:

1. Browse: Visit inspira-ui.com/components 2. Select: Choose the component you need 3. Copy: Copy the component code 4. Paste: Add to your components/ui/ directory 5. Import: Import and use in your pages/components 6. Customize: Modify to fit your design

Next Steps

• Browse components: https://inspira-ui.com/components
• Check component dependencies: components-list.md
• Learn code patterns: CODE_PATTERNS.md
• Troubleshoot issues: TROUBLESHOOTING.md

---

Last Updated: 2025-11-12

Inspira UI Troubleshooting Guide

Common issues and solutions when working with Inspira UI components.

Issue 1: TailwindCSS v4 Not Working

Symptoms:

• Components not styling correctly
• CSS variables undefined
• Tailwind classes not applied

Solution: 1. Verify TailwindCSS v4 is installed: bun add tailwindcss@next 2. Check @import "tailwindcss" is in your CSS 3. Ensure CSS variables are defined in :root and .dark 4. Verify @theme inline block is present 5. Check that @layer base styles are applied

Verification:

grep -r "@import \"tailwindcss\"" src/assets/
grep -r "var(--background)" src/assets/

---

Issue 2: Motion-V Animations Not Working

Symptoms:

• Motion components render but don't animate
• No transitions or movements
• Static content

Solution: 1. Install motion-v: bun add motion-v 2. Follow Motion-V setup guide 3. For Nuxt, ensure proper plugin configuration 4. Import Motion component: import { Motion } from "motion-v" 5. Verify you're using correct props (:initial, :animate, :transition)

Example Fix:

<script setup lang="ts">
// Correct import
import { Motion } from "motion-v";
</script>

<template>
  <!-- Correct usage -->
  <Motion
    :initial="{ opacity: 0 }"
    :animate="{ opacity: 1 }"
    :transition="{ duration: 0.5 }"
  >
    Content
  </Motion>
</template>

---

Issue 3: Three.js Components Not Rendering

Symptoms:

• 3D components (Globe, Cosmic Portal, 3D Carousel) show blank
• Canvas element present but empty
• WebGL context errors

Solution: 1. Install Three.js: bun add three @types/three 2. Wrap in <ClientOnly> for Nuxt 3. Check browser console for WebGL errors 4. Verify canvas element is rendering 5. Ensure proper cleanup in onUnmounted

Example:

<template>
  <ClientOnly>
    <GithubGlobe :markers="markers" />
  </ClientOnly>
</template>

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

onUnmounted(() => {
  // Clean up WebGL context if needed
});
</script>

---

Issue 4: OGL Components Not Working

Symptoms:

• OGL-based components (Fluid Cursor, Liquid Background) not displaying
• Shader compilation errors
• WebGL context issues

Solution: 1. Install OGL: bun add ogl 2. Ensure WebGL support in browser 3. Wrap in <ClientOnly> for SSR 4. Check for shader compilation errors in console 5. Verify proper disposal of resources

Debug:

// Check WebGL support
const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2') || canvas.getContext('webgl');
console.log('WebGL supported:', !!gl);

---

Issue 5: Props Type Errors

Symptoms:

• TypeScript errors with component props
• Runtime type mismatches
• Default values not applied

Solution: 1. Use interface-based props, not object syntax 2. Use withDefaults() for default values 3. Ensure explicit imports for types 4. Check props are correctly typed in parent component

Correct Pattern:

<script setup lang="ts">
// DO THIS
interface Props {
  title: string;
  count?: number;
}

const props = withDefaults(defineProps<Props>(), {
  count: 0,
});

// DON'T DO THIS
// const props = defineProps({
//   title: { type: String, required: true },
// });
</script>

---

Issue 6: Icons Not Showing

Symptoms:

• Icon components render empty
• Missing icon SVGs
• Icon library not found

Solution: 1. Install Iconify Vue: Follow Iconify guide 2. Or replace <Icon> with your preferred icon library 3. Or use SVG icons directly 4. Check icon name format (e.g., "mdi:home")

Alternative:

<!-- Direct SVG -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
  <path d="..." />
</svg>

<!-- Or use another library -->
<LucideIcon name="home" />

---

Issue 7: CSS Variables Not Applied

Symptoms:

• Colors or sizing not working as expected
• Default browser styles showing
• Dark mode not switching

Solution: 1. Verify :root CSS variables are defined 2. Check .dark variants are set up 3. Ensure @theme inline block includes all variables 4. Use var(--variable-name) syntax or Tailwind classes 5. Check for typos in variable names

Debug:

// In browser console
getComputedStyle(document.documentElement).getPropertyValue('--background');

---

Issue 8: Component Dependencies Missing

Symptoms:

• Component imports failing
• Features not working
• Runtime errors about missing modules

Solution: 1. Check component documentation for specific dependencies 2. Install required packages (Three.js, OGL, GSAP, etc.) 3. Verify peer dependencies are satisfied 4. Check for component-specific setup requirements 5. See components-list.md for dependency matrix

Common Dependencies:

# 3D components
bun add three @types/three

# WebGL shaders
bun add ogl

# Advanced animations
bun add gsap

# Confetti
bun add canvas-confetti

---

Issue 9: Accessibility Bug - Destructive Colors

Symptoms:

• Text on destructive backgrounds is invisible
• Poor contrast on error states
• Red text on red background

Root Cause: Original Inspira UI docs set --destructive-foreground to same color as --destructive.

Solution: Use the corrected CSS variables from this skill:

:root {
  --destructive: oklch(0.577 0.245 27.325);
  --destructive-foreground: oklch(0.985 0 0); /* CORRECTED - was same as destructive */
}

.dark {
  --destructive: oklch(0.396 0.141 25.723);
  --destructive-foreground: oklch(0.637 0.237 25.331);
}

---

Issue 10: SSR/Hydration Mismatches (Nuxt)

Symptoms:

• Hydration warnings in console
• Content flashing or jumping
• Different rendering on server vs client

Solution: 1. Wrap browser-only components in <ClientOnly> 2. Check for window or document access in setup 3. Use onMounted for browser-specific code 4. Verify no random values in SSR

Pattern:

<template>
  <ClientOnly>
    <FluidCursor />
    <template #fallback>
      <!-- Optional placeholder during SSR -->
      <div class="cursor-placeholder" />
    </template>
  </ClientOnly>
</template>

---

Issue 11: Animation Performance Issues

Symptoms:

• Choppy animations
• High CPU/GPU usage
• Frame drops

Solution: 1. Use transform and opacity for animations (GPU-accelerated) 2. Avoid animating width, height, top, left 3. Reduce particle counts for particle effects 4. Implement proper cleanup for WebGL resources 5. Use will-change sparingly

Performance Pattern:

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

// Store references for cleanup
let animationFrame: number;
let renderer: any;

onUnmounted(() => {
  if (animationFrame) cancelAnimationFrame(animationFrame);
  if (renderer) renderer.dispose();
});
</script>

---

Issue 12: Build/Bundle Size Issues

Symptoms:

• Large bundle size
• Slow builds
• Tree-shaking not working

Solution: 1. Only copy components you need 2. Import specific utilities, not entire libraries 3. Check for duplicate dependencies 4. Use dynamic imports for heavy components

Optimized Import:

// Specific imports (smaller bundle)
import { useWindowSize } from "@vueuse/core";

// Not entire library
// import * as VueUse from "@vueuse/core";

---

Issue 13: Nuxt Auto-Import Conflicts

Symptoms:

• Duplicate identifier errors
• Vue composables not working
• Import conflicts

Solution: 1. Add explicit imports even with auto-imports enabled 2. Check nuxt.config for auto-import settings 3. Verify no naming conflicts with local composables

Safe Pattern:

<script setup lang="ts">
// Always include explicit imports for compatibility
import { ref, onMounted, computed } from "vue";
import { useWindowSize } from "@vueuse/core";
</script>

---

Quick Diagnostic Commands

# Check package versions
bun pm ls | grep -E "tailwind|motion|three|ogl"

# Verify CSS imports
grep -r "@import" src/assets/

# Check for missing dependencies
bun install --dry-run

# Run setup verification
./scripts/verify-setup.sh

---

Getting More Help

• Official Docs: https://inspira-ui.com/docs
• GitHub Issues: https://github.com/unovue/inspira-ui/issues
• Discord Community: https://discord.gg/Xbh5DwJRc9
• Component Gallery: https://inspira-ui.com/components

---

Last Updated: 2025-11-12