Skip to Content
Product Information
Author's profile photo Dominik Schreiber

Contrast scoping in Belize and Belize Deep

ui5.sap.com%20with%20all%20themes%20of%20the%20Belize%20family%20applied%3A%20High%20Contrast%20White%2C%20Belize%2C%20High%20Contrast%20Black%20and%20Belize%20Deep

ui5.sap.com with all themes of the Belize family applied: High Contrast White, Belize, High Contrast Black and Belize Deep

The Belize theme was the first evolution for initially Bluecrystal-themed SAP Fiori applications. It was also the first theme that came as a whole family:

  • Belize the default version,
  • Belize Deep a variation with more dark (“deep”) parts, and
  • High Contrast Black and High Contrast White based on the Belize metrics.

For me personally, writing about Belize creates all sorts of flashbacks: the first major project I was part of at SAP was implementing Belize for classic UIs (applications built with SAP GUI for HTML and Web Dynpro for ABAP, i.e. with application frameworks based on Unified Rendering).

This blog post lays out

  • how the light and dark parts of Belize and Belize Deep were achieved technically with contrast scoping, and
  • why there are the labels Belize and Belize Deep but the technical ids sap_belize and sap_belize_plus (and why sap_belize_plus somehow is the “odd uncle” of the family).

Contrast Scoping

SAPUI5%20Shopping%20Cart%20demo%20app%20in%20Belize%20and%20Belize%20with%20the%20dark%20contrast%20scope

SAPUI5 Shopping Cart demo app in Belize and Belize with the dark contrast scope

The vision for light and dark parts in Belize and Belize Deep was that applications should be light by default but have the possibility to mark dark areas as they wish. The guidance to applications was to make Belize “more light” and Belize Deep “more dark” (i.e. mark less or more areas as dark).

This brought the restriction that each and every control/component could possibly end up in a light or dark area. So two whole sets of theme specifications had to be created: one for light and one for dark.

We gave those two sets the technical ids sap_belize (for the light set of parameters) and sap_belize_plus (for the dark set of parameters).

But from a customer perspective, he would select the theme Belize (more light) or Belize Deep (more dark). And both would have to contain the light set of parameters as well as the dark set of parameters.

To achieve this, we came up with contrast scoping: we

  • compile the CSS for the complete light set of parameters (sap_belize) and the complete dark set of parameters (sap_belize_plus),
  • compute the difference between both CSS files on a per-selector basis, and
  • append the resulting diff to the CSS of the light set of parameters by adding a CSS class (called “scope class”) to each selector.
/* ===== compiled CSS ====================== */
/* sap_belize */
button {
  min-width: 3rem;
  background-color: #f7f7f7;
  color: #346187;
}
/* sap_belize_plus */
button {
  min-width: 3rem; /* same as sap_belize */
  background-color: #435667;
  color: #cae4fb;
}
/* ===== combined CSS ====================== */
button {
  min-width: 3rem;
  background-color: #f7f7f7;
  color: #346187;
}
.sapContrast button,
button.sapContrast {
  background-color: #435667;
  color: #cae4fb;
}

The only difference between Belize and Belize Deep is actually the name of this “scope class”: it is sapContrast in Belize and sapContrastPlus in Belize Deep. This allows applications to mark dark areas for Belize (by adding the sapContrast class to the HTML) different from Belize Plus (where they add the sapContrastPlus class):

<div><!-- light in Belize and Belize Deep --></div>
<div class="sapContrast"><!-- dark in Belize, light in Belize Deep --></div>
<div class="sapContrastPlus"><!-- light in Belize, dark in Belize Deep --></div>
<div class="sapContrast sapContrastPlus"><!-- dark in Belize and Belize Deep --></div>

Technically this is achieved by mCssScopes in the .theming file (which is a configuration file for the theming-engine that compiles SAP- and custom themes).

Belize, Belize Deep, sap_belize and sap_belize_plus

Belize and Belize Deep are both light themes that just have a more or less prominent dark part, sap_belize is always light and sap_belize_plus is always dark, but when you select the Belize Deep theme, the actual sap-theme is set to sap_belize_plus. Confusion intensifies.

This is because we needed two themes the customer can select between, and we already had two themes (the light and the dark version), so it was decided to use sap_belize (the light part) as the base for compiling the Belize Deep CSS and scope the sap_belize_plus part itself into the CSS under the sapContrastPlus scope.

We regret this decision, as we regret the whole concept of scoping multiple themes into each other. It is an endless source of confusion and the oddest kinds of bugs. That’s why we dropped the “light and dark areas” concept with Quartz (the next evolution step) and just have a Quartz Light and a Quartz Dark version.

Oh-my-theme-scoping!

So in the Belize family we have

  • sap_belize, the technical id of the light parameter set,
  • sap_belize_plus, the technical id of the dark parameter set,
  • Belize, the “more light” theme (selected by ?sap-theme=sap_belize) where the dark part is available under the sapContrast scope, and
  • Belize Deep, the “more dark” theme (selected by ?sap-theme=sap_belize_plus) where the dark part is available under the sapContrastPlus scope.

Have you used Belize or Belize Deep and ever wondered why there are those sapContrast and sapContrastPlus scopes in the CSS? Have you used those scopes in your application, for what and why? I’d like to get into a discussion about that in the comments!

Assigned Tags

      Be the first to leave a comment
      You must be Logged on to comment or reply to a post.