|
|
@@ -5,11 +5,9 @@ order: 10
|
|
|
|
|
|
# Theme customization
|
|
|
|
|
|
-The [`@ckeditor/ckeditor5-theme-lark`](https://www.npmjs.com/package/@ckeditor/ckeditor5-theme-lark) is the default theme of CKEditor 5. Lark is modular, [BEM–friendly](https://en.bem.info/methodology/css/) and built in [SASS](http://sass-lang.com).
|
|
|
+The [`@ckeditor/ckeditor5-theme-lark`](https://www.npmjs.com/package/@ckeditor/ckeditor5-theme-lark) is the default theme of CKEditor 5. Lark is modular, [BEM–friendly](https://en.bem.info/methodology/css/) and built using [PostCSS](http://postcss.org/).
|
|
|
|
|
|
-Although it was designed with versatility and the most common editor use cases in mind, some integrations may require adjustments to make it match the style guidelines of the ecosystem. This kind of customization can be done in two different ways, which can also be used together if needed:
|
|
|
- * By building the editor with a set of custom SASS variables and overriding [defaults](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#Variable_Defaults___default), which does not change the size of the build.
|
|
|
- * By importing an extra `.scss` file and overriding the CSS rules, which increases the size of the build.
|
|
|
+Although it was designed with versatility and the most common editor use cases in mind, some integrations may require adjustments to make it match the style guidelines of the ecosystem. This kind of customization can be done by importing an extra `.css` file and overriding the [native CSS variables](https://www.w3.org/TR/css-variables/).
|
|
|
|
|
|
You can see the demo of an editor with the dark theme as a result of customizations described later in this guide:
|
|
|
|
|
|
@@ -25,214 +23,164 @@ CKEditor 5 is bundled using [webpack](https://webpack.js.org/) and it handles th
|
|
|
|
|
|
The entire process of building and managing the styles boils down to three steps:
|
|
|
|
|
|
-1. **Collecting**: Each JavaScript file in the project can import multiple `.scss` files using the ES6 [`import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) directive. Imported files are handled by the [CSS Loader](https://www.npmjs.com/package/css-loader).
|
|
|
+1. **Collecting**: Each JavaScript file in the project can import multiple `.css` files using the ES6 [`import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) directive. Imported files are handled by the [PostCSS Loader](https://www.npmjs.com/package/postcss-loader).
|
|
|
|
|
|
```js
|
|
|
- import '../theme/theme.scss';
|
|
|
+ import '../theme/styles.css';
|
|
|
|
|
|
class AnyEditorClass {
|
|
|
...
|
|
|
}
|
|
|
```
|
|
|
|
|
|
- ```scss
|
|
|
- // Contents of theme.scss.
|
|
|
- $color: red;
|
|
|
-
|
|
|
- .ck-editor {
|
|
|
- color: $color;
|
|
|
+ ```css
|
|
|
+ /* Contents of styles.css. */
|
|
|
+ :root {
|
|
|
+ --color: red;
|
|
|
}
|
|
|
- ```
|
|
|
|
|
|
-2. **Compiling**: The [SASS Loader](https://www.npmjs.com/package/sass-loader) compiles `.scss` files from SASS to CSS. Each file is compiled asynchronously, in a separate SASS thread.
|
|
|
-
|
|
|
- ```scss
|
|
|
.ck-editor {
|
|
|
- color: $color; // -> color: red;
|
|
|
+ color: var(--color);
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-3. **Loading**: Finally the [Style loader](https://www.npmjs.com/package/style-loader) loads the output CSS along with the `ckeditor.js` file into a `<style>` element in the `<head>` section of the web page.
|
|
|
+2. **Processing**: The PostCSS Loader processes `.css` files to the output CSS. Each file is compiled asynchronously, in a separate processor thread using pre–defined plugins.
|
|
|
+
|
|
|
+3. **Loading**: Finally the [style loader](https://www.npmjs.com/package/style-loader) loads the output CSS along with the `ckeditor.js` file into a `<style>` element in the `<head>` section of the web page.
|
|
|
|
|
|
```html
|
|
|
<head>
|
|
|
<style type="text/css">
|
|
|
.ck-editor {
|
|
|
- color: red;
|
|
|
+ color: var(--color);
|
|
|
}
|
|
|
</style>
|
|
|
</head>
|
|
|
```
|
|
|
|
|
|
-## Customization with SASS variables
|
|
|
+## Customization with CSS variables
|
|
|
|
|
|
-Having {@link builds/guides/development/custom-builds#Forking-an-existing-build cloned} an existing build of CKEditor for a quick start, take a look at the specific definitions in the `webpack.config.js` file.
|
|
|
+Having {@link builds/guides/development/custom-builds#forking-an-existing-build cloned} an existing build of CKEditor for a quick start, let's use the full potential of CSS variables. The customization in this guide will make the theme dark, with slightly bigger text and more rounded corners.
|
|
|
|
|
|
-```js
|
|
|
-module: {
|
|
|
- rules: [
|
|
|
- ...
|
|
|
- {
|
|
|
- test: /\.scss$/,
|
|
|
- use: [
|
|
|
- 'style-loader',
|
|
|
- 'css-loader',
|
|
|
- 'sass-loader'
|
|
|
- ]
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-```
|
|
|
+<info-box hint>
|
|
|
+ Check out the [colors sheet](https://github.com/ckeditor/ckeditor5-theme-lark/blob/master/theme/ckeditor5-ui/globals/_colors.css) for the full list of customizable colors. You can also browse [other files](https://github.com/ckeditor/ckeditor5-theme-lark/blob/master/theme/ckeditor5-ui/globals) to learn about other useful tools.
|
|
|
+</info-box>
|
|
|
|
|
|
-Each SASS file is compiled in a separate thread, so to override default variables (defined with `!default`) across the theme, new values must be imported or declared at the very beginning of **each single** SASS file's compilation process. SASS Loader offers the [`data`](https://www.npmjs.com/package/sass-loader#environment-variables) option to do this.
|
|
|
+The file containing custom variables will be named `custom.css` and it will look as below:
|
|
|
|
|
|
+```css
|
|
|
+:root {
|
|
|
+ /* Overrides the border-radius setting in the theme. */
|
|
|
+ --ck-border-radius: 4px;
|
|
|
|
|
|
-Now [`@import`](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#_import__import) a `custom.scss` file located in the root of the repository containing all custom variables.
|
|
|
+ /* Overrides the default font size in the theme. */
|
|
|
+ --ck-font-size-base: 14px;
|
|
|
|
|
|
-```js
|
|
|
-use: [
|
|
|
- 'style-loader',
|
|
|
- 'css-loader',
|
|
|
- {
|
|
|
- loader: 'sass-loader',
|
|
|
- options: {
|
|
|
- data: `@import 'custom.scss';`
|
|
|
- }
|
|
|
- }
|
|
|
-]
|
|
|
-```
|
|
|
+ /* Helper variables to avoid duplication in the colors. */
|
|
|
+ --ck-custom-background: hsl(270, 1%, 29%);
|
|
|
+ --ck-custom-foreground: hsl(255, 3%, 18%);
|
|
|
+ --ck-custom-border: hsl(300, 1%, 22%);
|
|
|
+ --ck-custom-white: hsl(0, 0%, 100%);
|
|
|
|
|
|
-Using the full potential of SASS variables, the customization will make the theme dark, with slightly bigger text and more rounded corners.
|
|
|
+ /* -- Overrides generic colors -------------------------------------------------------------- */
|
|
|
|
|
|
-<info-box hint>
|
|
|
- Check out the [colors helper](https://github.com/ckeditor/ckeditor5-theme-lark/blob/master/theme/helpers/_colors.scss) for the full list of customizable colors. You can also browse [other helpers](https://github.com/ckeditor/ckeditor5-theme-lark/tree/master/theme/helpers) to learn about other useful SASS variables.
|
|
|
-</info-box>
|
|
|
+ --ck-color-base-foreground: var(--ck-custom-background);
|
|
|
+ --ck-color-focus-border: hsl(208, 90%, 62%);
|
|
|
+ --ck-color-text: hsl(0, 0%, 98%);
|
|
|
+ --ck-color-shadow-drop: hsla(0, 0%, 0%, 0.2);
|
|
|
+ --ck-color-shadow-inner: hsla(0, 0%, 0%, 0.1);
|
|
|
|
|
|
-The contents of `custom.scss` could look as below:
|
|
|
-
|
|
|
-```scss
|
|
|
-// Overrides the border radius setting in the theme.
|
|
|
-$ck-border-radius: 4px;
|
|
|
-
|
|
|
-// Overrides the default font size in the theme.
|
|
|
-$ck-font-size-base: 14px;
|
|
|
-
|
|
|
-// Helper variables to avoid duplication in $ck-colors.
|
|
|
-$custom-background: #4A494B;
|
|
|
-$custom-foreground: #3a393d;
|
|
|
-$custom-border: #383738;
|
|
|
-$custom-white: #fff;
|
|
|
-
|
|
|
-// Colors used by the ck-color() mixin across the theme.
|
|
|
-$ck-colors: (
|
|
|
- // Overrides the default focus color used by the ck-focus-ring() mixin.
|
|
|
- 'border-focus': #48a3f5,
|
|
|
-
|
|
|
- // Overrides the default text color in the theme.
|
|
|
- 'text': #fafafa,
|
|
|
-
|
|
|
- // Overrides the default shadow colors in the theme.
|
|
|
- 'shadow-drop': rgba( 0, 0, 0, .2 ),
|
|
|
- 'shadow-inner': rgba( 0, 0, 0, .1 ),
|
|
|
-
|
|
|
- // Overrides the default .ck-button class colors.
|
|
|
- 'button-default-background': $custom-background,
|
|
|
- 'button-default-border': $custom-border,
|
|
|
- 'button-on-background': $custom-foreground,
|
|
|
- 'button-on-border': $custom-border,
|
|
|
- 'button-action-background': #1ABC9C,
|
|
|
- 'button-action-border': #49d2b7,
|
|
|
- 'button-action-text': $custom-white,
|
|
|
-
|
|
|
- // Overrides the default .ck-dropdown class colors.
|
|
|
- 'dropdown-panel-background': $custom-background,
|
|
|
- 'dropdown-panel-border': $custom-foreground,
|
|
|
- 'dropdown-symbol': #f1f1f1,
|
|
|
-
|
|
|
- // Overrides the default .ck-input class colors.
|
|
|
- 'input-background': $custom-foreground,
|
|
|
- 'input-border': #6b6970,
|
|
|
- 'input-text': #fafafa,
|
|
|
-
|
|
|
- // Overrides the default .ck-list class colors.
|
|
|
- 'list-background': $custom-background,
|
|
|
- 'list-item-background-hover': $custom-foreground,
|
|
|
- 'list-item-background-active': #1A8BF1,
|
|
|
- 'list-item-text-active': $custom-white,
|
|
|
-
|
|
|
- // Overrides the default .ck-balloon-panel class colors.
|
|
|
- 'panel-background': $custom-background,
|
|
|
- 'panel-border': $custom-border,
|
|
|
-
|
|
|
- // Overrides the default .ck-toolbar class colors.
|
|
|
- 'toolbar-background': $custom-foreground,
|
|
|
- 'toolbar-border': $custom-border,
|
|
|
-
|
|
|
- // Overrides the default .ck-tooltip class colors.
|
|
|
- 'tooltip-background': #212025,
|
|
|
- 'tooltip-text': #eee,
|
|
|
-
|
|
|
- // Overrides the default colors used by the editor.
|
|
|
- 'editor-border': $custom-background,
|
|
|
- 'editor-toolbar-background': $custom-background,
|
|
|
- 'editor-toolbar-button-background': $custom-background,
|
|
|
- 'editor-dropdown-background': #535254,
|
|
|
-
|
|
|
- // Overrides the default colors used by the ckeditor5-image package.
|
|
|
- 'image-caption-background': #f7f7f7,
|
|
|
- 'image-caption-text': #333,
|
|
|
-
|
|
|
- // Overrides the default colors used by the ckeditor5-widget package.
|
|
|
- 'widget-border-blurred': #ddd,
|
|
|
- 'widget-border-hover': #FFD25C,
|
|
|
- 'widget-editable-focused-background': $custom-white
|
|
|
-);
|
|
|
-```
|
|
|
+ /* -- Overrides the default .ck-button class colors ----------------------------------------- */
|
|
|
|
|
|
-It is time to build the editor using `npm run build-ckeditor` and see the results. From now on, the editor's theme is using customized styles.
|
|
|
+ --ck-color-button-default-background: var(--ck-custom-background);
|
|
|
+ --ck-color-button-default-focus-background: hsl(270, 1%, 22%);
|
|
|
+ --ck-color-button-default-active-background: hsl(270, 2%, 20%);
|
|
|
+ --ck-color-button-default-active-shadow: hsl(270, 2%, 23%);
|
|
|
+ --ck-color-button-default-disabled-background: var(--ck-custom-background);
|
|
|
|
|
|
-## Adding extra styles to the build
|
|
|
+ --ck-color-button-on-background: var(--ck-custom-foreground);
|
|
|
+ --ck-color-button-on-focus-background: hsl(255, 4%, 16%);
|
|
|
+ --ck-color-button-on-active-background: hsl(255, 4%, 14%);
|
|
|
+ --ck-color-button-on-active-shadow: hsl(240, 3%, 19%);
|
|
|
+ --ck-color-button-on-disabled-background: var(--ck-custom-foreground);
|
|
|
|
|
|
-Not every element of the theme can be customized using SASS variables and some visual tweaking may require more complex CSS rules.
|
|
|
+ --ck-color-button-action-background: hsl(168, 76%, 42%);
|
|
|
+ --ck-color-button-action-focus-background: hsl(168, 76%, 38%);
|
|
|
+ --ck-color-button-action-active-background: hsl(168, 76%, 36%);
|
|
|
+ --ck-color-button-action-active-shadow: hsl(168, 75%, 34%);
|
|
|
+ --ck-color-button-action-disabled-background: hsl(168, 76%, 42%);
|
|
|
+ --ck-color-button-action-text: var(--ck-custom-white);
|
|
|
|
|
|
-In the editor demo presented and the very beginning of this guide, the drop down button in the toolbar has a complex inner [`box-shadow`](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow?v=b) that makes it more appealing. By default, the [Lark](https://www.npmjs.com/package/@ckeditor/ckeditor5-theme-lark) theme does not support such shadow and that is why it must be defined separately.
|
|
|
+ /* -- Overrides the default .ck-dropdown class colors --------------------------------------- */
|
|
|
|
|
|
-```css
|
|
|
-.ck-editor-toolbar .ck-button.ck-dropdown__button {
|
|
|
- box-shadow: 0 0 0 1px #5c5b5d inset, 0 0 5px #5c5b5d inset;
|
|
|
-}
|
|
|
-```
|
|
|
+ --ck-color-dropdown-panel-background: var(--ck-custom-background);
|
|
|
+ --ck-color-dropdown-panel-border: var(--ck-custom-foreground);
|
|
|
|
|
|
-The rule above could be added directly to any stylesheet in the web page and most certainly would work as expected.
|
|
|
+ /* -- Overrides the default .ck-input class colors ------------------------------------------ */
|
|
|
|
|
|
-But what if the color set customized in the [previous part](#Customization-with-SASS-variables) of this guide has changed? Static CSS rules will neither update along with the SASS variables nor can they benefit from the mixins and functions provided by the theme. To add extra styles and keep them within the ecosystem, a separate SASS file should be created (in his example it will be called `extras.scss`):
|
|
|
+ --ck-color-input-background: var(--ck-custom-foreground);
|
|
|
+ --ck-color-input-border: hsl(257, 3%, 43%);
|
|
|
+ --ck-color-input-text: hsl(0, 0%, 98%);
|
|
|
+ --ck-color-input-disabled-background: hsl(255, 4%, 21%);
|
|
|
+ --ck-color-input-disabled-border: hsl(250, 3%, 38%);
|
|
|
+ --ck-color-input-disabled-text: hsl(0, 0%, 46%);
|
|
|
|
|
|
-```scss
|
|
|
-// Allow using Lark's ck-box-shadow() mixin.
|
|
|
-@import '~@ckeditor/ckeditor5-theme-lark/theme/helpers/_shadow.scss';
|
|
|
+ /* -- Overrides the default .ck-list class colors ------------------------------------------- */
|
|
|
|
|
|
-// Allow using colors defined in Lark and the ck-color() mixin.
|
|
|
-@import '~@ckeditor/ckeditor5-theme-lark/theme/helpers/_colors.scss';
|
|
|
+ --ck-color-list-background: var(--ck-custom-background);
|
|
|
+ --ck-color-list-item-background-hover: var(--ck-custom-foreground);
|
|
|
+ --ck-color-list-item-background-active: hsl(208, 88%, 52%);
|
|
|
+ --ck-color-list-item-text-active: var(--ck-custom-white);
|
|
|
|
|
|
-// The shadow should be 10% brighter than the toolbar background.
|
|
|
-$shadow-color: ck-color( 'editor-toolbar-background', 10 );
|
|
|
+ /* -- Overrides the default .ck-balloon-panel class colors ---------------------------------- */
|
|
|
|
|
|
-.ck-editor-toolbar {
|
|
|
- .ck-button.ck-dropdown__button {
|
|
|
- // Apply a dedicated inner box-shadow to the drop-down button.
|
|
|
- @include ck-box-shadow(
|
|
|
- 0 0 0 1px $shadow-color inset,
|
|
|
- 0 0 5px $shadow-color inset
|
|
|
- );
|
|
|
- }
|
|
|
+ --ck-color-panel-background: var(--ck-custom-background);
|
|
|
+ --ck-color-panel-border: var(--ck-custom-border);
|
|
|
+
|
|
|
+ /* -- Overrides the default .ck-toolbar class colors ---------------------------------------- */
|
|
|
+
|
|
|
+ --ck-color-toolbar-background: var(--ck-custom-background);
|
|
|
+ --ck-color-toolbar-border: var(--ck-custom-border);
|
|
|
+
|
|
|
+ /* -- Overrides the default .ck-tooltip class colors ---------------------------------------- */
|
|
|
+
|
|
|
+ --ck-color-tooltip-background: hsl(252, 7%, 14%);
|
|
|
+ --ck-color-tooltip-text: hsl(0, 0%, 93%);
|
|
|
+
|
|
|
+ /* -- Overrides the default colors used by ckeditor5-image package -------------------------- */
|
|
|
+
|
|
|
+ --ck-color-image-caption-background: hsl(0, 0%, 97%);
|
|
|
+ --ck-color-image-caption-text: hsl(0, 0%, 20%);
|
|
|
+
|
|
|
+ /* -- Overrides the default colors used by ckeditor5-widget package ------------------------- */
|
|
|
+
|
|
|
+ --ck-color-widget-border-blurred: hsl(0, 0%, 87%);
|
|
|
+ --ck-color-widget-border-hover: hsl(43, 100%, 68%);
|
|
|
+ --ck-color-widget-editable-focused-background: var(--ck-custom-white);
|
|
|
+
|
|
|
+ /* -- Overrides the default colors used by ckeditor5-link package ------------------------- */
|
|
|
+
|
|
|
+ --ck-color-link-default: hsl(190, 100%, 75%);
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-This file then needs to be imported into a JavaScript file that is processed by webpack and the [loaders](#Styles-processing-and-bundling), like for example an entry point of the application.
|
|
|
+This file can be referenced directly in HTML **after the `<link>` tag injected by the editor** and its content will simply override the default CSS variables. CSS variables are natively [supported](https://caniuse.com/#feat=css-variables) in all major web browsers and just like like any other CSS rule, they are prioritized in the order of precedence.
|
|
|
+
|
|
|
+```html
|
|
|
+<link rel="stylesheet" href="custom.css" type="text/css">
|
|
|
+```
|
|
|
+
|
|
|
+Alternatively, the style sheet can also be imported into a JavaScript file that is processed by webpack and the [loaders](#styles-processing-and-bundling) becoming part of the build, e.g. an entry point of the application.
|
|
|
+
|
|
|
+<info-box info>
|
|
|
+ Learn more about {@link framework/guides/quick-start building the editor using webpack}.
|
|
|
+</info-box>
|
|
|
|
|
|
```js
|
|
|
import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
|
|
|
-import 'extras.scss';
|
|
|
+
|
|
|
+// To override the default styles, this file must be imported after ClassicEditor.
|
|
|
+import 'custom.css';
|
|
|
|
|
|
ClassicEditor
|
|
|
.create( ... )
|
|
|
@@ -245,4 +193,4 @@ ClassicEditor
|
|
|
|
|
|
```
|
|
|
|
|
|
-This way, the additional styles will stay up–to–date as the application develops and changes over the time.
|
|
|
+It is time to build the editor using `npm run build-ckeditor` and see the results. From now on, the editor's theme is using customized styles, which are part of the build.
|