Custom Theming

Kanoa MES is styled with standard Ignition Perspective themes, so you can brand and restyle your installation by creating your own theme. This page explains where Kanoa's styles live, why the Kanoa style classes look empty in the Designer, and how to create a custom theme that survives module updates.

Where Kanoa's Styles Live

All of Kanoa's styling is in its Perspective themes on the gateway: kanoa-light, kanoa-dark, and the color variants kanoa-light-forest, kanoa-light-firetruck, kanoa-light-grape and kanoa-light-orange. The themes define the color palette as CSS variables and contain the CSS rules for Kanoa's views and components.

The themes are stored in this folder on the gateway server:

Ignition version	Themes folder
8.1	<Ignition install>/data/modules/com.inductiveautomation.perspective/themes/
8.3	<Ignition install>/data/config/resources/core/com.inductiveautomation.perspective/themes/

The Perspective > Styles folder in the kanoaAPP project does not contain Kanoa's styles. See About the Kanoa Style Classes.

About the Kanoa Style Classes

The style classes in kanoaAPP under Perspective > Styles are stub classes. They are intentionally empty. Each stub only registers a class name so that you can pick it from the style class list in the Designer. The styles for those classes are defined in the Kanoa theme files.

This is why, when you override one of these style classes (or the stylesheet.css advanced stylesheet) in an inheriting project, the inherited value is blank. With most Ignition projects, an override starts from the inherited styles. With Kanoa, there are no styles in the project to inherit.

The stub classes are not intended to be overridden. To change how Kanoa looks, create a custom theme instead.

Create a Custom Theme

Create your own theme that starts from a Kanoa theme and overrides its variables. Your theme still picks up Kanoa's theme fixes when you update the module.

warning

Don't edit the Kanoa theme files. Module updates overwrite the themes that Kanoa ships, so your changes are eventually lost. Module updates never change themes with other names.

When you name your theme, avoid these names, which Kanoa reserves:

• Any name that starts with kanoa
• palette, common, app and base

1. On the gateway server, open the themes folder for your Ignition version. Use the Kanoa theme files there as a reference.

2. Create a new CSS file named after your theme, for example acme-light.css. Import the Kanoa theme that you want to start from, then override variables in a :root block:

   @import "./kanoa-light.css";
   
   :root {
     --kcPrimary: #0b5fa5;
     --kcOnPrimary: #ffffff;
     --kcBackground: #0b5fa5;
     --kcSurface: #f7f9fb;
   }

3. To make a dark version, create a second file that imports kanoa-dark.css. Include dark as a hyphen-separated word in the name, for example acme-dark.css. Some Kanoa components, such as toasts, use the theme name to decide whether a theme is dark.

   @import "./kanoa-dark.css";
   
   :root {
     --kcPrimary: #95ccff;
   }

4. Make the gateway load the new theme:

   • Ignition 8.1: no action is needed. The gateway picks up new and changed theme files automatically.
   • Ignition 8.3: trigger a file system scan from the gateway web page. You don't need to restart the gateway.

5. In the Designer, set session.props.theme to the name of your theme (the file name without .css), for example acme-light. To use the theme for every session, set it in the session props of each runnable project, such as kanoaMES.

tip

Change one variable at a time and refresh your session to see what it affects. Most Kanoa components use the semantic variables, such as --kcPrimary and --kcSurface, so a few overrides are usually enough to rebrand the whole application.

Theme Variables

These are the variables defined in kanoa-light. The kanoa-dark theme defines the same variables with dark values.

Semantic Colors

Most components use these variables. They are the ones to override for branding.

Each --kcOn... variable is the text and icon color to use on top of the matching background. For example, text on a --kcPrimary background uses --kcOnPrimary. If you change a background color, check that its --kcOn... color still has enough contrast.

Variable	Default (light)	Used for
--kcPrimary / --kcOnPrimary	#00639a / #ffffff	Primary brand color
--kcPrimaryContainer / --kcOnPrimaryContainer	#cde5ff / #001d32	Lighter primary areas
--kcSecondary / --kcOnSecondary	#51606f / #ffffff	Secondary accents
--kcSecondaryContainer / --kcOnSecondaryContainer	#d5e4f6 / #0e1d2a	Lighter secondary areas
--kcTertiary / --kcOnTertiary	#a04100 / #ffffff	Tertiary accents
--kcTertiaryContainer / --kcOnTertiaryContainer	#ffdbcc / #351000	Lighter tertiary areas
--kcError / --kcOnError	#ba1a1a / #ffffff	Errors
--kcErrorContainer / --kcOnErrorContainer	#ffdad6 / #410002	Error messages and highlights
--kcBackground / --kcOnBackground	#00639a / #ffffff	Application background behind views
--kcSurface / --kcOnSurface	#fcfcff / #1a1c1e	Cards, containers and popups
--kcSurfaceVariant / --kcOnSurfaceVariant	#dee3eb / #42474e	Nested containers and tooltips
--kcOutline	#72777f	Card borders
--kcOutlineVariant	#c2c7cf	Input and tooltip borders
--kcInverseSurface / --kcInverseOnSurface	#2f3033 / #f0f0f4	Elements that contrast with the surface
--kcInversePrimary	#95ccff	Primary color on an inverse surface
--kcSurfaceTint	#00639a	Tint applied to raised surfaces
--kcShadow, --kcScrim	#000000	Shadows and modal overlays

Status Colors

Variable	Default (light)	Used for
--kcGood / --kcGoodContainer / --kcOnGoodContainer	#00639a / #cde5ff / #001d32	Good status, for example in KPIs
--kcOK / --kcOKContainer / --kcOnOKContainer	#f1b400 / #ffdea0 / #261a00	Warning status
--kcBad / --kcBadContainer / --kcOnBadContainer	#ba1a1a / #ffdad6 / #410002	Bad status

Component Variables

These variables are set from the semantic colors. If you override a semantic color, these follow it. You can also override them directly to change one kind of component.

Variable	Default	Used for
--kcRootBackground	var(--kcBackground)	Root container background
--kcContainerBackground	var(--kcSurface)	View container background
--kcNestedBackground	var(--kcSurfaceVariant)	Containers nested in other containers
--kcDockBackground / --kcDockColor	var(--kcPrimary) / var(--kcOnPrimary)	Docked header and navigation
--kcDockBackgroundAccent / --kcDockColorAccent	var(--kcTertiary) / var(--kcOnTertiary)	Highlighted items in docks
--kcCardBackground	var(--kcSurface)	Card background
--kcCardBorder	var(--kcOutline)	Card border
--kcCardShadow	2px 2px 3px #88888844	Card and button shadow
--popupBackground	var(--kcSurface)	Popup background
--kcTooltipBackground / --kcTooltipColor / --kcTooltipBorder	var(--kcSurfaceVariant) / var(--kcOnSurfaceVariant) / var(--kcOutlineVariant)	Tooltips
--kcTooltipBackground-Error / --kcTooltipColor-Error / --kcTooltipBorder-Error	var(--kcErrorContainer) / var(--kcOnErrorContainer) / var(--kcOnError)	Error tooltips
--kcInputBorder	var(--kcOutlineVariant)	Input borders
--checkbox--checked	var(--kcPrimary)	Checked checkboxes

Buttons have their own variables for each variant. Each variant has a Background, Color and Border variable, for example --kcButton-GreenBackground, --kcButton-GreenColor and --kcButton-GreenBorder:

Variant	Default background
--kcButton-Default...	var(--kcGray-20)
--kcButton-Disabled...	var(--kcGray-30)
--kcButton-Green...	var(--kcGreen-40)
--kcButton-Red...	var(--kcRed-40)
--kcButton-Blue...	var(--kcBlue-40)

--kcButtonShadow sets the shadow for all buttons. It defaults to var(--kcCardShadow).

Chart Colors

Charts use --kcChart-01 to --kcChart-09 for series colors, in order. Override them to match your brand palette:

:root {
  --kcChart-01: #0b5fa5;
  --kcChart-02: #f96900;
  --kcChart-03: #f7b801;
}

Tonal Palettes

The theme also defines tonal palettes that you can use in your own styles:

Palette	Variables	Notes
Theme palettes	--kcPrimary-0 to --kcPrimary-100, and the same steps for --kcSecondary, --kcTertiary, --kcNeutral, --kcNeutralVariant and --kcError	Steps 0, 10, 20, 25, 30, 35, 40, 50, 60, 70, 80, 90, 95, 98, 99 and 100. 0 is black and 100 is white.
General colors	--kcRed-0 to --kcRed-100, and the same steps for --kcOrange, --kcYellow, --kcGreen, --kcBlue, --kcPurple and --kcPink	Steps of 10. 0 is white and 100 is black.
Grays	--kcGray-0 to --kcGray-100, plus --kcGray-05	--kcGrey-* is an alias with the British spelling.

note

The semantic colors are set to fixed values, not to the palette variables. If you override a palette, such as --kcPrimary-40, the semantic colors don't change. To rebrand, override the semantic colors, such as --kcPrimary, directly.

The theme also maps Ignition's standard --neutral-0 to --neutral-100 variables to the Kanoa neutral palette, so standard Perspective components match Kanoa's colors.

Add Your Own Style Classes

To style individual components in your own views, create your own style classes in your custom project, such as _client_custom_mes (see Install Modules). Use a folder name of your own so your classes are separate from the Kanoa stubs, for example acme/card-highlight.

Reference theme variables in your style classes rather than fixed colors, for example var(--kcPrimary). The class then works in both your light and your dark theme.

Use the Advanced Stylesheet

For CSS that you can't express with a theme variable or a style class, use your project's advanced stylesheet (Perspective > Styles > stylesheet.css in the Designer). The advanced stylesheet is for your own rules. Kanoa doesn't put any rules in it, so it is empty when you override it.

/* Applies to any component whose style.classes includes "my-header".
   Perspective adds the psc- prefix to class names in style.classes. */
.psc-my-header {
  min-height: 56px;
}

Rules in the advanced stylesheet apply to the project whatever theme is active. To give light and dark themes different values, define the values as variables in each theme and reference them from the stylesheet.

Component-Specific Styling

Some Kanoa components have their own styling options:

• Toasts: set the --kanoa-toast-* variables. See Styling Toasts.
• Calendar: apply style classes to individual parts of the calendar through its class properties. See Calendar.

Which Option Should I Use?

You want to...	Use
Change brand colors or chart colors everywhere	A custom theme
Use different colors in light and dark mode	Two custom themes, one importing each Kanoa theme
Change how a Kanoa view or component looks	A custom theme. Don't override the Kanoa stub classes.
Style components in your own views	Your own style classes
Add CSS rules for one project only	The advanced stylesheet in that project
Change toast colors	The --kanoa-toast-* variables