🖌️ Default content styles

[Witoso]

CKEditor 5 historically added very few content styles. Only some features, like Mention or Images, defined spacing or colors, and those were adjustable in the integrator’s CSS.

Recently, we’ve noticed the need to add more styles and provide opinionated defaults for a few basic properties.

Sidenote: Keep in mind the editor sets some styles right now, one of them is the background color of the editable (white).

TL;DR Proposal: CKEditor 5 will introduce default content styles (such as font, color, and line-height) in the next major release to address integration issues and enhance accessibility. CSS variables will be standardized (--ck-content-*). This may require a migration as some visual changes may appear.

Dark mode issues in modern frameworks

We’re seeing the rise of default dark mode in frameworks' boilerplate projects. When someone launches a fresh editor, copied from Builder or docs, in new setups using Vite, Next.js, or others, they might be surprised about the effect. At first glance, launching the editor in a bare Vite setup looks fine. But once you start typing, no text appears!

The same issue occurs in Next.js.

The initial reaction is: I did something wrong in the setup, I cannot type. In reality, this is caused by the editor being non-opinionated and intentionally allowing page styles to leak into it. In the dark mode, the text becomes white.

This breaks the initial experience in some setups. Opinionated styles will solve this problem. The editor will display a sensible default look. If someone wants to change the appearance, they can inspect the CSS or refer to the documentation.

Making styling easier for everyone

The web isn’t just for experienced developers. While seasoned devs know how to target the editor and override styles like font color with selectors, the platform gives us better solutions now. CSS custom properties (variables) are a modern and accessible pattern for restyling applications, UI frameworks, or web components. CKEditor 5 already uses them for its features and UI, and we can go further in this direction.

Accessibility and sane defaults

While working on the line height feature, we discussed defaults and accessibility. MDN clearly states:

Use a minimum value of 1.5 for line-height for main paragraph content. This will help people experiencing low vision conditions, as well as people with cognitive concerns such as Dyslexia. If the page is zoomed to increase the text size, using a unitless value ensures that the line height will scale proportionately.

This is one of the few content styles we have already set in Builder by default. Most applications do this anyway because otherwise text becomes too crowded.

Again, providing obvious but changeable defaults makes sense in this case as well.

Other style concerns

While working on fonts and bullet styling (#5752), we noticed that achieving a writer-friendly effect requires deeper overriding of HTML markup to get the desired results. Defaults content styles were brought to the table again, and we will use them in a clever way in this feature too.

---

Proposal

Defaults

In the next release with breaking changes (major), we plan to introduce the following default content styles variables:

:root {
  --ck-content-background: TBD;
  --ck-content-font-family: TBD;
  --ck-content-font-size: TBD;
  --ck-content-font-color: TBD;
  --ck-content-line-height: TBD;
  --ck-content-font-weight: normal;
  --ck-content-font-style: normal;
}

and those will be applied to the content:

.ck-content {
  background: var(--ck-content-background);
  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);
  font-weight: var(--ck-content-font-weight);
  font-style: var(--ck-content-font-style);
}

Some values are still TBD, and will likely be provided in the coming days.

Most likely, these will be the defaults:

• --ck-content-background: #fff
• --ck-content-font-family: Helvetica, Arial, Tahoma, Verdana, Sans-Serif; (same as the editor's UI)
• --ck-content-font-size: 1rem (or medium)
• --ck-content-font-color: #000
• --ck-content-line-height: 1.5

Renames

As we already use some content variables in features. We plan to rename them to use the --ck-content-* prefix. For example:

• --ck-color-mention-background will become --ck-content-color-mention-background

Full list of vars in content styles

--ck-color-base-background
--ck-color-comment-marker
--ck-color-comment-marker-active
--ck-color-image-caption-background
--ck-color-image-caption-text
--ck-color-mention-background
--ck-color-mention-text
--ck-color-selector-caption-background
--ck-color-selector-caption-text
--ck-color-suggestion-marker-deletion-background
--ck-color-suggestion-marker-deletion-background-active
--ck-color-suggestion-marker-deletion-border
--ck-color-suggestion-marker-deletion-border-active
--ck-color-suggestion-marker-deletion-stroke
--ck-color-suggestion-marker-format-border
--ck-color-suggestion-marker-format-border-active
--ck-color-suggestion-marker-insertion-background
--ck-color-suggestion-marker-insertion-background-active
--ck-color-suggestion-marker-insertion-border
--ck-color-suggestion-marker-insertion-border-active
--ck-color-suggestion-widget-deletion-background
--ck-color-suggestion-widget-deletion-background-active
--ck-color-suggestion-widget-format-background
--ck-color-suggestion-widget-format-background-active
--ck-color-suggestion-widget-insertion-background
--ck-color-suggestion-widget-insertion-background-active
--ck-color-suggestion-widget-th-deletion-background
--ck-color-suggestion-widget-th-deletion-background-active
--ck-color-suggestion-widget-th-insertion-background
--ck-color-suggestion-widget-th-insertion-background-active
--ck-highlight-marker-blue
--ck-highlight-marker-green
--ck-highlight-marker-pink
--ck-highlight-marker-yellow
--ck-highlight-pen-green
--ck-highlight-pen-red
--ck-image-style-spacing
--ck-inline-image-style-spacing
--ck-table-of-contents-items-start-padding
--ck-table-of-contents-line-height
--ck-table-of-contents-padding
--ck-todo-list-checkmark-size

CLI code

wget -qO- \ https://cdn.ckeditor.com/ckeditor5/45.0.0/ckeditor5-content.css \ https://cdn.ckeditor.com/ckeditor5-premium-features/45.0.0/ckeditor5-premium-features-content.css \ | awk ' { while (match($0, /var\(\s*--[A-Za-z0-9_-]+/)) { v = substr($0, RSTART+5, RLENGTH-5) print "-" v $0 = substr($0, RSTART+RLENGTH) } } ' \ | sort -u

---

Impact

This change will have an impact on current setups of the editor:

• Updating the editor and using the new styles provided with the update may change how editor content looks and how published content renders.
  • The impact depends on whether any style overrides with higher specificity are already in place. In some cases, the change may not be noticeable.
  • Since fonts and bullet styling may ship in the same release, some updates to variables may be needed to align them and ensure good list rendering. Details will follow.
• If current variables are used and custom values are provided, migration will be required to align with the new naming convention.

---

The future

Being more opinionated about styles will let us implement dark mode more easily (+1 the #18709 if it’s something you’d like to see), mostly through CSS variables. To do that, we first need the core variables listed above.

---

If you'd like to see this improvement implemented, add a 👍 reaction to this post.

[Witoso]

To validate and decide:

• how this impacts exports (inline styles, PDF, Word)
  • the problem that the editable is not always the final publication place: Word, PDF or email,
• defaults values

[Witoso]

Changing the background and font variables to different values.

Export to PDF

Export to Word

Other background issues:

• .ck.ck-editor__main > .ck-editor__editable has a higher specificity than .ck-content.

• this affects comments: saved and writing

  

[Reinmar]

After all these years, I do believe that we should include more opinionated (and essentially "any") default styles. Text styles being one of the key things.

But it's 15 minutes that I stare at the problems that you described (the impact of introducing those default styles) and I can't figure out a heuristic or a design how these styles could be implemented so everything is:

• simple to understand (and ideally simple under the hood)
• simple to integrate (i.e. "it just works")

I'll try to write down my current train of thought. It may lead somewhere, but it's definitely not an answer itself (yet?).

---

To break down the styles that we apply within the editor editable region:

• There are "content styles" represented by the .ck-content selector prefix.
• And there are "UI styles within editor editable region" which we style with some other selectors.

The content styles, in turn, can be used in at least two contexts:

• To style the content when it's inside the editor.
• And to style the content when it's rendered outside the editor.

When it comes to content styles, we can also divide them into two categories:

• Color-theme related
• Other (e.g. margins, line height, etc)

The "other styles" could also be divided further:

• those that might be affected by medium's "responsiveness" (e.g. font size)
• and those which should be rather independent

---

No, depending on the medium, some styles make sense and some don't:

• Inside the editor, loaded in a desktop browser: All styles make sense.
• Inside the editor, loaded on a mobile browser: Some responsive styles need to be altered.
• In print/export: Color-theme related and responsive styles should not apply.
• Within rendered comments: well... I'm not sure if they have anything to do with "content styles" – this is editor interface and those styles should "lead".
• But then there's content inside comments editor's editable region: That's both: content styles and (overridden with) interface styles?

.... I give up here :D

---

Short remark about --ck-content-background. I feel that it should not be applied via .ck-content.

While this is an assumed background of the content and creates sort of a pair with --ck-content-font-color, technically it should be applied to the editable region as an editor interface style. Probably, just like it is applied today.

It may be that the same applies to font color too. I could see them not being treated as content styles. I know this is counter-intuitive. But all (?) colors are theme-related styles and don't apply to mediums outside the editor.

But this leads us to another problem: How many other theme-related styles do we have already within the content styles? How to apply theme? Invent another class to group them? 🙈

So there's also a second option: Maybe these theme-related styles should be overridden in medium's other than "within the editor editable region"?

So, when we display a comment's content or compile styles for PDF/Word, maybe these should be reset back to "not set"?

[Witoso]

Just for explicitness, the following:

  var(--ck-content-font-family);
  var(--ck-content-font-size);
  var(--ck-content-font-color);
  var(--ck-content-font-weight);
  var(--ck-content-font-style);

are needed in #5752, which forces to put them in the content styles AFAIU.

[Witoso]

Wrapping my head around this, and there are tons of valid points in @Reinmar comments.

Using somewhat the lowest surprise heuristic:

• Editor should work after initializing in black theme frameworks: we need font color for that.
• Comments are more part of UI than editor's content. Although we show there the content, comments already use their background color (--ck-color-comment-background).

Using integrator's paths:

• scenario 1 (editing and publishing differs a lot, think headless CMS): I implement the editor, style it the way I want editing to look like, I style how the content will look like separately.
• scenario 2 (WYSIWYG experience): I implement the editor, I align the style of the editing and content to be indentical.
• scenario 3 (app, notion like): editing and publishing is the same thing.
• scenario 4 (I export content to a non-web platform: email, Word, PDF): publishing styling is limited by the capabilities of the platform, it's not possible (to my knowledge) to style the page of Word/PDF export as black. What if email is opened in a black mode, etc.

Based on the above, what we might to do next:

• resign from the default content's background-color: it's too problematic, introduces a lot of surprises especially for scenarios no. 4. Scenarios 1 and 2 will manage with setting their backgrounds or treat content one as transparent. Also from CSS perspective: it's not inherited by default, child elements don’t automatically use their parent’s background color unless inherit is used.
• sidenote: technical implementation of fonts/bullet styling changed a bit, and we may resign from non-obvious --ck-content-font-weight and --ck-content-font-style.

[Witoso]

After some discussion, we decided to introduce --ck-content-word-break: break-word, for small editors it's a must-have, and developers may not notice it will not work well in Firefox in certain cases. This is already added to the Builder's output.