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
- 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
- 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:
- Plan your Vue 3 migration first
- Update component syntax (Composition API recommended)
- Install Meteor components after Vue 3 migration
Design Tool Integration
Figma Libraries
Replace old Shopware libraries with Meteor:
- Remove old libraries from your Figma files
- Add Meteor libraries from Figma Community
- 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.