American Express American Express |

Developers

What is the Design Language System?

The Design Language System (DLS) is a set of style and code implementation guidelines, UI design kit, UI front end components libraries, iconography, flags collection and other visual assets, to help digital teams at American Express deliver a blue box experience to our customers in a scalable way.

The DLS adheres to brand guidelines, accessibility standards, cross browsing compatibilities, modular, design forward and systematic approach to all its elements and components.

Benefits

  • Increase velocity and time to market - by designing and building the application with a UI kit.
  • Better UX - by ensuring your product is delivering an on brand, design forward, consistent, usable and accessible American Express experience.
  • Less time and resources spent - individual teams don’t have to spend time designing, building, qa’ing and maintaining the basic components of their applications.
  • Bridges the communication gap between designers and developers - by providing both the same library to design/build their application
  • Increased collaboration and knowledge sharing - with multiple teams having using the same guidelines and libraries, bugs enhancements and contributions are quickly shared and improvements scale to all.

With these benefits in mind, try and use the DLS as much as possible and be very conscious about deviation or modification – Developers shouldn’t lightly accept a design that might contradict or doesn’t utilize the DLS.

Things to Keep in Mind

  • Make sure your DLS versions match within the DLS Design Kit that your designers are using and the code that you’re writing. This will ensure there are no differences between mockup and code.
  • Dont overly customize components as it can deviate from the unified experience.
  • With each new version of the DLS, we introduce new features and bug fixes. If you cant find a documented component or are struggling with a bug, try updating the DLS to the most recent version.
  • Using the DLS does not guarantee that your page in its entirety is accessible. It is still your responsibility to properly test your pages.
  • Ensure you are using the right package for your site e.g. dls-react for react projects.
  • Think about responsive design and ensure your code works on both mobile and larger screen sizes (utility classes can help).
  • Avoid custom CSS when using the DLS. Custom CSS makes your code difficult to maintain, debug and makes your code bloated.

Getting Support

Find us on Slack and via email.

Before reaching out, please:

  • ✅ Check your question is related to the DLS. React questions are best placed in #react, one-app questions in #one-dev.
  • ✅ Search slack and check your question has not already been answered previously. You can search the DLS channel by including “in:dls-tech” in your slack search.
  • ✅ See whether bugs you may be experiencing have been fixed in a newer version of the DLS via our release notes.

When reaching out, please:

  • Make sure you include the version of the DLS that you are using.
  • Be as specific as possible.
  • Attach code, screenshots and screen recordings where appropriate.
  • Avoid reaching out to us individually.
  • Do not use @here or @channel. The DLS team will see you message, and using @here notifies all the community.

Contributing

We welcome contributions. Before contributing be sure to visit our contribution section of this site. It’s also important to read the CONTRIBUTING.md file for the repository you are contributing to.

Repositories

DLS Repo - https://github.aexp.com/amex-eng/axp-dls

Asset Repo - https://github.aexp.com/amex-eng/axp-static-assets

DLS React Repo - https://github.aexp.com/amex-eng/axp-dls-react

Getting Started

There are a few ways to start using the DLS. You can either: Download the library in zipped format; reference the CDN; or install the DLS using Node Package Manager (NPM).

Using the DLS in React

React developers can take advantage of dls-react, a library of DLS React components.
External? Please get in touch with us at DLS@aexp.com for installation steps and access.

Install dls-react using NPM by running the following commands in your terminal:

# Set up the Amex proxy. 
export HTTP_PROXY=http://proxy.aexp.com:8080
export HTTPS_PROXY=http://proxy.aexp.com:8080
export NO_PROXY=.aexp.com
 
# Use the internal npm repository. 
npm config set registry https://artifactory.aexp.com/api/npm/npm-virtual
 
# Install dls-react in your project. 
npm install @americanexpress/dls-react
Visit the DLS React Docs

A DLS stylesheet should be used with dls-react. To make sure a DLS stylesheet is included your application, a Helmet component <DefaultStyle /> is available to check if a DLS stylesheet is present and to include dls-mini at the <head> of the application if not. DLS Mini is a light-weight DLS stylesheet that only provides the global essentials such as style resets, typography, and basic layout.

One Amex developers should reference one-dev to see how DLS is included in modules.

Using the DLS in other Frameworks

In the index HTML page of your project, include the Design Language System CSS and JavaScript files (optional if your application is using a library or framework with its own functionality).

Load CSS, JS, and images remotely without the need to install local copies of the files. Just add the following 

<link>
and 
<script>
elements into your HTML pages. The 
<script>
tag must be included at the bottom of your root html file in order for the JS to work properly: 

<link rel="stylesheet" href="https://www.aexp-static.com/cdaas/one/statics/@americanexpress/dls/6.25.6/package/dist/6.25.6/styles/dls.min.css">
<script type="text/javascript" src="https://www.aexp-static.com/cdaas/one/statics/@americanexpress/dls/6.25.6/package/dist/6.25.6/scripts/dls.min.js"></script>

Note: One of the following lines must be added to the page for icons to work correctly.

  • For html pages:
    • <meta charset="utf-8">
  • For jsp pages:
    • <%@ page contentType="text/html; charset=UTF-8" %>

Folder Structure

You should reference the files in the dist folder:


@americanexpress/dls
└── dist
    └── {version}
        ├── css
        ├── scripts
        └── styles

What’s Included

CSS

CSS Modules for globals, utilities, and components.

Styles

Compiled and minified CSS files to include in your application. Also includes DLS Lite and DLS Mini.

Scripts
Compiled and minified JavaScript files. Optional if your application is using a library or framework with its own functionality. If you are using dls.js, you can apply functionality using data-toggle={component} and applicable data-attributes specified in the guideline examples. Otherwise, you can exclude data-attributes.

If you’re using React, check out our React components library dls-react.

Usage Example

<!doctype html>
  <html lang="en">
      <head>
          <title>American Express</title>
          <meta charset="utf-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
          <link type="text/css" rel="stylesheet" href="https://www.aexp-static.com/cdaas/one/statics/@americanexpress/dls/6.25.6/package/dist/6.25.6/styles/dls.css" media="all">
      </head>

      <body>
        ...
      <script type="text/javascript" src="https://www.aexp-static.com/cdaas/one/statics/@americanexpress/dls/6.25.6/package/dist/6.25.6/scripts/dls.js"></script>
      </body>
  </html>
</div>

Scripts

dls.js

dls.js offers basic functionality in vanilla JavaScript and is included in the full DLS library. To use dls.js, include it in a <script> tag at the bottom of your HTML. Apply functionality to a component using data-toggle={component} and the applicable data-attributes specified in the component’s coded examples.

Depending on your application setup, you may need to call DLS.render() or

  window.DLS = new DLSApp();
  window.DLS.render();

to initiate the DLS scripts.

If you are not using dls.js, you can exclude data-attributes from your code. Data-attributes are only used for dls.js.

Static Assets

Visual assets are hosted in a central internal repository for reference at axp-static-assets. This includes card art, flags, logos, social icons, icon and glyph svgs, iconfonts, and fonts.

While this repo is not accessible to external teams, assets can be used by referencing the hosted CDN source listed below:

https://www.aexp-static.com/cdaas/one/statics/@americanexpress/static-assets/{version}/package/dist/{path/to/asset}

Asset files available in @americanexpress/static-assets dist folder:

See the Graphics and Logos section for path references to cards, badges, flags, and other branding assets.

Example - AU Flag

<img src=“https://www.aexp-static.com/cdaas/one/statics/@americanexpress/static-assets/2.28.0/package/dist/img/flags/dls-flag-au.svg” />

Icon and glyph CDN files are named after their classnames and come in pdf, png, and svg:

Example - Icon

<img src=“https://www.aexp-static.com/cdaas/one/statics/@americanexpress/static-assets/2.28.0/package/dist/img/icons/dls-icon-account.svg” />

<img src=“https://www.aexp-static.com/cdaas/one/statics/@americanexpress/static-assets/2.28.0/package/dist/img/icons/dls-icon-account.png” />

<img src=“https://www.aexp-static.com/cdaas/one/statics/@americanexpress/static-assets/2.28.0/package/dist/img/icons/dls-icon-account.pdf” />

Font files for Guardian and Amex22 card text are hosted in the CDN as well, however there is no need to reference them directly as they are included by default with DLS and DLS-lite css.

DLS Lite and CSS Modules

Usage

The DLS is a common resource used by different teams on various platforms and frameworks.

As usage expands and each application pulls in its own version of the DLS, shared assets can operate across multiple applications and multiple versions of the DLS using CSS Modules.

DLS Lite

The DLS has a variety of styles and classes available for different components, but not all applications or platforms require all available DLS components. DLS Lite is a lightweight version of the style library that provides only the basics, such as typography, utilities, and color. It only includes CSS and not JS. Additional styles and classes can be be pulled in with CSS modules as needed. DLS Lite is available in the dist/{version}/styles folder.

DLS Lite includes:

  • Typography
  • Iconography
  • Grid layout
  • Cards
  • Buttons
  • Margin static and responsive utilities
  • Padding static and responsive utilities
  • Text utilities
  • Layout utilities

DLS Mini

DLS Mini is an even smaller version of DLS Lite that only provides the global essentials such as style resets, typography, and basic layout. DLS Mini is available in the dist/{version}/styles folder.

DLS Mini includes:

  • Typography
  • Grid layout
  • Margin static utilities
  • Padding static utilities
  • Display utilities
  • Flex utilities

CSS Modules

CSS modules create unique, dynamic class names for each locally defined style. CSS modules should be used for components that need unique classnames so that they aren’t affected by different versions of the DLS or other styles from different applications. Examples include navigation, footer, login widgets, and anything shared across tenancy or outside the company.

How it Works

All DLS components, globals, and utilities are compiled into their own CSS file within the dist/css folder. These can be referenced and used as CSS classes or exported as objects. CSS modules should be used in combination with DLS Lite.

Major differences to note:

  • Classnames are camelCased instead of using dashed separators
  • Columns need an additional .col class
  • DLS JS does not work with CSS Modules

Example - DLS Lite and CSS Modules

Add DLS Lite and the relevant CSS modules as style sheet references.

<link type="text/css" rel="stylesheet" href="@americanexpress/dls/dist/6.25.6/styles/dls-lite.css" media="all">
<link type="text/css" rel="stylesheet" href="@americanexpress/dls/dist/css/alert.css" media="all">
<link type="text/css" rel="stylesheet" href="@americanexpress/dls/dist/css/forms.css" media="all">
<link type="text/css" rel="stylesheet" href="@americanexpress/dls/dist/css/padResponsive.css" media="all">

  <div class="border dls-white-bg">
      <form class="formHasWarning">
          <div class="padResponsive alert dls-red" role="alert">
              <span class="icon dls-icon-warning-filled margin-1-r"></span>
              <span>Your User ID or Password is incorrect.<br />Please try again.</span>
          </div>
          <hr>
          <div class="padResponsive stack">
              <div>
                  <label for="eg1-user">User ID</label>
                  <input type="text" id="eg1-user" class="formControl" value="char•••••" />
              </div>
              <div>
                  <label for="eg1-pass">Password</label>
                  <input type="password" id="eg1-pass" class="formControl" />
              </div>
              <div>
                  <button type="submit" id="dls-example-login-button" class="btn fluid margin-auto-lr">Log In</button>
              </div>
          </div>
      </form>
  </div>

Example - React

Import the CSS object or camelCased classnames and use them as variables.

// Component.jsx
import { card } from '../../../../@americanexpress/dls/dist/css/card.css';
import { dlsColorAccentGray01 } from '../../../../@americanexpress/dls/dist/css/colors.css';
import { pad3t, padB } from '../../../../@americanexpress/dls/dist/css/padStatic.css';
import marginStatic from '../../../../@americanexpress/dls/dist/css/marginStatic.css';
import grid from '../../../../@americanexpress/dls/dist/css/grid.css';

...

return (
  <section className={`${card} ${marginStatic.marginT}`}>
    <div className={grid.row}>
      <div className={`${grid.colMd12} ${pad3t} ${padB}`}>
        <div className={dlsColorAccentGray01}>
        ...
        </div>
      </div>
    </div>
  </section>
  )

Folder Structure


@americanexpress/dls
└── dist
    └── {version}
        └── css
            ├── accentBar.css
            ├── accessibility.css
            ├── actionGroup.css
            ├── alert.css
            ├── alignment.css
            ├── animBar.css
            ├── animDelay.css
            ├── animFade.css
            ├── animSlide.css
            ├── animSpin.css
            ├── appBadge.css
            ├── badge.css
            ├── barChart.css
            ├── borders.css
            ├── breadcrumb.css
            ├── btn.css
            ├── btnChevron.css
            ├── btnCircle.css
            ├── btnCobrand.css
            ├── btnFloat.css
            ├── btnFloatingChat.css
            ├── btnFloatingScroll.css
            ├── btnGroup.css
            ├── btnIcon.css
            ├── btnLoading.css
            ├── btnTooltip.css
            ├── card.css
            ├── cardActionable.css
            ├── cardImg.css
            ├── caret.css
            ├── carousel.css
            ├── checkbox.css
            ├── checklist.css
            ├── collapsible.css
            ├── colors.css
            ├── colorsCard.css
            ├── colorsCobrand.css
            ├── colorsData.css
            ├── colorsDataVisualization.css
            ├── colorsDls.css
            ├── colorsFico.css
            ├── colorsFilter.css
            ├── colorsOffers.css
            ├── colorsTrend.css
            ├── copy.css
            ├── currency.css
            ├── datePicker.css
            ├── display.css
            ├── displayRanges.css
            ├── dlsCard.css
            ├── dlsCardField.css
            ├── dlsCardTilt.css
            ├── elements.css
            ├── fileUpload.css
            ├── filter.css
            ├── flag.css
            ├── flex.css
            ├── float.css
            ├── focus.css
            ├── focusRanges.css
            ├── fonts.css
            ├── forms.css
            ├── gradients.css
            ├── grid.css
            ├── gridAlignment.css
            ├── gridLayout.css
            ├── hero.css
            ├── hint.css
            ├── iconography.css
            ├── imagephoto.css
            ├── inputStatus.css
            ├── layout.css
            ├── list.css
            ├── logo.css
            ├── marginRanges.css
            ├── marginResponsive.css
            ├── marginStatic.css
            ├── modal.css
            ├── multiselect.css
            ├── nav.css
            ├── navAccordion.css
            ├── navDropdown.css
            ├── navFooter.css
            ├── navHorizontal.css
            ├── navVertical.css
            ├── overflowMenu.css
            ├── padRanges.css
            ├── padResponsive.css
            ├── padStatic.css
            ├── pagination.css
            ├── phone.css
            ├── position.css
            ├── progress.css
            ├── progressBar.css
            ├── progressCircle.css
            ├── progressLinear.css
            ├── progressMultiStep.css
            ├── pull.css
            ├── radio.css
            ├── required.css
            ├── scroll.css
            ├── search.css
            ├── searchfield.css
            ├── select.css
            ├── sizing.css
            ├── slider.css
            ├── smartField.css
            ├── smsfield.css
            ├── stepper.css
            ├── switches.css
            ├── table.css
            ├── tabs.css
            ├── tags.css
            ├── text.css
            ├── tooltip.css
            ├── typography.css
            ├── video.css
            └── visibility.css

Deprecated components

Deprecated

This badge indicates that the component is outdated and will be removed in the next major release*. If you see this badge next to a component in the library, use of component should be discontinued. Please reference the Changelog and Release Notes for details and alternatives.

*Releases follow the semver pattern: MAJOR.MINOR.PATCH

References

CDN References

DLS CDN - https://www.aexp-static.com/cdaas/one/statics/@americanexpress/dls/{version}/package/dist/{version}/{styles/scripts}/{dls.min.css/dls.min.js}

Asset CDN - https://www.aexp-static.com/cdaas/one/statics/@americanexpress/static-assets/{version}/package/{path/to/asset}

Trainings

One Amex CTP learning sessions are hosted once a month and there are some DLS-related trainings such as:

  • Overview of DLS
  • Flexbox / Grid
  • DLS Lite & CSS Modules

Migration Guide

Moving from DLS v5 to v6

This guide only shows major changes that affect end users. For more details please see the Changelog.

Overview

DLS v6.0.0 is all about accessibility and cleanup.

We’ve refactored the current codebase to reduce its size and remove many of the duplicative CSS classes. We’ve also refactored components and examples to meet accessibility best practices. We’ve placed all visual assets into a central repository with a CDN as a single point of reference (icons, glyphs, logos, flags, etc).

Changes

CSS - Classes that are redundant and could be replaced with other existing classes have been removed.

JS - All scripts were re-written to be simplified and more dynamic. Data-attributes are only used for dls.js functionality.

Markup - Components and examples were refactored to be semantically correct and accessible.

Central Asset Repository - We’ve separated all visual assets into a central point of reference at axp-static-assets to facilitate re-use of the most common assets. This includes images, icons, and fonts.

Path Reference - Path reference to styles and scripts have changed from dist/* to dist/{version}/*` for caching.

Components

Below is a list of components that have been refactored with major breaking changes. Check out the coded examples of each component provided in our guidelines and update your code accordingly. See Changelog for details.

  • Accent bars - removed classes
  • Badges - removed classes
  • Breadcrumbs - updated markup and styles, removed classes and data-attributes
  • Buttons - removed classes and removed default styling from <button> element for other components that are semantic buttons but that don’t look like .btn (add .btn to all visual buttons)
  • Cards - removed classes
  • Card field - removed classes, updated functionality and changed data-attributes
  • Carousel - updated markup and functionality, removed classes, redesigned with reduced min-height of 365px from 500px
  • Checkboxes - removed default built-in margin-bottom
  • Colors - removed legacy colors and added new brand colors
  • Collapsible panels - removed classes, updated markup and functionality, design tweaks for collapsible panels with icons
  • Copy field - removed classes
  • Currency field - updated markup and functionality
  • Data viz - removed classes
  • Date picker - removed classes, redesigned calendar
  • Dropdowns - removed classes, updated markup and functionality, no longer truncates text
  • Flags - removed classes, use images for each country flag instead
  • Forms - removed classes
  • Heroes - Redesigned with reduced min-height from 500px to 365px, max-height from 750px to 500px medium breakpoints and up, and max-width of 1280px
  • Inputs - removed classes, updated markup
  • Logos - removed legacy logos and added new brand logos
  • Modals - removed classes
  • Navigation - removed classes, updated markup and functionality, design tweaks for navigation with icons, built-in responsive padding
  • Notifications - updated functionality
  • Pagination - redesigned, updated markup and functionality
  • Progress stepper - updated markup
  • Search - removed classes, removed data-attributes, updated markup and functionality
  • Sliders - removed classes, updated markup and functioinality
  • Smart fields - removed classes, data-attributes, updated markup and functionality
  • Steppers - updated markup and functionality
  • Switches - removed classes
  • Table - removed classes and data-attributes
  • Tabs - redesigned mobile to be scrollable instead of switching to dropdown, updated markup and functionality, removed classes, removed default padding for tab content
  • Tags - updated markup and removed classes
  • Text links - Expandable text links should semantically be buttons, not links
  • Tooltips - removed classes, updated markup and functionality
  • Trackers and loaders - removed classes, redesigned
  • Typography - removed default margins from .label-* classes, removed .legal
  • Utilities - removed and updated classes
  • Video players - removed classes, updated functionality, redesigned

Assets

axp-static-assets acts as a central asset repository with CDN reference:

https://www.aexp-static.com/cdaas/one/statics/axp-static-assets/{version}/package/dist/{path/to/asset}

Use the CDN path reference for logos, flags, and cards.

Example - AU Flag

<img src=“https://www.aexp-static.com/cdaas/one/statics/@americanexpress/static-assets/2.28.0/package/dist/img/flags/dls-flag-au.svg” />