Document MJML theme tokens for GrapesJS Builder

[promptless-for-oss]

Open this suggestion in Promptless to view citations and reasoning process

Add documentation for the new MJML theme tokens feature that enables developers to define reusable style classes in email templates using mj-class definitions and automatic token application to new components.

Trigger Events

• mautic/mautic PR #16042: MJML theme tokens

---

Tip: Adjust how proactive or focused Promptless is in Agent Settings ⚙️

[promptless-for-oss]

Added MJML theme tokens section based on the new grapesjs-mjmlThemeTokens plugin introduced in PR #16042. Plugin source at plugins/GrapesJsBuilderBundle/Assets/library/js/plugins/grapesjs-mjmlThemeTokens/index.js.

Source: mautic/mautic#16042

[promptless-for-oss]

Default token mappings (t-body, t-btn t-btn-primary, t-section t-surface-1) taken from the defaults configuration object in index.js:3-20.

Source: https://github.com/mautic/mautic/pull/16042/files#diff-6d7a0c3c1b3e1d8e5f7a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4

[promptless-for-oss]

Utility functions extractMjHeadContent and createHeadInjectingMjmlParser documented from plugins/GrapesJsBuilderBundle/Assets/library/js/plugins/grapesjs-mjmlThemeTokens/utils.js.

Source: mautic/mautic#16042

[adiati98]

@promptless-for-oss please address the suggestions.

[promptless-for-oss]

Thanks for the feedback @escopecz! I've updated the documentation to clarify where to place the event listener code.

The "Custom events" section now explains that this JavaScript code belongs inside a custom GrapesJS Plugin, with a cross-reference to the "GrapesJS Builder Plugins" section for guidance on creating plugins.

[patrykgruszka]

I would suggest to add only these sections:

• MJML Theme tokens
• Defining Theme tokens
• How the Theme tokens Plugin works

To remove (not useful and I'm not sure if it's correct):

• Utility functions
• Custom events

[patrykgruszka]

This is part of core implementation, not configurable. Lets remove this section.

Suggested change

	**Plugin configuration options**
	Developers creating custom Plugins can configure the Theme tokens behavior:
	.. code-block:: javascript
	{
	// Provide mj-head inner content (preferred) or full original MJML
	headContent: '',
	originalMjml: '',
	// Default token mapping for newly dropped components
	defaults: {
	text: 't-body',
	button: 't-btn t-btn-primary',
	section: 't-section t-surface-1',
	},
	// Types to auto-apply defaults to
	applyDefaultsToTypes: ['mj-text', 'mj-button', 'mj-section'],
	}

[promptless-for-oss]

Thanks for the review feedback @patrykgruszka! I've updated the documentation to address your comments:

Removed sections:

• Plugin configuration options (core implementation, not configurable)
• Utility functions
• Custom events

Kept sections:

• MJML Theme tokens (overview)
• Defining Theme tokens
• How the Theme tokens Plugin works

The documentation now focuses only on what developers need to use the feature. Please take another look when you have a chance.

[promptless-for-oss]

Thanks for the additional feedback @patrykgruszka! I've removed the "How the Theme tokens Plugin works" section as requested — it was documenting internal core implementation rather than developer-configurable content.

The documentation now contains only:

• Overview of the MJML Theme tokens feature
• How to define Theme tokens in templates

Please let me know if there's anything else that needs adjustment.

[patrykgruszka]

Based on the reference guidelines provided, the docs update contains two critical errors in the MJML code block.

Here are the discrepancies:

1. Self-closing tags are used: The diff uses self-closing tags (e.g., <mj-class name="t-body" ... />). Section 7 of the guidelines explicitly forbids this, stating: "Self-closing syntax (e.g. <mj-class ... />) causes parsing issues. Always use explicit open/close pairs."
2. Missing <mj-attributes> tag: In the diff, the <mj-class> elements are placed directly inside <mj-head>. In MJML, they must be wrapped inside an <mj-attributes> block.

Suggested Correction

You need to update the reStructuredText code snippet to fix the MJML structure.

Click to expand the corrected diff snippet

@@ -43,6 +43,74 @@ The GrapesJS Builder doesn't require any special HTML syntax to edit content in
       </mj-body>
     </mjml>
 
+.. vale off
+
+MJML Theme tokens
+*****************
+
+.. vale on
+
+From Mautic 7, the GrapesJS Builder supports MJML Theme tokens. You can define reusable style classes in the ``<mj-head>`` section of your MJML Email templates using ``<mj-class>`` elements inside an ``<mj-attributes>`` block. When Users drop new Components into the Email Builder, Mautic automatically applies the matching Theme tokens, keeping styling consistent across the Email.
+
+.. vale off
+
+Defining Theme tokens
+=====================
+
+.. vale on
+
+Define Theme tokens in the ``<mj-head>`` section of your MJML template using ``<mj-class>`` elements wrapped in ``<mj-attributes>``. Each class specifies CSS properties that apply to Components using it. Note that self-closing tags can cause parsing issues; always use explicit open/close pairs.
+
+.. code-block:: html
+
+    <mjml>
+      <mj-head>
+        <mj-attributes>
+          <mj-class name="t-body" color="#333333" font-family="Arial, sans-serif"></mj-class>
+          <mj-class name="t-btn" background-color="#007bff" color="#ffffff"></mj-class>
+          <mj-class name="t-btn-primary" border-radius="4px"></mj-class>
+          <mj-class name="t-section" padding="20px"></mj-class>
+          <mj-class name="t-surface-1" background-color="#f8f9fa"></mj-class>
+        </mj-attributes>
+      </mj-head>
+      <mj-body>
+        <mj-section mj-class="t-section t-surface-1">
+          <mj-column>
+            <mj-text mj-class="t-body">Welcome to our newsletter</mj-text>
+            <mj-button mj-class="t-btn t-btn-primary" href="#">Click here</mj-button>
+          </mj-column>
+        </mj-section>
+      </mj-body>
+    </mjml>
+
+The builder parses these ``<mj-class>`` definitions and applies them to matching component types automatically.
+
+.. vale off
+
+How the Theme tokens Plugin works
+=================================
+
+.. vale on
+
+The ``grapesjs-mjmlThemeTokens`` Plugin provides automatic Theme token handling.
+
+**Default token mappings**
+
+The Plugin maps Component types to default Theme tokens:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Component type
+     - Default token
+   * - ``mj-text``
+     - ``t-body``
+   * - ``mj-button``
+     - ``t-btn t-btn-primary``
+   * - ``mj-section``
+     - ``t-section t-surface-1``
+
+When a User drops a new Component, the Plugin checks if the tokens exist in the template's ``<mj-head>``. If they do, it automatically applies them via the ``mj-class`` attribute.
+
 GrapesJS Builder Plugins
 ************************

Summary of changes made to the diff:

• Added the <mj-attributes> opening and closing tags.
• Replaced all /> self-closing <mj-class> tags with ></mj-class>.
• Updated the introductory text to specify that <mj-class> must go inside <mj-attributes>, and added a warning regarding self-closing tags.

[promptless-for-oss]

Thanks for catching those MJML syntax errors @patrykgruszka! I've fixed both issues:

1. ✅ Wrapped <mj-class> elements inside <mj-attributes> block
2. ✅ Replaced self-closing tags (/>) with explicit ></mj-class> closing tags
3. ✅ Updated the prose to document that <mj-class> must be inside <mj-attributes>
4. ✅ Added a note about avoiding self-closing syntax

Please take another look when you have a chance.