@stacklok/ui-kit-mono v1.0.1-0
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-kitfrom 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-kitConfiguration
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;
// ...
}5 months ago