magic-ui

Magic UI

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

何时使用

当用户要求以下内容时，使用此技能：

• 添加 Magic UI 组件（例如：marquee、globe、blur-fade、shiny-button）
• 使用 Magic UI 效果构建区块（主视觉区、用户评价、CTA、功能网格）
• 使用 Magic UI 组件替换自定义动画代码
• 排查 @magicui/* 的安装或导入问题

核心工作流

1. 首先明确 UI 目标。

• 确定区块类型、风格、动画强度和响应式行为。
• 让动画有明确目的；避免在同一视口中叠加多个高强度动画效果。

2. 确认项目的先决条件。

• 项目应使用 React/Next.js 和 Tailwind CSS。
• 添加注册表组件前，必须先初始化 shadcn：

npx shadcn@latest init

3. 安装所选组件。

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

示例：

npx shadcn@latest add @magicui/magic-card

4. 集成到目标区块中。

• 从生成的路径导入（通常为 @/components/ui/<component-slug>）。
• 保持组件 API 不变；优先通过 prop/className 自定义，而不是重写内部实现。
• 如果文档提到额外依赖或 CSS 关键帧，请在集成时一并添加。

5. 完成前验证质量。

• 无障碍性：使用语义化 HTML，支持键盘操作，并提供有意义的标签和文本。
• 响应式：检查移动端布局和溢出行为。
• 性能：避免不必要的仅客户端包装器和过多动画叠加。
• 可维护性：保持新增代码模块化，并遵循现有项目规范。

按需加载的参考资料

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

快速组件选择参考

• 社交证明/Logo 滚动栏：marquee、avatar-circles
• 主视觉区的视觉冲击效果：globe、warp-background、animated-grid-pattern
• 文本动画：blur-fade、text-animate、word-rotate、sparkles-text
• CTA 强调效果：shiny-button、shimmer-button、rainbow-button
• 氛围背景：grid-pattern、dot-pattern、particles、flickering-grid

先使用 1 个核心组件和 1 个辅助效果，仅在需要时再扩展。

故障排查

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

参考链接

• Magic UI 文档：https://magicui.design/docs
• 组件文档：https://magicui.design/docs/components
• 安装指南：https://magicui.design/docs/installation
• MCP 设置（可选，适用于 AI IDE 工作流）：https://magicui.design/docs/mcp