aceternity-ui

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Aceternity UI Skill

Aceternity UI 组件库使用指南

Overview

概述

Aceternity UI is a premium, production-ready React component library designed for Next.js applications. It provides 100+ beautifully animated and interactive components built with Tailwind CSS and Framer Motion. Components are installed via the shadcn CLI and can be customized directly in your codebase.
Key Features:
  • 100+ animated, production-ready components
  • Built for Next.js 13+ with App Router support
  • Full TypeScript support
  • Tailwind CSS v3+ styling
  • Framer Motion animations
  • Dark mode support
  • Copy-paste friendly (not an npm package)
  • Full source code access for customization
Prerequisites:
  • Next.js 13+ (App Router recommended)
  • React 16.8+
  • Tailwind CSS v3+
  • TypeScript (recommended)
  • Node.js 18+ with bun, npm, or pnpm
Aceternity UI是一款面向Next.js应用的优质、可用于生产环境的React组件库。它提供100+款采用Tailwind CSS和Framer Motion构建的精美动画交互组件。组件可通过shadcn CLI安装,并能在你的代码库中直接自定义。
核心特性:
  • 100+款可用于生产环境的动画组件
  • 为Next.js 13+打造,支持App Router
  • 完整的TypeScript支持
  • 基于Tailwind CSS v3+样式
  • Framer Motion动画效果
  • 支持深色模式
  • 支持直接复制粘贴使用(非npm包形式)
  • 可获取完整源代码进行自定义
前置要求:
  • Next.js 13+(推荐使用App Router)
  • React 16.8+
  • Tailwind CSS v3+
  • TypeScript(推荐)
  • Node.js 18+,搭配bun、npm或pnpm

Installation

安装步骤

Initial Setup

初始设置

For New Projects:
bash
undefined
针对新项目:
bash
undefined

Create Next.js project (bun preferred)

创建Next.js项目(推荐使用bun)

bunx create-next-app@latest my-app
bunx create-next-app@latest my-app

or: npx create-next-app@latest my-app

或:npx create-next-app@latest my-app

or: pnpm create next-app@latest my-app

或:pnpm create next-app@latest my-app

cd my-app
cd my-app

Select these options:

选择以下配置选项:

- TypeScript: Yes

- TypeScript:是

- ESLint: Yes

- ESLint:是

- Tailwind CSS: Yes

- Tailwind CSS:是

- src/ directory: Optional

- src/目录:可选

- App Router: Yes (recommended)

- App Router:是(推荐)

- Import alias: @/* (default)

- 导入别名:@/*(默认)


**Initialize Aceternity UI via shadcn CLI:**

```bash

**通过shadcn CLI初始化Aceternity UI:**

```bash

Using bun (preferred)

使用bun(推荐)

bunx --bun shadcn@latest init
bunx --bun shadcn@latest init

Using npm

使用npm

npx shadcn@latest init
npx shadcn@latest init

Using pnpm

使用pnpm

pnpm dlx shadcn@latest init
pnpm dlx shadcn@latest init

During setup:

设置过程中:

- Style: New York (recommended)

- 样式:New York(推荐)

- Color: Zinc (or your preference)

- 颜色:Zinc(或根据你的偏好选择)

- CSS variables: Yes (recommended)

- CSS变量:是(推荐)


**Configure Registry:**

After initialization, update `components.json` to add Aceternity registry:

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "app/globals.css",
    "baseColor": "zinc",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@aceternity": "https://ui.aceternity.com/registry/{name}.json"
  }
}

**配置注册表:**

初始化完成后,更新`components.json`以添加Aceternity注册表:

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "app/globals.css",
    "baseColor": "zinc",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  },
  "registries": {
    "@aceternity": "https://ui.aceternity.com/registry/{name}.json"
  }
}

Installing Components

安装组件

Using shadcn CLI 3.0+ (Namespaced Registry):
bash
undefined
使用shadcn CLI 3.0+(命名空间注册表):
bash
undefined

Install specific component

安装指定组件

bunx shadcn@latest add @aceternity/background-beams
bunx shadcn@latest add @aceternity/background-beams

or: npx shadcn@latest add @aceternity/background-beams

或:npx shadcn@latest add @aceternity/background-beams

or: pnpm dlx shadcn@latest add @aceternity/background-beams

或:pnpm dlx shadcn@latest add @aceternity/background-beams

Component will be added to: components/ui/background-beams.tsx

组件将被添加至:components/ui/background-beams.tsx


**Manual Installation:**

If the registry method doesn't work, install manually:

1. Install required dependencies:
```bash
bun add motion clsx tailwind-merge

**手动安装:**

如果注册表方法无法使用,可手动安装:

1. 安装所需依赖:
```bash
bun add motion clsx tailwind-merge

or: npm install motion clsx tailwind-merge

或:npm install motion clsx tailwind-merge


2. Add utility function to `lib/utils.ts`:
```typescript
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}
  1. Copy component code from ui.aceternity.com to your project

2. 将工具函数添加至`lib/utils.ts`:
```typescript
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}
  1. ui.aceternity.com复制组件代码到你的项目中

Component Categories

组件分类

1. Backgrounds & Effects (28 components)

1. 背景与特效(28款组件)

Create stunning animated backgrounds and visual effects for hero sections and full-page layouts.
Key Components:
  • Background Beams - Animated glowing beams following SVG paths
  • Background Gradient - Smooth gradient backgrounds with transitions
  • Wavy Background - Animated wave patterns
  • Aurora Background - Northern lights inspired animated gradients
  • Sparkles - Particle sparkle effects
  • Meteors - Falling meteor animations
  • Spotlight - Dynamic spotlight effects
  • Grid and Dot Backgrounds - Subtle grid/dot patterns
  • Vortex - Swirling vortex animations
  • Canvas Reveal Effect - Revealing content with canvas animations
Usage Example:
tsx
"use client";
import { BackgroundBeams } from "@/components/ui/background-beams";

export default function HeroSection() {
  return (
    <div className="h-screen w-full relative">
      <div className="max-w-4xl mx-auto z-10 relative p-8">
        <h1 className="text-5xl font-bold">Welcome</h1>
        <p className="text-xl mt-4">Beautiful animated backgrounds</p>
      </div>
      <BackgroundBeams />
    </div>
  );
}
When to Use:
  • Hero sections requiring visual impact
  • Landing pages with animated backgrounds
  • Full-screen sections needing depth
  • Portfolio or agency websites
  • Marketing pages with call-to-actions
为英雄区和全屏布局打造惊艳的动画背景与视觉效果。
核心组件:
  • Background Beams - 沿SVG路径运动的发光光束动画
  • Background Gradient - 带过渡效果的平滑渐变背景
  • Wavy Background - 动画波浪图案
  • Aurora Background - 灵感源自极光的动画渐变背景
  • Sparkles - 粒子闪烁效果
  • Meteors - 流星坠落动画
  • Spotlight - 动态聚光灯效果
  • Grid and Dot Backgrounds - 简约网格/点阵图案
  • Vortex - 漩涡旋转动画
  • Canvas Reveal Effect - 用画布动画展示内容
使用示例:
tsx
"use client";
import { BackgroundBeams } from "@/components/ui/background-beams";

export default function HeroSection() {
  return (
    <div className="h-screen w-full relative">
      <div className="max-w-4xl mx-auto z-10 relative p-8">
        <h1 className="text-5xl font-bold">欢迎访问</h1>
        <p className="text-xl mt-4">精美的动画背景</p>
      </div>
      <BackgroundBeams />
    </div>
  );
}
适用场景:
  • 需要视觉冲击力的英雄区
  • 带动画背景的着陆页
  • 需要层次感的全屏区域
  • 作品集或代理机构网站
  • 带行动号召的营销页面

2. Card Components (15 components)

2. 卡片组件(15款组件)

Interactive cards with hover effects, animations, and 3D transformations.
Key Components:
  • 3D Card Effect - Cards with CSS perspective and 3D transforms
  • Card Hover Effect - Smooth hover animations and transitions
  • Expandable Card - Cards that expand to show more content
  • Focus Cards - Cards that focus/highlight on hover
  • Card Spotlight - Spotlight effect following mouse
  • Glare Card - Holographic glare effect
  • Wobble Card - Playful wobble animations
  • Infinite Moving Cards - Auto-scrolling card carousel
  • Direction Aware Hover - Hover effects based on cursor direction
Usage Example:
tsx
"use client";
import { CardBody, CardContainer, CardItem } from "@/components/ui/3d-card";

export function ProductCard() {
  return (
    <CardContainer>
      <CardBody className="bg-gray-50 rounded-xl p-6">
        <CardItem translateZ="50" className="text-2xl font-bold">
          Product Title
        </CardItem>
        <CardItem translateZ="60" as="p" className="text-sm mt-2">
          Product description goes here
        </CardItem>
        <CardItem translateZ="100" className="w-full mt-4">
          <img src="/product.jpg" className="rounded-xl" alt="Product" />
        </CardItem>
      </CardBody>
    </CardContainer>
  );
}
When to Use:
  • Product showcases
  • Feature highlights
  • Portfolio items
  • Team member profiles
  • Pricing tiers
  • Blog post previews
带悬停效果、动画和3D变换的交互式卡片。
核心组件:
  • 3D Card Effect - 采用CSS透视和3D变换的卡片
  • Card Hover Effect - 流畅的悬停动画与过渡效果
  • Expandable Card - 可展开以显示更多内容的卡片
  • Focus Cards - 悬停时会高亮聚焦的卡片
  • Card Spotlight - 跟随鼠标的聚光灯效果
  • Glare Card - 全息眩光效果
  • Wobble Card - 趣味摇摆动画
  • Infinite Moving Cards - 自动滚动的卡片轮播
  • Direction Aware Hover - 根据光标方向触发的悬停效果
使用示例:
tsx
"use client";
import { CardBody, CardContainer, CardItem } from "@/components/ui/3d-card";

export function ProductCard() {
  return (
    <CardContainer>
      <CardBody className="bg-gray-50 rounded-xl p-6">
        <CardItem translateZ="50" className="text-2xl font-bold">
          产品标题
        </CardItem>
        <CardItem translateZ="60" as="p" className="text-sm mt-2">
          产品描述内容
        </CardItem>
        <CardItem translateZ="100" className="w-full mt-4">
          <img src="/product.jpg" className="rounded-xl" alt="产品" />
        </CardItem>
      </CardBody>
    </CardContainer>
  );
}
适用场景:
  • 产品展示
  • 功能亮点
  • 作品集项目
  • 团队成员简介
  • 定价层级
  • 博客文章预览

3. Scroll & Parallax (5 components)

3. 滚动与视差(5款组件)

Create engaging scroll-based animations and parallax effects.
Key Components:
  • Parallax Scroll - Images with parallax scrolling
  • Sticky Scroll Reveal - Content reveals while scrolling
  • Container Scroll Animation - Animated scroll containers
  • Hero Parallax - Parallax hero sections
  • MacBook Scroll - MacBook-style scroll interactions
Usage Example:
tsx
import { StickyScroll } from "@/components/ui/sticky-scroll-reveal";

const content = [
  {
    title: "Feature One",
    description: "Description of feature one...",
    content: <div>Visual content here</div>
  },
  // More items...
];

export function Features() {
  return <StickyScroll content={content} />;
}
When to Use:
  • Feature showcases with scroll interactions
  • Storytelling layouts
  • Product tours
  • Long-form content with visual breaks
  • Interactive timelines
打造引人入胜的滚动式动画和视差效果。
核心组件:
  • Parallax Scroll - 带视差滚动效果的图片
  • Sticky Scroll Reveal - 滚动时逐步显示的内容
  • Container Scroll Animation - 动画滚动容器
  • Hero Parallax - 视差英雄区
  • MacBook Scroll - 仿MacBook风格的滚动交互
使用示例:
tsx
import { StickyScroll } from "@/components/ui/sticky-scroll-reveal";

const content = [
  {
    title: "功能一",
    description: "功能一的详细描述...",
    content: <div>可视化内容</div>
  },
  // 更多内容项...
];

export function Features() {
  return <StickyScroll content={content} />;
}
适用场景:
  • 带滚动交互的功能展示
  • 叙事性布局
  • 产品导览
  • 带视觉断点的长内容
  • 交互式时间线

4. Text Components (10 components)

4. 文本组件(10款组件)

Animated text effects for headings, titles, and interactive typography.
Key Components:
  • Text Generate Effect - Text appearing character by character
  • Typewriter Effect - Typing animation
  • Flip Words - Word rotation animations
  • Text Hover Effect - Interactive text on hover
  • Hero Highlight - Gradient text highlights
  • Encrypted Text - Matrix-style encrypted text effect
  • Colourful Text - Gradient animated text
Usage Example:
tsx
import { TypewriterEffect } from "@/components/ui/typewriter-effect";

const words = [
  { text: "Build" },
  { text: "amazing" },
  { text: "websites", className: "text-blue-500" }
];

export function Hero() {
  return <TypewriterEffect words={words} />;
}
When to Use:
  • Hero headings
  • Attention-grabbing titles
  • Dynamic content displays
  • Interactive landing pages
  • Animated CTAs
用于标题、副标题和交互式排版的动画文本效果。
核心组件:
  • Text Generate Effect - 逐字符显示的文本动画
  • Typewriter Effect - 打字机动画
  • Flip Words - 文字旋转动画
  • Text Hover Effect - 交互式悬停文本
  • Hero Highlight - 渐变文本高亮
  • Encrypted Text - 仿矩阵风格的加密文本效果
  • Colourful Text - 渐变动画文本
使用示例:
tsx
import { TypewriterEffect } from "@/components/ui/typewriter-effect";

const words = [
  { text: "构建" },
  { text: "出色的" },
  { text: "网站", className: "text-blue-500" }
];

export function Hero() {
  return <TypewriterEffect words={words} />;
}
适用场景:
  • 英雄区标题
  • 吸引注意力的副标题
  • 动态内容展示
  • 交互式着陆页
  • 动画行动号召按钮

5. Buttons (4 components)

5. 按钮组件(4款组件)

Enhanced button components with animations and effects.
Key Components:
  • Tailwind CSS Buttons - Collection of styled buttons
  • Hover Border Gradient - Animated gradient borders
  • Moving Border - Animated border movement
  • Stateful Button - Multi-state button with transitions
Usage Example:
tsx
import { MovingBorder } from "@/components/ui/moving-border";

export function CTAButton() {
  return (
    <MovingBorder duration={2000} className="p-4">
      <span>Get Started</span>
    </MovingBorder>
  );
}
带动画和特效的增强型按钮组件。
核心组件:
  • Tailwind CSS Buttons - 多款样式的按钮集合
  • Hover Border Gradient - 动画渐变边框
  • Moving Border - 边框移动动画
  • Stateful Button - 带过渡效果的多状态按钮
使用示例:
tsx
import { MovingBorder } from "@/components/ui/moving-border";

export function CTAButton() {
  return (
    <MovingBorder duration={2000} className="p-4">
      <span>开始使用</span>
    </MovingBorder>
  );
}

6. Navigation (5 components)

6. 导航组件(5款组件)

Modern navigation menus and tab systems.
Key Components:
  • Floating Navbar - Floating navigation bar
  • Navbar Menu - Full-featured navigation menu
  • Tabs - Animated tab components
  • Resizable Navbar - Responsive navigation
  • Sticky Banner - Sticky announcement banners
现代化导航菜单和标签页系统。
核心组件:
  • Floating Navbar - 悬浮导航栏
  • Navbar Menu - 全功能导航菜单
  • Tabs - 动画标签页组件
  • Resizable Navbar - 响应式导航栏
  • Sticky Banner - 固定通知横幅

7. Input & Forms (3 components)

7. 输入与表单(3款组件)

Enhanced form inputs and file upload components.
Key Components:
  • Signup Form - Animated signup forms
  • Placeholders and Vanish Input - Inputs with animated placeholders
  • File Upload - Drag-and-drop file upload
Usage Example:
tsx
import { PlaceholdersAndVanishInput } from "@/components/ui/placeholders-and-vanish-input";

export function SearchBar() {
  const placeholders = [
    "Search for anything...",
    "What are you looking for?",
    "Type to search..."
  ];

  return (
    <PlaceholdersAndVanishInput
      placeholders={placeholders}
      onChange={(e) => console.log(e.target.value)}
      onSubmit={(e) => {
        e.preventDefault();
        console.log("submitted");
      }}
    />
  );
}
增强型表单输入和文件上传组件。
核心组件:
  • Signup Form - 动画注册表单
  • Placeholders and Vanish Input - 带动画占位符的输入框
  • File Upload - 拖拽式文件上传组件
使用示例:
tsx
import { PlaceholdersAndVanishInput } from "@/components/ui/placeholders-and-vanish-input";

export function SearchBar() {
  const placeholders = [
    "搜索任意内容...",
    "你在找什么?",
    "输入关键词搜索..."
  ];

  return (
    <PlaceholdersAndVanishInput
      placeholders={placeholders}
      onChange={(e) => console.log(e.target.value)}
      onSubmit={(e) => {
        e.preventDefault();
        console.log("提交成功");
      }}
    />
  );
}

8. Overlays & Popovers (3 components)

8. 遮罩与弹出层(3款组件)

Modal dialogs and tooltips with animations.
Key Components:
  • Animated Modal - Modal with smooth animations
  • Animated Tooltip - Tooltips with enter/exit animations
  • Link Preview - Link preview popover on hover
Usage Example:
tsx
import { Modal, ModalBody, ModalContent, ModalTrigger } from "@/components/ui/animated-modal";

export function BookingModal() {
  return (
    <Modal>
      <ModalTrigger className="bg-black text-white px-4 py-2 rounded-md">
        Book Now
      </ModalTrigger>
      <ModalBody>
        <ModalContent>
          <h2>Booking Details</h2>
          {/* Modal content */}
        </ModalContent>
      </ModalBody>
    </Modal>
  );
}
带动画的模态框和提示框。
核心组件:
  • Animated Modal - 带流畅动画的模态框
  • Animated Tooltip - 带进入/退出动画的提示框
  • Link Preview - 悬停时显示的链接预览弹出层
使用示例:
tsx
import { Modal, ModalBody, ModalContent, ModalTrigger } from "@/components/ui/animated-modal";

export function BookingModal() {
  return (
    <Modal>
      <ModalTrigger className="bg-black text-white px-4 py-2 rounded-md">
        立即预订
      </ModalTrigger>
      <ModalBody>
        <ModalContent>
          <h2>预订详情</h2>
          {/* 模态框内容 */}
        </ModalContent>
      </ModalBody>
    </Modal>
  );
}

9. Carousels & Sliders (4 components)

9. 轮播与滑块(4款组件)

Image sliders and carousel components.
Key Components:
  • Images Slider - Full-screen image slider
  • Carousel - Standard carousel component
  • Apple Cards Carousel - Apple-style card carousel
  • Animated Testimonials - Testimonial slider
图片滑块和轮播组件。
核心组件:
  • Images Slider - 全屏图片滑块
  • Carousel - 标准轮播组件
  • Apple Cards Carousel - 仿苹果风格的卡片轮播
  • Animated Testimonials - 动画 testimonials 滑块

10. Layout & Grid (3 components)

10. 布局与网格(3款组件)

Grid layouts and container components.
Key Components:
  • Layout Grid - Animated grid layouts
  • Bento Grid - Bento-box style grid
  • Container Cover - Full-screen container
网格布局和容器组件。
核心组件:
  • Layout Grid - 动画网格布局
  • Bento Grid - 便当盒风格网格
  • Container Cover - 全屏容器

11. Data & Visualization (2 components)

11. 数据与可视化(2款组件)

Components for displaying data and comparisons.
Key Components:
  • Timeline - Animated timeline component
  • Compare - Before/after comparison slider
用于展示数据和对比的组件。
核心组件:
  • Timeline - 动画时间线组件
  • Compare - 前后对比滑块

12. Cursor & Pointer (3 components)

12. 光标与指针(3款组件)

Cursor-following effects and interactions.
Key Components:
  • Following Pointer - Elements following cursor
  • Pointer Highlight - Highlight effect on cursor
  • Lens - Magnifying lens effect
跟随光标效果和交互组件。
核心组件:
  • Following Pointer - 跟随光标移动的元素
  • Pointer Highlight - 光标高亮效果
  • Lens - 放大镜效果

13. 3D Components (2 components)

13. 3D组件(2款组件)

3D visual effects using CSS transforms.
Key Components:
  • 3D Pin - Pinterest-style 3D card
  • 3D Marquee - 3D rotating marquee
采用CSS变换实现的3D视觉效果。
核心组件:
  • 3D Pin - 仿Pinterest风格的3D卡片
  • 3D Marquee - 3D旋转跑马灯

14. Loaders (2 components)

14. 加载器(2款组件)

Loading animations and progress indicators.
Key Components:
  • Multi-step Loader - Multi-step loading animation
  • Loader - Various loading spinners
加载动画和进度指示器。
核心组件:
  • Multi-step Loader - 多步骤加载动画
  • Loader - 多款加载旋转器

15. Sections & Blocks (3 components)

15. 区块与模板(3款组件)

Pre-built section templates.
Key Components:
  • Feature Sections - Feature showcase templates
  • Cards - Pre-designed card layouts
  • Hero Sections - Hero section templates
预构建的区块模板。
核心组件:
  • Feature Sections - 功能展示模板
  • Cards - 预设计卡片布局
  • Hero Sections - 英雄区模板

Common Patterns

通用模式

Dark Mode Support

深色模式支持

All Aceternity components support dark mode via Tailwind's dark mode classes:
tsx
<div className="bg-white dark:bg-black text-black dark:text-white">
  {/* Content */}
</div>
所有Aceternity组件均通过Tailwind的深色模式类支持深色模式:
tsx
<div className="bg-white dark:bg-black text-black dark:text-white">
  {/* 内容 */}
</div>

Responsive Design

响应式设计

Components are responsive by default. Use Tailwind's responsive prefixes:
tsx
<h1 className="text-2xl md:text-4xl lg:text-6xl">
  Responsive Heading
</h1>
组件默认支持响应式,可使用Tailwind的响应式前缀:
tsx
<h1 className="text-2xl md:text-4xl lg:text-6xl">
  响应式标题
</h1>

Combining Components

组件组合

Components can be combined for complex layouts:
tsx
import { BackgroundBeams } from "@/components/ui/background-beams";
import { TypewriterEffect } from "@/components/ui/typewriter-effect";
import { MovingBorder } from "@/components/ui/moving-border";

export default function Hero() {
  return (
    <div className="h-screen relative">
      <div className="z-10 relative flex flex-col items-center justify-center h-full">
        <TypewriterEffect words={words} />
        <MovingBorder>
          <button>Get Started</button>
        </MovingBorder>
      </div>
      <BackgroundBeams />
    </div>
  );
}
组件可组合使用以构建复杂布局:
tsx
import { BackgroundBeams } from "@/components/ui/background-beams";
import { TypewriterEffect } from "@/components/ui/typewriter-effect";
import { MovingBorder } from "@/components/ui/moving-border";

export default function Hero() {
  return (
    <div className="h-screen relative">
      <div className="z-10 relative flex flex-col items-center justify-center h-full">
        <TypewriterEffect words={words} />
        <MovingBorder>
          <button>开始使用</button>
        </MovingBorder>
      </div>
      <BackgroundBeams />
    </div>
  );
}

Best Practices

最佳实践

1. Performance Optimization

1. 性能优化

Use "use client" directive - Aceternity components use Framer Motion, requiring client-side rendering:
tsx
"use client";
import { Component } from "@/components/ui/component";
Lazy load heavy components:
tsx
import dynamic from 'next/dynamic';

const HeavyBackground = dynamic(
  () => import('@/components/ui/background-beams'),
  { ssr: false }
);
使用"use client"指令 - Aceternity组件依赖Framer Motion,需要客户端渲染:
tsx
"use client";
import { Component } from "@/components/ui/component";
懒加载重型组件:
tsx
import dynamic from 'next/dynamic';

const HeavyBackground = dynamic(
  () => import('@/components/ui/background-beams'),
  { ssr: false }
);

2. Accessibility

2. 可访问性

Add ARIA labels:
tsx
<button aria-label="Open menu">
  <MenuIcon />
</button>
Ensure keyboard navigation:
tsx
<div role="button" tabIndex={0} onKeyDown={handleKeyDown}>
  Interactive element
</div>
添加ARIA标签:
tsx
<button aria-label="打开菜单">
  <MenuIcon />
</button>
确保键盘导航支持:
tsx
<div role="button" tabIndex={0} onKeyDown={handleKeyDown}>
  交互式元素
</div>

3. Customization

3. 自定义

Override styles using className:
tsx
<BackgroundBeams className="opacity-50" />
Modify component source directly - Since components are copied to your project, you can edit them:
tsx
// components/ui/background-beams.tsx
export function BackgroundBeams({ className, myCustomProp }: Props) {
  // Customize as needed
}
通过className覆盖样式:
tsx
<BackgroundBeams className="opacity-50" />
直接修改组件源代码 - 由于组件会被复制到你的项目中,你可以直接编辑它们:
tsx
// components/ui/background-beams.tsx
export function BackgroundBeams({ className, myCustomProp }: Props) {
  // 根据需要自定义
}

4. Type Safety

4. 类型安全

Use TypeScript for prop types:
tsx
interface CardProps {
  title: string;
  description: string;
  image?: string;
}

export function Card({ title, description, image }: CardProps) {
  // Component implementation
}
使用TypeScript定义属性类型:
tsx
interface CardProps {
  title: string;
  description: string;
  image?: string;
}

export function Card({ title, description, image }: CardProps) {
  // 组件实现
}

Troubleshooting

故障排除

Common Issues

常见问题

1. "Module not found: motion"
bash
bun add motion
1. "Module not found: motion"
bash
bun add motion

or: npm install motion

或:npm install motion


**2. "cn is not defined"**
Ensure `lib/utils.ts` exists with the `cn` helper function.

**3. Components not animating**
Verify "use client" directive is at the top of the file.

**4. Tailwind classes not working**
Ensure Tailwind is configured and `globals.css` imports Tailwind directives:
```css
@tailwind base;
@tailwind components;
@tailwind utilities;
5. Dark mode not working Check
tailwind.config.ts
has
darkMode: "class"
configured.

**2. "cn is not defined"**
确保`lib/utils.ts`文件中存在`cn`工具函数。

**3. 组件无动画效果**
验证文件顶部是否添加了"use client"指令。

**4. Tailwind类不生效**
确保Tailwind已正确配置,且`globals.css`中导入了Tailwind指令:
```css
@tailwind base;
@tailwind components;
@tailwind utilities;
5. 深色模式不生效 检查
tailwind.config.ts
中是否配置了
darkMode: "class"

Token Efficiency

令牌效率

This skill provides significant token savings by:
  • Pre-vetted component selection - Saves ~3k tokens exploring component options
  • Installation instructions - Saves ~2k tokens debugging setup issues
  • Component categorization - Saves ~2k tokens finding the right component
  • Usage examples - Saves ~2k tokens writing boilerplate code
  • Troubleshooting guide - Saves ~1k tokens debugging common issues
Estimated savings: ~10k tokens (65-70% reduction) per implementation
Errors prevented:
  1. Missing motion dependency
  2. Incorrect shadcn CLI initialization
  3. Missing cn utility function
  4. Missing "use client" directive
  5. Incorrect registry configuration
  6. Wrong Next.js configuration (Pages Router vs App Router)
本指南可显著节省令牌使用:
  • 预筛选组件选择 - 节省约3k令牌的组件探索时间
  • 安装说明 - 节省约2k令牌的设置调试时间
  • 组件分类 - 节省约2k令牌的组件查找时间
  • 使用示例 - 节省约2k令牌的样板代码编写时间
  • 故障排除指南 - 节省约1k令牌的常见问题调试时间
预估节省:每次实现约节省10k令牌(减少65-70%)
避免的错误:
  1. 缺失motion依赖
  2. shadcn CLI初始化错误
  3. 缺失cn工具函数
  4. 缺失"use client"指令
  5. 注册表配置错误
  6. Next.js配置错误(Pages Router vs App Router)

When to Load References

何时加载参考文件

Load reference files based on task context:
If User Asks About...Load This Reference
New project setup, installation, getting started
references/quick-start.md
(465 lines)
Finding specific components, component categories, CLI commands
references/component-catalog.md
(635 lines)
Usage examples, patterns, troubleshootingMain SKILL.md (this file)
Reference Summary:
  • quick-start.md
    - 5-minute setup guide, first component examples, troubleshooting, project structure
  • component-catalog.md
    - Complete list of 100+ components with install commands and use cases
根据任务上下文加载对应的参考文件:
用户询问内容...加载此参考文件
新项目设置、安装、入门指南
references/quick-start.md
(465行)
查找特定组件、组件分类、CLI命令
references/component-catalog.md
(635行)
使用示例、模式、故障排除本SKILL.md文件
参考文件摘要:
  • quick-start.md
    - 5分钟快速设置指南、首个组件示例、故障排除、项目结构
  • component-catalog.md
    - 100+款组件的完整列表,包含安装命令和使用场景

Additional Resources

额外资源

Related Skills

相关技能

When using this skill, consider combining with:
  • nextjs
    - Next.js framework skill
  • tailwind-v4-shadcn
    - Tailwind CSS v4 configuration
  • react-hook-form-zod
    - Form validation
  • clerk-auth
    - Authentication
  • cloudflare-nextjs
    - Cloudflare deployment
使用本指南时,可结合以下技能:
  • nextjs
    - Next.js框架技能
  • tailwind-v4-shadcn
    - Tailwind CSS v4配置
  • react-hook-form-zod
    - 表单验证
  • clerk-auth
    - 身份认证
  • cloudflare-nextjs
    - Cloudflare部署

License

许可证

This skill documentation is provided under MIT License. Aceternity UI components have their own licensing - check https://ui.aceternity.com for details.

Last Updated: 2025-12-08 Version: 1.1.0 Maintainer: Claude Skills Maintainers
本指南采用MIT许可证。Aceternity UI组件有其独立许可证 - 详情请查看https://ui.aceternity.com。

最后更新: 2025-12-08 版本: 1.1.0 维护者: Claude Skills Maintainers