DOC-2367 restore creating-a-skin.adoc and only remove link to the Ski…

…n Tool (#3214)

* DOC-2367 restore creating-a-skin.adoc and only remove link to the Skin Tool

* replace TinyMCE instances with {productname} attribute

modules/ROOT/nav.adoc

@@ -148,6 +148,7 @@
 *** xref:troubleshoot-server.adoc[Troubleshoot server-side components]
 ** Customizing the editor appearance
 *** xref:customize-ui.adoc[Customizing the UI]
+*** xref:creating-a-skin.adoc[Create a skin]
 *** xref:creating-an-icon-pack.adoc[Create an icon pack]
 ** Images Guide
 *** xref:upload-images.adoc[Image uploads]

modules/ROOT/pages/creating-a-skin.adoc

@@ -0,0 +1,117 @@
+= Create a skin for {productname}
+:navtitle: Create a skin
+:description_short: Introducing skin creation.
+:description: Introducing skin creation, less and icon modification.
+:keywords: create, creator, skin, icon
+
+This section provides information on how to manually create a new skin to customize the appearance of {productname} {productmajorversion}.
+
+== Prerequisites
+
+This guide assumes:
+
+* Familiarity with the command line and running simple commands.
+* https://nodejs.org/en/[Node.js], https://yarnpkg.com/en/[Yarn] and https://gulpjs.com[Gulp] are already installed.
+* Basic understanding of http://lesscss.org[Less], the CSS preprocessor we use to build the skins. More specifically, http://lesscss.org/features/#variables-feature[read the section about variables].
+
+== Preparation
+
+The CSS that goes with a theme is called a skin. The default skin for {productname} {productmajorversion} is named Oxide and is written in http://lesscss.org[Less], a popular CSS preprocessor. With Oxide we introduced a concept we call the *Style API*. This API consists of around 300 variables which you use to modify the appearance of {productname}. You never touch the underlying CSS. The benefit of this approach is that improvements we make to the CSS and HTML won't break your custom skin. This also means that if things don't work as expected, we can provide support and bug fixes, something that was virtually impossible before.
+
+IMPORTANT: We do not recommend modifying or overriding CSS rules directly.
+
+To set up the skin development environment, begin with the following steps:
+
+. Download (or `+git clone+`) the https://github.com/tinymce/tinymce[{productname} source code].
+. Open the terminal and navigate to the folder you just downloaded.
+. Install dependencies with the command:
++
+[source,sh]
+----
+yarn install
+----
+. Launch the web server to preview the skins using the command:
++
+[source,sh]
+----
+yarn oxide-start
+----
+
+You should now be able to open a web browser and point it to the url displayed in the terminal, usually `+http://localhost:3000+`.
+
+The development environment is set up and ready to work.
+
+image::SDK-for-silver.png[{productname} skin SDK for Silver theme]
+
+If you just need to build the skins without launching a web server, run:
+
+[source,sh]
+----
+yarn oxide-build
+----
+
+== Making or editing a skin
+
+Make sure you have performed the preparation steps above.
+
+=== Overview
+
+Navigate to `+modules/oxide/src/less/skins/+`. There are two folders in this location:
+
+* `+/ui+` - which is the skins for the editor. The important file here is `+skin.less+`.
+* `+/content+` - which is the skins for the content within the editor.
+
+The folder `+modules/oxide/src/less/theme/+` contains the Less files. At the top of most files you'll find the available variables that defines the default colors, margins, fonts etc (variables are the strings that starts with an at-character, for example `+@background-color+`). _Do not edit these files_, instead use them as a reference when creating your skin. We recommend starting with the two files containing global variables: `+modules/oxide/src/less/theme/globals/global-variables.less+` and the toolbar buttons: `+modules/oxide/src/less/theme/components/toolbar-button/toolbar-button.less+`.
+
+The general workflow is that you look inside the less files within the theme folder and copy the variables you like to change into your skin's `+skin.less+` file.
+
+NOTE: The skin *only* changes the visual presentation of the UI and *not* the placement of elements. Placement of elements is done by the {productname} UI framework. This framework makes it possible to do complex UI layouts on all browsers without touching any CSS when plugins are created.
+
+[[creating-a-skin]]
+=== Creating a skin
+
+. Begin by duplicating the `+default+` folder located in `+modules/oxide/src/less/skins/ui/+` and rename it to the name of your skin.
+. Start the development server using the terminal command `+yarn oxide-start+`. If you already have the server running, you need to restart it to make it recognize your new skin using `+ctrl-c+` and then start it again.
+. Open the file `+modules/oxide/src/less/skin/ui/<your-skin-name>/skin.less+`.
+. Open any less file located in the theme folder, for example `+modules/oxide/src/less/theme/globals/global-variables.less+` and copy a variable you like to change, it's easiest to copy the whole line. Let's copy the `+@background-color+` variable to start with.
+. Paste the variable into the `+skin.less+` file you opened in step 2. For a striking look, change the variable value to be red, like this: `+@background-color: red;+`. Then save the file.
+
+Your skin.less file should now look like this:
+
+[source,less]
+----
+@import 'src/less/theme/theme';
+
+//
+// Place your variables here
+//
+
+@background-color: red;
+----
+
+Switch to the web browser. Select your skin from the _Skin menu_. It should show a fiery red editor
+
+image::SDK-for-silver-custom-example.png[{productname} skin SDK for Silver theme]
+
+This is how you skin {productname}: copy variables from the files in the theme folder and paste them into your skin file. There are variables for most things, like spacing between toolbar buttons to letter spacing. Simple yet powerful.
+
+TIP: You can change the {productname} config in `+modules/oxide/src/demo/index.html+` to suit your particular use case.
+
+== Creating a content CSS file
+
+To update the appearance of the content within the editor, such as headings, quotes, lists, etc... you create a content css. These are located in `+modules/oxide/src/less/skin/content/+`
+
+. Create a folder in `+modules/oxide/src/less/skins/content/+` and create a `+content.less+` file in it. Alternatively, you can duplicate any of the existing content css.
+. Start the development server using the terminal command yarn oxide-start. If you already have the server running, you need to restart it to make it recognize your new skin using ctrl-c and then start it again.
+. Add the relevant element selectors for the desired use case such as `+h1+` to `+h6+`, `+a+`, `+blockquote+`, `+code+`, `+table+`, etc...
+
+== Moving the skin into {productname}
+
+. Copy the skin and/or content CSS from `+modules/oxide/build/skins/+` to the corresponding folders in your production {productname} folder.
+. Update the {productname} init function with the xref:editor-skin.adoc#skin[skin] option and/or the xref:add-css-options.adoc#content_css[content_css] option.
+
+For more information on how to specify the location of the skin file, see xref:editor-skin.adoc#skin_url[this] section.
+
+== Modifying the icons
+
+For information on adding custom icons, see: xref:creating-an-icon-pack.adoc[Create an icon pack for {productname}].