---
name: magento-theme-developer
description: Creates custom Magento 2 themes, child themes, and theme modifications. Use when developing themes, customizing frontend, implementing responsive design, or working with Luma/Blank themes. Masters frontend architecture, layout XML, templates, and performance optimization.
---

# Magento 2 Theme Developer

Expert specialist in creating stunning, performant, and maintainable themes that deliver exceptional user experiences while adhering to Magento's frontend architecture principles.

## When to Use

- Creating custom themes or child themes
- Customizing frontend appearance and layout
- Implementing responsive design
- Working with layout XML and templates
- Optimizing frontend performance
- Modifying existing themes

## Theme Development Process

### 1. Planning & Design Analysis
- **Design System Review**: Analyze design mockups and create component libraries
- **Technical Requirements**: Identify custom components and functionality needs
- **Performance Goals**: Set loading time and performance benchmarks
- **Browser Support**: Define supported browsers and testing matrix
- **Accessibility Standards**: Plan for WCAG compliance and screen reader support

### 2. Theme Architecture Setup
- **Base Theme Selection**: Choose appropriate parent theme (Blank, Luma, or custom)
- **Child Theme Creation**: Set up theme inheritance structure
- **Asset Organization**: Plan CSS, JavaScript, and image file structure
- **Build Process**: Configure compilation and optimization workflows
- **Version Control**: Establish theme development and deployment strategies

### 3. Theme Structure
```
app/design/frontend/Vendor/theme-name/
├── etc/
│   └── view.xml
├── media/
│   └── preview.jpg
├── web/
│   ├── css/
│   ├── js/
│   └── images/
├── registration.php
└── theme.xml
```

### 4. Layout Development
- **Page Layouts**: Create custom page layouts and page configurations
- **Layout Updates**: Implement layout XML modifications and customizations
- **Block Customization**: Customize and extend Magento's block classes
- **Container Management**: Organize content containers and responsive behavior
- **Template Hierarchy**: Plan template file organization and reusability

### 5. Styling Implementation
- **Component Styling**: Develop modular, reusable CSS components
- **Responsive Breakpoints**: Implement mobile-first responsive design
- **Typography System**: Create consistent typography scales and hierarchies
- **Color Systems**: Implement theme color variables and variations
- **Animation & Interactions**: Add smooth transitions and micro-interactions

## Theme Components

### Layout XML
- Master layout instructions, containers, and blocks
- Understand fallback mechanism
- Create custom layout updates
- Manage block and container organization

### Template Files (.phtml)
- Create and customize template files
- Use proper output escaping (`$escaper->escapeHtml()`, etc.)
- Follow template best practices
- Implement proper PHPDoc for template variables

### CSS/LESS
- Build responsive, mobile-first stylesheets
- Use LESS preprocessing
- Utilize Magento's LESS variable system
- Optimize CSS for performance

### JavaScript
- Implement interactive functionality using RequireJS
- Work with KnockoutJS for dynamic components
- Follow Magento's JS framework patterns
- Optimize JavaScript loading

## Specialized Theme Types

### E-commerce Themes
- **Product Pages**: Design compelling product detail and listing pages
- **Checkout Flow**: Optimize checkout experience for conversion
- **Shopping Cart**: Create intuitive cart and mini-cart interfaces
- **Customer Account**: Design user-friendly account management interfaces
- **Search Results**: Implement effective search and filtering interfaces

### Responsive Themes
- **Mobile Optimization**: Prioritize mobile user experience
- **Touch Interactions**: Implement touch-friendly navigation and controls
- **Performance Budget**: Maintain fast loading on mobile networks
- **Progressive Enhancement**: Ensure functionality across capability ranges
- **Viewport Management**: Handle various screen sizes and orientations

### Accessibility-Focused Themes
- **Keyboard Navigation**: Ensure full keyboard accessibility
- **Screen Reader Support**: Implement proper ARIA labels and roles
- **Color Contrast**: Meet WCAG color contrast requirements
- **Focus Management**: Create clear focus indicators and logical tab order
- **Alternative Text**: Provide comprehensive image descriptions

## Best Practices

### Performance Optimization
- **Asset Optimization**: Minimize and compress CSS/JS files
- **Image Optimization**: Use modern image formats and lazy loading
- **Critical CSS**: Implement critical CSS for faster rendering
- **JavaScript Optimization**: Minimize JavaScript payload
- **Caching**: Leverage browser and CDN caching

### Code Organization
- **Modular Structure**: Organize code in logical, maintainable modules
- **Template Reusability**: Create reusable template components
- **CSS Architecture**: Use BEM or similar methodology
- **JavaScript Modules**: Organize JS in RequireJS modules
- **Version Control**: Use Git effectively for collaborative development

### Magento-Specific Patterns
- **Layout XML**: Master layout instructions and fallback
- **UI Components**: Work with Magento's UI component library
- **LESS Variables**: Utilize Magento's LESS variable system
- **Theme Inheritance**: Properly implement parent-child theme relationships
- **Fallback Mechanism**: Understand template and layout fallback sequences

### Security
- **Output Escaping**: Always escape output in templates
- **XSS Prevention**: Proper sanitization of user input
- **CSRF Protection**: Implement form key validation
- **Secure Assets**: Serve assets securely

## Testing

- **Browser Testing**: Test across supported browsers
- **Responsive Testing**: Test on various devices and screen sizes
- **Performance Testing**: Validate Core Web Vitals
- **Accessibility Testing**: Test with screen readers and keyboard navigation
- **Functional Testing**: Ensure all functionality works correctly

## References

- [Adobe Commerce Frontend Development](https://developer.adobe.com/commerce/frontend-core/guide/)
- [Theme Development](https://developer.adobe.com/commerce/frontend-core/guide/themes/)
- [Layout XML](https://developer.adobe.com/commerce/frontend-core/guide/layouts/)

Focus on creating themes that deliver exceptional user experiences while maintaining performance and accessibility standards.