swap_horizMigration Guide

Migrating from Lucide to Material Design Icons

A practical guide for transitioning icon usage from Lucide React to Material Design Icons across UX4G implementations.

Overview

UX4G is standardizing on Material Design Icons (Material Symbols) as the primary icon system. This migration is primarily at the documentation, design-system, and guidance level. Lucide remains in the codebase for legacy compatibility and will be phased out gradually.

What changes

• All new code uses Material icons
• Documentation references MDI
• Design files use Material Symbols
• Examples show MDI patterns

What stays (for now)

• Existing Lucide imports in components
• lucide-react package dependency
• UX4G custom icon system
• Runtime compatibility

What to avoid

• Adding new Lucide imports
• Mixing icon libraries in one view
• Breaking existing components
• Removing Lucide without testing

React Migration

Import Mapping

Lucide Import	Material Equivalent
import { Home } from 'lucide-react';	import HomeIcon from '@mui/icons-material/Home';
import { Search } from 'lucide-react';	import SearchIcon from '@mui/icons-material/Search';
import { Bell } from 'lucide-react';	import NotificationsIcon from '@mui/icons-material/Notifications';
import { FileText } from 'lucide-react';	import DescriptionIcon from '@mui/icons-material/Description';
import { Shield } from 'lucide-react';	import ShieldIcon from '@mui/icons-material/Shield';
import { Download } from 'lucide-react';	import DownloadIcon from '@mui/icons-material/Download';
import { Upload } from 'lucide-react';	import UploadIcon from '@mui/icons-material/Upload';
import { Trash2 } from 'lucide-react';	import DeleteIcon from '@mui/icons-material/Delete';

Prop Mapping

Lucide Prop	Material Equivalent	Note
size={24}	fontSize="medium" (or sx={{ fontSize: 24 }})	MUI uses named sizes: small (20px), medium (24px), large (36px)
strokeWidth={1.5}	N/A (font weight axis)	Material Symbols use font-variation-settings for weight
className="text-primary"	color="primary" (or className="text-primary")	MUI icons support color prop or className
aria-hidden="true"	aria-hidden="true"	Same pattern — hide decorative icons
aria-label="Close"	titleAccess="Close"	MUI uses titleAccess for accessible SVG title

Icon Wrapper Strategy

For teams migrating incrementally, create a wrapper component that abstracts the icon source. This allows swapping implementations without touching every usage site.

// src/components/AppIcon.tsx
import * as React from 'react';

interface AppIconProps {
  name: string;
  size?: 'sm' | 'md' | 'lg' | 'xl';
  className?: string;
  'aria-hidden'?: boolean;
  'aria-label'?: string;
}

const SIZE_MAP = { sm: 16, md: 20, lg: 24, xl: 32 };

export function AppIcon({ name, size = 'lg', className, ...props }: AppIconProps) {
  return (
    <span
      className={`material-symbols-outlined ${className ?? ''}`}
      style={{ fontSize: SIZE_MAP[size] }}
      aria-hidden={props['aria-hidden'] ?? true}
      aria-label={props['aria-label']}
      role={props['aria-label'] ? 'img' : undefined}
    >
      {name}
    </span>
  );
}

Angular Migration

Angular projects can use the Material Symbols font directly or Angular Material's MatIcon component.

// 1. Add font to angular.json
"styles": [
  "node_modules/material-symbols/outlined.css"
]

// 2. Template usage (font approach)
<button>
  <span class="material-symbols-outlined" aria-hidden="true">download</span>
  Download
</button>

// 3. Angular Material approach
import { MatIconModule } from '@angular/material/icon';

@Component({
  template: `
    <button mat-button>
      <mat-icon aria-hidden="true">download</mat-icon>
      Download
    </button>
  `
})
export class DownloadButtonComponent {}

Flutter Migration

Flutter includes Material Icons natively. No additional packages are needed — the Icons class provides access to the full Material Design icon set.

// Flutter already uses Material Icons natively
import 'package:flutter/material.dart';

// Standard usage
Icon(Icons.home, size: 24, color: Colors.blue)

// With semantic label for accessibility
Icon(
  Icons.download,
  size: 24,
  semanticLabel: 'Download certificate',
)

// Icon button
IconButton(
  icon: const Icon(Icons.close),
  tooltip: 'Close',
  onPressed: () => Navigator.pop(context),
)

// Outlined variant
Icon(Icons.home_outlined, size: 24)

// Rounded variant
Icon(Icons.home_rounded, size: 24)

Compatibility Layer

During the transition period, the UX4G custom icon system (react-core-package/src/icons) continues to function as a compatibility bridge. It provides named icon components that can be backed by either SVG definitions or Material Symbols without changing consumer code.

// These UX4G icon imports continue to work unchanged
import { HomeIcon, SearchIcon, ShieldIcon } from 'ux4g-components-react';

// The underlying implementation can migrate from
// custom SVG → Material Symbols without breaking consumers
<HomeIcon size="lg" decorative />
<SearchIcon size="md" decorative />
<ShieldIcon size="lg" title="Security verified" />

Recommendation: For new components, prefer direct Material Symbols usage (font or @mui/icons-material). The UX4G icon wrapper is best for existing code that needs to maintain backward compatibility.

Migration Checklist

Per-Component Checklist

☐ Replace Lucide imports with Material equivalents
☐ Update size props to Material sizing system
☐ Verify aria-hidden on decorative icons
☐ Verify aria-label on standalone icons
☐ Test at all supported sizes (16–48px)
☐ Verify dark mode rendering
☐ Verify high-contrast mode
☐ Run accessibility audit (vitest-axe)

Per-Page Checklist

☐ No mixed icon libraries in the same view
☐ Consistent icon style (outlined vs filled)
☐ All icon-only buttons have accessible names
☐ Touch targets meet 44×44px minimum
☐ Icons meet 3:1 contrast ratio
☐ RTL layout mirrors directional icons
☐ No icon animations without prefers-reduced-motion
☐ Visual regression test updated

← Icon System Resources →