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
- Working with Colors in Katana
- Introduction
- Carousel
- Number Selector
- Step Indicator
- Progress Indicator
- Other Updates
- Introduction
- Get Started with Code
- Building with Performance in Mind
- Working with Themes
- Tools
- Report Bug
- Spark React Resources
- Other React Community Solutions
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:
For production, we recommend limiting the CSS to just what’s needed for performance reasons. This can be done in the following manner:
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.
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:
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 oldersabre-spark
package no longer receive updates.
Carousel
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:
- Update your Hero Carousel’s HTML structure to reflect the new version. This includes removing the
data-spark-carousel-hero-dark
anddata-spark-carousel-hero-light
attributes in favor of the newdata-spark-carousel-hero
attribute. Refer to the HTML example for the new HTML structure. - Configure the
spark-carousel
element’s ARIA attributes to match your product or usage of the component. - Update the
spark-assistive-text
element’s label to match your product.
Multiple Panel and Filmstrip Carousel
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:
- 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
andsubtitle
have been removed, as they are longer part of the component. - An
onStepClick
callback has been added to expose click events on steps. currentLabel
andcompletedLabel
options have been made available for translating ARIA related text.- A
stepProgressionLabel
option has been added to allow for translation of theX of X
in the Dropdown Indicator example.
Read the updated Step Indicator’s Developer Notes for complete details.
Migration Steps:
- Update your Step Indicator’s HTML structure if you are currently using the Header Option variation found in v2.
- Remove the
header
andsubtitle
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:
- 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 toeta
- Removed
theta
- All
eta
changed tozeta
- All
zeta
changed toepsilon
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:
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:
5. Import Spark Javascript:
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.
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:
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
- Classic (Light) color variables (scss/config/_color.scss).
- Katana color variables (scss/themes/katana/config/_color.scss)
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:
CLI Example:
CLI Options
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](https://sabre-spark.s3.amazonaws.com/site_assets/images/resources/developer_resources/react-icon.png)
- Spark-React Storybook
- Spark-React Bitbucket Repository
- Spark-React Starter Project (Code Pending)
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.