Migration Guide

This guide helps designers and frontend developers transition to Meteor Design System from existing Shopware projects or other design systems.

From Legacy Shopware Admin Components

If you're working on Shopware 6 Administration or extensions using older components, here's how to transition to Meteor:

Visual Changes to Expect

Moving to Meteor brings a fresh, modern look:

• Refined Colors: Updated color palette with better accessibility
• Improved Typography: Enhanced readability with optimized font sizes and spacing
• Consistent Spacing: Harmonized spacing system across all components
• Modern Interactions: Smoother animations and better hover states

Component Updates

Most components have direct equivalents in Meteor:

Previous Component	Meteor Component	Visual Changes
sw-button	MtButton	Refined styling, better focus states
sw-text-field	MtTextfield	Cleaner borders, improved validation states
sw-card	MtCard	Modernized shadows and borders
sw-banner	MtBanner	Enhanced color variants and typography
sw-checkbox	MtCheckbox	Improved accessibility and visual feedback

Design Token Migration

Meteor uses a comprehensive design token system. Here's how to map common values:

Colors

/* Before: Custom CSS variables */
--color-shopware-blue: #189eff;
--color-success: #37d046;
--color-warning: #ffbd5d;

/* After: Meteor tokens */
--color-primary-default: #189eff;
--color-success-default: #37d046;  
--color-warning-default: #ffbd5d;

Spacing

/* Before: Inconsistent spacing */
margin: 8px 16px;
padding: 12px 20px;

/* After: Meteor spacing tokens */
margin: var(--spacing-2) var(--spacing-4);
padding: var(--spacing-3) var(--spacing-5);

From Admin Extension SDK to Meteor Admin SDK

Deprecated Package

The @shopware-ag/admin-extension-sdk package was archived in March 2024. It has been replaced by the new Meteor Admin SDK.

Official Documentation

For detailed migration guides and complete API documentation, visit the Shopware Admin Extension SDK Documentation.

What Changed

• Package name: @shopware-ag/admin-extension-sdk → @shopware-ag/meteor-admin-sdk
• Better integration: Native Meteor component support
• Improved DX: Better TypeScript support and documentation
• Modern architecture: Built for Vue 3 and modern development practices

Simple Migration Steps

1. Update your package.json:

# Remove old package
npm uninstall @shopware-ag/admin-extension-sdk

# Install new Meteor Admin SDK  
npm install @shopware-ag/meteor-admin-sdk

2. Update imports:

// Before
import { notification } from '@shopware-ag/admin-extension-sdk';

// After  
import { useAdminSdk } from '@shopware-ag/meteor-admin-sdk';
const { notification } = useAdminSdk();

Design System Migration

From Custom CSS to Design Tokens

If you've been using custom CSS variables, Meteor tokens provide better consistency:

/* Custom approach */
:root {
  --my-primary: #1a73e8;
  --my-spacing: 16px;
  --my-radius: 8px;
}

/* Meteor approach */
@import "@shopware-ag/meteor-tokens/css/tokens.css";

.my-component {
  color: var(--color-primary-default);
  padding: var(--spacing-4);
  border-radius: var(--border-radius-default);
}

From Icon Fonts to SVG Icons

Meteor uses modern SVG icons instead of icon fonts:

<!-- Before: Icon fonts -->
<i class="icon-checkmark"></i>

<!-- After: Meteor icons -->
<MtIcon name="check" />

Framework Considerations

Vue 2 to Vue 3

Meteor requires Vue 3. If you're on Vue 2:

1. Plan your Vue 3 migration first
2. Update component syntax (Composition API recommended)
3. Install Meteor components after Vue 3 migration

Design Tool Integration

Figma Libraries

Replace old Shopware libraries with Meteor:

1. Remove old libraries from your Figma files
2. Add Meteor libraries from Figma Community
3. Update component instances using Figma's swap functionality

Design Handoff

With Meteor, design-to-code handoff becomes easier:

• Consistent naming: Component names match between Figma and code
• Token references: Design tokens provide exact values
• Better documentation: Each component has clear usage guidelines

Common Migration Scenarios

Updating an Existing Admin Extension

For Designers:

• Update your Figma designs to use Meteor components
• Review color and spacing consistency
• Test designs in both light and dark modes

For Developers:

• Replace legacy components with Meteor equivalents
• Update styling to use design tokens
• Test functionality with new component APIs

Building New Features

Start fresh with Meteor from day one:

• Use Figma libraries for design work
• Follow component documentation for implementation
• Leverage design tokens for custom styling

Maintaining Legacy Projects

You can gradually migrate:

• Keep existing styles while introducing Meteor components
• Use CSS specificity to avoid conflicts
• Migrate page by page rather than all at once

Testing Your Migration

Visual Testing

• Compare before/after screenshots to ensure visual consistency
• Test in different browsers and screen sizes
• Verify dark mode appearance if applicable

Accessibility Testing

• Run accessibility audits (Meteor improves accessibility)
• Test keyboard navigation with new components
• Verify screen reader compatibility

Getting Design Support

Resources

• Component Documentation: See all available components
• Design Tokens: Browse available design tokens
• Figma Libraries: Access design resources

Community Support

• Slack Community: Ask questions and get help
• GitHub Issues: Report bugs or request features
• Book a Session: 30-minute consultation with UX team

---

Need help with your migration? Contact us for personalized support.