From fad5ee2fe50dd390236ab6b77bd27cd09f362c7b Mon Sep 17 00:00:00 2001
From: panr <radoslaw.koziel@gmail.com>
Date: Wed, 15 Jul 2020 12:59:56 +0200
Subject: [PATCH 1/8] Remove max-wdith from the alignment styles.

---
 packages/ckeditor5-image/theme/imagestyle.css | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/packages/ckeditor5-image/theme/imagestyle.css b/packages/ckeditor5-image/theme/imagestyle.css
index db502f743e2..755b73c753a 100644
--- a/packages/ckeditor5-image/theme/imagestyle.css
+++ b/packages/ckeditor5-image/theme/imagestyle.css
@@ -8,16 +8,10 @@
 }
 
 .ck-content {
-	& .image-style-side,
-	& .image-style-align-left,
-	& .image-style-align-center,
-	& .image-style-align-right {
-		max-width: 50%;
-	}
-
 	& .image-style-side {
 		float: right;
 		margin-left: var(--ck-image-style-spacing);
+		max-width: 50%;
 	}
 
 	& .image-style-align-left {

From bb63196d62e5be911e8ab9f3f873f23a21c193cc Mon Sep 17 00:00:00 2001
From: panr <radoslaw.koziel@gmail.com>
Date: Wed, 15 Jul 2020 13:00:47 +0200
Subject: [PATCH 2/8] Update snippets conifg.

---
 .../_snippets/features/image-resize-px.html   |  4 +-
 .../_snippets/features/image-resize-px.js     | 31 +++++++++++++++-
 .../docs/_snippets/features/image-resize.js   | 14 +++++++
 .../docs/_snippets/features/image-resizeui.js | 17 ++++++---
 .../features/image-resizeuidropdown.js        | 15 +++++++-
 .../features/image-style-custom.html          |  3 +-
 .../_snippets/features/image-style-custom.js  | 37 ++++++++++++++-----
 7 files changed, 101 insertions(+), 20 deletions(-)

diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.html b/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.html
index 015a4fdadb5..8d1e382da56 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.html
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.html
@@ -6,9 +6,9 @@ <h3>Resize me!</h3>
 		<figcaption>Autumn fields by Aleksander Nowodziński</figcaption>
 	</figure>
 
-	<h3>Resized image (width: 400px):</h3>
+	<h3>Resized image (width: 500px):</h3>
 
-	<figure class="image image_resized" style="width:400px;">
+	<figure class="image image_resized" style="width:500px;">
 		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
 	</figure>
 </div>
diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.js b/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.js
index 9a977e6e6fa..32fbf179805 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.js
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.js
@@ -11,7 +11,36 @@ ClassicEditor
 	.create( document.querySelector( '#snippet-image-resize-px' ), {
 		removePlugins: [ 'LinkImage' ],
 		image: {
-			resizeUnit: 'px'
+			resizeUnit: 'px',
+			resizeOptions: [
+				{
+					name: 'imageResize:original',
+					label: 'Original',
+					value: null
+				},
+				{
+					name: 'imageResize:250',
+					label: '250px',
+					value: '250'
+				},
+				{
+					name: 'imageResize:500',
+					label: '500px',
+					value: '500'
+				}
+			],
+			styles: [
+				'alignLeft',
+				'alignCenter',
+				'alignRight'
+			],
+			toolbar: [
+				'imageStyle:alignLeft',
+				'imageStyle:alignCenter',
+				'imageStyle:alignRight',
+				'|',
+				'imageResize'
+			]
 		},
 		toolbar: {
 			viewportTopOffset: window.getViewportTopOffsetConfig()
diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-resize.js b/packages/ckeditor5-image/docs/_snippets/features/image-resize.js
index 581c54d395f..b3118e6c7ba 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-resize.js
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-resize.js
@@ -13,6 +13,20 @@ ClassicEditor
 		toolbar: {
 			viewportTopOffset: window.getViewportTopOffsetConfig()
 		},
+		image: {
+			styles: [
+				'alignLeft',
+				'alignCenter',
+				'alignRight'
+			],
+			toolbar: [
+				'imageStyle:alignLeft',
+				'imageStyle:alignCenter',
+				'imageStyle:alignRight',
+				'|',
+				'imageTextAlternative'
+			]
+		},
 		cloudServices: CS_CONFIG
 	} )
 	.then( editor => {
diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-resizeui.js b/packages/ckeditor5-image/docs/_snippets/features/image-resizeui.js
index 2327d7c1167..b28f8a37183 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-resizeui.js
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-resizeui.js
@@ -17,7 +17,7 @@ ClassicEditor
 			resizeOptions: [
 				{
 					name: 'imageResize:original',
-					label: 'Original size',
+					label: 'Original',
 					value: null
 				},
 				{
@@ -31,12 +31,19 @@ ClassicEditor
 					value: '75'
 				}
 			],
+			styles: [
+				'alignLeft',
+				'alignCenter',
+				'alignRight'
+			],
 			toolbar: [
-				'imageStyle:full',
-				'imageStyle:side', '|',
-				'imageResize:original',
+				'imageStyle:alignLeft',
+				'imageStyle:alignCenter',
+				'imageStyle:alignRight',
+				'|',
 				'imageResize:50',
-				'imageResize:75'
+				'imageResize:75',
+				'imageResize:original'
 			]
 		},
 		cloudServices: CS_CONFIG
diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-resizeuidropdown.js b/packages/ckeditor5-image/docs/_snippets/features/image-resizeuidropdown.js
index 15675720c49..ca7aee4f502 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-resizeuidropdown.js
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-resizeuidropdown.js
@@ -17,7 +17,7 @@ ClassicEditor
 			resizeOptions: [
 				{
 					name: 'imageResize:original',
-					label: 'Original size',
+					label: 'Original',
 					value: null
 				},
 				{
@@ -31,7 +31,18 @@ ClassicEditor
 					value: '75'
 				}
 			],
-			toolbar: [ 'imageStyle:full', 'imageStyle:side', '|', 'imageResize' ]
+			styles: [
+				'alignLeft',
+				'alignCenter',
+				'alignRight'
+			],
+			toolbar: [
+				'imageStyle:alignLeft',
+				'imageStyle:alignCenter',
+				'imageStyle:alignRight',
+				'|',
+				'imageResize'
+			]
 		},
 		cloudServices: CS_CONFIG
 	} )
diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.html b/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.html
index adf9f2cec82..3dc22754ee9 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.html
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.html
@@ -1,5 +1,6 @@
 <div id="snippet-image-style-custom">
-	<p>An image to play with:</p>
+	<h2>Don't forget to resize me!</h2>
+	<p><strong>Set a prefered alignment option and drag the image handles to see how the text below the image responds.</strong></p>
 
 	<figure class="image">
 		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.js b/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.js
index 7000f9182c0..510808a985e 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.js
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.js
@@ -9,20 +9,39 @@ import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud
 
 ClassicEditor
 	.create( document.querySelector( '#snippet-image-style-custom' ), {
-		removePlugins: [ 'ImageResize', 'LinkImage' ],
+		removePlugins: [ 'LinkImage' ],
 		image: {
+			resizeOptions: [
+				{
+					name: 'imageResize:original',
+					label: 'Original',
+					value: null
+				},
+				{
+					name: 'imageResize:50',
+					label: '50%',
+					value: '50'
+				},
+				{
+					name: 'imageResize:75',
+					label: '75%',
+					value: '75'
+				}
+			],
 			styles: [
-				// This option is equal to a situation where no style is applied.
-				'full',
-
-				// This represents an image aligned to left.
 				'alignLeft',
-
-				// This represents an image aligned to right.
+				'alignCenter',
 				'alignRight'
 			],
-
-			toolbar: [ 'imageTextAlternative', '|', 'imageStyle:alignLeft', 'imageStyle:full', 'imageStyle:alignRight' ]
+			toolbar: [
+				'imageStyle:alignLeft',
+				'imageStyle:alignCenter',
+				'imageStyle:alignRight',
+				'|',
+				'imageResize:50',
+				'imageResize:75',
+				'imageResize:original'
+			]
 		},
 		toolbar: {
 			viewportTopOffset: window.getViewportTopOffsetConfig()

From 6689794e2b7e231e4dae277932a59e87f243a909 Mon Sep 17 00:00:00 2001
From: panr <radoslaw.koziel@gmail.com>
Date: Wed, 15 Jul 2020 13:01:19 +0200
Subject: [PATCH 3/8] Update manual tests configs for the image resize.

---
 packages/ckeditor5-image/tests/manual/imageresize.js   | 6 +++---
 packages/ckeditor5-image/tests/manual/imageresizepx.js | 6 +++---
 packages/ckeditor5-image/tests/manual/imageresizeui.js | 6 +++---
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/packages/ckeditor5-image/tests/manual/imageresize.js b/packages/ckeditor5-image/tests/manual/imageresize.js
index f8a15fe7469..eaa6d40b62e 100644
--- a/packages/ckeditor5-image/tests/manual/imageresize.js
+++ b/packages/ckeditor5-image/tests/manual/imageresize.js
@@ -25,11 +25,11 @@ const commonConfig = {
 	toolbar: [ 'heading', '|', 'bold', 'italic', 'link',
 		'bulletedList', 'numberedList', 'blockQuote', 'insertTable', 'undo', 'redo', 'outdent', 'indent' ],
 	image: {
-		toolbar: [ 'imageStyle:alignLeft', 'imageStyle:full', 'imageStyle:side' ],
+		toolbar: [ 'imageStyle:alignLeft', 'imageStyle:alignCenter', 'imageStyle:alignRight', '|', 'imageResize' ],
 		styles: [
-			'full',
 			'alignLeft',
-			'side' // Purposely using side image instead right aligned image to make sure it works well with both style types.
+			'alignCenter',
+			'alignRight'
 		]
 	},
 	table: {
diff --git a/packages/ckeditor5-image/tests/manual/imageresizepx.js b/packages/ckeditor5-image/tests/manual/imageresizepx.js
index b54512bcfd4..0ecd0d553bb 100644
--- a/packages/ckeditor5-image/tests/manual/imageresizepx.js
+++ b/packages/ckeditor5-image/tests/manual/imageresizepx.js
@@ -26,11 +26,11 @@ const commonConfig = {
 		'bulletedList', 'numberedList', 'blockQuote', 'insertTable', 'undo', 'redo', 'outdent', 'indent' ],
 	image: {
 		resizeUnit: 'px',
-		toolbar: [ 'imageStyle:alignLeft', 'imageStyle:full', 'imageStyle:side' ],
+		toolbar: [ 'imageStyle:alignLeft', 'imageStyle:alignCenter', 'imageStyle:alignRight', '|', 'imageResize' ],
 		styles: [
-			'full',
 			'alignLeft',
-			'side' // Purposely using side image instead right aligned image to make sure it works well with both style types.
+			'alignCenter',
+			'alignRight'
 		]
 	},
 	cloudServices: CS_CONFIG
diff --git a/packages/ckeditor5-image/tests/manual/imageresizeui.js b/packages/ckeditor5-image/tests/manual/imageresizeui.js
index 015043ef6a8..4296fb29dfa 100644
--- a/packages/ckeditor5-image/tests/manual/imageresizeui.js
+++ b/packages/ckeditor5-image/tests/manual/imageresizeui.js
@@ -50,11 +50,11 @@ const imageConfig1 = {
 			value: '75'
 		}
 	],
-	toolbar: [ 'imageStyle:alignLeft', 'imageStyle:full', 'imageStyle:side', '|', 'imageResize' ],
+	toolbar: [ 'imageStyle:alignLeft', 'imageStyle:alignCenter', 'imageStyle:alignRight', '|', 'imageResize' ],
 	styles: [
-		'full',
 		'alignLeft',
-		'side' // Purposely using side image instead right aligned image to make sure it works well with both style types.
+		'alignCenter',
+		'alignRight'
 	]
 };
 

From ca027a7dfdd73a96c0a6789cbb7877711cb96eaa Mon Sep 17 00:00:00 2001
From: panr <radoslaw.koziel@gmail.com>
Date: Wed, 15 Jul 2020 13:01:39 +0200
Subject: [PATCH 4/8] Update feature documention.

---
 .../ckeditor5-image/docs/features/image.md    | 56 +++++++++++--------
 1 file changed, 34 insertions(+), 22 deletions(-)

diff --git a/packages/ckeditor5-image/docs/features/image.md b/packages/ckeditor5-image/docs/features/image.md
index f73f29f1e50..aadebee6005 100644
--- a/packages/ckeditor5-image/docs/features/image.md
+++ b/packages/ckeditor5-image/docs/features/image.md
@@ -78,6 +78,14 @@ By default, if the image caption is empty, the `<figcaption>` element is not vis
 
 {@snippet features/image-caption}
 
+## Image upload
+
+See the {@link features/image-upload Image upload} guide.
+
+## Responsive images
+
+Support for responsive images in CKEditor 5 is brought by the {@link features/easy-image Easy Image} feature without any additional configuration. Learn more how to use the feature in your project in the {@link features/easy-image#responsive-images Easy Image integration} guide.
+
 ## Image styles
 
 In simple integrations it is enough to let the user insert images, set their text alternative and the editor's job is done. An example of such a simple solution are e.g. [GitHub](https://github.com) comments. The styling of the images (for example, their maximum width and margins) is controlled by GitHub through stylesheets.
@@ -86,9 +94,13 @@ In more advanced scenarios, the user may need to be able to decide whether the i
 
 This is what the {@link module:image/imagestyle~ImageStyle} feature is designed for.
 
-However, unlike in CKEditor 4, in CKEditor 5 the end user does not set the image border, alignment, margins, width, etc. separately. Instead, they can pick one of the styles defined by the developer who prepared the WYSIWYG editor integration. This gives the developer control over how the users style images and makes the user's life easier by setting multiple properties at once.
+The available image styles can be configured using the {@link module:image/image~ImageConfig#styles `image.styles`} option.
+
+### Semantical image styles
 
-A style is applied to the image in form of a class. By default, CKEditor 5 is configured to support two styles: "full width" (which does not apply any class &mdash; it is the default style) and "side image" (which applies the `image-style-side` class).
+Unlike in CKEditor 4, in CKEditor 5 the end user does not set the image border, alignment, margins, width, etc. separately. Instead, they can pick one of the styles defined by the developer who prepared the WYSIWYG editor integration. This gives the developer control over how the users style images and makes the user's life easier by setting multiple properties at once.
+
+A style is applied to the image in form of a class. By default, CKEditor 5 is configured to support two default semantical styles: **"full width"** (which does not apply any class &mdash; it is the default style) and **"side image"** (which applies the `image-style-side` class).
 
 A normal (full width) image:
 
@@ -108,30 +120,40 @@ A side image:
 	You can find the source of the default styles applied by the editor here: [`ckeditor5-image/theme/imagestyle.css`](https://github.com/ckeditor/ckeditor5-image/blob/master/theme/imagestyle.css).
 </info-box>
 
-Below you can see a demo of the WYSIWYG editor with the image styles feature enabled. The default configuration is used. You can change the styles of images through the image's contextual toolbar.
+Below you can see a demo of the WYSIWYG editor with the semantical image styles. The default configuration is used. You can change the styles of images through the image's contextual toolbar.
 
 {@snippet features/image-style}
 
-### Configuring image styles
+It's important to note, that semantical image styles are powerfull concepts and can easily replace some other features presented in this documentation. For example, the "side image" works as a combination of the [presentational](#presentational-image-styles) styles like: "resize image to 50%" and "align it to the right". But what's intresting here, by appling the semantical styles to the image, you're apping also a new meaning the that element with the relation to the surrending content.
 
-The available image styles can be configured using the {@link module:image/image~ImageConfig#styles `image.styles`} option.
+<info-box hint>
+	In the example above the options represent simple "align left" and "align right" styles. Most text editors support left, center and right alignments, however, it is better not to think about CKEditor 5's image styles in this way. Try to understand what use cases the system needs to support and define semantic options accordingly. Defining useful and clear styles is one of the steps towards a good user experience and clear, portable output. For example, the "side image" style can be displayed as a floated image on wide screens and as a normal image on low resolution screens.
+</info-box>
+
+<info-box warning>
+	At the moment, semantical styles like "full width" and "side image" are not fully compatibile with the [`Image Resize`](#resizing-images) feature and should not be used together. However, to achieve the same, but with more flexibility, you can use [**presentational image styles**](#presentational-image-styles).
+</info-box>
+
+### Presentational image styles
 
-The following WYSIWYG editor supports the default full image style plus left- and right-aligned images:
+Think of them as styles that don't add any special meaning to the changed content. Sometimes you just want to align an image to the right without making it a special kind of element. The only reason you want to do this is the **presentational** purpose. From the editor's content perspective, the image only gets additional styles.
+
+The following WYSIWYG editor supports the default alignment features — left, center and right:
 
 ```js
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		image: {
 			// You need to configure the image toolbar, too, so it uses the new style buttons.
-			toolbar: [ 'imageTextAlternative', '|', 'imageStyle:alignLeft', 'imageStyle:full', 'imageStyle:alignRight' ],
+			toolbar: [ 'imageStyle:alignLeft', 'imageStyle:alignCenter', 'imageStyle:alignRight', '|', 'imageTextAlternative' ],
 
 			styles: [
-				// This option is equal to a situation where no style is applied.
-				'full',
-
 				// This represents an image aligned to the left.
 				'alignLeft',
 
+				// This represents an image aligned to the center.
+				'alignCenter',
+
 				// This represents an image aligned to the right.
 				'alignRight'
 			]
@@ -141,15 +163,13 @@ ClassicEditor
 	.catch( ... );
 ```
 
-The code sample above uses predefined image styles: `'full'`, `'alignLeft'` and `'alignRight'`. The latter two apply, respectively, the `.image-style-align-left` and  `.image-style-align-right` classes to the `<figure>` element.
+The code sample above uses predefined presentational image styles: `'alignLeft'`, `'alignCenter'` and `'alignRight'`. The all three apply, respectively, the `.image-style-align-left`, `.image-style-align-center` and  `.image-style-align-right` classes to the `<figure>` element.
 
 See the result below:
 
 {@snippet features/image-style-custom}
 
-<info-box hint>
-	In the example above the options represent simple "align left" and "align right" styles. Most text editors support left, center and right alignments, however, it is better not to think about CKEditor 5's image styles in this way. Try to understand what use cases the system needs to support and define semantic options accordingly. Defining useful and clear styles is one of the steps towards a good user experience and clear, portable output. For example, the "side image" style can be displayed as a floated image on wide screens and as a normal image on low resolution screens.
-</info-box>
+As you can see, our predefined image alignment styles work beautifully with image resizing. They're not limited to work only with resizing by handles, they work with resize options via [dropdown](#resize-image-using-the-plugin-dropdown) or [standalone buttons](#resize-image-using-the-standalone-buttons) as well.
 
 ### Defining custom styles
 
@@ -171,14 +191,6 @@ You can find advanced examples in the {@link module:image/image~ImageConfig#styl
 
 <!-- TODO (live example)... -->
 
-## Image upload
-
-See the {@link features/image-upload Image upload} guide.
-
-## Responsive images
-
-Support for responsive images in CKEditor 5 is brought by the {@link features/easy-image Easy Image} feature without any additional configuration. Learn more how to use the feature in your project in the {@link features/easy-image#responsive-images Easy Image integration} guide.
-
 ## Resizing images
 
 The [image styles](#image-styles) feature is meant to give the user the choice between a set of styling options provided by the system (so by the developer or administrator who created it). There are also scenarios where the user should be able to freely set the width of an image. And that is where the image resize feature comes to play.

From c9d36f3db424d86840a42d9915e2258620dd75f5 Mon Sep 17 00:00:00 2001
From: panr <radoslaw.koziel@gmail.com>
Date: Tue, 21 Jul 2020 09:57:08 +0200
Subject: [PATCH 5/8] Fix custom styles snippet.

---
 .../docs/_snippets/features/image-style-custom.js        | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.js b/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.js
index 510808a985e..aec21ab1715 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.js
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.js
@@ -15,17 +15,20 @@ ClassicEditor
 				{
 					name: 'imageResize:original',
 					label: 'Original',
-					value: null
+					value: null,
+					icon: 'original'
 				},
 				{
 					name: 'imageResize:50',
 					label: '50%',
-					value: '50'
+					value: '50',
+					icon: 'medium'
 				},
 				{
 					name: 'imageResize:75',
 					label: '75%',
-					value: '75'
+					value: '75',
+					icon: 'large'
 				}
 			],
 			styles: [

From a607233aab4b3946c8520bd48d4d99be5b2e90b5 Mon Sep 17 00:00:00 2001
From: panr <radoslaw.koziel@gmail.com>
Date: Tue, 21 Jul 2020 09:57:14 +0200
Subject: [PATCH 6/8] Fix resize px snippet.

---
 .../docs/_snippets/features/image-resize-px.html            | 4 ++--
 .../docs/_snippets/features/image-resize-px.js              | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.html b/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.html
index 8d1e382da56..015a4fdadb5 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.html
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.html
@@ -6,9 +6,9 @@ <h3>Resize me!</h3>
 		<figcaption>Autumn fields by Aleksander Nowodziński</figcaption>
 	</figure>
 
-	<h3>Resized image (width: 500px):</h3>
+	<h3>Resized image (width: 400px):</h3>
 
-	<figure class="image image_resized" style="width:500px;">
+	<figure class="image image_resized" style="width:400px;">
 		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
 	</figure>
 </div>
diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.js b/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.js
index 32fbf179805..e51cae24a0d 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.js
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-resize-px.js
@@ -24,9 +24,9 @@ ClassicEditor
 					value: '250'
 				},
 				{
-					name: 'imageResize:500',
-					label: '500px',
-					value: '500'
+					name: 'imageResize:400',
+					label: '400px',
+					value: '400'
 				}
 			],
 			styles: [

From 57364f2f1200b2c21f8fd8d45293d71f211b3a43 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Piotrek=20Koszuli=C5=84ski?= <pkoszulinski@gmail.com>
Date: Tue, 21 Jul 2020 11:26:58 +0200
Subject: [PATCH 7/8] Better wording and adjustments.

---
 ...m.html => image-style-presentational.html} |  9 +-
 ...ustom.js => image-style-presentational.js} | 26 +-----
 .../ckeditor5-image/docs/features/image.md    | 83 ++++++++++++-------
 3 files changed, 63 insertions(+), 55 deletions(-)
 rename packages/ckeditor5-image/docs/_snippets/features/{image-style-custom.html => image-style-presentational.html} (75%)
 rename packages/ckeditor5-image/docs/_snippets/features/{image-style-custom.js => image-style-presentational.js} (65%)

diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.html b/packages/ckeditor5-image/docs/_snippets/features/image-style-presentational.html
similarity index 75%
rename from packages/ckeditor5-image/docs/_snippets/features/image-style-custom.html
rename to packages/ckeditor5-image/docs/_snippets/features/image-style-presentational.html
index 3dc22754ee9..8c9afedc79a 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.html
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-style-presentational.html
@@ -1,10 +1,15 @@
 <div id="snippet-image-style-custom">
-	<h2>Don't forget to resize me!</h2>
-	<p><strong>Set a prefered alignment option and drag the image handles to see how the text below the image responds.</strong></p>
+	<p>This is a default image (no style):</p>
 
 	<figure class="image">
 		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
 	</figure>
 
+	<p>This is a right-aligned image:</p>
+
+	<figure class="image image-style-align-right">
+		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
+	</figure>
+
 	<p>Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here. Lots of text here.</p>
 </div>
diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.js b/packages/ckeditor5-image/docs/_snippets/features/image-style-presentational.js
similarity index 65%
rename from packages/ckeditor5-image/docs/_snippets/features/image-style-custom.js
rename to packages/ckeditor5-image/docs/_snippets/features/image-style-presentational.js
index aec21ab1715..16b6f22fef7 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-style-custom.js
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-style-presentational.js
@@ -9,28 +9,8 @@ import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud
 
 ClassicEditor
 	.create( document.querySelector( '#snippet-image-style-custom' ), {
-		removePlugins: [ 'LinkImage' ],
+		removePlugins: [ 'ImageResize', 'LinkImage' ],
 		image: {
-			resizeOptions: [
-				{
-					name: 'imageResize:original',
-					label: 'Original',
-					value: null,
-					icon: 'original'
-				},
-				{
-					name: 'imageResize:50',
-					label: '50%',
-					value: '50',
-					icon: 'medium'
-				},
-				{
-					name: 'imageResize:75',
-					label: '75%',
-					value: '75',
-					icon: 'large'
-				}
-			],
 			styles: [
 				'alignLeft',
 				'alignCenter',
@@ -41,9 +21,7 @@ ClassicEditor
 				'imageStyle:alignCenter',
 				'imageStyle:alignRight',
 				'|',
-				'imageResize:50',
-				'imageResize:75',
-				'imageResize:original'
+				'imageTextAlternative'
 			]
 		},
 		toolbar: {
diff --git a/packages/ckeditor5-image/docs/features/image.md b/packages/ckeditor5-image/docs/features/image.md
index aadebee6005..b3044ded40f 100644
--- a/packages/ckeditor5-image/docs/features/image.md
+++ b/packages/ckeditor5-image/docs/features/image.md
@@ -92,13 +92,15 @@ In simple integrations it is enough to let the user insert images, set their tex
 
 In more advanced scenarios, the user may need to be able to decide whether the image should take the whole width (if it is the article's main photo) or it should take, for example, 50% of the width and be pulled out of the content (so called "pulled images"). Various integration scenarios require different types of images to be used.
 
-This is what the {@link module:image/imagestyle~ImageStyle} feature is designed for.
+Finally, in certain situations, the user should be able to granularly control how an image is presented so they should be able to set the size and alignment separately.
 
-The available image styles can be configured using the {@link module:image/image~ImageConfig#styles `image.styles`} option.
+The {@link module:image/imagestyle~ImageStyle} feature solves the last two scenarios. The former is handled by so-called ["semantical styles"](#semantical-styles) and the latter by ["presentational styles"](#presentational-styles) in combination with [image resize](#resizing-images).
 
-### Semantical image styles
+The available image styles can be configured using the {@link module:image/image~ImageConfig#styles `config.image.styles`} option. Respective buttons should also be added to the image toolbar via {@link module:image/image~ImageConfig#toolbar `config.image.toolbar`}.
 
-Unlike in CKEditor 4, in CKEditor 5 the end user does not set the image border, alignment, margins, width, etc. separately. Instead, they can pick one of the styles defined by the developer who prepared the WYSIWYG editor integration. This gives the developer control over how the users style images and makes the user's life easier by setting multiple properties at once.
+### Semantical styles
+
+A semantical style let the user choose from a predefined "types" of images. The user is not able to set the image border, alignment, margins, width, etc. separately. Instead, they can pick one of the styles defined by the developer who prepared the WYSIWYG editor integration. This gives the developer control over how the users style images and makes the user's life easier by setting multiple properties at once.
 
 A style is applied to the image in form of a class. By default, CKEditor 5 is configured to support two default semantical styles: **"full width"** (which does not apply any class &mdash; it is the default style) and **"side image"** (which applies the `image-style-side` class).
 
@@ -115,47 +117,72 @@ A side image:
 ```
 
 <info-box>
-	The actual styling of the images is the developer's job. CKEditor 5 WYSIWYG editor comes with some default styles, but they will only be applied to images inside the editor. The developer needs to style them appropriately on the target pages.
+	The actual styling of the images is the integrator's job. CKEditor 5 WYSIWYG editor comes with some default styles, but they will only be applied to images inside the editor. The integrator needs to style them appropriately on the target pages.
+
+	You can find the source of the default styles applied by the editor here: [`ckeditor5-image/theme/imagestyle.css`](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-image/theme/imagestyle.css).
 
-	You can find the source of the default styles applied by the editor here: [`ckeditor5-image/theme/imagestyle.css`](https://github.com/ckeditor/ckeditor5-image/blob/master/theme/imagestyle.css).
+	Read more about {@link builds/guides/integration/content-styles styling the content of the editor}.
 </info-box>
 
-Below you can see a demo of the WYSIWYG editor with the semantical image styles. The default configuration is used. You can change the styles of images through the image's contextual toolbar.
+Below you can see a demo of the WYSIWYG editor with the semantical image styles. The "full" and "side" styles are the default value of {@link module:image/image~ImageConfig#styles `config.image.styles`} so you do not need to set it.
 
-{@snippet features/image-style}
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Image, ImageToolbar, ImageCaption, ImageStyle ],
+		image: {
+			toolbar: [
+				'imageStyle:full',
+				'imageStyle:side',
+				'|',
+				'imageTextAlternative'
+			],
 
-It's important to note, that semantical image styles are powerfull concepts and can easily replace some other features presented in this documentation. For example, the "side image" works as a combination of the [presentational](#presentational-image-styles) styles like: "resize image to 50%" and "align it to the right". But what's intresting here, by appling the semantical styles to the image, you're apping also a new meaning the that element with the relation to the surrending content.
+			// The default value,
+			styles: [
+				'full',
+				'side'
+			]
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+See the result below. You can change the styles of images through the image's contextual toolbar.
+
+{@snippet features/image-style}
 
 <info-box hint>
-	In the example above the options represent simple "align left" and "align right" styles. Most text editors support left, center and right alignments, however, it is better not to think about CKEditor 5's image styles in this way. Try to understand what use cases the system needs to support and define semantic options accordingly. Defining useful and clear styles is one of the steps towards a good user experience and clear, portable output. For example, the "side image" style can be displayed as a floated image on wide screens and as a normal image on low resolution screens.
+Try to understand what use cases the system needs to support and define semantic options accordingly. Defining useful and clear styles is one of the steps towards a good user experience and clear, portable output. For example, the "side image" style can be displayed as a floated image on wide screens and as a normal image on low resolution screens (e.g. mobile browsers).
 </info-box>
 
 <info-box warning>
-	At the moment, semantical styles like "full width" and "side image" are not fully compatibile with the [`Image Resize`](#resizing-images) feature and should not be used together. However, to achieve the same, but with more flexibility, you can use [**presentational image styles**](#presentational-image-styles).
+	While semantical styles can be combined with manual [image resizing](#image-resizing), these features were not designed to be used together.
+
+	If you want to enable image resizing, use [presentational image styles](#presentational-styles).
 </info-box>
 
-### Presentational image styles
+### Presentational styles
 
-Think of them as styles that don't add any special meaning to the changed content. Sometimes you just want to align an image to the right without making it a special kind of element. The only reason you want to do this is the **presentational** purpose. From the editor's content perspective, the image only gets additional styles.
+Presentational styles do not add any special meaning to the content. They directly control the visual aspect of an image.
 
-The following WYSIWYG editor supports the default alignment features — left, center and right:
+Currently, the available presentational styles are "align center", "align left" and "align right".
 
 ```js
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		image: {
-			// You need to configure the image toolbar, too, so it uses the new style buttons.
-			toolbar: [ 'imageStyle:alignLeft', 'imageStyle:alignCenter', 'imageStyle:alignRight', '|', 'imageTextAlternative' ],
-
+			// Configure the available styles.
 			styles: [
-				// This represents an image aligned to the left.
-				'alignLeft',
-
-				// This represents an image aligned to the center.
-				'alignCenter',
+				'alignLeft', 'alignCenter', 'alignRight'
+			],
 
-				// This represents an image aligned to the right.
-				'alignRight'
+			// You need to configure the image toolbar, too, so it shows the new style buttons.
+			toolbar: [
+				'imageStyle:alignLeft', 'imageStyle:alignCenter', 'imageStyle:alignRight',
+				'|',
+				'imageTextAlternative'
 			]
 		}
 	} )
@@ -163,13 +190,11 @@ ClassicEditor
 	.catch( ... );
 ```
 
-The code sample above uses predefined presentational image styles: `'alignLeft'`, `'alignCenter'` and `'alignRight'`. The all three apply, respectively, the `.image-style-align-left`, `.image-style-align-center` and  `.image-style-align-right` classes to the `<figure>` element.
+The code sample above uses predefined presentational image styles: `'alignLeft'`, `'alignCenter'` and `'alignRight'`. They apply, respectively, the `.image-style-align-left`, `.image-style-align-center` and  `.image-style-align-right` classes to the `<figure>` element.
 
 See the result below:
 
-{@snippet features/image-style-custom}
-
-As you can see, our predefined image alignment styles work beautifully with image resizing. They're not limited to work only with resizing by handles, they work with resize options via [dropdown](#resize-image-using-the-plugin-dropdown) or [standalone buttons](#resize-image-using-the-standalone-buttons) as well.
+{@snippet features/image-style-presentational}
 
 ### Defining custom styles
 
@@ -187,7 +212,7 @@ you can also define your own styles or modify the existing ones.
 	Reusing (or modifying) predefined styles has the following advantage: CKEditor 5 will use its official translations for the defined button titles.
 </info-box>
 
-You can find advanced examples in the {@link module:image/image~ImageConfig#styles `image.styles`} configuration option documentation.
+You can find advanced examples in the {@link module:image/image~ImageConfig#styles `config.image.styles`} configuration option documentation.
 
 <!-- TODO (live example)... -->
 

From 32af113139f8891d3fa50799e76e3e13ed1309fd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Piotrek=20Koszuli=C5=84ski?= <pkoszulinski@gmail.com>
Date: Tue, 21 Jul 2020 12:26:33 +0200
Subject: [PATCH 8/8] Further improvements.

---
 .../_snippets/features/image-resizeui.html    |  6 -----
 .../features/image-resizeuidropdown.html      |  6 -----
 .../ckeditor5-image/docs/features/image.md    | 26 ++++++++++++++-----
 3 files changed, 20 insertions(+), 18 deletions(-)

diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-resizeui.html b/packages/ckeditor5-image/docs/_snippets/features/image-resizeui.html
index df8ec9be02a..0177c424678 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-resizeui.html
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-resizeui.html
@@ -5,10 +5,4 @@ <h3>Resize me using image toolbar buttons!</h3>
 		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
 		<figcaption>Autumn fields by Aleksander Nowodziński</figcaption>
 	</figure>
-
-	<h3>Resized image (width: 75%):</h3>
-
-	<figure class="image image_resized" style="width:75%;">
-		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
-	</figure>
 </div>
diff --git a/packages/ckeditor5-image/docs/_snippets/features/image-resizeuidropdown.html b/packages/ckeditor5-image/docs/_snippets/features/image-resizeuidropdown.html
index 692ddb981f6..0868262878a 100644
--- a/packages/ckeditor5-image/docs/_snippets/features/image-resizeuidropdown.html
+++ b/packages/ckeditor5-image/docs/_snippets/features/image-resizeuidropdown.html
@@ -5,10 +5,4 @@ <h3>Resize me using the dropdown!</h3>
 		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
 		<figcaption>Autumn fields by Aleksander Nowodziński</figcaption>
 	</figure>
-
-	<h3>Resized image (width: 75%):</h3>
-
-	<figure class="image image_resized" style="width:75%;">
-		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
-	</figure>
 </div>
diff --git a/packages/ckeditor5-image/docs/features/image.md b/packages/ckeditor5-image/docs/features/image.md
index b3044ded40f..ddcc25fb224 100644
--- a/packages/ckeditor5-image/docs/features/image.md
+++ b/packages/ckeditor5-image/docs/features/image.md
@@ -158,7 +158,7 @@ Try to understand what use cases the system needs to support and define semantic
 </info-box>
 
 <info-box warning>
-	While semantical styles can be combined with manual [image resizing](#image-resizing), these features were not designed to be used together.
+	While semantical styles can be combined with manual [image resizing](#resizing-images), these features were not designed to be used together.
 
 	If you want to enable image resizing, use [presentational image styles](#presentational-styles).
 </info-box>
@@ -224,11 +224,21 @@ It is implemented by the {@link module:image/imageresize~ImageResize} plugin and
 
 The plugin also gives you an ability to change the size of the image through the image toolbar. You can set an optional static configuration with {@link module:image/image~ImageConfig#resizeOptions} and choose whether you want to use a dropdown or set of the standalone buttons.
 
-### Resize image using handles
+### Methods to resize images
+
+The editor offers three ways to resize images. One of them (resize handles) is
+
+#### Using handles
+
+In this case, the user is able to resize images via dragging square handles displayed in each corner of the image. Once [image resizing was enabled](#enabling-image-resizing), this option does not require any additional configuration.
 
 {@snippet features/image-resize}
 
-### Resize image using the plugin dropdown
+#### Using the dropdown
+
+In this case, the user is able to choose from a set of predefined options. These options can be displayed in the image toolbar in form of a dropdown.
+
+To use this option, you need to [enable image resizing](#enabling-image-resizing) and configure the available {@link module:image/image~ImageConfig#resizeOptions resize options}.
 
 ```js
 const imageConfiguration = {
@@ -249,13 +259,17 @@ const imageConfiguration = {
 			value: '75'
 		}
 	],
-	toolbar: [ ... , 'imageResize' ]
+	toolbar: [ ..., 'imageResize' ]
 }
 ```
 
 {@snippet features/image-resizeuidropdown}
 
-### Resize image using the standalone buttons
+#### Using standalone buttons
+
+In this case, the resize options are displayed in form of separate buttons. The benefit of this solution is the smoothest UX as the user needs just one click to resize an image.
+
+To use this option, you need to [enabling image resizing](#enabling-image-resizing) and configure the available {@link module:image/image~ImageConfig#resizeOptions resize options}.
 
 ```js
 const imageConfiguration = {
@@ -277,7 +291,7 @@ const imageConfiguration = {
 		}
 	],
 	toolbar: [
-		// ...,
+		...,
 		'imageResize:original',
 		'imageResize:50',
 		'imageResize:75'