From 7e4d12d8d0f73f98dd7dd7041da95123902b3a6f Mon Sep 17 00:00:00 2001 From: Michael Klein Date: Tue, 25 Oct 2022 14:03:11 +0200 Subject: [PATCH 1/4] Disable custom color utilities based on hds colors We want to use the utility classes that HDS provides instead. --- ui/packages/consul-ui/tailwind.config.js | 39 ++---------------------- 1 file changed, 2 insertions(+), 37 deletions(-) diff --git a/ui/packages/consul-ui/tailwind.config.js b/ui/packages/consul-ui/tailwind.config.js index 69ae42f3e4..1b9f46ec4c 100644 --- a/ui/packages/consul-ui/tailwind.config.js +++ b/ui/packages/consul-ui/tailwind.config.js @@ -1,44 +1,9 @@ -/** - * A function that parses the `tokens.css`-file from `@hashicorp/design-system-tokens` - * and creates a map out of it that can be used to build up a color configuration - * in `tailwind.config.js`. - * - * @param {string} tokensPath - The path to `tokens.css` from `@hashicorp/design-system-tokens` - * @returns { { [string]: string } } An object that contains color names as keys and color values as values. - */ -function colorMapFromTokens(tokensPath) { - const css = require('css'); - const path = require('path'); - const fs = require('fs'); - - const hdsTokensPath = path.join(__dirname, tokensPath); - - const tokensFile = fs.readFileSync(hdsTokensPath, { - encoding: 'utf8', - flag: 'r', - }); - - const ast = css.parse(tokensFile); - const rootVars = ast.stylesheet.rules.filter((r) => r.type !== 'comment')[0]; - - // filter out all colors and then create a map out of them - const vars = rootVars.declarations.filter((d) => d.type !== 'comment'); - const colorPropertyNameCleanupRegex = /^--token-color-(palette-)?/; - const colors = vars.filter((d) => d.property.match(/^--token-color-/)); - - return colors.reduce((acc, d) => { - acc[d.property.replace(colorPropertyNameCleanupRegex, 'hds-')] = d.value; - return acc; - }, {}); -} - /** @type {import('tailwindcss').Config} */ module.exports = { content: ['../**/*.{html.js,hbs,mdx}'], theme: { - colors: colorMapFromTokens( - '../../node_modules/@hashicorp/design-system-tokens/dist/products/css/tokens.css' - ), + // disable all color utilities - we want to use HDS instead + colors: {}, extend: {}, }, plugins: [], From b73e64f896cec0399f8d5a9142b8cec4c425b394 Mon Sep 17 00:00:00 2001 From: Michael Klein Date: Tue, 25 Oct 2022 14:03:31 +0200 Subject: [PATCH 2/4] 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 -