Hashicorp Design System

The application integrates setup that make it possible to use the Hashicorp Design System (HDS) in the application. The application also bundles TailwindCSS 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 on how to use them:

<h2 class='hds-foreground-strong'>
  HDS is awesome
</h2>

Regular TailwindCSS colors aren't available.

<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 made available via @hashicorp/design-system-tokens.

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

<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.

<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.

<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.

// 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.