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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.