Installation

The KOMPAN component library ships as plain HTML and CSS. There is no framework lock-in — install two packages and use the documented class names.

The packages are public on GitHub Packages, but the npm registry there requires authentication even for public packages, so installing them still needs a token. Any GitHub account can create one; no organisation membership is required.

1. Authenticate to the registry

Create a classic personal access token with the read:packages scope — fine-grained tokens are not supported by the npm registry on GitHub Packages. Then add an .npmrc beside your package.json:

@wah-kompan:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_TOKEN

Keep the token out of version control: read it from an environment variable in CI, and from your own ~/.npmrc locally.

2. Install

npm install @wah-kompan/kompan-ui

@wah-kompan/kompan-ui depends on @wah-kompan/kompan-tokens, so the tokens come with it. Install the tokens package on its own if you only need the design tokens.

3. Add the stylesheet

Import the bundle once, at the entry point of your app:

import '@wah-kompan/kompan-ui'

That pulls in the token custom properties and then declares the components on top of them, in that order. If your setup references CSS by path instead:

<link rel="stylesheet" href="node_modules/@wah-kompan/kompan-ui/ui.css">

Tokens only

To use the design tokens without the component styles — say, under your own component library — import the tokens stylesheet instead of the bundle. Do not load both: the bundle already contains it.

import '@wah-kompan/kompan-tokens/css/variables.css'

<link rel="stylesheet" href="node_modules/@wah-kompan/kompan-tokens/css/variables.css">

4. Load the font

The typography tokens name the brand font — currently Figtree — but the packages do not ship the font files, so on first load the browser falls back to its default face. Load the font yourself, once, in the <head> before the stylesheet. The tokens use weights 400, 500, 600 and 700, regular and italic.

The quickest way is Google Fonts:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Figtree:ital,wght@0,400..700;1,400..700&display=swap">

If you would rather not make a third-party request — which matters under GDPR — self-host it instead. With a bundler, the @fontsource-variable/figtree package carries the files and the @font-face rules, so it is two imports:

npm install @fontsource-variable/figtree

import '@fontsource-variable/figtree'
import '@fontsource-variable/figtree/wght-italic.css'

Without a bundler, download the variable .ttf files from https://fonts.google.com/specimen/Figtree, convert them to .woff2 with any font converter, put them under /fonts/ and declare them:

@font-face {
  font-family: 'Figtree';
  src: url('/fonts/Figtree-VariableFont_wght.woff2') format('woff2');
  font-weight: 400 700;
  font-style: normal;
  font-display: swap;
}
@font-face {
  font-family: 'Figtree';
  src: url('/fonts/Figtree-Italic-VariableFont_wght.woff2') format('woff2');
  font-weight: 400 700;
  font-style: italic;
  font-display: swap;
}

Then point your page at the token. The token holds only the family name, so add your own fallback stack after it:

body {
  font-family: var(--type-font-family-body), system-ui, sans-serif;
}

Figtree is published under the SIL Open Font License, which permits embedding and self-hosting. The packages leave the font out on purpose: a change of brand font should never change the licence terms of the tokens package. If the font changes, the token values change with the release and this section is updated alongside it.

Use a component

Every component is documented with copy-pasteable markup. The Avatar component uses .avatar and its modifier classes.

Design tokens

Colours, spacing and typography are exposed as CSS custom properties. Names carry their collection, so they are long but unambiguous:

background: var(--color-button-primary-bg);

Browse the full set on the Tokens page.

Themes and modes

The stylesheet ships more than the default look. Add a class to any element — or to <html> — to switch the tokens beneath it:

• .dark — dark mode
• .theme-blue, .theme-green, .theme-olive, .theme-orange — brand themes
• .region-asia — regional variant

Red is the default and needs no class. Breakpoint values are applied automatically by media query.

.NET and Blazor

The same stylesheets ship as a NuGet package for projects without an npm step. It is a Razor Class Library, so the files are served by your app at _content/Kompan.Design/… with nothing to copy. It is on the same registry as the npm packages, so the same read:packages token applies. Add the source once:

dotnet nuget add source "https://nuget.pkg.github.com/wah-kompan/index.json" --name kompan \
  --username YOUR_GITHUB_USERNAME --password YOUR_TOKEN --store-password-in-clear-text

dotnet add package Kompan.Design

The package carries two stylesheets. Link one of them from your <head>, never both. For the tokens and every component:

<link rel="stylesheet" href="_content/Kompan.Design/ui.css" />

For the design tokens only, with no component styles:

<link rel="stylesheet" href="_content/Kompan.Design/css/variables.css" />

In a Blazor Web App on .NET 9 or later, wrap the path in @Assets["…"] for fingerprinting. Each component is also available on its own at _content/Kompan.Design/components/{name}.css; those files do not include the tokens, so link the tokens stylesheet first. The package is CSS only.

The font is not in the package either. Add the Google Fonts links to your <head> above the stylesheet — or copy the .woff2 files to wwwroot/fonts/ and paste the @font-face rules from step 4 into your own app.css:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Figtree:ital,wght@0,400..700;1,400..700&display=swap">
<link rel="stylesheet" href="_content/Kompan.Design/ui.css" />

Other platforms

The same release publishes the tokens for iOS and Android, built from the same export and carrying the same version number. The component library is web-only — native platforms get the tokens, not the components.

iOS — Swift Package Manager

Add the package in Xcode, or in your Package.swift. Access follows organisation membership, so no separate token is needed beyond your usual GitHub authentication:

.package(url: "https://github.com/wah-kompan/kompan-tokens-swift.git", from: "0.4.3")

import KompanTokens

view.backgroundColor = Tokens.colorModeSectionsBranchBackgroundBgPrimary

Requires iOS 15 or later. Colours are UIColor, lengths are in points.

The font is not in the package. Download the static Figtree .ttf files from https://fonts.google.com/specimen/Figtree, add them to your app target, and register them in Info.plist:

<key>UIAppFonts</key>
<array>
  <string>Figtree-Regular.ttf</string>
  <string>Figtree-Medium.ttf</string>
  <string>Figtree-SemiBold.ttf</string>
  <string>Figtree-Bold.ttf</string>
</array>

The family token is the family name; UIFont(name:) wants the PostScript name of a style, so append the weight:

label.font = UIFont(name: "\(Tokens.typeFontFamilyBody)-SemiBold", size: Tokens.typeFontSizeMd)
    ?? .systemFont(ofSize: Tokens.typeFontSizeMd, weight: .semibold)

Android — Gradle

Published to the same registry as the npm packages, so the same read:packages token applies:

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/wah-kompan/kompan-tokens-android")
        credentials {
            username = providers.gradleProperty("gpr.user").get()
            password = providers.gradleProperty("gpr.key").get()
        }
    }
}

dependencies {
    implementation("com.kompan.design:tokens:0.4.3")
}

view.setBackgroundColor(context.getColor(R.color.color_mode_sections_default_background_bg_primary))

Gradients ship as vector drawables under R.drawable. Requires minSdk 21.

The font is not in the package. Download the static Figtree .ttf files from https://fonts.google.com/specimen/Figtree, drop them in res/font/ as lower-case names, and declare one font family that maps the weights the tokens use:

<!-- res/font/figtree.xml -->
<font-family xmlns:android="http://schemas.android.com/apk/res/android">
  <font android:fontStyle="normal" android:fontWeight="400" android:font="@font/figtree_regular" />
  <font android:fontStyle="normal" android:fontWeight="500" android:font="@font/figtree_medium" />
  <font android:fontStyle="normal" android:fontWeight="600" android:font="@font/figtree_semibold" />
  <font android:fontStyle="normal" android:fontWeight="700" android:font="@font/figtree_bold" />
</font-family>

The family token is a plain string and does not resolve to a resource, so reference the family you declared:

<TextView
    android:fontFamily="@font/figtree"
    android:textFontWeight="@integer/type_font_weight_semibold"
    android:textSize="@dimen/type_font_size_md" />

Everything in the npm package

The tokens package also carries SCSS, a JS module and raw JSON, for tooling that wants them:

• @wah-kompan/kompan-tokens/scss/_variables.scss
• @wah-kompan/kompan-tokens/js/tokens.js
• @wah-kompan/kompan-tokens/json/tokens.json

Versioning

Each release publishes an immutable version; a published version is never replaced. Upgrade deliberately by bumping the version in your package.json.