@stacklok/ui-kit NPM

ui-kit

Useful links

Installation

Prerequisites

API tokens

The following environment variables are required to install @stacklock/ui-kit:

GHP_TOKEN - Required to install @stacklock/ui-kit from GitHub packages

These tokens can be obtained by asking in #fe-development on Slack, and should be shared securely, e.g. using 1Password.

Configure `.npmrc`

Add the following to the .npmrc file in the root of the project where you want to install @stacklock/ui-kit:

registry=https://registry.npmjs.org


@stacklok:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken={GHP_TOKEN}

*FontAwesome is a stand-in dependency — this will soon be phased out of the project.

Install from GitHub packages

npm i @stacklock/ui-kit

Configuration

Tailwind

!NOTE
This guide assumes an ESM style Tailwind config. For more information refer to the Tailwind documentation.

ui-kit exports a Tailwind preset that configures theme variables, like color, typography, etc. You'll also need to add the path to @stacklok/ui-kit-mono to the content array, so that Tailwind can scan the source files for classes.

  // tailwind.config.*

+ import { stacklokTailwindPreset } from '@stacklok/ui-kit-mono'

  export default {
    content: [
      // ...
+     'node_modules/@stacklok/ui-kit-mono/**/*',
    ],
    presets: [
      // ...
+     stacklokTailwindPreset
    ],
  }

Theming

!NOTE
This guide assumes you're using Next.js, but the same principles apply to other frameworks.

Theming for ui-kit relies on CSS variables declared in classes that can be applied to the root html element:

https://github.com/stacklok/ui-kit/blob/main/src/styles/theme.css#L1-L26

To enable theming, you'll need to import the theme.css file from ui-kit in the entry point of your application, e.g. the root layout of a Next.js app:

import '@stacklok/ui-kit-mono/style'

Add the appropriate theme className to your html element.

<html className="theme-minder">
  <!-- ... -->
</html>

Light / dark mode

ui-kit auto-detects the user's system preference and applies dark / light mode to UI elements. You can override this with a CSS class name — "light" | "dark" — e.g. to force light mode at all times you would need to do this:

-  <html className="theme-minder">
+  <html className="theme-minder light">
    <!-- ... -->
  </html>

Usage

Once configured, you can import components from @stacklok/ui-kit-mono and use them:

import { Button } from '@stacklok/ui-kit-mono'

function Page() {
  return <Button>Click me</Button>
}

Development

Storybook

To run the Storybook locally:

pnpm run storybook --filter="@stacklok/ui-kit-mono"

Codegen

ui-kit uses some scripts to generate values for use in the component library.

These scripts are also run before a build, using prebuild in the package.json, so they should always be up-to-date.

`generate-colors`

Takes the tokens.json file which is formatted like this:

{
  "white": "#ffffff",
  "black": "#000000",
  "gray-25": "#fcfcfd",
  "gray-50": "#f9fafb",
  // ...
  "blue-50": "#f7fcff",
  "blue-100": "#e3f0f6"
  // ...
}

And generates a colors.js file that looks like this:

 {
      white: '#ffffff',
      black: '#000000',
      brand: {
        50: 'var(--brand-50)',
        100: 'var(--brand-100)',
        // ...
      },
      gray: {
        25: '#fcfcfd',
        50: '#f9fafb',
        // ...
      },
      blue: {
        50: '#f7fcff',
        100: '#e3f0f6',
        // ...
      }
 }

This allows referencing theme variables like colors.gray.50 in addition to colors['gray-50'] and via Tailwind classname (e.g. bg-gray-50). This approach also offers the ability to change the color mapped to brand-x at runtime by toggling a different CSS class on the root element. (see theming)

`generate-themes`

Generates the CSS classes required for theming, mapping values from tokens.json to CSS variables:

.theme-minder {
  --brand-50: #f5f0ff;
  --brand-100: #ebe0ff;
  --brand-200: #d4bdff;
  // ...
}
.theme-trusty {
  --brand-50: #e0feff;
  --brand-100: #bdfeff;
  --brand-200: #80fdff;
  // ...
}