Merge pull request #18765 from ckeditor/ck/18710

Other (core): Implemented the --ck-content-font-family, --ck-content-font-size and --ck-content-font-color CSS variables to standardize font family, size, and color styling in CKEditor 5 content. Closes #18710.

MAJOR BREAKING CHANGE: The editor now enforces a default font family of Helvetica, Arial, Tahoma, Verdana, Sans-Serif, affecting both editing and rendered content. This may impact existing styling and layout, so custom font-family settings should be reviewed. See #18710.

MAJOR BREAKING CHANGE: The editor now enforces a default font size of medium, affecting both editing and rendered content. This may impact existing styling and layout, so custom font-size settings should be reviewed. See #18710.

MAJOR BREAKING CHANGE: The editor now enforces a default font color of #000, affecting both editing and rendered content. This may impact existing styling and layout, so custom color settings should be reviewed. See #18710.

MAJOR BREAKING CHANGE: The editor now enforces a default word break of break-word, affecting both editing and rendered content. This may impact existing styling and layout, so custom word-break settings should be reviewed. See #18710.

Author: Witoso

docs/getting-started/setup/css.md

@@ -60,14 +60,36 @@ For example, the override below will tweak the border radius of several elements
 
 ## Customizing the look of the features
 
-Similarly to the customizable editor look, some features also provide an interface to change their styles via [native CSS variables](https://www.w3.org/TR/css-variables/).
+Similarly to the customizable editor look, some features also provide an interface to change their styles via [native CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_cascading_variables/Using_CSS_custom_properties).
 
-For example, if you want to change the color of the mentions' background and text, you can do the following override:
+### General content styling
+
+CKEditor 5 provides CSS variables to standardize font and line height styling across the content. These variables control the default appearance of text the content. You can override them in the following way:
+
+```css
+:root {
+	/* Override the default font family */
+	--ck-content-font-family: "Roboto";
+	
+	/* Override the default font size */
+	--ck-content-font-size: 16px;
+	
+	/* Override the default font color */
+	--ck-content-font-color: hsl(225, 5%, 45.00%);
+
+	/* Override the default line height */
+	--ck-content-line-height: 2;
+}
+```
+
+### Feature-specific styling
+
+Individual features also provide CSS variables for their specific styling needs. For example, if you want to change the color of the mentions' background and text, you can do the following override:
 
 ```css
 :root {
-	--ck-color-mention-background: black;
-	--ck-color-mention-text: white;
+	--ck-content-color-mention-background: black;
+	--ck-content-color-mention-text: white;
 }
 ```
 

docs/updating/update-to-46.md

@@ -80,19 +80,18 @@ If your build throws errors after the update, search and replace the old names w
 	Manually updating all these numerous imports could be time-consuming and error-prone. We recommend using the [tables with the changed import/export names](https://raw.githubusercontent.com/ckeditor/ckeditor5/refs/heads/master/docs/updating/nim-migration/migrating-exports.md) as context for tools such as Copilot, ChatGPT, or other LLM-based services that can automatically update all imports in your project.
 </info-box>
 
-Last but not least, this release put us on the clean and straight path towards the [deprecation of old installation methods](https://github.com/ckeditor/ckeditor5/issues/17779). Please let us know if you have any questions on GitHub or support channels.
-
-### Opinionated default content styles and CSS renames
+### Introduction of the default content styles
 
 To improve the out-of-the-box experience and accessibility, we are introducing opinionated defaults for content styling. From this version, we ship a small defaults layer applied to `.ck-content`:
 
 ```css
 
 :root {
---ck-content-font-family: Helvetica, Arial, Tahoma, Verdana, Sans-Serif;
---ck-content-font-size: medium;
---ck-content-font-color: #000;
---ck-content-line-height: 1.5;
+  --ck-content-font-family: Helvetica, Arial, Tahoma, Verdana, Sans-Serif;
+  --ck-content-font-size: medium;
+  --ck-content-font-color: #000;
+  --ck-content-line-height: 1.5;
+  --ck-content-word-break: break-word;
 }
 
 .ck-content {
@@ -103,11 +102,13 @@ To improve the out-of-the-box experience and accessibility, we are introducing o
 }
 ```
 
-Those content styles are easily replaceable via CSS variable override. It is possible that you already style those things with more specific selectors. 
+Those content styles are easily replaceable via CSS variable override. It is possible that you already style those things with more specific selectors but we recommend to use the variables from now on.
+You can read more about the reasons in our [GitHub issue](https://github.com/ckeditor/ckeditor5/issues/18710).
 
-While working on this initiative, we decided to standardize the CSS naming, too. All older variables that applied to the content styles now share the consistent `--ck-content-*` prefix.
+**Migration:**
+* If you notice that the new editor's content styling affected your content appearance, make sure to update your custom style sheet, and use the new variable names.
 
-#### Content area CSS variables renamed to `--ck-content-*` prefix
+### Content area CSS variables renamed to `--ck-content-*` prefix
 
 To improve consistency, all CSS variables that affect the styles of the editor content area ("content styles") have been renamed to use the `--ck-content-*` prefix. This change affects variables used for highlights, image captions, mentions, table captions, image style spacing, and to-do list checkmarks.
 

packages/ckeditor5-core/theme/core.css

@@ -4,9 +4,18 @@
  */
 
 :root {
+	--ck-content-font-family: Helvetica, Arial, Tahoma, Verdana, Sans-Serif;
+	--ck-content-font-size: medium;
+	/* stylelint-disable-next-line declaration-property-value-disallowed-list */
+	--ck-content-font-color: #000;
 	--ck-content-line-height: 1.5;
+	--ck-content-word-break: break-word;
 }
 
 .ck-content {
+	font-family: var(--ck-content-font-family);
+	font-size: var(--ck-content-font-size);
+	color: var(--ck-content-font-color);
 	line-height: var(--ck-content-line-height);
+	word-break: var(--ck-content-word-break);
 }

packages/ckeditor5-page-break/theme/pagebreak.css

@@ -27,7 +27,6 @@
 	text-transform: uppercase;
 	border: 1px solid hsl(0, 0%, 77%);
 	border-radius: 2px;
-	font-family: Helvetica, Arial, Tahoma, Verdana, Sans-Serif;
 	font-size: 0.75em;
 	font-weight: bold;
 	color: hsl(0, 0%, 20%);