pre-released

Integrate Branding

 

Foreword

It is possible to customize the look of the application (colors, buttons radius, fonts, price format) as well as the logo by editing and uploading two files: style.jsonc and logo.png.

Introduction to the Settings Files

style.jsonc

This file contains the list of all customizable style properties. Note that it doesn't need to inform them all, just the ones to customize are enough, the other ones will be automatically set to the default values.

This is a jsonc format, which is a usual JSON format with javascript-style comments allowed.

The top-level of this object contains 3 root attributes: "colors", "variables" and "rules".

{
  "colors": {},
  "variables": {},
  "rules": {}
}
  1. colors object
"colors": {
    /*  BRAND COLORS
        primary color set */
    "primary-default": "#006699",
    "primary-active": "#333366",
    /*  alt- color set */
    "alt-default": "#08a67f",
    "alt-active": "#06926f",
    /*  secondary- color set */
    "secondary-default": "#eeeeee",
    "secondary-active": "#b6b6b6",

    /*  TEXT COLORS 
        primary- color set */
    "txt-primary-default": "#ffffff",
    "txt-primary-active": "#ffffff",
    /*  alt- color set */
    "txt-alt-default": "#ffffff",
    "txt-alt-active": "#ffffff",
    /*  secondary- color set */
    "txt-secondary-default": "#222222",
    "txt-secondary-active": "#222222",

    /*  LINK COLORS
        primary- color set */
    "link-primary-default": "#006699",
    "link-primary-active": "#333366",
    /*  secondary- color set */
    "link-alt-default": "#08a67f",
    "link-alt-active": "#06926f",

    /* ! --------------------------------------- EVENT COLORS --------------------------------------------
    /*  MESSAGE 
        event- color set */
    "event-success": "#1a88ab",
    "event-error": "#ae2b34",
    "event-info": "#eeeeee",
    "event-tip": "#1a88ab",
    /*   txt-event- color set */
    "txt-event-success": "#ffffff",
    "txt-event-error": "#ffffff",
    "txt-event-info": "#212121",
    "txt-event-tip": "#ffffff",

    /* ! --------------------------------------- CTA COLORS --------------------------------------------
    //   the 1px wide border is part of the total CTA height calculation
    // - If an outline button is wanted, please add "transparent" as the background color value.
    // - If an icon is present in the CTA (cta-primary-icon f.e.), the icon will have the same colors as the text
        primary cta- color set */
    "cta-primary-background-default": "#006699" /*  this value can be "transparent" */,
    "cta-primary-background-active": "#333366" /*  this value can be "transparent" */,
    "cta-primary-border-default": "#006699",
    "cta-primary-border-active": "#333366",
    "cta-primary-txt-default": "#ffffff",
    "cta-primary-txt-active": "#ffffff",
    /*  alt cta- color set */
    "cta-alt-background-default": "#08a67f" /*  this value can be "transparent" */,
    "cta-alt-background-active": "#06926f" /*  this value can be "transparent" */,
    "cta-alt-border-default": "#08a67f",
    "cta-alt-border-active": "#06926f",
    "cta-alt-txt-default": "#ffffff",
    "cta-alt-txt-active": "#ffffff",
    /*  secondary cta- color set */
    "cta-secondary-background-default": "#eeeeee" /*  this value can be "transparent" */,
    "cta-secondary-background-active": "#b6b6b6" /*  this value can be "transparent" */,
    "cta-secondary-border-default": "#eeeeee",
    "cta-secondary-border-active": "#b6b6b6",
    "cta-secondary-txt-default": "#222222",
    "cta-secondary-txt-active": "#222222"
  }

These variables define the colors of each customizable UI elements.

Default values are formatted as hexadecimal values: "#rrggbb", 2 hexadecimal digits (0-9+a-f) for each primary color red, green, blue, though it is also possible to format them as "rgb(R, G, B)" where R, G and B are numbers between 0 and 255. In the end, it will all be converted to R, G, B format in the loaded css. Note that keyword "transparent" is also allowed, though only for "CTA background" variables.

For more details about the targeted UI element of each of these variables, please refer to the Global Colors section below.

  1. variables object
"variables": {
    /*  CTA CUSTOMIZATION
        primary CTA font weight - default: "bold" */
    "brand-font-weight-cta-l-primary": "bold",
    /*  alt CTA font weight - default: "bold" */
    "brand-font-weight-cta-l-alt": "bold",
    /*  secondary CTA font weight - default: "normal" */
    "brand-font-weight-cta-l-secondary": "normal",
    /*  CTA RADIUS */
    "brand-radius-cta": "2px",

    /* ! --------------------------------------- FONTS --------------------------------------------*/
    /*  font family - default: "Helvetica, Arial, \"Bitstream Vera Sans\", sans-serif" */
    "font-family": "Helvetica, Arial, \"Bitstream Vera Sans\", sans-serif"
  }

These variables define the font family, font weight as well as the border radius of each customizable texts and buttons.

Possible values for weight are the common ones allowed in css, see https://htmldog.com/references/css/properties/font-weight/ Radius is defined in pixel. Possible values for fonts are described in the Family section below.

For more details about the targeted UI element of each of these variables, please refer to the Fonts section below.

  1. rules object
"rules": {
    /* ! --------------------------------------- PRICING CUSTOMIZATION - optional --------------------------------------------*/
    /*   CASE 1: normal price
    /*   standard pricing style for .standard-price */
    "standard-price": [],
    /* ! -----------------------------------------------------------------------------------*/
    /*   CASE 2: membership price
    /*   membership pricing style for .standard-price */
    /*   This setting manages the display of the standard price indicated below the membership price. */
    "membership-standard-price": [],

    /*   membership pricing style for .membership-price */
    /*   This setting overwrites the display of the value of the membership price defined in membership-standard-price-label-branding. */
    "membership-price": [
        "color: #ff9d1a"
    ],

    /*   membership pricing style for .membership-price-label */
    /*   This setting manages the display of both label and value of the membership price. */
    "membership-price-label": [
        "color: #212121"
    ],

    /* ! -----------------------------------------------------------------------------------*/
    /*   CASE 3: reduced price
    /*   reduced pricing style for .standard-price */
    "reduced-standard-price": [
        "position: relative",
        "text-decoration: none"
    ],

    "reduced-standard-price-after": [
      "background-image: url(\"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHN0eWxlPSJ3aWR0aDogMTAwJTsgaGVpZ2h0OiAxMDAlOyI+PGxpbmUgeDE9IjAiIHkxPSIxMDAlIiB4Mj0iMTAwJSIgeTI9IjAiIHN0eWxlPSJzdHJva2U6cmdiKDE5OSw3Miw4NSk7IHN0cm9rZS13aWR0aDoxIi8+PC9zdmc+\")",
      "content: \"\"",
      "display: block",
      "height: 100%",
      "left: 0",
      "position: absolute",
      "top: 0",
      "width: 100%"
    ],

    "reduced-standard-price-printable": [],

    "reduced-standard-price-printable-after": [],

    /*   reduced pricing style for .reduced-price */
    "reduced-price": []
  }

These variables define the colors and layout of each customizable price elements.

Allowed values are the same as those commonly allowed by CSS standards. Note that the hexadecimal color values of this category won't be converted in a R, G, B format.

For more details about the targeted UI element of each of these variables, please refer to the Pricing Override section below.

Validation

This style.jsonc file will be validated as application page loads. If it contains any syntax error, unauthaurized variable name or wrongly formatted values, it will be dismissed with console errors/warnings and no customized css will be loaded in the application page, so be careful to properly edit this file before uploading it.

Common errors:

  1. Wrong json syntax (missing closing "}" for instance) -> solution: validate the JSON object with a free online JSON validator such as https://jsonlint.com/. It also necessary to remove comments before validation (jsonc not supported).

  2. Non existing variable name. -> solution: make sure all variable names belong to the lists mentioned above.

  3. Wrong formatted value. -> solution: make sure all values belong to the expected ones, e.g. colors should be either #rrggbb or rgb(R,G,B).

logo.png

This file is the logo that will be displayed at the top left end corner of the application.

It must be a PNG format file, ideally of size 200x80 pixels, though it could be smaller or larger but keeping the same ratio will ensure a nice looking layout.

Uploading the Settings Files

Once both style.jsonc and logo.png files are created, it is necessary to upload them on the ByMe platform in order for the application to process them at launch. For each asset to upload in our platform there is a succession of 3 network calls to make, that are documented below.

NOTE : The following procedure is for a specific environment. These steps should be followed on every environments based on the target (staging, main, etc.).

  1. Get a temporary bucket access

The first step is to retrieve a temporary access to the upload bucket. The corresponding call is one of our web services: POST storages/presigned/post/aws. For more details, see documentation here.

It is necessary to provide a key parameter. Need to choose the name, and it doesn't need to have an extension. We advise to use a UUID generator to have a different key each time, but it is also fine to reuse always the same key.

The response of this web-service is in the following form:

{
  "url": "string",
  "fields": {
    "key": "string",
    "bucket": "string",
    "X-Amz-Algorithm": "string",
    "X-Amz-Credential": "string",
    "X-Amz-Date": "string",
    "Policy": "string",
    "X-Amz-Signature": "string"
  }
}

It contains all the necessary information in order to upload the asset on the temporary bucket. For the context of this documentation, let's call this return object tmpBucketResponse

  1. Upload the asset on the temporary bucket

The second call to perform is not a ByMe web-service, but an AWS upload call. Refer to Amazon documentation for a detailed explanation of how to do this.

Need to do a POST call to tmpBucketResponse.url. The body of the request must contain the following fields in a form-data:

key                ⮞ tmpBucketResponse.fields.key
acl                ⮞ "private" or "public-read". If we indicated an acl value in the first call, it must be the same here.
bucket             ⮞ tmpBucketResponse.fields.bucket
X-Amz-Credential   ⮞ tmpBucketResponse.fields.X-Amz-Credential
X-Amz-Algorithm    ⮞ tmpBucketResponse.fields.X-Amz-Algorithm
X-Amz-Date         ⮞ tmpBucketResponse.fields.X-Amz-Date
X-Amz-Signature    ⮞ tmpBucketResponse.fields.X-Amz-Signature
policy             ⮞ tmpBucketResponse.fields.policy
file               ⮞ the file asset to upload. The value given is of type File.

⚠️ Make sure that the "file" attribute is always the last in the form. The reason is that all elements placed after this "file" attribute are ignored.

Fore more details about how to send a request containing a form-data, refer to this MDN resource.

  1. Copy the settings files to the right place

Now that the asset is uploaded on the temporary bucket, the last step is to copy it to the main bucket. This last step is a call to one of these two web services:

  • POST applications/{applicationID}/assets/{path}
  • POST applicationdistributions/{distributionID}/assets/{path}

Notes:

  • applicationID is the application ID to target. Using the first web-service will target the application level.
  • distributionID is the application distribution ID to target. Using the second web-service will target the application-distribution level.
  • At runtime, when launching the planner, the application-distribution asset is used in priority, and we use the application asset as a fallback.
  • path is the path on the main bucket where the asset will be copied. here are the correct values to use for this path parameter:
logo filestyle file
branding%2Flogo.pngbranding%2Fstyle.jsonc

The formatting is not a mistake here, need to write "%2F" and not "/".

⚠️ Be very careful with the value of this "path" parameter. It is necessary to use exclusively those 2 values. You take the risk of overwritting another asset by using another path.

This web-service call must contain the following body:

{
    "tmpUploadKey" : "string"
}

The value of tmpUploadKey must be the generated temporary key. In other words, we need to put the value of tmpBucketResponse.fields.key.

CSS impact on the UI

The JSON file will be converted to a CSS file, which contains all the customizable branding settings in the application. The following documentation will detail how each setting impacts the UI.

Note: the hexadecimal codes and screenshots used in this documentation are based on the default Core theme. These are the fallback settings if no branding file is provided.

Global Colors

Branding Colors

Primary and alt colors are the brand's identity colors. Primary and alt can be similar, but we recommend that the secondary color be different (more neutral, eg. a light grey).

Primary

$brand-clr-primary-default: #006699;
$brand-clr-primary-active: #333366;

The primary color is used in multiple places in the UI (default and active state):

Focused input border color Focused input

Checkboxes background Checkboxes background

Radio buttons Radio buttons

Focused select box (dropdown menu) border Focused select box

Icon button's icon on hover, focus, selected state Icon button's icon

Icon and label button's text and icon on hover, focus, selected state Icon and label button's

Label button's text on hover + label button's background on focus and selected state Label button's text on hover

Checked toggle buttons background Checked toggle buttons background

Button text's text Button text's text

Arrow button's text on active state Arrow button's text

Tab button's background on selected state Tab button's background

Nav button's text on hover Nav button's text

Catalog browser's product cards border on hover and selected state Catalog browser's product cards

Room shape's selected state Room shape's selected state

Sun position's circle Sun position's circle

Sun inclination half circle Sun inclination half circle

Viewpoint's slider track and handle + viewpoint label's background Viewpoint's slider

Alt

$brand-clr-alt-default: #08A67F;
$brand-clr-alt-active: #06926F;

The alt color is used in the navigation. Brands can choose to use the same color for primary and alt variables; if so, there will be no difference for the navigation color.

Navigation button's background on focus and selected state

Navigation Button

Secondary

$brand-clr-secondary-default: #eee;
$brand-clr-secondary-active: #b6b6b6;

The secondary color is used in multiple places in the UI (default and active state):

Icon button with background's background color and border color

Icon with background color

Tab button's background color in default state

Tab button

Header Colors

$brand-clr-header-border-bottom: #08a67f;
$brand-clr-header-title-idle: #212121;
$brand-clr-header-title-hover: #08a67f;
$brand-clr-header-title-disable: #cbcbcb;
$brand-clr-header-title-active: #08a67f;
$brand-clr-header-hamburger-hover: #bbbbbb;

Header colors are used to set colors for the header of the application.

Header

Branding Text Colors

The branding text colors are used whenever we need to add text above a background with a branding color. Readability is the main concern here. There are 2 states, that match the background color's states: default and active.

Primary A text in $brand-clr-txt-primary-default must be readable on a $brand-clr-primary-default background.
A text in $brand-clr-txt-primary-active must be readable on a $brand-clr-primary-active background.

Alt A text in $brand-clr-txt-alt-default must be readable on a $brand-clr-alt-default background.
A text in $brand-clr-txt-alt-active must be readable on a $brand-clr-alt-active background.

Secondary A text in $brand-clr-txt-secondary-default must be readable on a $brand-clr-secondary-default background.
A text in $brand-clr-txt-secondary-active must be readable on a $brand-clr-secondary-active background.

Link Colors

The link colors are used to style href links. There are no href links in the Bathroom application, therefore the links settings are not used.

Event Colors

The event colors include 4 types: info, success, error and tip. They are used to provide user feedbacks on UI elements, such as: notifications (informative notifications, success notifications, error notifications); recommendations, warnings or tips in the help center; input errors, etc.

Colors

Success

$brand-clr-event-success: #1a88ab;

The event success color is used on success notification's background. Success notification

Error

$brand-clr-event-error: #ae2b34;

The event error color is used in multiple places in the UI:

Input's border and input error message when there is an error in a field (input or text area): Input border and error message

Help center's error counter's background: Help center count

Help center's expired product's or warning's section icon: Help center warning icons

Help center's expired products or warnings card title: Help center cards

Error notification's background: Error notification

Info

$brand-clr-event-info: #eeeeee;

The event info color is used on info notification's background.

Event info color

Tip

$brand-clr-event-tip: #1a88ab;

The event tip color is used in the help center:

Help center's recommendation's section icon: Help Center recommendation

Help center's recommendation's card title: Help Center recommendation card title

Help center's tool tips' title and icon: Help Center tool tips

Text Colors

The event text colors are used whenever we need to add text above a background with an event color. Readability is the main concern here.

Success A text in $brand-clr-txt-event-success must be readable on a $brand-clr-event-success background.
Error A text in $brand-clr-txt-event-error must be readable on a $brand-clr-event-error background.
Info A text in $brand-clr-txt-event-info must be readable on a $brand-clr-event-info background.
Tip A text in $brand-clr-txt-event-tip must be readable on a $brand-clr-event-tip background.

Call to Actions (CTA)

There are 3 types of CTA: primary, alt and secondary.
Each type has different sizes: S, M, L.
There are 2 customizable states for each CTA: default and active (active = on hover, focus and selected state).
The "disabled" state is automatically generated, using the CTA default settings with a 0.5 opacity and default cursor.

The settings file allows to modify multiple parameters:

All Types

Radius

$brand-radius-cta: rem( 2 );

This variable changes the border radius of all CTA (primary, alt, secondary) in the application (buttons, such as navigation or catalog entries, won't be modified by this variable).

Each type of CTA has the same settings: font-weight, background color, border color and text color. Here are the details for the primary CTA.The same is true for Alt and Secondary CTA.

Primary (same logic applies to Alt and Secondary)

Font Weight

$brand-font-weight-cta-l-primary: bold;

This variable changes the font-weight of the primary CTA's text for L size and bigger. To ensure readability, smaller buttons will always have normal font-weight.

Background

$brand-clr-cta-primary-background-default: $brand-clr-primary-default;
$brand-clr-cta-primary-background-active: $brand-clr-primary-active;

These variables change the primary CTA's background color, in default and active state. It can be the same as the branding primary color or any other hexadecimal code. It can be "transparent" for an outline button.

Border

$brand-clr-cta-primary-border-default: $brand-clr-primary-default;
$brand-clr-cta-primary-border-active: $brand-clr-primary-active;

These variables change the primary CTA's border color, in default and active state. It can be the same as the branding primary color or any other hexadecimal code. If no border is wanted, the same color code as the CTA background should be used (do not use "transparent", as the 1px wide border is part of the total CTA height/width calculation).

Text

$brand-clr-cta-primary-txt-default: $brand-clr-txt-primary-default;
$brand-clr-cta-primary-txt-active: $brand-clr-txt-primary-active;

These variables change the primary CTA's text color, in default and active state. It can be the same as the branding primary text color or any other hexadecimal code, as long as it is readable on the chosen CTA primary background color.

Fonts

The different font sizes and line heights in the application are calculated based on those settings.

Family

$font-family : Helvetica, Arial, "Bitstream Vera Sans", sans-serif;

This variable changes the font-family throughout the entire application.

Size

$font-size : 14;

This variable changes the font-size base upon which the different font sizes are scaled.

Line Height

$line-height-base : 18;

This variable changes the line height base upon which the different line-heights are scaled.

Header

$brand-header-height: 51px;
$brand-header-action-height: 51px;
$brand-menu-icon-width: 24px;
$brand-hover-width: 50px;

These variables change the header size based upon the provided values

Header

Header title

$brand-title-padding-side: 15px,
$brand-title-padding-bottom: 13px,
$brand-title-margin-gap: 0px,
$brand-title-margin-bottom: 0px,
$brand-title-border-bottom-width: 4px

These variables change the header title size based upon the provided values

Header title

Pricing Override

This section is dedicated to the override styling for each type of price. SASS mixins are available and can be filled with CSS properties to override default price styling. As there is a default style, this override is optional. The branding style will override any CSS property, as it is meant to.

New CSS properties will impact every price displayed in the application, therefore it is not advisable to change properties that can break the layout, such as the font-size, as it will change the visible price in every location (topbar, template info window, catalog browser, etc).

There are 3 possible cases handled:

No Reduction

Only the standard price is visible and its style can be overridden.

// case 1: standard pricing -> overriding style for .standard-price
@mixin standard-price-branding {
}

Default style: Default style price

Membership Pricing

Displays the standard price under the fidelity program price. Membership price can have a label before its value. Both prices and the membership label styles can be overridden. Text of membership label is a localized string which is managed by the application translation key planner.app.member_price. To know more, refer to Localization.

// case 2: membership pricing -> overriding style for .standard-price
// This setting manages the display of the standard price indicated below the membership price.
@mixin membership-standard-price-branding {
}

// case 2: membership pricing -> overriding style for .membership-price
// This setting overrides the display of the value of the membership price defined in membership-standard-price-label-branding.
@mixin membership-membership-price-branding {
}

// case 2: membership pricing -> overriding style for .membership-price-label
// This setting manages the display of both label and value of the membership price.
@mixin membership-standard-price-label-branding {
}

Default style: Default style membership price

Discounted Pricing

Displays the standard price under the discounted price.

Default style: Default style discounted price

Reduced Pricing

Displays the standard price under the reduced price. Both can be overridden.

// case 3: reduced pricing -> overriding style for .standard-price
@mixin reduced-standard-price-branding {
}

// case 3: reduced pricing -> overriding style for .reduced-price
@mixin reduced-reduced-price-branding {
}

Default style: Default style reduced price

← PreviousNext →