# magic-ui

Helps add, customize, and troubleshoot Magic UI animated components in React and Next.js projects using the shadcn registry.

Skill by Magic UI. Category: Web and browsers.

## Install

Project (for this project only):

```sh
npx skills add magicuidesign/magicui --skill magic-ui
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add magicuidesign/magicui --skill magic-ui -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass
- Runlayer: Pass
- ZeroLeaks: Pass

Installs: 1038. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/magicuidesign/magicui/magic-ui)

## Source

[Open the source](https://github.com/magicuidesign/magicui/tree/HEAD/skills/magic-ui). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: magic-ui
description: Use this skill when users want to add, customize, or troubleshoot Magic UI components in React/Next.js projects. It covers component selection, shadcn registry installation (`@magicui/*`), integration patterns, and practical quality checks for accessibility and maintainability.
metadata:
  short-description: Build and customize UIs with Magic UI components
---

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

## 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/*`

## Core Workflow

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

2. 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
```

3. Install the selected component(s).
```bash
npx shadcn@latest add @magicui/<component-slug>
```
Example:
```bash
npx shadcn@latest add @magicui/magic-card
```

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

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

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

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

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

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

- Previous: [convert-documents-to-markdown](https://syn4pse.dev/terminal/convert-documents-to-markdown.md)
- Next: [cloud-run-basics](https://syn4pse.dev/terminal/cloud-run-basics.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
