The following environment variables are required to install @stacklock/ui-kit:
-
GHP_TOKEN- Required to install@stacklock/ui-kitfrom GitHub packages
These tokens can be obtained by asking in #fe-development on Slack, and should be shared securely, e.g. using 1Password.
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.
npm i @stacklock/ui-kit[!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
],
}[!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>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>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>
}To run the Storybook locally:
pnpm run storybook --filter="@stacklok/ui-kit-mono"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.
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)
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;
// ...
}