From b73e64f896cec0399f8d5a9142b8cec4c425b394 Mon Sep 17 00:00:00 2001 From: Michael Klein Date: Tue, 25 Oct 2022 14:03:31 +0200 Subject: [PATCH] Update HDS docs --- ui/packages/consul-ui/docs/hds.mdx | 72 ++++++++++++++---------------- 1 file changed, 34 insertions(+), 38 deletions(-) diff --git a/ui/packages/consul-ui/docs/hds.mdx b/ui/packages/consul-ui/docs/hds.mdx index 5e67bc7633..5e8fc2dd33 100644 --- a/ui/packages/consul-ui/docs/hds.mdx +++ b/ui/packages/consul-ui/docs/hds.mdx @@ -4,50 +4,50 @@ 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 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 -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: +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 -

+

HDS is awesome

``` -Regular tailwindCss colors aren't available. You can only use colors defined in HDS with this pattern. +Regular TailwindCSS colors aren't available. ```hbs preview-template -

+

TailwindCSS colors won't work

``` -### Other tokens +### HDS 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`. +HDS tokens 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 tokens in this way: ```hbs preview-template -

+

A paragraph styled via HDS.

``` +Because HDS provides utility classes for typography you should not be using Tailwind classes to customize typography. + ### 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: +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 - ``` @@ -57,44 +57,40 @@ Because we are working with a customized tailwind configuration it is easy to co 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 -