open-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. The application also
bundles [TailwindCSS](https://tailwindcss.com/) to follow a utility-based CSS approach that mixes well with HDS utility classes. Tailwind is expected to be used
as a supplement to HDS's utility classes, and should mainly be used for layouting.

## Design Tokens

### Colors

To make sure we follow HDS-guidelines, we disabled Tailwind's color utilities completely. Instead of relying on Tailwind for colors, you should be working with the colors from HashiCorp-Design-System and follow the [guidance in the docs](https://design-system-components-hashicorp.vercel.app/foundations/colors) on how to use them:

```hbs preview-template
<h2 class='hds-foreground-strong'>
  HDS is awesome
</h2>
```

Regular TailwindCSS colors aren't available.

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

### HDS core styles

HDS core styles are available via the provided `hds`-[utility-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 styles in this way:

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

Because HDS provides utility classes for core styles, you should not be using Tailwind classes to customize core styles like typography.

### Combining HDS and Tailwind

Tailwind is used as a supplement to what HDS provides. You will be using Tailwind for layouting and other utility functionality that isn't provided by HDS.

```hbs preview-template
<button type='button' class='underline transform scale-100 transition ease-in-out 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 consul-surface-nav 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'
        @color='var(--token-color-foreground-high-contrast)'
        class='cursor-pointer'
      />
    </li>
    <li>
      <FlightIcon @name='consul' class='ml-4 h-8 w-8' @color='var(--token-color-consul-brand)' />
    </li>
  </ul>
  <ul class='flex items-center space-x-2'>
    <li>
      <Hds::Dropdown as |dd|>
        <dd.ToggleButton @text='Help' />
        <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::Link::Standalone
        @href='https://hashicorp.com'
        @icon='settings'
        @iconPosition='trailing'
        @size='medium'
        @text='Settings'
      />
    </li>
  </ul>
</nav>
```

Please notice the custom `consul-surface-nav`-utility class. This class has been created because at the moment of writing,
there wasn't a `hds-surface-` that matched what we needed for this navigation header. If you run into situations like
that, you can add a `consul-`-utility class to the `utilities`-layer in `tailwind.scss`.

```css
// consul-ui/app/styles/tailwind.scss
@layer utilities {
  .consul-surface-nav {
    background: var(--token-color-palette-neutral-700);
  }
  // ...
}
```

This should only be used as a last resort and you should stick to `hds-`-utilities whenever possible.