aceternity-ui
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAceternity 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
undefinedCreate 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:**
```bashUsing 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
undefinedInstall 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-mergeor: 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))
}- 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))
}- 从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 motion1. "Module not found: motion"
bash
bun add motionor: 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 has configured.
tailwind.config.tsdarkMode: "class"
**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.tsdarkMode: "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:
- Missing motion dependency
- Incorrect shadcn CLI initialization
- Missing cn utility function
- Missing "use client" directive
- Incorrect registry configuration
- Wrong Next.js configuration (Pages Router vs App Router)
本指南可显著节省令牌使用:
- 预筛选组件选择 - 节省约3k令牌的组件探索时间
- 安装说明 - 节省约2k令牌的设置调试时间
- 组件分类 - 节省约2k令牌的组件查找时间
- 使用示例 - 节省约2k令牌的样板代码编写时间
- 故障排除指南 - 节省约1k令牌的常见问题调试时间
预估节省:每次实现约节省10k令牌(减少65-70%)
避免的错误:
- 缺失motion依赖
- shadcn CLI初始化错误
- 缺失cn工具函数
- 缺失"use client"指令
- 注册表配置错误
- 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 | |
| Finding specific components, component categories, CLI commands | |
| Usage examples, patterns, troubleshooting | Main SKILL.md (this file) |
Reference Summary:
- - 5-minute setup guide, first component examples, troubleshooting, project structure
quick-start.md - - Complete list of 100+ components with install commands and use cases
component-catalog.md
根据任务上下文加载对应的参考文件:
| 用户询问内容... | 加载此参考文件 |
|---|---|
| 新项目设置、安装、入门指南 | |
| 查找特定组件、组件分类、CLI命令 | |
| 使用示例、模式、故障排除 | 本SKILL.md文件 |
参考文件摘要:
- - 5分钟快速设置指南、首个组件示例、故障排除、项目结构
quick-start.md - - 100+款组件的完整列表,包含安装命令和使用场景
component-catalog.md
Additional Resources
额外资源
- Official Documentation: https://ui.aceternity.com/docs
- Component Gallery: https://ui.aceternity.com/components
- Shadcn UI: https://ui.shadcn.com
- Framer Motion: https://www.framer.com/motion
- Tailwind CSS: https://tailwindcss.com
- 官方文档: https://ui.aceternity.com/docs
- 组件画廊: https://ui.aceternity.com/components
- Shadcn UI: https://ui.shadcn.com
- Framer Motion: https://www.framer.com/motion
- Tailwind CSS: https://tailwindcss.com
Related Skills
相关技能
When using this skill, consider combining with:
- - Next.js framework skill
nextjs - - Tailwind CSS v4 configuration
tailwind-v4-shadcn - - Form validation
react-hook-form-zod - - Authentication
clerk-auth - - Cloudflare deployment
cloudflare-nextjs
使用本指南时,可结合以下技能:
- - Next.js框架技能
nextjs - - Tailwind CSS v4配置
tailwind-v4-shadcn - - 表单验证
react-hook-form-zod - - 身份认证
clerk-auth - - Cloudflare部署
cloudflare-nextjs
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