PLAN: shadcn/ui Component Library Adoption

Executive Summary

+======================================================================+
|                                                                      |
|   ███████╗██╗  ██╗ █████╗ ██████╗  ██████╗███╗   ██╗                |
|   ██╔════╝██║  ██║██╔══██╗██╔══██╗██╔════╝████╗  ██║                |
|   ███████╗███████║███████║██║  ██║██║     ██╔██╗ ██║                |
|   ╚════██║██╔══██║██╔══██║██║  ██║██║     ██║╚██╗██║                |
|   ███████║██║  ██║██║  ██║██████╔╝╚██████╗██║ ╚████║                |
|   ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝ ╚═════╝╚═╝  ╚═══╝                |
|                                                                      |
|   U I   A D O P T I O N   P L A N                                   |
|                                                                      |
|   Magic e-VERSE Design System                                        |
|   shadcn/ui + Tailwind CSS + Radix Primitives                        |
|                                                                      |
|   Status:     WACHT OP AKKOORD                                       |
|   Prioriteit: Hoog                                                   |
|   Impact:     Alle frontend projecten                                |
|                                                                      |
+======================================================================+

Het Magic e-VERSE ecosysteem heeft momenteel geen gedeelde component library. Elke app herbouwt buttons, modals, tabellen en formulieren from scratch. Dit plan beschrijft de adoptie van shadcn/ui als standaard component library, verpakt in een gedeeld @magiverse/ui pakket dat het bestaande design behoudt.

---

Huidige Situatie

Wat we hebben

Project	Framework	UI Library	Styling
PIM Storefront	Next.js 15	Medusa UI (Radix)	Tailwind 3.x
Omniverse Storefront	Next.js 15	Medusa UI (Radix)	Tailwind 3.x
Magiceverse Evolved	Next.js 14	Geen	Tailwind 3.4
Magic Portal	Vite + React 19	Geen	Plain CSS (370KB!)
Magic Management	Vite + React 19	Geen	Plain CSS
Magic Tenant Portal	Vite + React 19	Geen	Plain CSS
Magic Moodshot	Vite + React 19	Geen	Plain CSS
PIM Admin	Medusa Admin SDK	Medusa UI	Medusa preset

Problemen

1. Geen gedeelde componenten - Buttons, modals, tabellen worden per project opnieuw gebouwd
2. Inconsistente styling - Tailwind in storefronts, plain CSS in portals
3. Duplicatie - MagicHeader, modals, badges, form groups herhaald per project
4. Onderhoudslast - 370KB App.css in magic_portal is onwerkbaar
5. Geen design tokens - Kleuren/spacing alleen als losse CSS variables, geen single source of truth

Wat we al hebben dat matcht met shadcn/ui

• Radix UI primitives - Al in gebruik via Medusa UI (shadcn is ook gebouwd op Radix)
• Tailwind CSS - Al in gebruik in 3 van de 8 projecten
• CSS Variables - Design tokens zijn al gedefinieerd (--pink, --green, --blue, etc.)
• Monorepo structuur - packages/ directory bestaat al (@magiverse/i18n)

---

Waarom shadcn/ui

Je bezit de code

shadcn/ui is geen npm dependency - componenten worden gekopieerd naar je repo. Volledig aanpasbaar, geen vendor lock-in.

Zelfde foundation

Gebouwd op Radix + Tailwind - exact dezelfde stack die je al gebruikt in de storefronts.

Incrementele adoptie

Voeg een component per keer toe. Geen big-bang migratie nodig.

Grootste community

2M+ maandelijkse downloads, 80K+ GitHub stars, honderden templates en voorbeelden.

Vergelijking met alternatieven

Library	Score /50	Sterkte	Zwakte voor ons
shadcn/ui	47	Code ownership, Radix+Tailwind, incrementeel	Tailwind nodig in portal projects
Radix Themes	42	Al in stack via Medusa	Minder community, geen code ownership
Ark UI + Park UI	38	Modern, token-based	Nieuw primitief systeem naast Radix
Mantine	35	120+ componenten	CSS Modules, conflicteert met Tailwind
NextUI (HeroUI)	33	Mooi out-of-box	Framer Motion dependency, React 19 issues

---

Aanbevolen shadcn Templates & Starters

Template Selectie

Deze templates zijn geselecteerd op basis van onze stack (Next.js + Vite), design stijl, en use cases. Ze dienen als referentie en inspiratie, niet als directe copy-paste.

Voor Storefronts (E-Commerce)

Template	Waarom relevant	URL
taxonomy	App shell met sidebar navigatie, goed voor account/dashboard paginas	shadcn/ui officieel voorbeeld
shadcn/ui Blocks - Ecommerce	Product cards, cart components, checkout flows	ui.shadcn.com/blocks

Voor Portals & Dashboards

Template	Waarom relevant	URL
shadcn-admin	Complete admin dashboard met sidebar, tables, charts, forms	github.com/satnaing/shadcn-admin
shadcn/ui Dashboard	Officieel dashboard voorbeeld met data tables, charts, auth	ui.shadcn.com/examples/dashboard
shadcn/ui Blocks - Sidebars	Sidebar navigatie patronen (past bij portal layout)	ui.shadcn.com/blocks#sidebar
shadcn/ui Blocks - Login	Auth pages die we kunnen themen naar onze stijl	ui.shadcn.com/blocks#login

Voor Landing Pages (Magiceverse Evolved)

Template	Waarom relevant	URL
shadcn-landing-page	Hero sections, features, pricing, CTA - past bij evolved site	github.com/leoMirandaa/shadcn-landing-page
shadcn/ui Blocks	Modulaire hero, feature, pricing secties	ui.shadcn.com/blocks

Voor het Shared Package (@magiverse/ui)

Template	Waarom relevant	URL
shadcn/ui CLI	Officieel init + add systeem, beste basis voor eigen package	ui.shadcn.com/docs/cli
ui/registry pattern	shadcn’s eigen registry systeem voor custom component distributie	ui.shadcn.com/docs/registry

Specifieke Componenten om te starten

Gebaseerd op wat we nu custom bouwen, zijn dit de shadcn componenten met de hoogste impact:

Component	Vervangt	Projecten
Button	.btn-primary, .btn-success, .btn-cancel (5 varianten per project)	Alle
Dialog	Custom modal met overlay/backdrop (per project anders)	Alle
Table + DataTable	Custom <table> styling + pagination	Portal, Tenant Portal, PIM Admin
Input + Label	.form-group input + floating labels	Alle
Select	<NativeSelect> + custom dropdowns	Alle
Badge	.role-badge, .version-badge, .status-dot	Alle
Card	.project-card, .app-card, .site-card	Alle
Tabs	Custom tab implementations	Portal, Tenant Portal
Toast / Sonner	Custom notification systemen	Alle
Sheet	Mobile sidebar patterns	Portal
Dropdown Menu	User menu, context menus	Alle
Skeleton	Loading states (nu vaak spinners)	Alle
Command	Search (Cmd+K pattern in portal header)	Portal

---

Design Token Mapping

Onze bestaande kleuren mappen naar shadcn’s CSS variable systeem:

/* @magiverse/ui - globals.css */
@layer base {
  :root {
    /* Map Magic e-VERSE kleuren naar shadcn variabelen */
    --background: 35 33% 96%;          /* #f5f3f0 (beige) */
    --foreground: 236 33% 14%;         /* #1a1a2e (dark) */

    --primary: 340 67% 51%;            /* #d62e6e (pink) */
    --primary-foreground: 0 0% 100%;   /* white */

    --secondary: 160 51% 54%;          /* #3dd598 (green) */
    --secondary-foreground: 0 0% 100%;

    --accent: 210 100% 56%;            /* #1e90ff (blue) */
    --accent-foreground: 0 0% 100%;

    --destructive: 12 100% 64%;        /* #ff6b4a (orange/red) */
    --destructive-foreground: 0 0% 100%;

    --muted: 210 11% 96%;              /* #f0f0f0 */
    --muted-foreground: 215 16% 47%;

    --card: 0 0% 100%;                 /* white */
    --card-foreground: 236 33% 14%;

    --border: 220 13% 91%;             /* #e0e0e0 */
    --input: 220 13% 91%;
    --ring: 340 67% 51%;               /* pink focus ring */

    --radius: 0.5rem;                  /* 8px - ons standaard border-radius */

    /* Custom Magic e-VERSE tokens (buiten shadcn standaard) */
    --purple: 291 65% 43%;             /* #9c27b0 */
    --orange: 12 100% 64%;             /* #ff6b4a */
  }

  .dark {
    --background: 236 33% 14%;         /* #1a1a2e */
    --foreground: 210 11% 96%;
    --card: 230 25% 18%;               /* #16213e */
    --primary: 349 76% 59%;            /* #e94560 (moodshot pink) */
    /* ... overige dark mode tokens */
  }
}

---

Implementatie Plan

1. Fase 0: Package Setup (1 dag)

   Maak het @magiverse/ui pakket aan in de monorepo:

   packages/
     magiverse-i18n/    (bestaand)
     magiverse-ui/      (nieuw)
       src/
         components/
           ui/          (shadcn componenten)
         lib/
           utils.ts     (cn helper)
         styles/
           globals.css  (design tokens)
       package.json
       tailwind.config.ts
       tsconfig.json

   • Initialiseer shadcn/ui met npx shadcn@latest init
   • Configureer design tokens (kleuren, radius, fonts)
   • Stel Tailwind config in met Magic e-VERSE preset
   • Exporteer componenten als npm package

2. Fase 1: Tailwind toevoegen aan Portal Projects (1-2 dagen)

   Voeg Tailwind CSS toe aan de 4 Vite-projecten die nu plain CSS gebruiken:

   • magic_portal
   • magic_management
   • magic_tenant_portal
   • magic_moodshot

   Caution

   Bestaande CSS blijft werken naast Tailwind. Geen CSS hoeft verwijderd te worden in deze fase.

3. Fase 2: Core Components (2-3 dagen)

   Installeer en theme de meest gebruikte componenten:

   • Button (primary=pink, secondary=green, accent=blue, destructive=orange)
   • Input + Label (met focus ring in pink)
   • Badge (role colors: admin=green, developer=blue, client=purple)
   • Card (white, 12px radius, subtle shadow, hover lift)
   • Dialog/Modal (backdrop blur, header/body/footer)
   • Toast (via Sonner)

   Vervang in 1 project (magic_management - kleinste) alle custom componenten.

4. Fase 3: Data Components (2-3 dagen)

   • Table + DataTable met sorting, filtering, pagination (TanStack Table)
   • Select + Combobox
   • Tabs
   • Dropdown Menu
   • Command (search)

   Vervang in magic_tenant_portal.

5. Fase 4: Portal Migratie (3-5 dagen)

   Migreer magic_portal (het grootste project):

   • Vervang 370KB App.css met Tailwind + shadcn componenten
   • Refactor naar component-bestanden (uit de monolithische App.tsx)
   • Behoud MagicHeader maar bouw met shadcn primitives

6. Fase 5: Storefront Integratie (2-3 dagen)

   Gebruik @magiverse/ui naast Medusa UI in de storefronts:

   • Medusa UI blijft voor commerce-specifieke componenten (cart, checkout)
   • shadcn/ui voor generieke UI (modals, forms, toasts, badges)
   • Beide gebruiken Radix, geen conflicten

7. Fase 6: Evolved Site (1-2 dagen)

   Magiceverse Evolved gebruikt al Tailwind - voeg shadcn componenten toe:

   • Vervang custom section components met shadcn Cards/Buttons
   • Behoud custom animaties en glassmorphism effecten

---

Compatibiliteit met Medusa UI

Medusa UI blijft

Medusa UI wordt NIET vervangen. Het blijft de primaire library voor commerce-specifieke admin componenten in de PIM backend. shadcn/ui wordt gebruikt voor alle andere UI.

Scenario	Library
PIM Admin dashboard	Medusa UI (via Admin SDK)
Storefront checkout/cart	Medusa UI
Storefront account pages	@magiverse/ui (shadcn)
Portal/Management/Tenant	@magiverse/ui (shadcn)
Landing pages	@magiverse/ui (shadcn)
Moodshot	@magiverse/ui (shadcn)

Beide libraries gebruiken Radix UI primitives en Tailwind CSS - ze werken naadloos samen.

---

Risico’s & Mitigatie

Risico	Impact	Mitigatie
Tailwind toevoegen breekt bestaande CSS	Medium	Tailwind preflight uitzetten, co-existentie testen
Bundle size toename	Laag	Tailwind purge + tree-shaking, shadcn is copy-paste (geen library overhead)
Leercurve team	Laag	shadcn docs zijn uitstekend, patronen zijn standaard React
Medusa UI conflicten	Laag	Beide op Radix, namespace scheidbaar via import paths
Migratie tijd onderschat	Medium	Incrementele aanpak - elk project onafhankelijk migreerbaar

---

Resultaat

Na voltooiing:

• 1 gedeelde component library (@magiverse/ui) voor het hele ecosysteem
• Consistente design - zelfde buttons, modals, forms in elke app
• ~80% minder custom CSS - van 370KB+ naar component-scoped Tailwind
• Snellere development - nieuwe features bouwen met bestaande componenten
• Betere accessibility - Radix primitives hebben ARIA support ingebouwd
• Dark mode ready - shadcn’s CSS variable systeem ondersteunt themes out of the box