
package com.smartgwt.client.docs;

/**
 * <h3>Customizing Skins</h3>
 * 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:
 *  <ul>
 *  <li><code>skin_styles.css</code> - the stylesheet.
 * <li><code>load_skin.js</code> - loads the stylesheet and the skin's fonts, and applies the
 * skin's
 *  widget defaults (scrollbars, icon sizing, spacing and so on).
 *  <li><code>images/</code> - the skin's image assets.
 *  </ul>
 *  <P>
 * For the general picture of how Smart GWT components are styled, see {@link
 * com.smartgwt.client.docs.Skinning}.  This
 *  discussion covers creating and customizing Smart GWT's <i>modern</i> skins.
 * 
 *  <h3>Modern skins</h3>
 * 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.
 *  <P>
 *  That approach has three parts:
 *  <ul>
 *  <li>styling is driven by CSS custom properties, <code>var(--isc-*)</code>;
 *  <li>a skin is edited as data - a single JSON file, <code>config.json</code>;
 * <li>the built <code>skin_styles.css</code> and <code>load_skin.js</code> are <i>tokenized</i>:
 * they
 * carry marked regions that the framework fills from <code>config.json</code> - the variable
 * values,
 *  plus any custom CSS, fonts and JavaScript.
 *  </ul>
 *  <P>
 * A modern skin's whole appearance therefore comes down to the values in its
 * <code>config.json</code>.
 *  You edit that file, and <code>skin_styles.css</code> is produced from it; you never edit
 *  <code>skin_styles.css</code> by hand.
 *  <P>
 *  A modern skin also normally <i>derives</i> from another.  It names a <code>baseSkin</code> 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.
 *  <P>
 * (Some older skins, such as the Enterprise series, are still generated from Sass templates, and
 * are
 *  customized differently.)
 * 
 *  <h3>The config.json format</h3>
 * A skin's <code>config.json</code> is a single object.  A minimal one names the skin, names the
 * base
 *  it derives from, and lists the variables it changes:
 *  <pre>
 *  {
 *      "name": "MyTheme",
 *      "baseSkin": "Tahoe",
 *      "settings": {
 *          "--isc-highlight_color": "#40BF41",
 *          "--isc-standard_button_border_radius": "5px"
 *      }
 *  }
 *  </pre>
 *  <P>
 *  The top-level fields are:
 *  <P>
 *  <b><code>name</code></b><br>
 *  The skin's name.  Matches its directory.
 *  <P>
 *  <b><code>baseSkin</code></b><br>
 *  The skin this one derives from.  A base skin is its own base.
 *  <P>
 *  <b><code>settings</code></b><br>
 *  An object mapping <code>--isc-*</code> 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.
 *  <P>
 *  <b><code>useLiveCSS</code></b><br>
 *  Whether the skin is served live (<code>true</code>, the default) or as a frozen snapshot.  See
 *  "Deploying a skin" below.
 *  <P>
 * <b><code>customCSS</code>, <code>customJS</code>, <code>customSVG</code>,
 * <code>fontCss</code></b><br>
 *  The skin's own custom CSS, JavaScript, stock-icon SVG symbols and <code>@font-face</code>
 *  declarations, held inline.  See "Custom CSS, fonts and JavaScript" below.
 *  <P>
 * <b><code>customCSSFile</code>, <code>customJSFile</code>, <code>customSVGFile</code>,
 * <code>fontCssFile</code></b><br>
 * 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 <i>either</i> inline <i>or</i> as a
 * file
 *  reference, never both.
 *  <P>
 *  <b><code>fontList</code></b><br>
 *  The fonts the skin uses, so the framework can load them.
 *  <P>
 *  <b><code>density</code></b><br>
 *  The skin's spacing density.
 *  <P>
 *  <b><code>version</code></b><br>
 *  A counter, bumped each time the skin is saved.
 * 
 *  <h3>Variables and the cascade</h3>
 * A skin is driven entirely by CSS custom properties, so a few high-level changes can restyle the
 *  whole framework.
 *  <P>
 *  Most of a skin's look derives from a small set of "primary" variables.  For example,
 * <code>--isc-highlight_color</code> sets the accent color used across buttons, headers,
 * selection
 *  and focus.
 *  <P>
 *  Variables can be defined in terms of one another, and can use CSS color math such as
 * <code>oklch()</code> and <code>color-mix()</code>.  A single edit can therefore retune an
 * entire
 *  palette while preserving its contrast and tint relationships.
 *  <P>
 *  The complete list of variables lives in any skin's <code>config.json</code>, or in the
 * <code>:root{}</code> block of its <code>skin_styles.css</code>.  The Skin Editor presents the
 * same
 *  variables organized by component and role, with a live preview.
 * 
 *  <h3>Custom CSS, fonts and JavaScript</h3>
 * Beyond variable values, a skin can carry its own custom CSS, <code>@font-face</code>
 * declarations
 *  and JavaScript.  These live in the <code>customCSS</code>, <code>fontCss</code> and
 *  <code>customJS</code> fields - inline, or in sibling files via their <code>...File</code>
 *  counterparts.
 *  <P>
 *  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.
 * 
 *  <h3>Compact skins</h3>
 *  If your application runs on the Smart GWT server, a skin can take a more compact form.
 *  <P>
 *  In place of the three files above, the skin's directory holds a single <code>.skin.json</code>
 * 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.
 *  <P>
 *  Because the server does this on every request, a compact skin is served <i>live</i>: it always
 *  reflects the current version of the base skin it derives from.
 *  <P>
 * A <code>.skin.json</code> is written as an <code>isc_userSkin</code> record.  The record serves
 * only
 *  to identify the skin - its outer <code>name</code> and <code>baseSkin</code> - and to hold the
 *  skin's config in a <code>userSettings</code> field.  That <code>userSettings</code> object is
 *  exactly the <code>config.json</code> content described above.
 *  <P>
 * For example, a purple variant of Shiva is a directory <code>skins/PurpleShiva</code> holding
 * one
 *  file, <code>PurpleShiva.skin.json</code>:
 *  <pre>
 *  {
 *      "name": "PurpleShiva",
 *      "baseSkin": "Shiva",
 *      "userSettings": {
 *          "name": "PurpleShiva",
 *          "baseSkin": "Shiva",
 *          "useLiveCSS": true,
 *          "settings": { "--isc-highlight_color": "purple" }
 *      }
 *  }
 *  </pre>
 *  <P>
 * Load any page with <code>skin=PurpleShiva</code> in the URL - for example the Feature Explorer
 * at
 * <code>/showcase/?skin=PurpleShiva</code>.  The server serves it as though it were a base skin,
 * with
 *  your highlight color applied everywhere it cascades.
 * 
 *  <h3>Creating a skin</h3>
 * 
 *  <h4>With the Skin Editor</h4>
 * The {@link com.smartgwt.client.docs.SkinEditor 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.
 *  <P>
 *  It is available online, or in your own environment with a
 *  <a href='https://www.smartclient.com/product/' target='_blank'>Pro or better</a> license.
 *  <P>
 *  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.
 * 
 *  <h4>By hand, as a compact skin</h4>
 * A compact skin (above) is the simplest skin to write by hand.  Create the skin's directory, add
 * a
 * <code>.skin.json</code> naming a base skin and the settings you want to change, and load the
 * page
 *  with <code>skin=<i>YourSkin</i></code>.
 * 
 *  <h4>As a full skin directory</h4>
 * For a self-contained skin with its own stylesheet and assets, copy an existing skin's
 * directory.
 *  For example, copy <code>skins/Tahoe</code> to <code>skins/MySkin</code>, replace "Tahoe" with
 * "MySkin" in <code>load_skin.js</code>, and edit <code>MySkin</code>'s <code>config.json</code>.
 * 
 *  <h3>Deploying a skin</h3>
 * 
 *  <h4>With the Smart GWT server</h4>
 * Deploy the skin's <code>config.json</code> (or its <code>.skin.json</code> record), and the
 * server
 *  produces <code>skin_styles.css</code> on demand.
 *  <P>
 *  By default this is the live overlay described above.  You can instead <i>freeze</i> a skin
 * (<code>useLiveCSS:false</code>): 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.
 * 
 *  <h4>On a static web server</h4>
 *  To host a skin with no Smart GWT server at all, deploy a built <code>skin_styles.css</code>.
 * Each skin ships with a small command-line build that regenerates it from
 * <code>config.json</code>,
 *  with no server and no Sass toolchain.
 */
public interface CustomSkins {
}
