creating-a-skin.adoc

Create a Skin for {productname}

This guide explains how to manually create a new skin to customize the appearance of {productname} {productmajorversion}.

Prerequisites

Before beginning, ensure that:

• Familiarity with the command line and basic commands is established.

• Node.js and Yarn are already installed.

• A basic understanding of Less, the CSS preprocessor used to build skins, is required. Specifically, review the section on variables.

Preparation

The CSS associated with a theme is called a skin. The default skin for {productname} {productmajorversion} is Oxide, written in Less. Oxide introduces the Style API, which consists of approximately 300 variables that allow customization of {productname} without modifying the underlying CSS. This approach ensures compatibility with future updates and provides continued support for bug fixes.

Important

{companyname} recommends not modifying or overriding CSS rules directly.

Follow these steps to set up the skin development environment:

1. Download (or git clone) the {productname} source code.

2. Open a terminal and navigate to the folder you just downloaded.

3. Install dependencies and build the project using the following commands:

   yarn && yarn dev && yarn build

4. Start the development server to preview skins:

   yarn oxide-start

5. Once the server starts, open a browser and navigate to the displayed URL, typically http://localhost:3000.

The development environment is now setup and should look similar to the following:

Note	If required to modify the skin without launching a web server, run yarn oxide-build instead of yarn oxide-start.

Creating or Editing a Skin

Ensure completion of the preparation steps before proceeding.

Directory Structure

Navigate to modules/oxide/src/less/skins/. This folder contains:

1. /ui: Contains editor UI skins. The main file here is skin.less.

2. /content: Contains skins for the content inside the editor.

The modules/oxide/src/less/theme/ folder contains Less files defining global styles. Most files list available variables at the top, such as colors, margins, and fonts. Variables are prefixed with @ (e.g., @background-color).

Important

Do not edit these files directly. Instead, use them as references when creating a custom skin. Start by reviewing: modules/oxide/src/less/theme/globals/global-variables.less modules/oxide/src/less/theme/components/toolbar-button/toolbar-button.less The typical workflow involves copying variables from the theme folder into the skins skin.less file and modifying them as needed.

Note	Skins only affect the visual appearance of the UI. Element positioning is managed by {productname}'s UI framework.

Creating a Skin

1. Duplicate the default folder in modules/oxide/src/less/skins/ui/ and rename it.

2. Rebuild the project to recognize the newly created skins by running:

   yarn build

3. Start the development server by running:

   yarn oxide-start

   Tip	If the server is already running, restart it (Ctrl+C) and run the command again.

4. Open modules/oxide/src/less/skin/ui/<your-skin-name>/skin.less.

5. Open a Less file from the theme folder (e.g., modules/oxide/src/less/theme/globals/global-variables.less) and copy a variable to modify. For example:

   @background-color: red;

6. Paste the variable into the skin.less file.

   The updated skin.less should look like this:

   @import 'src/less/theme/theme';
   
   //
   // Place your variables here
   //
   
   @background-color: red;

7. Save the file and check the changes in a browser. Select the skin from the Skin menu.

8. The editor should now display with a red background.

This method allows customization of {productname} by modifying predefined variables, such as toolbar spacing or letter spacing.

Tip	Adjust {productname} configurations in modules/oxide/src/demo/index.html to match specific use cases.

Creating a Content CSS File

To modify the appearance of content inside the editor (e.g., headings, lists, quotes), create a content CSS file:

1. Create a folder in modules/oxide/src/less/skins/content/ and add a content.less file. Alternatively, duplicate an existing content CSS file.

2. Rebuild the project to recognize the newly created content skin.

   yarn build

3. Start the development server:

   yarn oxide-start

   Tip	If the server is already running, restart it (Ctrl+C) and run the command again.

4. Add styles for relevant elements (h1 to h6, a, blockquote, code, table, etc.). For example:

   h1 {
     color: red;
   }

5. Save the file and check the changes in a browser.

6. The editor should now display with red headings.

Moving the Skin into {productname}

1. Copy the skin and/or content CSS from modules/oxide/build/skins/ to the appropriate folders in the production {productname} setup.

2. Update {productname}'s initialization options:

   • Use the skin option for UI skins.

   • Use the content_css option for content styles.

For details on specifying the skin file location, see this section.

Modifying Icons

For details on adding custom icons, see: Create an Icon Pack for {productname}.