magic-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Magic UI

Use this skill when the task involves Magic UI components, animated UI sections, or converting static sections into interactive UI using the Magic UI registry.

当任务涉及Magic UI组件、动画UI区块，或是使用Magic UI注册表将静态区块转换为交互式UI时，可使用本技能。

When To Apply

适用场景

Apply this skill when users ask to:

Add a Magic UI component (for example: marquee, globe, blur-fade, shiny-button)
Build a section with Magic UI effects (hero, testimonials, CTA, feature grid)
Replace custom animation code with Magic UI components
Troubleshoot installation/import issues for
```
@magicui/*
```

当用户提出以下需求时，应用本技能：

添加Magic UI组件（例如：marquee、globe、blur-fade、shiny-button）
构建带有Magic UI效果的区块（首页横幅、客户评价、呼叫行动、功能网格）
用Magic UI组件替换自定义动画代码
排查
```
@magicui/*
```
的安装/导入问题

Core Workflow

核心工作流

Define the UI outcome first.

Identify section type, tone, motion intensity, and responsive behavior.
Keep motion intentional; avoid stacking many high-motion effects in one viewport.

Confirm project prerequisites.

Project should be React/Next.js with Tailwind CSS.
shadcn must be initialized before adding registry components:

bash

npx shadcn@latest init

Install the selected component(s).

bash

npx shadcn@latest add @magicui/<component-slug>

Example:

bash

npx shadcn@latest add @magicui/magic-card

Integrate into the target section.

Import from the generated path (typically
```
@/components/ui/<component-slug>
```
).
Keep component APIs intact; prefer prop/className customization over rewriting internals.
If docs mention extra dependencies or CSS keyframes, add them during integration.

Validate quality before finishing.

Accessibility: semantic HTML, keyboard access, meaningful labels/text.
Responsiveness: check mobile layout and overflow behavior.
Performance: avoid unnecessary client-only wrappers and heavy animation stacking.
Maintainability: keep new code modular and consistent with existing project conventions.

先定义UI目标。

确定区块类型、风格、动效强度和响应式表现。
动效应有目的性；避免在同一视口内叠加过多高动效元素。

确认项目前置条件。

项目需为基于Tailwind CSS的React/Next.js项目。
在添加注册表组件前必须先初始化shadcn：

bash

npx shadcn@latest init

安装选定的组件。

bash

npx shadcn@latest add @magicui/<component-slug>

示例：

bash

npx shadcn@latest add @magicui/magic-card

集成到目标区块。

从生成的路径导入（通常为
```
@/components/ui/<component-slug>
```
）。
保持组件API完整；优先通过props/className进行定制，而非重写内部代码。
若文档提及额外依赖或CSS关键帧，请在集成时添加。

完成前验证质量。

可访问性：语义化HTML、键盘可访问、有意义的标签/文本。
响应式：检查移动端布局和溢出行为。
性能：避免不必要的仅客户端包装器和过重的动效叠加。
可维护性：保持新代码模块化，与现有项目规范一致。

References To Load On Demand

按需加载的参考资料

For component choice, install shape, and dependency expectations:
- Read
```
references/components.md
```
For section-level implementation patterns:
- Read
```
references/recipes.md
```

关于组件选择、安装形式和依赖要求：
- 阅读
```
references/components.md
```
关于区块级实现模式：
- 阅读
```
references/recipes.md
```

Quick Component Selection Heuristics

快速组件选择指南

Social proof/logo rails:
```
marquee
```
,
```
avatar-circles
```

Hero visual impact:

globe

warp-background

animated-grid-pattern

Text animation:

blur-fade

text-animate

word-rotate

sparkles-text

CTA emphasis:

shiny-button

shimmer-button

rainbow-button

Ambient backgrounds:

grid-pattern

dot-pattern

particles

flickering-grid

Start with 1 core component + 1 supporting effect, then expand only if needed.

社交证明/Logo滚动栏：
```
marquee
```
、
```
avatar-circles
```

首页横幅视觉效果：

globe

、

warp-background

、

animated-grid-pattern

文本动画：

blur-fade

、

text-animate

、

word-rotate

、

sparkles-text

呼叫行动强调：

shiny-button

、

shimmer-button

、

rainbow-button

氛围背景：

grid-pattern

、

dot-pattern

、

particles

、

flickering-grid

从1个核心组件+1个辅助效果开始，仅在需要时再扩展。

Troubleshooting

问题排查

```
components.json
```
or registry init error:
- Run
```
npx shadcn@latest init
```
  in the project root.
Import path mismatch (
```
@/
```
alias not configured):
- Use the project's alias style or relative imports.
Visual mismatch after install:
- Check for required global CSS/keyframes listed in the component docs.
Missing package errors:
- Install dependencies listed in the component's manual installation steps.

```
components.json
```
或注册表初始化错误：
- 在项目根目录运行
```
npx shadcn@latest init
```
  。
导入路径不匹配（未配置
```
@/
```
别名）：
- 使用项目的别名风格或相对导入。
安装后视觉效果不符：
- 检查组件文档中列出的必需全局CSS/关键帧。
缺失包错误：
- 安装组件手动安装步骤中列出的依赖项。

Reference Links

参考链接

Magic UI docs:
```
https://magicui.design/docs
```
Component docs:
```
https://magicui.design/docs/components
```

Installation:

https://magicui.design/docs/installation

MCP setup (optional, for AI IDE workflows):
```
https://magicui.design/docs/mcp
```

Magic UI文档：
```
https://magicui.design/docs
```
组件文档：
```
https://magicui.design/docs/components
```

安装指南：

https://magicui.design/docs/installation

MCP设置（可选，用于AI IDE工作流）：
```
https://magicui.design/docs/mcp
```