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

115 lines
3.8 KiB
Plaintext

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