Themes

What is a theme?

In order to understand what a theme is, we need to understand first that the definition of colors, sizes, shapes... is an intrinsic part of a design system. Since these parameters are essential for guaranteeing accessibility and a good user experience, having the ability of changing them, might go frontally against the intentions of the design system.

This is precisely what themes are, just custom defined objects that allow users to override fundamental decisions of Halstack Design System. They are a way of escaping the restrictions imposed by the Design System, and using themes could result in applications not being compliant with the Halstack guidelines, or even introducing many different types of accessibility issues if not used carefully.

Typically, you would create a Halstack Design System application, and after that, only if there is a white-labeling requirement, we would apply a theme on top of the base application. This, and only this, is the whole purpose of using themes.

Different theming strategies

As explained in the previous section, themes are basically a list of properties that allow you to override fundamental decisions of the design system. Based on the amount of decisions that can be overridden, Halstack Design System has two different theming strategies which will be explained below:

Opinionated theme.
Advanced theme.

Opinionated Theme

This theming strategy lets you change some decisions of the design system, but is still opinionated about the ones we consider fundamental. The list of configurable properties is small, but it applies at the component level.

information

We strongly recommend using the opinionated theme generator to create the theme, but you can also create it yourself from scratch.

Either through the theme-generator or by creating it from scratch, you will have to build a theme containing as many objects as components you want to customize. The props of each component are a key-value pair where:

key: Corresponds to the 'Theme input' column of the tables that you can see in the Opinionated theme input list section.
value: The color, must be hexadecimal without alpha channel.

In the opinionated theme we must take into account that some of the colours that affect the component will be calculated based on the theme inputs of the component. As you can see as follows:

Opinionated theme inputs list

Tokens in the second column, which names are in bold, will have the value that results from applying the transformation indicated in brackets to the 'Theme input'. (If nothing, they will have the same value as the 'Theme input').

Theme inputs value must be hexadecimal without alpha channel.

Alert

Theme Input	Tokens (calculation)
Base color	`infoBackgroundColor`
Accent color	`infoIconColor` `infoBorderColor`
Overlay color	`overlayColor`

Accordion

Theme Input	Tokens (calculation)
Accent color	`arrowColor` `iconColor` `hoverBackgroundColor` (+57% of lightness)
Title font color	`titleLabelFontColor`
Assistive text font color	`assistiveTextFontColor`

Box

Theme Input	Tokens (calculation)
Base color	`backgroundColor`

Button

Theme Input	Tokens (calculation)
Base color	`primaryBackgroundColor` `secondaryFontColor` `secondaryBorderColor` `secondaryHoverBackgroundColor` `textFontColor` `primaryHoverBackgroundColor` (-8% of lightness) `primaryActiveBackgroundColor` (-18% of lightness) `secondaryActiveBackgroundColor` (-18% of lightness) `textHoverBackgroundColor` (+57% of lightness) `textActiveBackgroundColor` (+52% of lightness)
Primary font color	`primaryFontColor`
Secondary hover font color	`secondaryHoverFontColor`

Checkbox

Theme Input	Tokens (calculation)
Base color	`backgroundColorChecked` `borderColor` `hoverBackgroundColorChecked` (-15% of lightness) `hoverBorderColor` (-15% of lightness)
Check color	`checkColor`
Font color	`fontColor`

Chip

Theme Input	Tokens (calculation)
Base color	`backgroundColor`
Font color	`fontColor`
Icon color	`iconColor` `hoverIconColor` (+10% lightness) `activeIconColor` (+30% lightness)

Date Input

Theme Input	Tokens (calculation)
Base Color	`pickerSelectedBackgroundColor` `pickerCurrentYearFontColor` `pickerActiveBackgroundColor` (-8% of lightness) `pickerHeaderActiveBackgroundColor` (-8% of lightness) `pickerHoverBackgroundColor` (+52% lightness) `pickerCurrentDateBorderColor` (+42% lightness) `pickerHeaderHoverBackgroundColor` (+52% lightness)
Selected font color	`pickerSelectedFontColor` `pickerActiveFontColor` `pickerHeaderActiveFontColor`

Dialog

Theme Input	Tokens (calculation)
Base color	`backgroundColor`
Close icon color	`closeIconColor`
Overlay color	`overlayColor`

Theme Input	Tokens (calculation)
Base color	`buttonBackgroundColor` `hoverButtonBackgroundColor` (-5% of lightness) `activeButtonBackgroundColor` (-12% of lightness) `hoverOptionBackgroundColor` (-5% of lightness) `activeOptionBackgroundColor` (-20% of lightness)
Font color	`buttonFontColor` `buttonIconColor` `caretIconColor`
Option font color	`optionFontColor` `optionIconColor`

File input

Theme Input	Tokens (calculation)
Font color	`labelFontColor` `helperTextFontColor` `dropLabelFontColor` `fileNameFontColor`

Footer

Theme Input	Tokens (calculation)
Base color	`backgroundColor`
Font color	`bottomLinksFontColor` `copyrightFontColor` `socialLinksColor`
Accent color	`bottomLinksDividerColor`
Logo	`logo`

Header

Theme Input	Tokens (calculation)
Base color	`backgroundColor`
Accent color	`underlinedColor`
Font color	`hamburguerFontColor`
Menu base color	`menuBackgroundColor`
Hamburguer color	`hamburguerIconColor` `hamburguerHoverColor` (+90% of lightness)
Logo	`logo`
Logo responsive	`logoResponsive`
Content color	`contentColor`
Overlay color	`overlayColor`

Link

Theme Input	Tokens (calculation)
Base color	`visitedFontColor` `visitedUnderlineColor`

Nav tabs

Theme Input	Tokens (calculation)
Base color	`selectedFontColor` `unselectedFontColor` `selectedIconColor` `unselectedIconColor` `hoverBackgroundColor` (+55% of lightness) `pressedBackgroundColor` (+50% of lightness)
Accent color	`selectedUnderlineColor`

Paginator

Theme Input	Tokens (calculation)
Base color	`backgroundColor`
Font color	`fontColor`

Progress bar

Theme Input	Tokens (calculation)
Base color	`totalLineColor`
Accent color	`trackLineColor`
Font color	`labelFontColor` `valueFontColor` `helperTextFontColor`
Overlay color	`overlayColor`
Overlay font color	`overlayFontColor`

Quick Nav

Theme Input	Tokens (calculation)
Accent color	`hoverFontColor`
Font color	`fontColor`

Radio Group

Theme Input	Tokens (calculation)
Base color	`radioInputColor` `hoverRadioInputColor` (-10% lightness) `activeRadioInputColor` (-25% lightness)
Font color	`labelFontColor` `helperTextFontColor` `radioInputLabelFontColor`

Select

Theme Input	Tokens (calculation)
Selected option background color	`selectedListOptionBackgroundColor` `selectedHoverListOptionBackgroundColor` (-5% of lightness) `selectedActiveListOptionBackgroundColor` (-15% of lightness)
Font color	`valueFontColor` `labelFontColor` `helperTextFontColor` `placeholderFontColor` (+30% of lightness) `collapseIndicatorColor`
Option font color	`listOptionFontColor`
Hover border color	`hoverInputBorderColor`

Sidenav

Theme Input	Tokens (calculation)
Base color	`backgroundColor`

Slider

Theme Input	Tokens (calculation)
Base color	`thumbBackgroundColor` `focusThumbBackgroundColor` `tickBackgroundColor` `trackLineColor` `hoverThumbBackgroundColor` (-15% of lightness) `activeThumbBackgroundColor` (-15% of lightness)
Total line color	`totalLineColor`
Font color	`labelFontColor` `helperTextFontColor` `limitValuesFontColor`

Spinner

Theme Input	Tokens (calculation)
Base color	`totalCircleColor`
Accent color	`trackCircleColor`
Font color	`labelFontColor` `progressValueFontColor`
Overlay color	`trackCircleColorOverlay`
Overlay font color	`overlayLabelFontColor` `overlayProgressValueFontColor`

Switch

Theme Input	Tokens (calculation)
Checked base color	`checkedTrackBackgroundColor` `disabledCheckedTrackBackgroundColor` (+57% of lightness)
Font color	`labelFontColor`

Table

Theme Input	Tokens (calculation)
Base color	`headerBackgroundColor`
Header font color	`headerFontColor` `sortIconColor`
Cell font color	`dataFontColor`

Tabs

Theme Input	Tokens (calculation)
Base color	`selectedFontColor` `selectedIconColor` `selectedUnderlineColor` `focusOutline` `hoverBackgroundColor` (+57% of lightness) `pressedBackgroundColor` (+52% of lightness)

Theme Input	Tokens (calculation)
Font color	`fontColor`
Icon color	`iconColor`

Text input

Theme Input	Tokens (calculation)
Font color	`labelFontColor` `helperTextFontColor` `valueFontColor` `actionIconColor` `hoverActionIconColor` `focusActionIconColor` `activeActionIconColor` `suffixColor` (+40% of lightness) `prefixColor` (+40% of lightness) `placeholderFontColor` (+30% of lightness)
Hover border color	`hoverBorderColor`

Textarea

Theme Input	Tokens (calculation)
Font color	`labelFontColor` `helperTextFontColor` `valueFontColor` `placeholderFontColor` (+30% of lightness)
Hover border color	`hoverBorderColor`

Toggle group

Theme Input	Tokens (calculation)
Selected base color	`selectedBackgroundColor` `unselectedActiveBackgroundColor` `selectedHoverBackgroundColor` (-8% of lightness) `selectedActiveBackgroundColor` (-18% of lightness) `selectedDisabledBackgroundColor` (+57% of lightness) `selectedDisabledFontColor` (+42% of lightness)
Selected font color	`selectedFontColor`
Unselected base color	`unselectedBackgroundColor` `unselectedHoverBackgroundColor` (-10% of lightness)
Unselected font color	`unselectedFontColor`

Wizard

Theme Input	Tokens (calculation)
Base color	`selectedStepBackgroundColor` `selectedStepBorderColor`
Selected step font color	`selectedStepFontColor`
Font color	`visitedLabelFontColor` `selectedLabelFontColor` `visitedHelperTextFontColor` `selectedHelperTextFontColor` `unvisitedStepBorderColor` (+40% of lightness) `unvisitedStepFontColor` (+40% of lightness) `unvisitedLabelFontColor` (+40% of lightness) `unvisitedHelperTextFontColor` (+40% of lightness)

Example

Finally, here you can see an example of an opinionated theme object:

{
 "accordion": {
  "accentColor": "#1b75bb",
  "fontColor": "#666666"
 },
 "button": {
  "baseColor": "#1b75bb",
  "primaryFontColor": "#ffffff",
  "secondaryHoverFontColor": "#ffffff"
 },
 "checkbox": {
  "baseColor": "#1b75bb",
  "checkColor": "#000000",
  "fontColor": "#000000"
 },
 "chip": {
  "baseColor": "#e6e6e6",
  "fontColor": "#000000"
 },
 "dateInput": {
  "selectedDateBackgroundColor": "#1b75bb",
  "selectedDateFontColor": "#ffffff"
 },
 "dropdown": {
  "baseColor": "#ffffff",
  "fontColor": "#000000",
  "optionFontColor": "#000000"
 },
 "fileInput": {
  "fontColor": "#000000"
 },
 "footer": {
  "baseColor": "#1b75bb",
  "fontColor": "#ffffff",
  "accentColor": "#0095ff",
  "logo": "https://assure.proxy.lambda/image/image_1674206626901.jpg"
 },
 "header": {
  "baseColor": "#ffffff",
  "accentColor": "#000000",
  "fontColor": "#000000",
  "menuBaseColor": "#ffffff",
  "hamburguerColor": "#000000",
  "logo": "https://assure.proxy.lambda/image/image_1674206652560.jpg",
  "logoResponsive": "https://assure.proxy.lambda/image/image_1674206660896.jpg",
  "contentColor": "#000000"
 },
 "paginator": {
  "baseColor": "#eeeeee",
  "fontColor": "#000000"
 },
 "progressBar": {
  "accentColor": "#8bc53f",
  "baseColor": "#cecece",
  "fontColor": "#000000"
 },
 "quickNav": {
  "fontColor": "#666666",
  "accentColor": "#1b75bb"
 },
 "radioGroup": {
  "baseColor": "#000000",
  "fontColor": "#000000"
 },
 "select": {
  "selectedOptionBackgroundColor": "#d9d9d9",
  "fontColor": "#000000",
  "optionFontColor": "#000000"
 },
 "sidenav": {
  "baseColor": "#F2F2F2"
 },
 "slider": {
  "baseColor": "#0067b3",
  "fontColor": "#000000"
 },
 "spinner": {
  "accentColor": "#8bc53f",
  "baseColor": "#ffffff",
  "fontColor": "#000000"
 },
 "switch": {
  "checkedBaseColor": "#1b75bb",
  "fontColor": "#000000"
 },
 "table": {
  "baseColor": "#f2f7f6",
  "headerFontColor": "#000000",
  "cellFontColor": "#000000"
 },
 "tabs": {
  "baseColor": "#1b75bb"
 },
 "textInput": {
  "fontColor": "#000000"
 },
 "toggleGroup": {
  "selectedBaseColor": "#8bc53f",
  "selectedFontColor": "#ffffff",
  "unselectedBaseColor": "#e6e6e6",
  "unselectedFontColor": "#808285"
 },
 "wizard": {
  "baseColor": "#1b75bb",
  "fontColor": "#000000",
  "selectedFontColor": "#ffffff"
 }
}

More examples can be found in the Halstack Provider section.

Advanced Theme

This theming strategy lets you change most of the design decisions of the design system (all the design tokens), trying to be as little opinionated as possible. Have in mind that it is impossible to make the components 100% configurable without writing actual code, since some design decisions are structural to the component. The list of configurable properties is large, and it applies at the component level.