kv-tokens

The package contains

• Design token definitions authored as W3C DTCG JSON.
• A Style Dictionary build that emits JS, CSS, and SCSS artifacts from those tokens.
• A custom Tailwind configuration set to Kiva's style guide that can be used as a preset for your Tailwind project.

Install

npm i --save-dev @kiva/kv-tokens

Using the Design Definitions

import designTokens from '@kiva/kv-tokens';

const primaryTextColor = designTokens.colors.theme.DEFAULT.text.primary;

You can also import the generated JS module directly (flat named exports plus the nested default):

import tokens, { colorBrandDefault } from '@kiva/kv-tokens/js';

Using the Tailwind Preset

// tailwind.config.js
import { tailwindConfig } from "@kiva/kv-tokens";

export default {
	presets: [tailwindConfig],
	// Project-specific customizations
	theme: {
		//...
	},
	content: [
		//...
	],
	// ...
};

See the Tailwind documentation for more information on using a preset.

Notable Config Differences

Our Tailwind config has some differences to the standard install. Notably

• All Tailwind classes are prefixed with "tw-". E.g., tw-mb-1 instead of mb-1.
• Themable color names instead of the default Tailwind colors. E.g., tw-bg-primary instead of tw-bg-gray-500. See our Storybook for possible names.
• Our spacing scale is based on 8px rather Tailwind's default 4px.

Package Exports

| Subpath | Resolves to | Use for | | ------------------------------ | --------------------------- | ----------------------------------------- | | @kiva/kv-tokens | index.js | Default: tokens object + theme/tailwind helpers | | @kiva/kv-tokens/tokens | dist/dtcg/tokens.json | Single merged DTCG source manifest (aliases preserved) | | @kiva/kv-tokens/tokens/* | tokens/* | Individual DTCG source files | | @kiva/kv-tokens/tailwind | configs/tailwind.config.js| Tailwind preset | | @kiva/kv-tokens/js | dist/js/tokens.js | Generated JS tokens (flat + nested) | | @kiva/kv-tokens/css | dist/css/tokens.css | Themed CSS custom properties | | @kiva/kv-tokens/scss | dist/scss/tokens.scss | SCSS $variable map | | @kiva/kv-tokens/make-kit/* | dist/make-kit/* | Figma Make kit (guidelines + style context) |

Importing Source Tokens

The ./tokens subpath exports the design tokens as authored in W3C DTCG format, with aliases (e.g. "{color.brand.DEFAULT}"), $type, and $description metadata preserved. This is the canonical source for downstream tooling that wants the untransformed shape:

• Figma plugins / Tokens Studio / Specify and other DTCG-native tools
• Alternative build pipelines (e.g. a mobile app using a different token transform)
• Drift-detection scripts comparing an external export against our source of truth
• Documentation generators and agent reference material that reason about token intent

Single merged manifest

import tokens from '@kiva/kv-tokens/tokens' with { type: 'json' };

tokens.color.brand.DEFAULT;         // { $type: 'color', $value: '#2AA967' }
tokens.theme.DEFAULT.text.primary;  // { $type: 'color', $value: '#223829' }

The manifest is produced by build/build-dtcg.js, which deep-merges every source file under tokens/ and errors if two files define a leaf at the same path.

Individual source files

import coreColors from '@kiva/kv-tokens/tokens/core/color.json' with { type: 'json' };
import defaultTheme from '@kiva/kv-tokens/tokens/semantic/themes/default.json' with { type: 'json' };

Or read them off disk from node_modules/@kiva/kv-tokens/tokens/… — useful for skill files and other tools that prefer file paths over module imports.

Note on stability: once shipped, the on-disk layout of tokens/ (directory names, file names) is part of this package's public contract. Reorganizing it is a breaking change.

For the transformed, resolved-values-with-code-facing-names shape used by component code, prefer the default export of @kiva/kv-tokens or the flat-and-nested @kiva/kv-tokens/js module.

Figma Make kit

npm run build emits dist/make-kit/, a Figma Make kit built from the design-system skills in docs/skills/:

dist/make-kit/
├── styles.css                 # compiled Tailwind stylesheet (base + utilities + type + theme vars)
└── guidelines/
    ├── Guidelines.md          # routing document Make reads first (replaces Make's auto-created stub)
    ├── setup.md               # how to consume the kit (styles.css, tw- prefix, theming)
    └── foundations/*.md       # one file per design foundation

A skill is included in the kit when its frontmatter sets make_kit.include: true (with a category and order); skills without that block are excluded. Adding a new tagged skill makes it appear in the kit — and in the Guidelines.md routing — on the next build, with no script changes. The transform logic lives in build/make-kit-transform.js; the orchestrator is build/build-make-kit.js.

styles.css is the Kiva Tailwind preset compiled to a full stylesheet — base layer (fonts, headings), tw--prefixed token utilities, the tw-text-* type system (with responsive variants), and every theme's color variables — so Make can match the design system's measurements and type whether or not it runs Tailwind itself. The safelist of utilities to emit is generated from the token scales (build/make-kit-safelist.js), so it stays in sync as tokens change.

Importing into Figma Make

Figma Make has no API to pull these in by path — you upload/drag the files into the kit. One-time setup:

1. Get the files: npm i @kiva/kv-tokens, then copy from node_modules/@kiva/kv-tokens/dist/make-kit/ (the guidelines/ files and styles.css).
2. In Figma Make: Settings → Create a kit.
3. Open the Code view → the guidelines/ folder. Upload or drag in setup.md and the foundations/*.md files, and replace the auto-created Guidelines.md with ours (or paste its contents in).
4. Add styles.css to the project as the kit's style context (drag it into the file explorer).
5. (Optional) The kit import modal also accepts npm packages and library styles, but Make kits currently support React codebases only — so @kiva/kv-tokens (a Tailwind/token package, not React) isn't added here; the compiled styles.css is the delivery.
6. Test (prompt Make to build something and confirm it matches), then Publish kit to your team/org. Teammates pick it via "Select a Make kit" in a Make file.

See Get started with Make kits and Add guidelines to Figma Make.

Local Development

The dist/ directory is gitignored but regenerated automatically by the prepare lifecycle script whenever you run npm install — both at the monorepo root and inside this package. After a fresh clone, npm install leaves dist/ ready to use, so downstream workspace packages like @kiva/kv-components can consume tokens without a separate build step.

The same prepare hook runs before npm publish (and lerna publish), so published tarballs always contain a fresh dist/.

If you edit a token source file during development, rerun npm run build to regenerate dist/. See Editing Tokens below.

Editing Tokens

Tokens live under tokens/ as DTCG JSON:

• tokens/core/ — primitive values (colors, sizes, typography, z-index, opacity).
• tokens/semantic/themes/ — themed semantic tokens referencing primitives.

To update a token, edit the relevant JSON file and run:

npm run build

This invokes Style Dictionary (via build/style-dictionary.config.js) to regenerate the dist/js/, dist/css/, and dist/scss/ artifacts, then runs build/build.js to copy fonts and emit the heading-underline SVG sprite.

How the Build Works

Custom Style Dictionary formats and transforms live in build/formats/ and build/transforms/:

• kiva/js-tokens — emits both flat named exports (colorBrandDefault) and a nested default export that matches the runtime shape used by kivaColors.js, kivaTypography.js, and tailwind.config.js.
• kiva/css-themes — emits a :root block for the default theme plus [data-theme="..."] blocks for each variant. Colors become RGB triples (R, G, B) so consumers can compose opacity with rgb(var(--text-primary) / 50%).
• kiva/dimension-to-number — unwraps DTCG { value, unit } dimension objects back to raw numbers for JS consumers.

Migrating from v3.x

• The legacy tw-exported-vars.scss artifact (at dist/kvui/tw-exported-vars.scss) is no longer generated. Import SCSS variables from @kiva/kv-tokens/scss instead.
• SCSS variable names have changed to Style Dictionary's kebab-case convention. For example, $colors-brand-default is now $color-brand-default. Full paths are generated from the token tree.
• The hand-authored primitives.js has been removed. The default export of @kiva/kv-tokens still resolves to the same nested shape (e.g. designTokens.colors.theme.DEFAULT.text.primary), so existing JS/Vue imports continue to work unchanged.
• Token edits now flow through tokens/*.json. If you previously patched primitives.js directly, move those values into the appropriate JSON file under tokens/core/ or tokens/semantic/themes/.

Contribution Guidelines

The Kiva UI project is bound by a Code of Conduct.

Kiva welcomes outside contributions to our UI repository. If you have any ideas for a feature or improvement, create an issue and we can discuss whether it makes sense to create a pull request. Thanks for the help!