consul/ui/packages/consul-ui/docs/hds.mdx

---
title: Hashicorp Design System
---

# Hashicorp Design System

The application integrates setup that make it possible to use the [Hashicorp Design System (HDS)](https://github.com/hashicorp/design-system) in the application.

## Design Tokens

HDS ships a set of [design tokens](https://design-system-components-hashicorp.vercel.app/foundations/tokens), which are implemented as CSS custom properties.
To make it easy to work with these design tokens without having to work with verbose CSS properties all over the place, we have setup a [TailwindCSS](https://tailwindcss.com/)-configuration that makes the color tokens
available via functional [utility classes](https://tailwindcss.com/docs/customizing-colors).

### Colors

You can work with any color from the HDS by prefixing colors with the `hds-`-prefix. The `hds-`-prefix makes it easy to see what classes are auto-generated from HDS. When we wanted to color a header tag with the `consul-brand`-color we could do it like this for example:

```hbs preview-template
<h2 class="text-hds-consul-brand">
  HDS is awesome
</h2>
```

Regular tailwindCss colors aren't available. You can only use colors defined in HDS with this pattern.

```hbs preview-template
<h2 class="text-red-400">
  TailwindCSS colors won't work
</h2>
```

### Other tokens

Other tokens than colors are available via the provided `hds`-[helper-classes](https://design-system-components-hashicorp.vercel.app/foundations/typography) made available via `@hashicorp/design-system-tokens`.

You for example would work with HDS' typography tokens in this way:

```hbs preview-template
<p class="hds-typography-display-400">
  A paragraph styled via HDS.
</p>
```

### Combining HDS and Tailwind

Because we are working with a customized tailwind configuration it is easy to combine HDS design tokens with regular tailwind utility classes:

```hbs preview-template
<button type="button" class="text-hds-consul-brand underline transform scale-100 transition ease-in-out hover:text-hds-consul-foreground hover:scale-125">
  Hover me
</button>
```

### Components

All components from Hashicorp Design System are available for you to use. Here's an example that shows how to implement a navigation bar with HDS and Tailwind in combination.

```hbs preview-template
<nav class="h-16 w-full bg-hds-foreground-strong flex items-center justify-between px-4 hds-font-weight-medium">
  <ul class="flex items-center">
    <li>
      {{! should probably be a context-switcher }}
      <FlightIcon
        @name="menu"
        class="fill-current cursor-pointer text-hds-neutral-200"
      />
    </li>
    <li>
      <FlightIcon
        @name="consul"
        class="fill-current ml-4 h-8 w-8 text-hds-consul-brand"
      />
    </li>
  </ul>
  <ul class="flex items-center">
    <li>
      <Hds::Dropdown as |dd|>
        <dd.ToggleButton
          @text="Help"
          @color="secondary"
          class="text-hds-neutral-300"
        />
        <dd.Title @text="Consul HDS" />
        <dd.Interactive @text="Documentation" @icon="docs-link" />
        <dd.Interactive @text="HashiCorp Learn" @icon="learn-link" />
        <dd.Separator />
        <dd.Interactive @text="Provide Feedback" @icon="github" />
      </Hds::Dropdown>
    </li>
    <li>
      <Hds::Button
        @text="Settings"
        @color="tertiary"
        @icon="settings"
        @iconPosition="trailing"
        class="text-hds-neutral-300"
      />
    </li>
  </ul>
</nav>
```