Platforms: Android, iOS, Web
Themes are configured with a
themes map in the
.aesthetic/<name>/themes.yaml file, where the key
is the theme name, and the value is a configuration object of colors, palettes, and additional
One such setting is
scheme, which requires either "light" or "dark", and is utilized in color
scheme preference detection. This allows for the automatic detection of light or dark modes for a
For every color that's been defined in the design language, an associated
entry must exist within each theme under
colors.<name>. A color supports a range of 10 hexcode
90) known as shades.
In a light color scheme, the
00 shade is the lightest color, while
90 is the darkest. This is
reversed for dark color schemes, where
00 is darkest, and
90 is lightest. In both schemes, the
40 shade is the base "common" shade.
Colors also support single shades, for those scenarios where you only need a single hexcode, like white and black. These types are colors cannot be used as a palette, but can be referenced in palette states.
Palettes are the defining feature of Aesthetic, as they enable true interoperability and backwards compatibility with other Aestheic powered design systems. In Aesthetic, colors are not directly accessible to consumers, as colors are not deterministic between systems, but palettes are!
A palette is a collection of color references for both text, foreground (text on background) and background colors, grouped by states and interactions. The available palettes are:
brand- Organization or company brand color.
primary- Primary color. Typically buttons, links, bars, active states, etc.
secondary- Accent color. Provides emphasis and contrast to the primary color.
tertiary- Additional complementary color for more variation.
neutral- Whites, grays, blacks, etc that make up background, border, shadow, and other layout related pieces.
muted- Disabled and empty like states.
warning- State that warns the user of something minor.
danger- State that indicates a destructive, atomic, or irreversible action.
negative- State when something negative occurs, like errors or failures.
positive- State when something positive occurs, like successful operations.
Hopefully you have a better understanding of all the palettes, so let's dive into the configuration. Each palette contains the following settings, each of which requires a color + shade combination value.
color- The color range this palette is based on. Will make the color range available downstream under this palette.
text- Text color when displayed on the document background (typically the
bg- Background color that maps shades to 5 different states.
fg- Text color that maps shades to 5 different states when displayed on the background color (
In the example above, we mentioned 5 different states. In order of priority and specificity (based on LVHA), they are:
base- The base palette color. Defaults to shade
focused- State when a target is focused through user interaction. Defaults to shade
hovered- State when a target is being hovered. Defaults to shade
selected- State when a target is selected, active, expanded, etc. Defaults to shade
disabled- State when a target is disabled. Should override all previous states. Defaults to shade
All of the states are optional, and will default to the shade references above. If you prefer to always use the defaults, a shorthand configuration is available, where the setting value can simply be set to the color name. The above example can now be written as:
This may seem like a lot to configure, and it is, but it's thorough and covers many common and industry standard use cases. It also mitigates problems between light and dark themes.
While color schemes offer a light or dark option, what about preferences for low or
high contrast colors? With the
contrast setting, a theme can be marked as "low" or "high"
contrast, and will be utilized during the detection phase.
A contrast variant usually extends a base theme, as we want to use the same palette, but adjust the colors. For example, say we have a "night" dark theme, and want to provide a vibrant high contrast variant.
Aesthetic also supports the concept of extending themes, where a theme (the child) can extend another theme (the parent), to inherit all its colors, palettes, and settings. The child theme can then define individual settings, instead of having to define them all.
To extend another theme, use the
extends setting, which requires the parent theme's name. The
child theme object will deep merge with the parent theme object.
Like the design language, themes also enforce the following constraints as the system currently relies on fixed settings.
- 10 color shades (00, 10, 20, 30, 40 (default), 50, 60, 70, 80, 90)
- 10 palettes (brand, primary, secondary, tertiary, neutral/layout, muted, positive, warning, danger, negative)
- 5 palette states (base, hovered, selected, disabled, focused)
- Light scheme OR dark scheme
- High, low, OR normal contrast