public interface CustomSkins

Customizing Skins

A skin gives a Smart GWT application its look and feel. On disk, a skin is a directory the framework loads, made up of three parts:

skin_styles.css - the stylesheet.
load_skin.js - loads the stylesheet and the skin's fonts, and applies the skin's widget defaults (scrollbars, icon sizing, spacing and so on).
images/ - the skin's image assets.

For the general picture of how Smart GWT components are styled, see Skinning. This discussion covers creating and customizing Smart GWT's modern skins.

Modern skins

Smart GWT's modern skins - the "Flat" series, such as Tahoe, Shiva and Stratus - were built with Sass in earlier releases. They no longer are: they are free of that toolchain, and use a purely CSS-and-JSON approach.

That approach has three parts:

styling is driven by CSS custom properties, var(--isc-*);
a skin is edited as data - a single JSON file, config.json;
the built skin_styles.css and load_skin.js are tokenized: they carry marked regions that the framework fills from config.json - the variable values, plus any custom CSS, fonts and JavaScript.

A modern skin's whole appearance therefore comes down to the values in its config.json. You edit that file, and skin_styles.css is produced from it; you never edit skin_styles.css by hand.

A modern skin also normally derives from another. It names a baseSkin and records only the variables - and any custom CSS, fonts or JavaScript - that it changes. This keeps skins small, and lets a skin inherit later improvements to the one it was built on.

(Some older skins, such as the Enterprise series, are still generated from Sass templates, and are customized differently.)

The config.json format

A skin's config.json is a single object. A minimal one names the skin, names the base it derives from, and lists the variables it changes:

  {
      "name": "MyTheme",
      "baseSkin": "Tahoe",
      "settings": {
          "--isc-highlight_color": "#40BF41",
          "--isc-standard_button_border_radius": "5px"
      }
  }

The top-level fields are:

name
The skin's name. Matches its directory.

baseSkin
The skin this one derives from. A base skin is its own base.

settings
An object mapping --isc-* variables to their values: colors, fonts, sizes, corner radii and so on. You list only the variables you want to change from the base skin. This is the bulk of most skins; see "Variables and the cascade" below.

useLiveCSS
Whether the skin is served live (true, the default) or as a frozen snapshot. See "Deploying a skin" below.

customCSS, customJS, customSVG, fontCss
The skin's own custom CSS, JavaScript, stock-icon SVG symbols and @font-face declarations, held inline. See "Custom CSS, fonts and JavaScript" below.

customCSSFile, customJSFile, customSVGFile, fontCssFile
A file alternative to each field above. Instead of inline content, the field holds the name of a sibling file in the skin's directory. A value is stored either inline or as a file reference, never both.

fontList
The fonts the skin uses, so the framework can load them.

density
The skin's spacing density.

version
A counter, bumped each time the skin is saved.

Variables and the cascade

A skin is driven entirely by CSS custom properties, so a few high-level changes can restyle the whole framework.

Most of a skin's look derives from a small set of "primary" variables. For example, --isc-highlight_color sets the accent color used across buttons, headers, selection and focus.

Variables can be defined in terms of one another, and can use CSS color math such as oklch() and color-mix(). A single edit can therefore retune an entire palette while preserving its contrast and tint relationships.

The complete list of variables lives in any skin's config.json, or in the :root{} block of its skin_styles.css. The Skin Editor presents the same variables organized by component and role, with a live preview.

Custom CSS, fonts and JavaScript

Beyond variable values, a skin can carry its own custom CSS, @font-face declarations and JavaScript. These live in the customCSS, fontCss and customJS fields - inline, or in sibling files via their ...File counterparts.

The framework merges them into the skin, keeping a base skin's own custom styles separate from those a derived skin adds. Customizing a skin therefore never discards the styling it inherited.

Compact skins

If your application runs on the Smart GWT server, a skin can take a more compact form.

In place of the three files above, the skin's directory holds a single .skin.json file. The server expands it into a working skin on the fly, overlaying the skin's config onto its base skin and serving the result.

Because the server does this on every request, a compact skin is served live: it always reflects the current version of the base skin it derives from.

A .skin.json is written as an isc_userSkin record. The record serves only to identify the skin - its outer name and baseSkin - and to hold the skin's config in a userSettings field. That userSettings object is exactly the config.json content described above.

For example, a purple variant of Shiva is a directory skins/PurpleShiva holding one file, PurpleShiva.skin.json:

  {
      "name": "PurpleShiva",
      "baseSkin": "Shiva",
      "userSettings": {
          "name": "PurpleShiva",
          "baseSkin": "Shiva",
          "useLiveCSS": true,
          "settings": { "--isc-highlight_color": "purple" }
      }
  }

Load any page with skin=PurpleShiva in the URL - for example the Feature Explorer at /showcase/?skin=PurpleShiva. The server serves it as though it were a base skin, with your highlight color applied everywhere it cascades.

Creating a skin

With the Skin Editor

The Skin Editor is the easiest way to create and customize a skin. It manages the skin's config for you, editing its variables and custom CSS, fonts and JavaScript with a live preview.

It is available online, or in your own environment with a Pro or better license.

When a skin is stored in a DataSource and the Skin Editor runs on the same server as your application, your changes take effect immediately - the skin does not have to be exported.

By hand, as a compact skin

A compact skin (above) is the simplest skin to write by hand. Create the skin's directory, add a .skin.json naming a base skin and the settings you want to change, and load the page with skin=YourSkin.

As a full skin directory

For a self-contained skin with its own stylesheet and assets, copy an existing skin's directory. For example, copy skins/Tahoe to skins/MySkin, replace "Tahoe" with "MySkin" in load_skin.js, and edit MySkin's config.json.

Deploying a skin

With the Smart GWT server

Deploy the skin's config.json (or its .skin.json record), and the server produces skin_styles.css on demand.

By default this is the live overlay described above. You can instead freeze a skin (useLiveCSS:false): the server then serves a baked, self-contained snapshot that no longer tracks its base. Freezing is useful when you want a skin's appearance pinned.

On a static web server

To host a skin with no Smart GWT server at all, deploy a built skin_styles.css. Each skin ships with a small command-line build that regenerates it from config.json, with no server and no Sass toolchain.

Interface CustomSkins