From adebbd251f5a050ab4d6b0bdfc113d94e7668029 Mon Sep 17 00:00:00 2001
From: Jeslyn Bo <jeslyn.bo@tiny.cloud>
Date: Thu, 14 May 2026 11:32:04 +1000
Subject: [PATCH] DOC-618: Enhance inline mode documentation: clarify CSS
 handling and styling recommendations

---
 modules/ROOT/pages/use-tinymce-inline.adoc     | 18 ++++++++++++++++++
 .../partials/configuration/content_css.adoc    |  2 +-
 .../partials/configuration/content_style.adoc  |  2 ++
 3 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/modules/ROOT/pages/use-tinymce-inline.adoc b/modules/ROOT/pages/use-tinymce-inline.adoc
index c3b580a7b5..1dac058d8a 100644
--- a/modules/ROOT/pages/use-tinymce-inline.adoc
+++ b/modules/ROOT/pages/use-tinymce-inline.adoc
@@ -49,3 +49,21 @@ The following demonstration is using four {productname} editors in inline mode,
 liveDemo::inline[]
 
 For information on inline mode and the `+inline+` setting, see: xref:inline-editor-options.adoc#inline[User interface options - inline].
+
+== Styling content in inline mode
+
+In inline mode, {productname}’s editor content area is not contained within an iframe sandbox, unlike in the classic editor mode.
+
+When using:
+* `+content_css+`
+* `+content_style+`
+
+the styles are loaded into and applied within the host page. In inline mode, this means they can affect other page elements depending on CSS selectors and scoping.
+
+=== Recommended approaches for styling content in inline mode
+
+*Preferred:* Add content styles directly to the host page's stylesheet, scoped to the editable element (e.g., using a CSS class on the editable element).
+
+*Alternative:* Use body_class to scope editor styles to a specific class, preventing them from applying globally.
+
+*Avoid:* Using content_css or content_style for content styling in inline mode — reserve them only for editor UI component adjustments if needed.
diff --git a/modules/ROOT/partials/configuration/content_css.adoc b/modules/ROOT/partials/configuration/content_css.adoc
index fbcc163b39..efd00607e9 100644
--- a/modules/ROOT/partials/configuration/content_css.adoc
+++ b/modules/ROOT/partials/configuration/content_css.adoc
@@ -5,7 +5,7 @@ The `+content_css+` option loads the specified CSS files into the editable area.
 
 *Type:* `+String+`, `+Array+`
 
-NOTE: This option is intended for use with {productname}'s classic mode, as the editable area is sandboxed within an iframe. For inline mode editors, relevant CSS stylesheets should be loaded as part of the webpage {productname} is rendered in, not using the `+content_css+` option.
+NOTE: This option is intended for use with {productname}'s xref:use-tinymce-classic.adoc[classic mode], as the editable area is sandboxed within an iframe. For xref:use-tinymce-inline.adoc[inline mode] editors, relevant CSS stylesheets should be loaded as part of the webpage {productname} is rendered in, not using the content_css option. Applying these iframe-targeted styles in inline mode can lead to unexpected style leakage, layout shifts, or overflow issues (e.g., content spilling outside its container) because editor styles interact directly with the surrounding page.
 
 include::partial$misc/shipped-content-css.adoc[]
 
diff --git a/modules/ROOT/partials/configuration/content_style.adoc b/modules/ROOT/partials/configuration/content_style.adoc
index 92e9ce116f..5f9e11cf0f 100644
--- a/modules/ROOT/partials/configuration/content_style.adoc
+++ b/modules/ROOT/partials/configuration/content_style.adoc
@@ -3,6 +3,8 @@
 
 This option allows custom CSS styles to be set as a string. The styles are injected into the `+head+` of the page containing the editable area. In {productname}'s classic mode, it is injected into the `+head+` of {productname}'s iframe. In inline mode, it is injected into the `+head+` of the page {productname} is rendered in.
 
+NOTE: In xref:use-tinymce-classic.adoc[classic mode], styles are scoped to {productname}’s iframe. In xref:use-tinymce-inline.adoc[inline mode], content_style is injected into the host page, so styles may affect other elements if not properly scoped, potentially causing style conflicts, overflow risk or layout issues.
+
 *Type:* `+String+`
 
 NOTE: `+content_style+` styles are not saved within {productname}'s content. If they are needed for display purposes, ensure the styles are also included in the page the content will be displayed on.