Imported from ProxiBlue/claude-skills (email-theme-styling/SKILL.md). Install upstream with npx skills add ProxiBlue/claude-skills --skill email-theme-styling. Copyright stays with the author.

Magento 2 Email Theme & Styling Skill

Purpose

This skill provides comprehensive guidance on theming and styling Magento 2 transactional emails via theme files. It covers the full email rendering pipeline, CSS inlining architecture, template override patterns, Hyvä Email module integration, and the Tailwind-to-LESS compilation approach.

When to Use This Skill

• Customizing the look and feel of transactional emails (order confirmation, account creation, etc.)
• Overriding email header/footer templates via the theme
• Adding custom CSS styles to emails
• Setting up a custom email logo
• Debugging email rendering or CSS inlining issues
• Understanding how Hyvä interacts with the email system
• Using Tailwind CSS as a source for email styles

Architecture Overview

Email Rendering Pipeline

1. Module defines template in email_templates.xml (e.g. sales_email_order_template)
       ↓
2. TransportBuilder triggers template rendering
       ↓
3. AbstractTemplate::getProcessedTemplate()
   - applyDesignConfig() → emulates store/theme context
   - addEmailVariables() → populates store data, template_styles
       ↓
4. Filter->filter(templateText) processes directives:
   - {{template config_path="design/email/header_template"}} → includes header
   - {{template config_path="design/email/footer_template"}} → includes footer
   - {{css file="css/email.css"}} → outputs CSS in <style> tag
   - {{inlinecss file="css/email-inline.css"}} → queues CSS for inlining
   - {{var variable}} → outputs variable values
   - {{trans "text"}} → translatable strings
   - {{layout handle="..."}} → renders layout blocks
       ↓
5. applyInlineCss() callback:
   - Loads compiled CSS via asset repository
   - Processes CSS placeholders (@base_url_path, @locale)
   - Passes HTML + CSS to Emogrifier (Pelago\Emogrifier\CssInliner)
   - Emogrifier converts CSS selectors to inline style="" attributes
       ↓
6. Final inlined HTML sent via SMTP transport (Symfony Mailer)

Two-File CSS Strategy

Magento splits email CSS into two files because email clients like Gmail strip <style> tags:

The header template (header.html) contains both directives:

<style type="text/css">
    {{var template_styles|raw}}
    {{css file="css/email.css"}}
</style>
<!-- ... later in the template ... -->
{{inlinecss file="css/email-inline.css"}}

The template_styles Variable

Each email template can declare per-template styles in a <!--@styles @--> comment block at the top:

<!--@styles
.custom-class { color: #333; }
@-->

These are injected into the <style> tag via {{var template_styles|raw}}.

Hyvä Email Module

Why It Exists

Hyvä replaces the Luma/Blank LESS-based frontend with TailwindCSS. This breaks the LESS file inheritance chain that Magento's email system depends on. The hyva-themes/magento2-email-module re-adds the necessary LESS files and creates a fallback specifically for email rendering.

Module: Hyva_Email (enabled in app/etc/config.php) Location: vendor/hyva-themes/magento2-email-module/src/

What It Does

1. FallbackRulePlugin - Adds the module's view/frontend/web directory to the design fallback so email.less and email-inline.less are found during static content deployment
2. PackageFilePlugin - Treats the module's static files as global scope for proper deployment

What It Does NOT Do

• Does NOT provide custom email templates (uses default Magento templates)
• Does NOT change the CSS inlining mechanism (still uses Emogrifier)
• Does NOT use TailwindCSS for emails (uses LESS, same as Luma)

LESS Files Provided

Located at vendor/hyva-themes/magento2-email-module/src/view/frontend/web/css/:

LESS Import Chain (email-inline.less)

@import 'source/lib/_lib.less';              // Global Magento UI library
@import 'source/lib/variables/_email.less';  // Global email variables
@import 'source/_theme.less';                // Global variable overrides
@import 'source/_variables.less';            // Local theme variables
@import 'source/_email-variables.less';      // Email-specific variables
@import 'source/_email-base.less';           // Core email styles
@import 'source/_email-extend.less';         // Theme customizations
//@magento_import 'source/_email.less';       // Module-specific email styles

How Styles Get Split

_email-base.less contains all styles. The build splits them:

• Styles inside .email-non-inline() and .media-width() mixins → email.css (in <style> tag)
• Styles outside those mixins → email-inline.css (inlined by Emogrifier)

Theme-Based Email Customization

Directory Structure

app/design/frontend/Uptactics/nto/
├── Magento_Email/
│   ├── email/
│   │   ├── header.html              # Custom email header (wraps ALL emails)
│   │   └── footer.html              # Custom email footer
│   └── web/
│       └── logo_email.png           # Custom email logo
├── Magento_Sales/
│   └── email/
│       ├── order_new.html           # Custom new order email
│       ├── order_new_guest.html     # Custom new order for guests
│       ├── invoice_new.html         # Custom invoice email
│       ├── shipment_new.html        # Custom shipment email
│       └── creditmemo_new.html      # Custom credit memo email
├── Magento_Customer/
│   └── email/
│       ├── account_new.html         # Custom new account email
│       ├── password_new.html        # Custom new password email
│       └── password_reset_confirmation.html
├── Magento_Contact/
│   └── email/
│       └── submitted_form.html      # Custom contact form email
└── web/
    └── css/
        ├── email.less               # Override non-inline styles (optional)
        ├── email-inline.less        # Override inline styles (optional)
        └── source/
            ├── _email-extend.less   # Custom style overrides (recommended)
            ├── _email-variables.less # Custom variable overrides (recommended)
            └── _theme.less          # Global variable overrides

Template Fallback Order

1. Admin-configured templates (database email_template table) - highest priority
2. Current theme (app/design/frontend/Uptactics/nto/)
3. Parent theme (vendor/hyva-themes/magento2-default-theme/)
4. Hyvä Email module (vendor/hyva-themes/magento2-email-module/src/)
5. Module default (vendor/mage-os/module-*/view/frontend/email/)

Override Pattern

Copy the source file to your theme following this path convention:

vendor/mage-os/module-{name}/view/frontend/email/{filename}.html
                ↓
app/design/frontend/Uptactics/nto/Magento_{Name}/email/{filename}.html

For CSS overrides:

vendor/hyva-themes/magento2-email-module/src/view/frontend/web/css/source/_email-extend.less
                ↓
app/design/frontend/Uptactics/nto/web/css/source/_email-extend.less

Common Templates to Override

CSS Customization Approaches

Approach 1: LESS Variable Overrides (Simplest)

Create app/design/frontend/Uptactics/nto/web/css/source/_email-variables.less:

// Brand colors
@email__background-color: #f5f5f5;
@email-body__background-color: #ffffff;
@email-body__width: 600px;

// Links
@link__color: #006bb4;
@link__text-decoration: underline;
@link__visited__color: #006bb4;

// Header
@email-header__background-color: #003366;

// Buttons
@button__background-color: #006bb4;
@button__border-color: #006bb4;
@button__color: #ffffff;

// Typography
@font-family__base: 'Segoe UI', 'Helvetica Neue', Arial, sans-serif;
@font-size__base: 14px;
@heading__color: #333333;

Approach 2: LESS Style Extensions (Moderate)

Create app/design/frontend/Uptactics/nto/web/css/source/_email-extend.less:

@import url("@{baseUrl}css/email-fonts.css");

// Custom header styles
.email-header {
    background-color: @email-header__background-color;
}

// Custom button styles
.email-button {
    border-radius: 4px;
    text-transform: uppercase;
    font-weight: bold;
}

// Custom footer
.email-footer {
    border-top: 2px solid @border__color;
    padding-top: 20px;
}

Approach 3: Tailwind-to-LESS Compilation (Advanced)

Use PostCSS to compile Tailwind @apply directives into LESS-compatible CSS.

Setup

Create app/design/frontend/Uptactics/nto/web/tailwind/emails/postcss.config.js:

module.exports = {
    plugins: [
        require('postcss-import'),
        require('tailwindcss/nesting'),
        require('tailwindcss')({ config: './emails/tailwind.email.config.js' }),
    ]
}

Create app/design/frontend/Uptactics/nto/web/tailwind/emails/tailwind.email.config.js:

const defaultConfig = require('../tailwind.config.js');

module.exports = {
    ...defaultConfig,
    corePlugins: {
        // CRITICAL: Disable opacity plugins - LESS cannot parse RGBA syntax
        backdropOpacity: false,
        backgroundOpacity: false,
        borderOpacity: false,
        divideOpacity: false,
        ringOpacity: false,
        textOpacity: false
    }
};

Create app/design/frontend/Uptactics/nto/web/tailwind/theme/email.css:

.footer {
    @apply border-t-2 border-primary;
}

.email-header {
    @apply bg-primary text-white;
}

.btn-primary {
    @apply bg-primary text-white font-bold py-2 px-4 rounded;
}

Add build script to app/design/frontend/Uptactics/nto/web/tailwind/package.json:

{
    "scripts": {
        "build-email": "npx postcss --config ./emails theme/email.css -o ../css/source/_theme.less"
    }
}

Build

cd app/design/frontend/Uptactics/nto/web/tailwind
npm run build-email

This outputs web/css/source/_theme.less with plain CSS (no Tailwind utilities), which Magento's LESS processor can consume.

Known constraints:

• LESS processor cannot parse RGBA syntax (disable opacity plugins)
• Some border utilities (border-b, border-t) may need explicit CSS fallbacks
• Background image URLs with LESS variables need single quotes: url('@{baseDir}css/bg.svg')

Template Directives Reference

Template Metadata Comments

Every email template starts with metadata:

<!--@subject {{trans "Your %store_name order confirmation" store_name=$store.frontend_name}} @-->
<!--@vars {
"var order.increment_id":"Order ID",
"var order.created_at":"Order Date",
"var billing":"Billing Address HTML"
} @-->
<!--@styles
.custom-table { border: 1px solid #ccc; }
@-->

Available Global Variables

Emogrifier CSS Inlining

How It Works

1. email-inline.less compiled to email-inline.css
2. {{inlinecss}} directive loads the compiled CSS
3. Emogrifier receives full HTML + CSS string
4. CSS selectors matched against DOM elements
5. Matched properties written as inline style="" attributes
6. Modified HTML returned

Supported CSS Selectors

• ID selectors (#id)
• Class selectors (.class)
• Type selectors (table, td, p)
• Descendant selectors (table td)
• Child selectors (table > tr)
• Adjacent sibling (h1 + p)
• Attribute selectors ([attr], [attr=value])

Unsupported (Must Go in email.css)

• Pseudo-classes (:hover, :first-child, :nth-child)
• Pseudo-elements (::before, ::after)
• Universal selector (*)
• Media queries (@media)
• @font-face declarations
• CSS animations/transitions

HTML Best Practices for Email

Layout Rules

• Use table-based layouts (<table>, <tr>, <td>) - not <div> with CSS
• Use HTML4 elements - many clients don't support HTML5
• Set explicit width on tables/images via HTML attribute AND CSS
• Use cellpadding, cellspacing, border attributes on tables
• Avoid position, float, flexbox, grid
• Use align attribute for centering (not margin: 0 auto alone)

CSS Rules

• Use CSS2 properties only - avoid shadows, animations, CSS3
• Use specific properties: padding-top not padding shorthand
• Use full 6-digit hex colors: #FFFFFF not #FFF
• Use standard system fonts: Arial, Verdana, Georgia
• Design buttons at minimum 44x44px for mobile touch targets
• Keep email width at 600px maximum

Responsive Design

• Place media queries in .media-width() mixins (outputs to email.css)
• Use percentage widths for fluid layouts within the 600px container
• Minimum font size 14px for body text
• Test across: Gmail (web/app), Outlook (desktop/web), Apple Mail, Yahoo Mail

Email Logo Customization

Via Theme File

Place logo at:

app/design/frontend/Uptactics/nto/Magento_Email/web/logo_email.png

Via Admin Panel

Navigate to: Content > Design > Configuration > [Store View] > Transactional Emails

• Upload logo image (JPG, GIF, PNG; max 2MB)
• Set alt text, width, height

Retina Support

Provide image at 3x display size. For 200x100px display, upload 600x300px image and set:

• Logo Width: 200
• Logo Height: 100

Build & Deployment

Compile Email CSS

# Deploy static content (includes email CSS compilation)
ddev exec bin/magento setup:static-content:deploy -f --area=frontend --theme Uptactics/nto

# Or use composer script
ddev exec composer build-static

# Verify compiled output exists
ls -la pub/static/frontend/Uptactics/nto/en_US/css/email*.css

Clear Caches After Changes

# Clear view preprocessed (required for LESS changes)
ddev exec rm -rf var/view_preprocessed/*

# Clear static content
ddev exec rm -rf pub/static/frontend/Uptactics/nto/*

# Flush Magento cache
ddev exec bin/magento cache:flush

# Redeploy static content
ddev exec bin/magento setup:static-content:deploy -f --area=frontend --theme Uptactics/nto

Full Email Style Rebuild

ddev exec rm -rf var/view_preprocessed/* pub/static/frontend/Uptactics/nto/*
ddev exec bin/magento cache:flush
ddev exec bin/magento setup:static-content:deploy -f --area=frontend --theme Uptactics/nto

Verifying Email Changes via Mailpit

IMPORTANT: Every email styling change MUST be visually verified via Mailpit before considering the change complete. This is a mandatory step in the workflow.

Mailpit Access

DDEV runs Mailpit internally to capture all outgoing emails. No emails leave the local environment.

• Browser UI: https://ntotank.ddev.site:8443/mailpit/
• API Base URL: http://127.0.0.1:8025/mailpit/api/v1/

Mailpit API Reference

All API calls use the base URL http://127.0.0.1:8025/mailpit/api/v1/.

Verification Workflow

After making any email template or CSS change, follow this process:

Step 1: Rebuild and Clear Caches

ddev exec rm -rf var/view_preprocessed/* pub/static/frontend/Uptactics/nto/*
ddev exec bin/magento cache:flush
ddev exec bin/magento setup:static-content:deploy -f --area=frontend --theme Uptactics/nto

Step 2: Trigger a Test Email

Place a test order or trigger the relevant transactional email from the admin panel. For order emails, use the admin to create a test order or resend an existing order confirmation.

Step 3: Check Mailpit for the Email

# List all captured emails
curl -s http://127.0.0.1:8025/mailpit/api/v1/messages | python3 -m json.tool

# Get the most recent email's ID and subject
curl -s http://127.0.0.1:8025/mailpit/api/v1/messages | python3 -c "
import sys, json
data = json.load(sys.stdin)
for msg in data['messages']:
    print(f'ID: {msg[\"ID\"]}')
    print(f'Subject: {msg[\"Subject\"]}')
    print(f'From: {msg[\"From\"][\"Name\"]} <{msg[\"From\"][\"Address\"]}>')
    print(f'To: {msg[\"To\"][0][\"Name\"]} <{msg[\"To\"][0][\"Address\"]}>')
    print(f'Date: {msg[\"Created\"]}')
    print('---')
"

Step 4: Inspect the Email HTML

# Get full message details (includes HTML, Text, metadata)
curl -s http://127.0.0.1:8025/mailpit/api/v1/message/{MESSAGE_ID} | python3 -m json.tool

# Get just the rendered HTML (for saving/viewing)
curl -s http://127.0.0.1:8025/mailpit/api/v1/message/{MESSAGE_ID}/html > /tmp/email_preview.html

Step 5: Visual Verification

Open Mailpit in the browser to visually confirm styling:

https://ntotank.ddev.site:8443/mailpit/

Click on the email to view the rendered HTML. Mailpit displays the email as it would appear in a mail client. Check:

• Logo renders correctly with proper dimensions
• Brand colors are applied (header, buttons, links)
• Typography is consistent (font family, sizes, weights)
• Table layouts are properly structured (order items, totals, addresses)
• Footer content is present and styled
• Responsive layout works (Mailpit supports viewport toggling)

Step 6: Verify CSS Inlining

To confirm Emogrifier is properly inlining styles, inspect the raw HTML:

# Check that inline style attributes are present on elements
curl -s http://127.0.0.1:8025/mailpit/api/v1/message/{MESSAGE_ID}/html | grep -o 'style="[^"]*"' | head -20

# Check for <style> tag content (non-inline styles like media queries)
curl -s http://127.0.0.1:8025/mailpit/api/v1/message/{MESSAGE_ID}/html | grep -oP '<style[^>]*>.*?</style>' | head -5

What to look for:

• style="" attributes on <body>, <table>, <td>, <p>, <a>, <h1>-<h6> elements confirm inlining is working
• <style> tag should contain media queries and :hover/:visited/:active pseudo-class rules
• No unstyled elements that should have brand colors/fonts applied

Quick Verification Checklist

After every email style change, confirm ALL of the following:

• Email captured in Mailpit (check message list)
• Logo image loads correctly (not broken image icon)
• Brand colors visible in header area
• Link colors match brand (not default blue)
• Button styles applied (background color, text color, border radius)
• Table layout for order items is properly aligned
• Totals section (subtotal, shipping, grand total) is formatted
• Footer text and contact info present
• Inline style attributes present on HTML elements (Emogrifier working)
• Media queries present in <style> tag (responsive styles)

Admin Preview (Alternative)

Navigate to: Marketing > Communications > Email Templates

1. Create a new template (or load default)
2. Click "Preview Template" to see rendered output

Note: Admin preview does NOT process {{inlinecss}} or {{css}} directives. Mailpit shows the actual rendered email as sent, making it the definitive verification method.

Cross-Client Testing (Production)

For production readiness, additionally test on these priority clients:

1. Gmail (web + mobile app) - strips <style> tags, inline only
2. Outlook (desktop) - uses Word rendering engine, limited CSS
3. Apple Mail (iOS/macOS) - best CSS support
4. Yahoo Mail - strips some styles
5. Use Litmus or Email on Acid for comprehensive cross-client testing

Strict Mode Restrictions (Magento 2.4+)

Custom email templates cannot call methods directly on objects. Only scalar values and DataObject getData() access are allowed.

Forbidden (Will Break)

{{var order.getCustomerName()}}
{{var subscriber.getConfirmationLink()}}

Allowed

{{var order_data.customer_name}}
{{var subscriber_data.confirmation_link}}

Check Compatibility

ddev exec bin/magento dev:email:override-compatibility-check
ddev exec bin/magento dev:email:newsletter-compatibility-check

Troubleshooting

"LESS file is empty" Error

CSS inlining error: Compilation from source: LESS file is empty: frontend/.../css/email-inline.less

Cause: Hyvä theme doesn't have LESS files in its inheritance chain. Fix: Ensure Hyva_Email module is enabled:

ddev exec bin/magento module:status Hyva_Email
ddev exec bin/magento module:enable Hyva_Email
ddev exec bin/magento setup:upgrade

Styles Not Appearing in Emails

1. Clear preprocessed files: ddev exec rm -rf var/view_preprocessed/*
2. Clear static content: ddev exec rm -rf pub/static/frontend/Uptactics/nto/*
3. Redeploy: ddev exec bin/magento setup:static-content:deploy -f --area=frontend
4. Flush cache: ddev exec bin/magento cache:flush
5. Verify compiled CSS exists: ls pub/static/frontend/Uptactics/nto/en_US/css/email*.css

Emogrifier Not Inlining Styles

• Verify selectors are supported (no pseudo-classes, no *)
• Check that styles are in email-inline.less, not email.less
• Ensure HTML elements have matching classes/IDs
• In developer mode, Emogrifier outputs debug info

Template Overrides Not Loading

1. Verify file path matches convention: Magento_{ModuleName}/email/{filename}.html
2. Check file permissions are readable
3. Run ddev exec bin/magento cache:flush
4. Check if admin has a custom template configured (database overrides take priority)

Key File Locations

Core Engine

• vendor/mage-os/module-email/Model/AbstractTemplate.php - Template loading & processing
• vendor/mage-os/module-email/Model/Template/Filter.php - Directive processing (1,145 lines)
• vendor/mage-os/framework/Css/PreProcessor/Adapter/CssInliner.php - Emogrifier wrapper

Hyvä Email Module

• vendor/hyva-themes/magento2-email-module/src/view/frontend/web/css/ - LESS source files
• vendor/hyva-themes/magento2-email-module/src/Plugin/FallbackRulePlugin.php - Design fallback
• vendor/hyva-themes/magento2-email-module/src/Plugin/PackageFilePlugin.php - Static deployment

Default Templates

• vendor/mage-os/module-email/view/frontend/email/header.html - Email header
• vendor/mage-os/module-email/view/frontend/email/footer.html - Email footer
• vendor/mage-os/module-sales/view/frontend/email/ - All sales email templates (16 templates)
• vendor/mage-os/module-customer/view/frontend/email/ - Customer email templates
• vendor/mage-os/module-contact/view/frontend/email/ - Contact form template

Template Registration

• vendor/mage-os/module-email/etc/email_templates.xml - Header/footer template IDs
• vendor/mage-os/module-sales/etc/email_templates.xml - Sales template IDs (16 templates)
• vendor/mage-os/module-customer/etc/email_templates.xml - Customer template IDs

Compiled Output

• pub/static/frontend/Uptactics/nto/en_US/css/email.css - Non-inline styles
• pub/static/frontend/Uptactics/nto/en_US/css/email-inline.css - Inline styles
• pub/static/frontend/Uptactics/nto/en_US/css/email-fonts.css - Font declarations

Admin Configuration

• Content > Design > Configuration > Transactional Emails - Logo, header/footer template selection
• Marketing > Communications > Email Templates - Create/edit custom templates
• Stores > Configuration > Sales > Sales Emails - Enable/disable specific email types

References

• Adobe Commerce - Email Templates
• Adobe Commerce - Email Template Migration (Strict Mode)
• Hyvä Docs - Styling Emails
• Hyvä Docs - Styling Emails with Tailwind CSS
• GitHub - hyva-themes/magento2-email-module
• Emogrifier Library