inspira-ui

Inspira UI - 动画 Vue/Nuxt 组件库

Inspira UI 是一个包含 120 多个可复用动画组件的集合，由 TailwindCSS v4、motion-v、GSAP 和 Three.js 提供支持，旨在帮助你更快地构建精美的 Vue 和 Nuxt 应用。

目录

• 适用场景
• 快速开始
• 组件选择
• 核心模式
• 关键注意事项
• 详细参考资料

适用场景

在以下场景中使用 Inspira UI：

• 动画落地页，包含主视觉区、用户评价和特效
• 现代 Web 应用，需要 3D 可视化和交互元素
• 营销网站，需要醒目的背景和文本动画
• 作品集网站，包含图片库、轮播图和展示效果
• 交互体验，包含自定义光标、特殊效果和粒子系统
• Vue 3 或 Nuxt 4 项目，需要可用于生产环境的动画组件

主要优势：

• 120 多个可复制粘贴的组件（并非传统的 npm 库）
• 全面支持 TypeScript 和 Vue 3 Composition API
• 使用 OkLch 色彩空间的 TailwindCSS v4
• 支持响应式设计并针对移动设备优化
• 免费开源（MIT 许可证）

快速开始

1. 安装核心依赖

# 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. 设置 CN 工具

创建 lib/utils.ts：

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

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

3. 配置 CSS 变量

添加到 main.css。有关使用 OkLch 颜色的完整 CSS 配置，请参阅 references/SETUP.md。

4. 验证设置

./scripts/verify-setup.sh

5. 复制组件

浏览 inspira-ui.com/components，将所需组件复制到 components/ui/。

安全安装

此操作会安装 6 个以上的软件包，其中包括依赖树庞大的 3D 库（three、ogl）。安装前，请遵循供应链安全最佳实践：

• 阻止安装后脚本 — npm config set ignore-scripts true（或使用 Bun：默认禁用）
• 冷却期 — 等待 7 天，让社区审查新版本的软件包
• 安装前审核 — 运行 socket package score npm <pkg> 或使用 socket npm install <pkg> 检查软件包

加载 dependency-upgrade 技能，获取完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

组件选择工作流

你需要哪种效果？

1. 背景效果 → Aurora、Cosmic Portal、Particles、Neural Background

   • 参阅：references/components-list.md#backgrounds

2. 文本动画 → Morphing Text、Glitch、Hyper Text、Sparkles Text

   • 参阅：references/components-list.md#text-animations

3. 3D 可视化 → Globe、3D Carousel、Icon Cloud、World Map

   • 依赖：bun add three @types/three
   • 参阅：references/components-list.md#visualization

4. 交互式光标 → Fluid Cursor、Tailed Cursor、Smooth Cursor

   • 依赖：bun add ogl（用于 WebGL 光标）
   • 参阅：references/components-list.md#cursors

5. 动画按钮 → Shimmer、Ripple、Rainbow、Gradient

   • 无需额外依赖
   • 参阅：references/components-list.md#buttons

6. 特殊效果 → Confetti、Meteors、Neon Border、Glow Border

   • 参阅：references/components-list.md#special-effects

查看完整实现详情（属性、完整代码、安装说明）： 获取 https://inspira-ui.com/docs/llms-full.txt — 面向大模型优化的文档，包含结构化属性表和可运行的代码示例。

核心使用模式

模式 1：动画落地页

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

模式 2：使用 TypeScript 接口定义属性

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

模式 3：显式导入（对 Vue.js 兼容性至关重要）

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

模式 4：WebGL 组件清理

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

模式 5：仅客户端包装器（Nuxt）

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

需要避免的关键问题

1. 无障碍访问问题（严重）

原始 Inspira UI 文档将 --destructive-foreground 设置为与 --destructive 相同的颜色，导致文本不可见。请使用修正后的值：

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

2. 缺少 CSS 导入

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

3. Props 语法错误

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

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

4. Nuxt 中未使用 ClientOnly 的 Three.js

<GithubGlobe :markers="markers" />


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

5. 使用枚举而非 as const

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

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

Token 效率

平均 Token 节省：约 65%

• 不使用技能：约 15k 个 Token（通过反复试错完成配置）
• 使用技能：约 5k 个 Token（直接实现）

可避免的错误：13 个以上的常见问题，包括：

1. 严重的无障碍访问问题（destructive-foreground）
2. TailwindCSS v4 CSS 变量配置错误
3. 缺少 @import "tw-animate-css"
4. Motion-V 设置问题
5. Three.js/OGL 未使用 ClientOnly
6. 使用对象语法而非接口定义 Props 类型
7. 缺少显式导入

详细文档

完整配置及所有 CSS 变量：references/SETUP.md

全部 120 多个组件及其依赖：references/components-list.md

常见问题排查：references/TROUBLESHOOTING.md

TypeScript 模式和约定：references/CODE_PATTERNS.md

关键词

框架：Vue、Vue 3、Nuxt、Nuxt 4、Composition API、script setup

样式：TailwindCSS v4、OkLch、CSS 变量、深色模式

动画：motion-v、GSAP、Three.js、WebGL、OGL、canvas

组件：极光背景、微光按钮、变形文本、3D 地球、流体光标、五彩纸屑、霓虹边框、图标云、翻转卡片、粒子

使用场景：落地页、主视觉区、动画背景、交互式 UI、营销网站、作品集、3D 网站

解决的问题：Vue 动画、Nuxt 动画、动画组件、3D 效果、粒子效果、现代 UI 效果

资源

• 官方文档：https://inspira-ui.com/docs
• 面向 LLM 优化的文档：https://inspira-ui.com/docs/llms-full.txt（完整的 props、代码示例和安装说明）
• 组件库：https://inspira-ui.com/components
• GitHub 仓库：https://github.com/unovue/inspira-ui
• Discord 社区：https://discord.gg/Xbh5DwJRc9

---

生产状态：✅ 可用于生产环境 Token 效率：✅ 节省约 65% 错误预防：✅ 可避免 13 个以上的常见问题 最后更新：2025-11-12