Getting started for engineers

The Design Systems Team maintains design tokens, icons, and components in a monorepo and publishes them regularly to npm.

Components

We provide components as an Ember addon with associated styles in Sass and CSS. By installing the components, you also have access to the design tokens and CSS helper classes.

Install components package

.bash

pnpm add @hashicorp/design-system-components

Import component styles

You can choose between importing styles as CSS or Sass. CSS is preferred because the files are pre-compiled, resulting in faster build times in your app, while the Sass approach requires consumer-side compilation and more setup steps.

CSS

Import one or more of the following lines to the ember-cli-build.js configuration file. Pick the lines that match your application's stage in the migration to the "carbonized" HDS.

.js

// "classic" HDS
app.import('node_modules/@hashicorp/design-system-components/dist/styles/@hashicorp/design-system-components.css');

// "carbonized" HDS with support for "light/dark/system" (g0/g100 modes)
app.import('node_modules/@hashicorp/design-system-tokens/dist/products/css/themed-tokens/with-css-selectors/tokens.css');
app.import('node_modules/@hashicorp/design-system-components/dist/styles/@hashicorp/design-system-components-common.css');
app.import('node_modules/@hashicorp/design-system-components/dist/styles/@hashicorp/design-system-plex-fonts.css');

// "classic" HDS + "carbonized" HDS with support for "light/dark/system" (g0/g100 modes)
// useful during the migration from "classic" to "carbonized" HDS, when both visual languages must co-exist in the same UI application
app.import('node_modules/@hashicorp/design-system-tokens/dist/products/css/themed-tokens/with-css-selectors--migration/tokens.css');
app.import('node_modules/@hashicorp/design-system-components/dist/styles/@hashicorp/design-system-components-common.css');
app.import('node_modules/@hashicorp/design-system-components/dist/styles/@hashicorp/design-system-plex-fonts.css');

// "classic" HDS + "carbonized" HDS with support for "light/dark/system" (g0/g10/g90/g100 modes)
// useful if all the IBM Carbon modes need to be available in the application, alongside the "classic" HDS
app.import('node_modules/@hashicorp/design-system-tokens/dist/products/css/themed-tokens/with-css-selectors--advanced/tokens.css');
app.import('node_modules/@hashicorp/design-system-components/dist/styles/@hashicorp/design-system-components-common.css');
app.import('node_modules/@hashicorp/design-system-components/dist/styles/@hashicorp/design-system-plex-fonts.css');

Note: the design-system-plex-fonts.css file assumes that the application serves fonts from /assets; if that's not the case you will need to follow the Sass-based approach.

If your application uses SuperSelect, make sure ember-basic-dropdown is installed and the ember-power-select styles are imported:

.js

app.import('node_modules/ember-power-select/vendor/ember-power-select.css');

If your application uses the Ember PowerSelect component directly, import the HDS style overrides for it:

.js

app.import('node_modules/@hashicorp/design-system-components/dist/styles/@hashicorp/design-system-power-select-overrides.css');

Sass

Install and configure Sass to preprocess styles, handle source maps, and include paths in your application.

.bash

ember install ember-cli-sass

Use the scss extension to ensure the styles are being preprocessed. For example, you may need to change app/styles/app.css to app/styles/app.scss.
Add the following configuration in ember-cli-build.js to set the number of decimal places and enable access to the design system tokens:

.js

module.exports = function (defaults) {
  const app = new EmberApp(defaults, {
    // ... other app configurations
    sassOptions: {
      precision: 4,
      includePaths: [
        // these are the packages for HDS tokens and components
        './node_modules/@hashicorp/design-system-tokens/dist/products/css',
        './node_modules/@hashicorp/design-system-components/dist/styles',
        // this is needed for the IBM Plex fonts
        './node_modules/@ibm',
      ],
    },
  })
};

We also suggest adding this configuration in ember-cli-build.js to prevent ember-cli from trying to over-optimize the generated CSS by changing the order of the CSS declarations (reference):

.js

module.exports = function (defaults) {
  const app = new EmberApp(defaults, {
    // ... other app configurations
    minifyCSS: {
      options: {
        advanced: false,
      },
    },
  })
};

Add one of the following line(s) to the main Sass file in your application (for example, in app.scss). Pick the line(s) that match your application's stage in the migration to the "carbonized" HDS.

.scss

// "classic" HDS
@use "@hashicorp/design-system-components";

// "carbonized" HDS with support for "light/dark/system" (g0/g100 modes)
@use "@hashicorp/design-system-components-common";
@use "themed-tokens/with-css-selectors/tokens";
@use '@hashicorp/design-system-plex-fonts';

// "classic" HDS + "carbonized" HDS with support for "light/dark/system" (g0/g100 modes)
// useful during the migration from "classic" to "carbonized" HDS, when both visual languages must co-exist in the same UI application
@use "@hashicorp/design-system-components-common";
@use "themed-tokens/with-css-selectors--migration/tokens";
@use '@hashicorp/design-system-plex-fonts';

// "classic" HDS + "carbonized" HDS with support for "light/dark/system" (g0/g10/g90/g100 modes)
// useful if all the IBM Carbon modes need to be available in the application, alongside the "classic" HDS
@use "@hashicorp/design-system-components-common";
@use "themed-tokens/with-css-selectors--advanced/tokens";
@use '@hashicorp/design-system-plex-fonts';

If your application serves fonts from a path other than /assets (e.g. /app/assets) configure the $hds-ibm-plex-fonts-assets-path Sass variable.

.scss

@use '@hashicorp/design-system-plex-fonts' with ($hds-ibm-plex-fonts-assets-path: '/app/assets');

If your application uses SuperSelect, make sure ember-basic-dropdown is installed and the ember-power-select styles are imported:

.scss

@use "ember-power-select";

If your application uses the Ember PowerSelect component directly, import the HDS style overrides for it:

.scss

@use "@hashicorp/design-system-power-select-overrides";

Single file components

If you are are using single file components (i.e., .gts or .gjs files), the components need to be individually imported into the file for them to render. All components can be imported from the @hashicorp/design-system-components/components path. To use a component's signature, you must import it from the definition file.

.gts

import type { TemplateOnlyComponent } from '@ember/component/template-only';
import {
  HdsButton,
  HdsFormTextInputField,
} from '@hashicorp/design-system-components/components';

import type { HdsButtonSignature } from '@hashicorp/design-system-components/components/hds/button/index';
import type { HdsFormTextInputFieldSignature } from '@hashicorp/design-system-components/components/hds/form/text-input/field';

interface LocalComponentSignature {
  Args: {
    fieldLabel: string;
    buttonSize?: HdsButtonSignature['Args']['size'];
  };
  Element: HdsFormTextInputFieldSignature['Element'];
}

const LocalComponent: TemplateOnlyComponent<LocalComponentSignature> =
  <template>
    <HdsFormTextInputField ...attributes as |F|>
      <F.Label>{{@fieldLabel}}</F.Label>
    </HdsFormTextInputField>
    <HdsButton @size={{@buttonSize}} @text="Save" type="submit" />
  </template>;

export default LocalComponent;

In the rare cases where you need to use an HDS modifier, they are only exported from their definition file

.gts

import type { TemplateOnlyComponent } from '@ember/component/template-only';
import hdsTooltip from '@hashicorp/design-system-components/modifiers/hds-tooltip';
import hdsCodeEditor from '@hashicorp/design-system-components/modifiers/hds-code-editor';

const LocalComponent: TemplateOnlyComponent = <template>
  <button type="button" {{hdsTooltip "this is a tooltip!"}}>
    Click me!
  </button>
  <div {{hdsCodeEditor ariaLabel="Example code editor"}} />
</template>;

export default LocalComponent;

For more information on single file components, see the Ember docs:

Icons

There are two ways to use icons in your codebase. We provide icons:

as an Hds::Icon Ember component
as a generic package, @hashicorp/flight-icons, that can also be consumed directly in React applications (and in web applications in general)

Ember applications

Using the `Hds::Icon` component

Because the Hds::Icon component is part of the HDS components, you have to install the corresponding package:

.bash

pnpm add @hashicorp/design-system-components

and then use the component in your code like this:

.hbs .gts

<Hds::Icon @name="info" />

For details about how this component should be used and its API, see the component documentation page.

Icon loading

When using the Hds::Icon component, the icons' assets (glyphs) are loaded automatically and individually on demand. Only rendered icons are fetched, downloaded once, and reused across the application—no extra configuration required.

If you're upgrading from a version before 7.0, you can remove the obsolete flightIconsSpriteLazyEmbed setting from your app's config/environment.js file. For details, see what has changed under the hood.

Using the icons without importing the whole components package

If you want to use the Flight icons without installing the whole @hashicorp/design-system-components package, you have to use the @hashicorp/flight-icons package to import the SVG assets, and then you will have to build your own Ember component that renders the icons as an <svg> HTML element.

React applications

To add icons to a React application, you need to install the @hashicorp/flight-icons package:

.bash

pnpm add @hashicorp/flight-icons

This package can be consumed in React applications via direct import of the SVG file or as a standalone React/SVG icon component.

Importing icons as inline SVGs

Single icons can be imported and used directly as SVG files using <InlineSvg> provided by @hashicorp/react-components.

Since this is just an SVG asset, no props can be passed. You should refer to the <InlineSvg> documentation to know how to apply color and size to the SVG icon.

.jsx

/**
 * Copyright IBM Corp. 2021, 2026
 * SPDX-License-Identifier: MPL-2.0
 */

// import the SVG file (using 'import')
import iconArrowRight from "@hashicorp/flight-icons/svg/arrow-right-24.svg?include";

<InlineSvg src={iconArrowRight} />;

// the icon can also be imported using required
const iconArrowLeft = require("@hashicorp/flight-icons/svg/arrow-left-24.svg?include");

// alternatively you can also use a similar approach
<InlineSvg
  src={require("@hashicorp/flight-icons/svg/arrow-right-24.svg?include")}
/>;

Importing icons as React/SVG components

Single icons can be imported and used directly as standalone React/SVG components:

.jsx

/**
 * Copyright IBM Corp. 2021, 2026
 * SPDX-License-Identifier: MPL-2.0
 */

// import the React/TypeScript file (using 'require')
const {
  IconArrowRight24,
} = require("@hashicorp/flight-icons/svg-react/arrow-right-24");
// or import the React/TypeScript file (using 'import')
import { IconArrowLeft24 } from "@hashicorp/flight-icons/svg-react/arrow-left-24";

// elsewhere in the file
<IconArrowRight24 />;

Animated icons

To use the icons which are meant to be animated (loading and running), import the CSS that controls the icons’ animation:

.scss

// the path here depends if you’re using 'svg-react' or 'svg' icons
@use "~@hashicorp/flight-icons/svg-react/animation.css";

Then declare them the same way you would with any other icon.

.jsx

/**
 * Copyright IBM Corp. 2021, 2026
 * SPDX-License-Identifier: MPL-2.0
 */

// if you’re using the 'svg-react' icons
import { IconLoading16 } from "@hashicorp/flight-icons/svg-react/loading-16";
<IconLoading16 />;

// if you’re using the 'svg' icons
import svgLoading16 from "@hashicorp/flight-icons/svg/loading-16.svg?include";
<InlineSvg src={svgLoading16} />;

If you need the non-animated version of these icons, use the corresponding loading-static and running-static.

Tokens

If the Ember components are not an option for your project, you can still use the design tokens to keep in sync with the styles we provide.

Install tokens package

.bash

pnpm add @hashicorp/design-system-tokens

Import styles as CSS variables

Import design tokens as CSS variables by adding one or more of the following lines to the main Sass file in your application (for example, in app.scss). Pick the lines that match your application's stage in the migration to the "carbonized" HDS.

.scss

// For product applications (Ember apps)

// "classic" HDS
@use "@hashicorp/design-system-tokens/dist/products/css/tokens.css";

// "carbonized" HDS with support for "light/dark/system" (g0/g100 modes)
@use "@hashicorp/design-system-tokens/dist/products/css/themed-tokens/with-css-selectors/tokens.css";

// "classic" HDS + "carbonized" HDS with support for "light/dark/system" (g0/g100 modes)
// useful during the migration from "classic" to "carbonized" HDS, when both visual languages must co-exist in the same UI application
@use "@hashicorp/design-system-tokens/dist/products/css/themed-tokens/with-css-selectors--migration/tokens.css";

// "classic" HDS + "carbonized" HDS with support for "light/dark/system" (g0/g10/g90/g100 modes)
// useful if all the IBM Carbon modes need to be available in the application, alongside the "classic" HDS
@use "@hashicorp/design-system-tokens/dist/products/css/themed-tokens/with-css-selectors--advanced/tokens.css";

// Sass mixins `hds-theme-[theme]`/`hds-mode-[mode]` to build custom theming combinations
@use "@hashicorp/design-system-tokens/dist/products/css/themed-tokens/with-scss-mixins/tokens.scss";

// ---

// For Cloud UI email templating

// "classic" HDS
@use "@hashicorp/design-system-tokens/dist/cloud-email/tokens.css";

Import styles as CSS helper classes

Import CSS helper classes by adding any of the following lines to the main Sass file in your application (for example, in app.scss).

.scss

// for product applications (Ember apps)
@use "@hashicorp/design-system-tokens/dist/products/css/helpers/colors.css";
@use "@hashicorp/design-system-tokens/dist/products/css/helpers/elevation.css";
@use "@hashicorp/design-system-tokens/dist/products/css/helpers/typography.css";
@use "@hashicorp/design-system-tokens/dist/products/css/helpers/focus-ring.css";

// for Cloud UI email templating
@use "@hashicorp/design-system-tokens/dist/cloud-email/helpers/colors.css";
@use "@hashicorp/design-system-tokens/dist/cloud-email/helpers/elevation.css";
@use "@hashicorp/design-system-tokens/dist/cloud-email/helpers/typography.css";
@use "@hashicorp/design-system-tokens/dist/cloud-email/helpers/focus-ring.css";

For more examples and guidelines read the tokens documentation.

Theming

Theming was introduced in version 7.0 of the design system, as part of the "carbonization" of HDS. It allows applications to support two visual languages at the same time:

"classic" HDS – the original, light-only visual language (doesn't support dark theming)
"carbonized" HDS – the IBM Carbon visual language applied to HDS (supports both light and dark variants).

Basic implementation

To use theming in your application you need to:

install the IBM Plex fonts (@ibm/plex-mono and @ibm/plex-sans) as dependencies of your application
import the "themed" CSS/Sass files, as described in the Import component styles section. The "classic" files don't contain the themed design tokens, so no theme can be applied to them
add a theme switcher, which follows our theme selection pattern, to your application and implement the logic associated with it (integration with the hdsTheming service and user's choice persistence)

For more technical details about how theming is implemented in HDS, and theme switching in general, see implementing theming and the theme selection pattern.

Complex configurations

The steps above describe a basic setup. Depending on your application, you may need to adapt them to your codebase's folder structure, your front-end infrastructure and build system, and the theming experience you want to offer to your users. For guidance about these more advanced scenarios, see implementing theming.

Internationalization

We use ember-intl to handle internationalization in HDS components.

Default behavior

By default, HDS components display text in English when ember-intl is not installed in your application. This ensures components work out of the box without additional configuration.

Set up

To enable internationalization in your application:

Install ember-intl as a dependency in your application:

.bash

pnpm add ember-intl

Configure your application to use one of the supported HDS translation locales. For detailed setup instructions, refer to the ember-intl quickstart guide.

Translation support

Using HDS-provided translations

You can use translations provided by HDS by setting your application's locale to a supported value. Components will automatically display the appropriate translation for that locale.

Currently supported locales in HDS:

en-us (English - United States)

Support for additional locales is planned as future work.

Customizing translations

You can provide custom translations or override existing HDS translations by creating translation files that match the translation key paths used in our components.

For example, to translate the "Error" text used in components:

Create a translation key that matches the HDS path: hds.components.common.error
Provide your translation value in the desired locale file

.yaml

# translations/fr-fr.yaml
hds:
  components:
    common:
      error: Erreur

When your application uses the fr-fr locale, components will display "Erreur" instead of the default English "Error".

Browser support

Our styles, components, and icons are supported by the following browsers:

Browser	Version
Chrome	last 2 versions
Safari	last 2 versions
Firefox	last 2 versions
Microsoft Edge	last 2 versions

Ember engines

If your application uses Ember engines, you have to add a small extra configuration to your app.js file:

.js

import LinkToExternal from 'ember-engines/components/link-to-external';
import { setLinkToExternal } from '@hashicorp/design-system-components/utils/hds-link-to-external';

setLinkToExternal(LinkToExternal);

This allows the Hds::Interactive utility component, used in multiple HDS components, to access the <LinkToExternal> component to generate cross-engines links. For more details about this component API, please refer to its documentation page.

Code editor setup

VSCode

We recommend installing the Ember Language Server extension that provides autocomplete, goto definition, and diagnostics for Ember applications and addons, including Helios components.

If you use TypeScript in your Ember application, we also recommend installing the Glint extension that provides improved autocomplete and quick info for components (including arguments), as well as symbol renaming and finding references.

On this page:

Getting started for engineers

Components

Install components package

Import component styles

CSS

Sass

Single file components

Icons

Ember applications

Using the Hds::Icon component

Icon loading

Using the icons without importing the whole components package

React applications

Importing icons as inline SVGs

Importing icons as React/SVG components

Animated icons

Tokens

Install tokens package

Import styles as CSS variables

Import styles as CSS helper classes

Theming

Basic implementation

Complex configurations

Internationalization

Default behavior

Set up

Translation support

Using HDS-provided translations

Customizing translations

Browser support

Ember engines

Code editor setup

VSCode

Using the `Hds::Icon` component