Skip Navigation

Developer Resources

The Spark Design Language consists of a robust set of coded UI components developed with production-grade HTML, CSS and Javascript to provide a consistent, accessible user experience across all of Sabre's products.

Introduction

The new Katana theme marks a significant phase in the evolution of the Spark Design Language and in our efforts to enable teams to build accessible products. Complying with WCAG 2.1 standards, we have re-imagined the design underpinnings of the Language to update and modernize the visual style of the language.

From a code-perspective, the updates we made are stylistic in nature and limited to the introduction of new CSS. In addition to making visual changes to components, we made updates to the following design foundations:

  • Primary Color Palette – introduced a new primary palette with extended colors and tints alongside a usage system that allows for accessible combination of colors. Read our Color Guidelines for more information.
  • Data Visualization Color Palette – introduced new colors and new palettes for different types of data visualizations. Read our Color Palettes for Data Visualization documentation for more information.
  • New font – we have introduced the Roboto Condensed Bold for use with headings. Read our Typography documentation for more details.

The path and ease of adopting the Katana theme will be dependent on whether you are building a new application or updating an existing application.

Building new applications

Using the Katana theme in new applications is straightforward and can be accomplished by including the Katana theme CSS.

In development environments, you can link to the full CSS library as follows:

<!doctype html>
<html>
  <head>
    ...
    <link rel="stylesheet" href="path/to/css/spark.katana.css">
    ...
  </head>
  <body>
    ...
  </body>
</html>

For production, we recommend limiting the CSS to just what’s needed for performance reasons. This can be done in the following manner:

<!doctype html>
<html>
  <head>
    ...
    <!-- Include common styles for all components: grid, messaging, etc. -->
    <link rel="stylesheet" href="path/to/css/components/common.katana.min.css">
    <!-- Include individual components -->
    <link rel="stylesheet" href="path/to/css/components/text-input.katana.min.css">
    ...
  </head>
  <body>
    ...
  </body>
</html>

Refer to our documentation on building with performance in mind for more details.

Updating an existing application

When looking to use the Katana theme within an existing application, you will need to determine what version of Spark you are working with, and whether you have any custom CSS in use that either overrides Spark Classic CSS, or is used for custom components.

If you are working with Spark v2, you will first need to upgrade to Spark v3. Instructions on how to migrate are available in our Developer Resources. Once you have migrated to v3, follow the steps below.

If you are already on Spark v3, and do not have any custom CSS or custom components, you should be able to switch the CSS from the Light/Classic theme to the Katana theme to get the updated visual look. The code snippets below illustrate what to change.

<!-- Change from this -->
<!-- <link rel="stylesheet" href="path/to/css/spark.light.css"> -->

<!-- Change to this -->
<link rel="stylesheet" href="path/to/css/spark.katana.css">

If you have custom CSS or custom components, you will first need to determine the updates needed to align the custom code with the Katana look and feel. This could include but is not limited to color changes, typography changes and implementing box-shadows and rounded corners.

The changes needed to then use the Katana theme would mirror the examples illustrated above, and in development environments could look as follows:

<!-- Change from this -->
<!-- <link rel="stylesheet" href="path/to/css/spark.light.css"> -->
<!-- <link rel="stylesheet" href="path/to/css/product-custom-styles.css"> -->

<!-- Change to this -->
<link rel="stylesheet" href="path/to/css/spark.katana.css">
<link rel="stylesheet" href="path/to/css/product-custom-styles-with-katana.css">
</html>

Working with Colors in Katana

As previously mentioned, one of the key updates in the Katana theme is the Color palette. We have provided a list of the Extended Color palette variables as well as guidance on how to select accessible color pairs from the palette.

We highly recommend using the referenced SASS color variables e.g. $blue-60 in code as well as in discussions with other developers or designers as it simplifies the communication of color values. It also ensures that should updates be made to the palette then the change can easily propagate into applications as compared to using hex values.

The full mapping of SASS color variables to hex values can be found by reviewing the color configurations file in the Spark codebase.

Introduction

As part of our commitment to improving the Spark Design Language, Spark v3 builds on top of the Spark v2 to bring new features as well as improvements to the codebase. One of the primary goals of v3 is ensuring that the Spark codebase is fully accessible to screen readers and other assistive technologies and/or provides the necessary means for product teams to ensure their products are accessible. As part of this process, some of our components’ HTML structure and/or Javascript APIs changed. The details of these changes and steps for migrating from v2 to v3 are detailed below.

Outside of accessibility improvements, we have also worked to introduce new features such as animations, and optimized the codebase by removing deprecated code and streamlining portions of our code.

As Spark v3’s codebase is built on top of v2, we strongly encourage you to update your applications to use the latest version. For more details on how we plan to support older versions of Spark, refer to our support plan below.

Migrating from v2 to v3

Update the NPM Package

If you are working with Spark from the internal Nexus registries, you will need to update the Spark NPM package name in your package.json file. The package is now published under the name @sabre/spark which is a shift from the older sabre-spark name. This change was made in order to adopt Sabre standards for publishing internal packages to Nexus.

Update Components and Code

The following components introduced breaking changes to their HTML structure and/or Javascript APIs. In order to migrate from v2 to v3, these components will need to be updated if they are present in your applications. The changes to each component are detailed below, including steps on how to update the component to the latest structure/APIs.

Changes made to optimize the library are also detailed below.

Support for Older Versions

As part of releasing Spark v3, we are updating which versions of Spark we will continue to support as follows:

  • Spark v1 is no longer supported. However, the codebase will still be available on Sabre’s git repository, and the documentation will still be available on this site.

  • Spark v2 will receive updates for bug fixes and any issues that arise from its codebase only. New components will not be added to the v2 codebase. All updates to v2 will be published in the @sabre/spark package, with the older sabre-spark package no longer receive updates.

Hero Banner

The dark and light variations of the Hero Carousel have been removed in favor of a single Hero Carousel. This single variation has controls that account for differing image colors to ensure the controls are always visible. We have also added additional ARIA attributes to the component to provide more details to screen readers and other assistive technologies. Refer to the Carousel’s Accessibility documentation for more details on how to work with these attributes.

We have also changed how users navigate the carousel when using a keyboard. It is no longer possible to use the Tab key to navigate through all the available slides. Instead, we have made the Back, Forward and Pause/Play controls accessible via keyboard to allow interaction with the carousel.

Migration Steps:

  1. Update your Hero Carousel’s HTML structure to reflect the new version. This includes removing the data-spark-carousel-hero-dark and data-spark-carousel-hero-light attributes in favor of the new data-spark-carousel-hero attribute. Refer to the HTML example for the new HTML structure.
  2. Configure the spark-carousel element’s ARIA attributes to match your product or usage of the component.
  3. Update the spark-assistive-text element’s label to match your product.

We added an optional Skip Carousel link to allow users to bypass the Carousel if it has a large number of slides when the page is being navigated via keyboard. Refer to our documentation on when and where to include this link.

Migration Steps:

If you need to include a Skip Carousel link, add the markup for it within the spark-carousel__container-mask but before the spark-carousel__container element. Refer to our examples for more details on the markup for the link and where to place it in the HTML.

Number Selector

The Number Selector has been re-designed and the HTML markup re-written to better fit with existing Spark form fields. This includes updating the messaging styling to better match that found in other form components e.g. Text Input. Right-to-Left support has also been added to the component.

Migration Steps:

  1. Refer to the Number Selector HTML examples for the updated structure that you current implementation should change to.

Step Indicator

The Header Option feature of the Step Indicator has been removed. If you would like to have a title or subtitle, utilize the appropriate heading (H1-H6) outside of the Step Indicator component’s markup. We have also added additional ARIA attributes to the component to provide more details to screen readers and other assistive technologies. Refer to the Step Indicator’s Accessibility documentation for additional details.

The options available when instantiating a new Step Indicator have also changed as follows:

  • The options for header and subtitle have been removed, as they are longer part of the component.
  • An onStepClick callback has been added to expose click events on steps.
  • currentLabel and completedLabel options have been made available for translating ARIA related text.
  • A stepProgressionLabel option has been added to allow for translation of the X of X in the Dropdown Indicator example.

Read the updated Step Indicator’s Developer Notes for complete details.

Migration Steps:

  1. Update your Step Indicator’s HTML structure if you are currently using the Header Option variation found in v2.
  2. Remove the header and subtitle options from your Javascript instantiation.

Progress Indicator

The Extra Small Progress Indeterminate Indicator in v3 is no longer a button. If you wish to use a Progress Indicator in a Button we recommend using the Progress Button component.

Migration Steps:

  1. Update your Extra Small Progress Indicator HTML source with the standard Progress Indicator code making sure to add the .spark-progress--xs class.

Other Updates

In addition to the changes to the components above, we have optimized the Spark codebase to remove styles and Javascript that were deprecated in Spark v2 and due for removal with the next major release. The details of these changes are noted below including how to update your applications if necessary.

Typography Updates

Removed the following color palettes that are not in use:

  • $cyan and $cyan-color-steps

Update modular scale to remove duplicates and unused sizes:

  • Removed iota
  • All theta changed to eta
  • Removed theta
  • All eta changed to zeta
  • All zeta changed to epsilon

CSS and Javascript cleanup

All HTML examples have been updated as needed to reflect the changes below.

Removed the following deprecated Badge classes:

  • .spark-badge--info - Use .spark-badge--neutral instead.
  • .spark-badge--error - Use .spark-badge--critical instead.

Removed the following deprecated Header classes:

  • .spark-header__search
  • .spark-header__logout

Removed the following deprecated Helper classes and their variants in favor of the updated Spacing Helper classes:

  • .spark-margin (including .spark-margin-* and .spark-margin--*)
  • .spark-padding (including .spark-padding-* and .spark-padding--*)

Removed the following deprecated Button class:

.spark-btn--link

Removed the following deprecated Color variables in favor of updated, accessibility-tested Warning colors:

  • $color-state-warning
  • $color-state-warning--dark

The following components had deprecated or unused SASS variables removed:

  • Badge
  • Button
  • Calendar Popover
  • Checkbox
  • Filter
  • Header
  • Menu
  • Panel
  • Progress Indicator
  • Select
  • Slider
  • Tables
  • Toast Notifications
  • Toggles
  • Transaction Summary Bar
  • Progress Indicator

Fixed the following animation SASS variable:

  • $ease-in-out- has been replaced with $ease-in-out-quart

Updated HTML Examples

We have updated the HTML markup for the Table with Messaging variation as follows to be in line with our recommended usage of icons:

  • Changed instances of large airplane icons to medium
  • Update all Status icons to use fill instead of line within Tables
  • Removed Icon Buttons that do not have any usage within Tables and replaced them with vertically centered Icons when not inside a status wrapper.

For more details on how best to use Spark Icons, refer to the Iconography documentation.

Introduction

The Spark Design Language is developed as a responsive and mobile-first suite of components that are a great starting point for web-based applications. Built using SASS and vanilla Javascript and without external dependencies (other than build tools), Spark components can be easily integrated into Sabre products without adding bloat, and can be paired with libraries and frameworks such as React. Spark itself is not a framework.

Get Started with Code

Installing Spark

There are two options for installing and working with Spark components: working with compiled CSS and Javascript or utilizing a build system as part of your development process.

Working with Compiled CSS and Javascript

1. Download a zip of the latest Spark library components

2. Include the necessary CSS and Javascript within your HTML documents, which could be as follows:

<!doctype html>
<html>
  <head>
    ...
    <link rel="stylesheet" href="path/to/css/spark.light.min.css">
    ...
    <!-- Styles custom to your product if needed -->
    <link rel="stylesheet" href="path/to/css/product-custom-styles.css">
    ...
  </head>
  <body>
    ...
    <script src="path/to/js/spark.min.js"></script>
  </body>
</html>

When utilizing this approach, it is important to keep in mind that you would need to manually download and update the library with each new release of Spark.

Utilizing a Build System

1. Add an .npmrc file to your product (or update your existing one) and add the following:

registry=https://repository.sabre-gcp.com/repository/npm-all/

2. Authenticate with Nexus using your SG credentials:

npm login

Follow the user/pass prompt. This will add your personal Nexus token to /Users/your-user/.npmrc, so you will only need to run this command once.

3. Install Spark in your product via NPM:

npm install --save @sabre/spark

4. Add the Spark fonts directory and import Spark SASS into your SCSS file:

$font-directory: '~@sabre/spark/dist/css/fonts';
@import '~@sabre/spark/scss/spark.katana';

5. Import Spark Javascript:

// Load from ES5 compiled code
import {TextInput, DateInput} from '@sabre/spark';

// Or load from ES6 source code
import {TextInput, DateInput} from '@sabre/spark/js/src/spark';

// Or load a single component from ES6 source code
import TextInput from '@sabre/spark/js/src/components/text-input';
import DateInput from '@sabre/spark/js/src/components/date-input';

Working with Components

Once you have installed the Spark codebase, you can then include Spark-specific component markup. For details on how to integrate each component, refer to the UI Components section of this site. Some things to be mindful of:

  • Not all Spark components require the use of Javascript, and if one does it will be noted within that component’s documentation under the Developer tab.
  • Deviating from the provided HTML example markup/structure could lead to broken functionality and bugs in your application.

Spark uses SASS as a CSS preprocessor because it is powerful, stable and widely adopted, and utilizes the BEM (block, element, modifier) CSS methodology. When using Spark’s SASS files in your project, it is recommended you use node-sass instead of the sass Ruby gem. In addition to being much faster (by up to 4000%!), some features of Spark do not work with older Ruby-based versions of SASS.

Spark’s Javascript library powers some of the more complex UI components of Spark. It has no external dependencies and is required if you wish to use Spark UI components that are Javascript-driven.

Spark’s Javascript modules will not be instantiated automatically. In order to support a broad range of use cases, the modules do not automatically create instances of themselves when the page loads. For example, a Text Input would need to be instantiated after the document is ready by using the following:

new Spark.TextInput(document.querySelector('#textinputid'));

If you are using a framework like React, Vue or Angular, instantiating each component can be done on the fly when views are rendered.

As of Spark v2, the following method of loading the modules into a namespace NO LONGER WORKS. This approach should be considered an ES6 anti-pattern.

// DON'T DO THIS ANYMORE
import Spark from 'sabre-spark';
let headerInstance = new Spark.Header();

Building with Performance in Mind

In order to build performant applications, it is important to utilize techniques that reduce the amount of code that is included in applications. To assist with this, the Spark codebase is available as minified CSS and Javascript for applications that are not utilizing a build process that would automatically minify code as it is being built and deployed. To use Spark’s minified assets, use the minified CSS and Javascript (available in the dist folder of the downloadable zip file) identified with the abbreviation min prior to the file extension:

<link rel="stylesheet" href="path/to/css/spark.light.min.css">

As of Spark v2, it is possible to include individual components (ideally minified) into your application on an as-needed basis to reduce the amount of code in your application. This could look like this:

<!doctype html>
<html>
  <head>
    ...
    <!-- Include common styles for all components: grid, messaging, etc. -->
    <link rel="stylesheet" href="path/to/css/components/common.light.min.css">
    <!-- Include individual components -->
    <link rel="stylesheet" href="path/to/css/components/text-input.light.min.css">
    <link rel="stylesheet" href="path/to/css/components/calendar.light.min.css">
    <link rel="stylesheet" href="path/to/css/components/date-input.light.min.css">
    <link rel="stylesheet" href="path/to/css/components/button.light.min.css">
    <!-- Styles custom to your product if needed -->
    <link rel="stylesheet" href="path/to/css/product-custom-styles.css">
  </head>
  <body>
    ...
    <script src="path/to/js/components/text-input.min.js"></script>
    <script src="path/to/js/components/calendar.min.js"></script>
    <script src="path/to/js/components/date-input.min.js"></script>
  </body>
</html>

Note that required common styles are included before the individual component styles. For more advanced component integration, take a look at the Custom Component Export Tool.

Working with Themes

The Spark library is built to accommodate different “themes”. While the core of the SASS is the same, each theme can define its own variables to alter colors, font weights, etc. The themes are: White Label (spark.whitelabel.scss), Light (spark.light.scss) and Katana (spark.katana.scss).

Color Variables

Although your product may eventually ship with the “White Label” theme, all initial development should use the Light theme. When delivering a whitelabel product using Spark, simply replace references to spark.light.css with spark.whitelabel.css. If you are using the Spark SASS files directly, replace your @import /path/to/spark.light; with @import /path/to/spark.whitelabel;.

Tools

Custom Component Exporter

If you need to generate JS, SCSS and/or CSS files for a custom set of UI components, you can use the spark-export-components command line tool. It can output a .js file for use globaly or with a package manager, an .scss file with @import statements for each requested component, or a compiled .css file.

CLI Usage:

spark-export-components [components]

CLI Example:

spark-export-components button expand panel --theme light --out spark.custom

CLI Options

-t, --theme       Name of the theme to use
-o, --out         Output directory
-h, --help        Print usage info
--nojs            Don't output JS for components
--nocss           Don't output CSS for components
--noscss          Don't output SCSS for components
--filename        The name to use for output files
--jsfilename      The name to use for output JS files
--cssfilename     The name to use for output CSS files

Report Bug

Found a bug? Please submit a request through JIRA.

Spark React Resources

Starting in 2019, the Spark team in conjunction with the Sabre Developers community has been developing a Spark-React library which would have full component and feature parity with the core, HTML/CSS/Vanilla JS Spark library. Based off of version 3 of the core Spark library, the Spark-React library will be actively maintained and receive the same features, updates and bug-fixes as the core library.

React Icon

We are actively seeking and welcome any contributions to the Spark-React library including submission of new components, bug-fixes, enhancements and code reviews.

Other React Community Solutions

The following Spark-React libraries currently exist within the Sabre Development community, and are maintained by teams in different business units. As such, they are not part of the official Spark development cycle.

Airlines Solutions Sabre-Spark (Deprecated)

Hospitality Solutions Sabre-Spark (Deprecated)