Skip to content

UI Library for Design Engineers. Animated components and effects you can copy and paste into your apps. Free. Open Source.

feat(skills): add magic-ui SKILL.md and references (#910)

Yeom-JinHo8f73f8518dc1
diff --git a/skills/magic-ui/SKILL.md b/skills/magic-ui/SKILL.md
new file mode 100644
index 00000000..5bf7fa38
--- /dev/null
+++ b/skills/magic-ui/SKILL.md
@@ -0,0 +1,87 @@
+---
+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`
diff --git a/skills/magic-ui/references/components.md b/skills/magic-ui/references/components.md
new file mode 100644
index 00000000..ac90b881
--- /dev/null
+++ b/skills/magic-ui/references/components.md
@@ -0,0 +1,84 @@
+# Magic UI Component Reference
+
+## Purpose
+
+Use this document to choose the right Magic UI component and avoid integration mistakes before implementation.
+
+## Install Contract
+
+- Initialize shadcn once per project:
+```bash
+npx shadcn@latest init
+```
+- Add components via registry:
+```bash
+npx shadcn@latest add @magicui/<component-slug>
+```
+- Default import path is usually:
+```tsx
+import { ComponentName } from "@/components/ui/<component-slug>"
+```
+
+If the project does not use `@/` aliases, adapt import paths to local conventions.
+
+## Families
+
+### Layout And Social Proof
+
+- `marquee`
+- `avatar-circles`
+- `bento-grid`
+
+Use for logo rails, testimonial movement, and feature grids.
+
+### Hero And Visual Anchors
+
+- `globe`
+- `warp-background`
+- `animated-grid-pattern`
+- `retro-grid`
+
+Use one primary visual anchor per hero to keep hierarchy clear.
+
+### Text Motion
+
+- `blur-fade`
+- `text-animate`
+- `word-rotate`
+- `sparkles-text`
+- `typing-animation`
+
+Use when product messaging needs motion emphasis.
+
+### Buttons And CTA Emphasis
+
+- `shiny-button`
+- `shimmer-button`
+- `rainbow-button`
+- `ripple-button`
+
+Keep CTA style consistent within one page section.
+
+### Ambient Effects
+
+- `particles`
+- `flickering-grid`
+- `dot-pattern`
+- `grid-pattern`
+- `light-rays`
+
+Use these as supporting layers, not primary content.
+
+## Integration Notes
+
+- Some components require additional dependencies (for example `cobe`, `motion` for `globe` patterns).
+- Some components require global CSS keyframes (for example `marquee` variants).
+- Prefer prop-level customization before editing generated source.
+- If customization grows large, wrap the component in a local section component rather than editing registry output directly.
+
+## Quality Checks
+
+- Accessibility: interactive controls remain keyboard-accessible.
+- Readability: animated backgrounds do not reduce text contrast.
+- Responsiveness: no horizontal overflow on small screens.
+- Performance: avoid stacking multiple expensive animated backgrounds in one viewport.
diff --git a/skills/magic-ui/references/recipes.md b/skills/magic-ui/references/recipes.md
new file mode 100644
index 00000000..85a2c5f9
--- /dev/null
+++ b/skills/magic-ui/references/recipes.md
@@ -0,0 +1,89 @@
+# Magic UI Recipes
+
+## Purpose
+
+Use these recipes when the user asks for concrete UI sections rather than a single component.
+
+## Recipe 1: Hero With Visual Depth
+
+### Goal
+
+Create a hero section with strong visual identity and clear CTA hierarchy.
+
+### Suggested Stack
+
+- Primary visual: `warp-background` or `animated-grid-pattern`
+- Heading entrance: `blur-fade`
+- CTA: `shiny-button`
+
+### Steps
+
+1. Install components:
+```bash
+npx shadcn@latest add @magicui/warp-background @magicui/blur-fade @magicui/shiny-button
+```
+2. Wrap hero content in the background component.
+3. Animate heading and subheading with subtle stagger.
+4. Keep one primary CTA and one secondary action.
+
+### Guardrails
+
+- Keep animations under control: avoid combining more than two high-motion effects in hero.
+- Preserve text contrast over animated backgrounds.
+
+## Recipe 2: Testimonial And Logo Trust Rail
+
+### Goal
+
+Show social proof without static blocks.
+
+### Suggested Stack
+
+- `marquee`
+- `avatar-circles` (optional for compact profile clusters)
+
+### Steps
+
+1. Install:
+```bash
+npx shadcn@latest add @magicui/marquee @magicui/avatar-circles
+```
+2. Use horizontal marquee for desktop and reduced density on mobile.
+3. If using avatar clusters, add concise labels and accessible alt text.
+
+### Guardrails
+
+- Ensure auto-scrolling content can pause on hover/focus for usability.
+- Do not overload with long testimonial paragraphs in moving rails.
+
+## Recipe 3: Feature Grid With Motion Highlights
+
+### Goal
+
+Present product capabilities in an interactive but readable grid.
+
+### Suggested Stack
+
+- `bento-grid`
+- One text motion component per card group (`text-animate` or `word-rotate`)
+
+### Steps
+
+1. Install:
+```bash
+npx shadcn@latest add @magicui/bento-grid @magicui/text-animate
+```
+2. Keep card copy short and scannable.
+3. Use motion for emphasis on only 1-2 cards.
+
+### Guardrails
+
+- Maintain consistent card heights where possible.
+- Avoid running simultaneous animations in every card.
+
+## Final Validation Checklist
+
+- Layout works at mobile and desktop breakpoints.
+- Interactive elements are reachable with keyboard navigation.
+- Motion supports content hierarchy instead of competing with it.
+- Added components compile with the current path alias setup.