themes.yaml
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
settings.
Color scheme#
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
user.
Color shades#
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
values (00 - 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 and 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 theneutralpalette).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 (bg).
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 shade40.focused- State when a target is focused through user interaction. Defaults to shade50. (optional)hovered- State when a target is being hovered. Defaults to shade50. (optional)selected- State when a target is selected, active, expanded, etc. Defaults to shade60. (optional)disabled- State when a target is disabled. Should override all previous states. Defaults to shade20. (optional)
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.
Contrast levels#
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.
Extending themes#
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.
Constraints#
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