## Aurora theming - color schemes A **color scheme** is a set of information that allows painting a control in a specific visual state. In general, a color scheme defines a collection of colors that are used by the various Aurora [painters](../painters/overview.md) to paint different control areas (such as background fill, border etc) under a specific visual state. The `AuroraColorScheme` contains all the APIs officially supported by Aurora color schemes. The APIs can be roughly divided in three categories: * Base colors. These are defined in the `SchemeBaseColors` * Derived colors. These are defined in the `SchemeDerivedColors` * Creating derived color schemes. ### Base colors The `SchemeBaseColors` defines the following base colors: * Ultra light * Extra light * Light * Mid (medium) * Dark * Ultra dark * Foreground The first six colors are used to paint the background "layer" of a control, such as, for example, the background fill of a button. The foreground color is primarily used to paint the foreground "layer" of a control, such as, for example, the button text and optionally the themed button icon. It is up to the [fill painter](../painters/fill.md) to decide which specific colors to use for the background layer, and how to use them. For example, a completely flat (non-gradient) look can be achieved by the fill painter using a single color, or by a color scheme specifying identical color values for the entire ultra light / ultra dark spectrum. ### Derived colors The `SchemeDerivedColors` defines the following derived colors: * Line * Focus ring * Mark * Echo * Background fill * Text background fill * Accented background fill * Selection background * Selection foreground * Separator primary * Separator secondary The idea behind derived colors is to find the balance between consistent visuals across all surfaces painted by Aurora and allowing the app to customize specific colors to fit the particulars of its design language. Let's take a look at the following UI under the core Dust Coffee skin: Dust Coffee To point out just a few places where Aurora is using derived colors: * Mark color is used for the selected mark / dot of checkboxes and radio buttons, as well as the arrow of the combobox. * Separator secondary color is used for the double content border of the tabbed pane * Separator primary and secondary colors are used to paint the drag bump dots of the toolbar, as well as the separators in the toolbar * Accented background fill is used to fill the scroll bar track * Text background fill is used to fill the text field for better visual indication of editable content Providing one or more of the derived colors in your [color schemes file](colorschemes-fileformat.md) is the recommended approach to tweaking the overall visual language of your application while maintaining continuity across different UI surfaces. ### Core light color schemes The Aurora theming library provides the following sixteen light color schemes: Aqua, Barby Pink

Aqua Barby Pink

Bottle Green, Brown

Bottle Green Brown

Creme, Light Aqua

Creme Light Aqua

Lime Green, Olive

Lime Green Olive

Orange, Purple

Orange Purple

Raspberry, Sepia

Raspberry Sepia

Steel Blue, Sunset

Steel Blue Sunset

Sun Glare, Terracotta

Sun Glare Terracotta

### Core dark color schemes The Aurora theming library provides the following five dark color schemes: Ebony, Dark Violet

Ebony Dark Violet

Charcoal, Jade Forest

Charcoal Jade Forest

Ultramarine

Ultramarine

### Deriving color schemes The `AuroraColorScheme` interface contains a number of APIs to create derived color schemes. Note that a color scheme is a delicate balance between the foreground color and the background colors, providing visually appealing selection of colors that are designed to work together on various painters. In some cases, creating a derived color scheme with one the these APIs (especially negated and inverted color schemes) will not result in visually pleasing appearance. The following API allows shifting both the background and the foreground colors: ```kotlin /** * Creates a shift version of this scheme. * * @param backgroundShiftColor * Shift color for background colors. Should have full opacity. * @param backgroundShiftFactor * Value in 0.0...1.0 range. Larger values shift more towards the * specified color. * @param foregroundShiftColor * Shift color for foreground colors. Should have full opacity. * @param foregroundShiftFactor * Value in 0.0...1.0 range. Larger values shift more towards the * specified color. * @return Shift version of this scheme. */ fun shift( backgroundShiftColor: Color, backgroundShiftFactor: Float, foregroundShiftColor: Color, foregroundShiftFactor: Float ): AuroraColorScheme ``` Here is the `Purple` color scheme shifted 80% towards light green in background colors and 70% towards dark red in foreground color (see the foreground color of the default button): Derived Shifted The following API allows tinting the colors (shifting towards white): ```kotlin /** * Creates a tinted (shifted towards white) version of this * color scheme. * * @param tintFactor * Value in 0.0...1.0 range. Larger values shift more towards white * color. * @return Tinted version of this scheme. */ fun tint(tintFactor: Float): AuroraColorScheme ``` The following API allows toning the colors (shifting towards gray): ```kotlin /** * Creates a toned (shifted towards gray) version of this color * scheme. * * @param toneFactor * Value in 0.0...1.0 range. Larger values shift more towards gray * color. * @return Toned version of this scheme. */ fun tone(toneFactor: Float): AuroraColorScheme ``` The following API allows shading the colors (shifting towards black): ```kotlin /** * Creates a shaded (shifted towards black) version of this * color scheme. * * @param shadeFactor * Value in 0.0...1.0 range. Larger values shift more towards black * color. * @return Shaded version of this scheme. */ fun shade(shadeFactor: Float): AuroraColorScheme ``` Here is the same `Purple` color scheme tinted 40%, toned 40% and shaded 40%: Derived Tinted Derived Toned Derived Shaded The following API allows saturating or desaturating the colors: ```kotlin /** * Creates a saturated or desaturated version of this scheme. * The value and brightness stay the same. * * @param saturateFactor * Value in -1.0...1.0 range. Positive values create more saturated * colors. Negative values create more desaturated colors. * @return Saturated version of this scheme. */ fun saturate(saturateFactor: Float): AuroraColorScheme ``` Here is the same `Purple` color scheme saturated 40% and desaturated 40%: Derived Saturated Derived Desaturated The following API allows inverting the colors: ```kotlin /** * Creates an inverted version of this scheme. * * @return Inverted version of this scheme. */ fun invert(): AuroraColorScheme ``` The following API allows negating the colors: ```kotlin /** * Creates a negated version of this scheme. * * @return Negated version of this scheme. */ fun negate(): AuroraColorScheme ``` Here is the same `Purple` color scheme inverted and negated: Derived Inverted Derived Negated The following API allows shifting the hue of the colors: ```kotlin /** * Creates a hue-shifted (in HSB space) version of this color * scheme. * * @param hueShiftFactor * Value in -1.0...1.0 range. * @return Hue-shifted version of this scheme. */ fun hueShift(hueShiftFactor: Float): AuroraColorScheme ``` Here is the same `Purple` color scheme hue-shifted 40%: Derived Hue Shifted