agent-module-frontend-ui-magic-shadcn

name	agent-module-frontend-ui-magic-shadcn
description	Module: Frontend UI Implementation with Shadcn and Magic UI

Module: Frontend UI Implementation with Shadcn and Magic UI

1. Module Metadata

• Module ID: agent.module.frontend-ui-magic-shadcn
• Version: 1.0.0
• Maturity: production
• Scope: Guides agents on generating, installing, configuring, and using Shadcn and Magic UI components natively in Next.js + Tailwind web applications.
• Primary outcomes:
  • Standardized setup of Tailwind CSS, Shadcn architecture, and Magic UI tokens.
  • Reproducible premium component generation using CLI and MCP native tools.
  • Consistent and robust aesthetic across UI components.

2. Mission and Applicability

Use this module when generating rich, highly animated, and premium frontend interfaces in Next.js.

Apply when:

• Creating new visual components, dashboards, or landing pages.
• Adding complex micro-animations or modern glassmorphism designs.
• Interacting with UI design tools (e.g., Shadcn CLI, Magic UI MCP Context).

Do not apply when:

• Working on backend node APIs or pure data orchestration.
• The user requests a basic vanilla HTML/CSS implementation without a build step.

3. Architecture Pattern

• Pattern: Atomic Component Architecture (Next.js + Tailwind + Framer Motion + Shadcn + Magic UI)
• Core design rules:
  • Component Isolation: All UI primitives should reside within components/ui/.
  • Utility Consolidation: Use cn() helper (clsx + tailwind-merge) for dynamic styling rules (located in lib/utils or lib/utils.ts).
  • Theming & Variables: Maintain design tokens (colors, animations, border radii) as native CSS variables within app/globals.css. Do not hardcode absolute magic colors.

4. Implementation Workflow

Phase A: Environment Setup and Initialization

1. Ensure project has Next.js and Tailwind configurations.
2. Initialize Shadcn UI: Run npx shadcn@latest init to setup components.json and utility files.
3. Integrate Magic UI Configuration:
   • Expand tailwind.config.js to include Magic UI keyframes and animations (e.g., orbit, marquee, pulse, shine, aurora, shimmer-slide).
   • Append Magic UI color token variables to app/globals.css (e.g., --color-1 to --color-5 for rainbow accents).
   • Ensure framer-motion and lucide-react are installed. Run npm install framer-motion clsx tailwind-merge if required.

Exit criteria:

• components.json, tailwind.config.js, and app/globals.css cleanly unify both libraries without compilation errors.
• /lib/utils.ts (or equivalent) exports a working cn function.

Phase B: Component Sourcing and Installation

1. Requesting Shadcn Components:
   • Use the terminal/CLI tool to add standard UI primitives.
   • Command: npx shadcn@latest add <component_name> (e.g., button, dialog, card, input).
2. Requesting Magic UI Components (Agentic Workflow via MCP):
   • DO NOT hallucinate Magic UI source code.
   • Step 1: Use mcp_magic-ui_searchRegistryItems to search and find the correct component identifier.
   • Step 2: Use mcp_magic-ui_getRegistryItem with includeSource: true to reliably retrieve the exact canonical implementation of the requested Magic UI component from your MCP connection.
   • Step 3: Extract the code from the MCP response and write the retrieved content into components/ui/<component>.tsx.
   • Step 4: Add any component-specific dependencies or Tailwind configurations returned by the registry item payload.

Exit criteria:

• The component is physically present in components/ui/ and is exported cleanly.
• Peer dependencies mapped by the MCP are resolved.

Phase C: Assembling Views and Animations

1. Import primitives into the feature layout/page inside app/ or components/.
2. Construct advanced premium aesthetic by composing magic-card, bento-grid, animated-list, etc., wrapped around solid Shadcn form elements.
3. Validate responsive behavior across Tailwind modifiers (sm:, md:, lg:).
4. Utilize glass-effect class names, text-gradient, or other globals.css utility layers.

Exit criteria:

• The interface fulfills the user requirements and delivers a wow-factor presentation with smooth micro-animations.

5. Decision Framework

Decision Area	Preferred Option	Alternative	Selection Rule
Core Primitives (Buttons, Forms, Inputs)	Shadcn UI	Custom Tailwind	Standardize accessible interaction elements using Shadcn primitives.
Hero Sections, Animations, Eye-candy	Magic UI	Framer Motion Custom	Use Magic UI elements for premium, vibrant layouts. Build custom with Framer Motion only if unsupported.
Magic UI Component Retrieval	MCP Tools (magic-ui)	Web Scraping/Browsing	Native MCP retrieval guarantees up-to-date accurate source code directly from the Magic UI registry.

6. Validation Strategy

Functional Validation

• Ensure Framer Motion <motion.div> hooks have no hydration mismatches in Next.js (prepend "use client"; directive at the top of client-side animation components).
• Ensure Shadcn form controls successfully connect with standard react context or hook forms.

Failure Validation

• Verify that standard dark mode toggling (using next-themes) correctly flips oklch() or hsl() variables inside app/globals.css. Fallback gracefully if conditional rendering disrupts Framer Motion layouts.

Contract/Security/Performance Validation

• Keep excessive animated node counts minimized (e.g., particles, confetti) to guarantee ~60fps scrolling on lower-end devices.

7. Benchmarks and SLO Targets

• Design Fidelity: Components must align exactly with the design language (fonts, shadow softness, glass effects) established in globals.css.
• Reusability: UI components should act purely as visual layers and not contain business logic.
• MCP Context Accuracy: Always query the registry before writing component code to prevent hallucinations.

8. Risks and Controls

• Risk: Hallucinating complex Magic UI component code leading to syntax or un-handled runtime errors.
  • Control: Utilize the explicitly configured magic-ui MCP connection tools (mcp_magic-ui_getRegistryItem) to pull official pristine source files perfectly.
• Risk: Clashing Tailwind configurations or missed dependencies.
  • Control: Rigorously audit tailwind.config.js extension maps (keyframes, colors) against the required metadata returned by the Magic UI registry.

9. Agent Execution Checklist

• Determine required visual interactive elements for the page.
• Auto-generate standard Shadcn components using npx shadcn@latest add ... via terminal.
• For premium animations, search Magic UI registry via MCP: call:mcp_magic-ui_searchRegistryItems.
• Pull specific Magic UI component source code via MCP: call:mcp_magic-ui_getRegistryItem{name: "<item>", includeSource: true}.
• Merge returned Tailwind constraints (extend objects, keyframes, etc.) into tailwind.config.js.
• Verify imported variables align seamlessly with core themes mapped inside app/globals.css.
• Incorporate components into the UI layout with fluid, responsive structures.

10. Reuse Notes

Adapt only:

• Base color tokens in globals.css (e.g. overriding --color-1) when implementing customized branding.
• The animation object inside tailwind.config.js to change loop speeds and durations.