Tableau UI for Angular

Theming

The theme service sets the colour mode and the font size; CSS custom properties set the rest.

Start the theme

Call ThemeService.initialize() once, when the app starts. It applies the stored theme, follows the system's mode, and stores each change. Until then the page stays light at the default size; on the server it does nothing. This is the docs site's own app.config.ts:

import type { ApplicationConfig } from '@angular/core';
import { inject, provideAppInitializer, provideZonelessChangeDetection } from '@angular/core';
import { provideRouter } from '@angular/router';
import { ThemeService } from 'tableau-ui-angular/theme';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideZonelessChangeDetection(),
    provideRouter(routes),
    // Applies the stored theme before the first render, and keeps it applied; on the server it does nothing
    provideAppInitializer(() => {
      inject(ThemeService).initialize();
    }),
  ],
};

Dark mode and font size

setColorMode() takes light, dark or auto, which follows the system; the service puts the dark-mode class on the root element and the body. setFontSize() sets the base size, which the library's other sizes follow, and reset() goes back to the default. $theme and $appliedThemeMode give the current choice as signals, and theme$ and appliedThemeMode$ as observables.

Colour mode
px

Showing the light mode at 12px. The choice is stored in the browser for the next visit.

import { ChangeDetectionStrategy, Component, computed, inject } from '@angular/core';
import { TableauUiButtonModule } from 'tableau-ui-angular/button';
import { TableauUiButtonToggleModule } from 'tableau-ui-angular/button-toggle';
import { TableauUiCommonModule } from 'tableau-ui-angular/common';
import { TableauUiFormFieldModule } from 'tableau-ui-angular/form-field';
import { ThemeService } from 'tableau-ui-angular/theme';

@Component({
  selector: 'app-theme-switcher-example',
  imports: [TableauUiButtonModule, TableauUiButtonToggleModule, TableauUiCommonModule, TableauUiFormFieldModule],
  templateUrl: './theme-switcher.example.html',
  styleUrl: './theme-switcher.example.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ThemeSwitcherExampleComponent {
  protected readonly theme = inject(ThemeService);

  protected readonly $mode = computed(() => this.theme.$theme().mode);
  protected readonly $fontSize = computed(() => parseInt(this.theme.$theme().fontSize, 10));

  // 'auto' follows the system's mode, and $appliedThemeMode says which one shows
  protected setMode(mode: 'auto' | 'dark' | 'light' | undefined) {
    if (mode) {
      this.theme.setColorMode(mode);
    }
  }

  // The base size, in --twc-font-size-body; the library's other sizes are relative to it
  protected setFontSize(event: Event) {
    const size = Number((event.target as HTMLInputElement).value);
    if (size >= 10 && size <= 24) {
      this.theme.setFontSize(`${size}px`);
    }
  }
}

CSS custom properties

Every colour, font and size is a custom property, set on :root and, for dark mode, on :root.dark-mode, body.dark-mode, since the theme service puts the class on both. Set one on an element to change it inside that element, or on those selectors in styles.scss to change it for the app: a colour set on :root.dark-mode alone stops at the body, which has its own.

The theme's
Overridden here
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { TableauUiButtonModule } from 'tableau-ui-angular/button';
import { TableauUiCheckboxModule } from 'tableau-ui-angular/checkbox';

@Component({
  selector: 'app-theme-override-example',
  imports: [TableauUiButtonModule, TableauUiCheckboxModule],
  templateUrl: './theme-override.example.html',
  styleUrl: './theme-override.example.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ThemeOverrideExampleComponent {}

Colours

PropertyNowLightDark
--twc-color-basergb(255 255 255)rgb(27, 27, 27)
--twc-color-base-highlightrgb(250 250 250)rgb(30 30 30)
--twc-color-textrgb(0 0 0 / 80%)rgb(255 255 255 / 87%)
--twc-color-text-strongrgb(0 0 0 / 100%)rgb(255 255 255)
--twc-color-text-lightrgb(102 102 102)rgb(180 180 180)
--twc-color-linkrgb(26 105 158)rgb(98, 137, 163)
--twc-color-primary-r55
--twc-color-primary-g9898
--twc-color-primary-b138138
--twc-color-primaryrgb(var(--twc-color-primary-r), var(--twc-color-primary-g), var(--twc-color-primary-b))rgb(var(--twc-color-primary-r), var(--twc-color-primary-g), var(--twc-color-primary-b))
--twc-color-primary-lightrgb(207 233 254)rgb(27, 48, 68)
--twc-color-primary-darkrgb(2 50 72)rgb(14, 151, 209)
--twc-color-on-primaryrgb(234 245 254)rgb(226, 226, 226)
--twc-color-primary-on-basevar(--twc-color-primary)rgb(80 185 230)
--twc-color-errorrgb(190 10 30)rgb(255 133 133)
--twc-color-error-darkrgb(100 1 3)rgb(211, 122, 122)
--twc-color-error-lightrgb(255 203 203)rgb(100 1 3)
--twc-color-successrgb(0 128 0)rgb(58, 167, 58)
--twc-color-success-lightrgb(212 248 212)rgb(29, 87, 29)
--twc-color-disabledrgb(205 205 205)rgb(90 90 90)
--twc-color-text-grayrgb(145 145 145)rgb(130 130 130)
--twc-color-highlightrgb(220 220 220)rgb(60 60 60)
--twc-color-mouse-highlightrgb(235 235 235)rgb(41, 40, 40)
--twc-color-border-lightrgb(203 203 203)rgb(70 70 70)
--twc-color-borderrgb(116 116 116)rgb(100 100 100)
--twc-color-border-darkrgb(46 46 46)rgb(140 140 140)
--twc-color-border-dark-disabledrgb(174 174 174)rgb(80 80 80)
--twc-color-focused-inputrgb(10 91 171)rgb(60 130 200)
--twc-tab-color-active-underlinergb(92 92 92)rgb(160 160 160)
--twc-tab-color-inactive-underlinergb(230 230 230)rgb(50 50 50)
--twc-modal-color-headerrgb(243 243 243)rgb(40 40 40)
--twc-modal-color-box-shadowrgba(0, 0, 0, 0.35)rgba(112, 112, 112, 0.35)
--twc-modal-color-backdroprgb(245, 245, 245, 0.33)rgba(31, 31, 31, 0.644)
--twc-dialog-box-shadow0 2px 16px 0 rgb(46 46 46 / 15%)0 2px 16px 0 rgba(77, 77, 77, 0.4)

Fonts, sizes, menus and inputs

PropertyDefault
--twc-font-family'Benton Sans', 'Roboto', arial, helvetica, sans-serif
--twc-low-dpi-font-family'Benton Sans Low-DPI', 'Roboto', arial, helvetica, sans-serif
--twc-font-size-body12px
--twc-font-size-body-large1.1em
--twc-font-size-subtitle1.3em
--twc-font-size-title1.4em
--twc-font-size-page-title1.6em
--twc-menu-border-radius1px
--twc-input-border-radius1px
--twc-menu-highlight-outline1px solid var(--twc-color-text-gray)
--twc-menu-highlight-outline-offset-1px
--twc-menu-selected-background-colorrgb(var(--twc-color-primary-r) var(--twc-color-primary-g) var(--twc-color-primary-b) / 10%)
--twc-menu-selected-outline1px solid var(--twc-color-primary-on-base)
--twc-menu-selected-outline-offset-1px
--twc-input-border1px solid var(--twc-color-border)

Accessibility

Error text, the primary drawn as text, an icon, a border or the checkbox's and the radio button's focus rings, and the error and primary buttons' labels read at 4.5:1 or more, the contrast WCAG asks of body text and more than the 3:1 it asks of borders and rings, on every surface the library draws them on, at rest and under the pointer, in light and in dark. A spec in the library reads each pair below in both themes, in Chromium and Firefox.

ColourBackgroundWhere
--twc-color-error--twc-color-baseError text on the page, a dialog's body or an input; a stroked error button's label
--twc-color-error--twc-color-primary-lightError text on a table's selected row
--twc-color-error--twc-color-highlightError text on the keyboard highlight in a list, a select, an autocomplete or a menu
--twc-color-error--twc-modal-color-headerError text on a modal's header
--twc-color-error--twc-color-mouse-highlightA stroked error button's label under the pointer
--twc-color-base--twc-color-errorA raised error button's label
--twc-color-base--twc-color-error-darkA raised error button's label under the pointer
--twc-color-primary-on-base--twc-color-basePrimary text and icons on the page, a dialog or a menu; a stroked primary button's label and border; a checkbox's and a radio button's focus ring, a selected option's outline, a column's resize line
--twc-color-primary-on-base--twc-color-mouse-highlightA stroked primary button's label and border under the pointer
--twc-color-primary-on-base--twc-color-highlightA primary menu item on the highlight; a selected option's outline on the keyboard highlight
--twc-color-primary-on-base--twc-color-primary-lightAn info snack's icon, border and timer; a primary icon on a table's selected row
--twc-color-primary-on-base--twc-modal-color-headerPrimary text or an icon on a modal's header
--twc-color-on-primary--twc-color-primaryA raised primary button's label; a checked button toggle option's label
--twc-color-base--twc-color-primary-darkA raised primary button's label under the pointer

For its own error text, such as a negative number, an app reads var(--twc-color-error) rather than copying the value, so the text follows the theme. Text an app puts on --twc-color-error, such as a count badge, takes --twc-color-base, as the raised error button now does: a light text there reads below 4.5:1 on the dark theme's red. An app that sets one of these colours keeps each pair at 4.5:1, --twc-color-base on --twc-color-error included.

The library draws the primary on the page's surfaces, as text, icons, a stroked button, the checkbox's and the radio button's focus rings or a selected option's outline, in --twc-color-primary-on-base. In light it is --twc-color-primary itself; in dark, where the primary is 2.56:1 on the base, it is a lighter blue. Fills keep --twc-color-primary under --twc-color-on-primary, and a raised primary button's label under the pointer takes --twc-color-base. An app that sets --twc-color-primary sets --twc-color-primary-on-base beside it, at 4.5:1 on --twc-color-base, --twc-color-mouse-highlight and --twc-color-highlight, as the green row of the sample above does: in dark always, on :root.dark-mode, body.dark-mode, and in light wherever it isn't :root, since on :root the light one follows it by itself. An app that sets --twc-color-primary-dark keeps --twc-color-base on it at 4.5:1; --twc-color-on-primary colours the raised label at rest only.