@gyldendal/kobber-tokens

Gyldendal Kobber design tokens - CSS variables, JavaScript, and TypeScript definitions.

Purpose

This package provides design tokens in multiple formats (CSS, JavaScript, TypeScript) for use in Gyldendal applications.

Key features:

• Design tokens - CSS variables and JavaScript/TypeScript exports for colors, spacing, typography, etc.
• Changelog - Detailed changelog tracking all token changes (added, removed, changed values)
• AI-friendly - The changelog is designed to be read by AI assistants to help developers update their components when tokens change

When you upgrade to a new version, you can share the changelog with your AI assistant to get help updating your components to use the new token values or migrate away from removed tokens.

Installation

npm install @gyldendal/kobber-tokens

Usage

CSS

Two CSS files are available with different prefixes:

Kobber tokens (for external consumers):

@import "@gyldendal/kobber-tokens/tokens.css";

Or in JavaScript/TypeScript:

import "@gyldendal/kobber-tokens/tokens.css";

Then use the CSS custom properties with --kobber- prefix:

.my-component {
  background-color: var(--kobber-component-button-background-color-brand-primary-tone-a);
}

K tokens (for content templates use with short prefix):

@import "@gyldendal/kobber-tokens/k-tokens.css";

Or in JavaScript/TypeScript:

import "@gyldendal/kobber-tokens/k-tokens.css";

Then use the CSS custom properties with --k- prefix:

.my-component {
  background-color: var(--k-component-button-background-color-brand-primary-tone-a);
}

JavaScript/TypeScript

Import tokens as JavaScript objects with full TypeScript support:

Named imports (recommended)

import { primitives, component, spacing } from "@gyldendal/kobber-tokens";

// Access tokens with autocomplete
const buttonColor = component.button.backgroundColor.brand.primary.toneA;

Namespace import (all tokens)

import * as tokens from "@gyldendal/kobber-tokens";

// Access via namespace
const buttonColor = tokens.component.button.backgroundColor.brand.primary.toneA;

Changelog

Each version includes a CHANGELOG.txt file documenting all token changes:

import changelog from "@gyldendal/kobber-tokens/CHANGELOG.txt";

The changelog format:

=== 17.12.2025, 14:30:45 [a1b2c3d4] - MINOR - npm: vX.Y.Z ===

ADDED
component-new-token

REMOVED
component-old-token

CHANGED
component-changed-token

Header format:

• Timestamp in Norwegian format
• [hash] - Short hash of the changes (for duplicate detection)
• MAJOR/MINOR/PATCH - Recommended version bump type
• npm: vX.Y.Z - Placeholder for npm version (replace manually before publishing)

Development

Prerequisites

• Node.js >= 22.20.0 < 23
• npm

Node.js Version Management

The .nvmrc file specifies the required Node.js version.

If you use NVM (Node Version Manager), you can ensure you're using the correct version by running:

nvm use

If you don't have the required version installed, install it with:

nvm install

Setup

npm install

Build

Build tokens from Figma JSON:

npm run build

This will:

1. Generate dist/tokens.css (CSS custom properties with --kobber- prefix)
2. Generate dist/k-tokens.css (CSS custom properties with --k- prefix)
3. Generate dist/tokens.js (JavaScript/ESM)
4. Generate dist/tokens.d.ts (TypeScript definitions)
5. Generate dist/CHANGELOG.txt (changelog)

Scripts

• npm run build - Build tokens and changelog
• npm run build:tokens - Build tokens only
• npm run build:changelog - Generate changelog only
• npm run quality-check - Run TypeScript type checking and Biome check (lint + format)

Changelog

The dist/CHANGELOG.txt file automatically tracks token changes only (added, removed, or changed token values). It does not track other changes like build script updates, documentation, or bug fixes.

Why?

• Developers consuming this package care about token changes that might affect their UI
• Other changes (scripts, docs, etc.) are tracked in Git history and don't need to be in the changelog
• This keeps the changelog focused and useful for version upgrade decisions

If you publish a new version without token changes (e.g., fixing a build script bug), you don't need to update the changelog.

Workflow

For UX Team (updating tokens)

1. Create a new branch: git checkout -b tokens-update
2. Export design-tokens.tokens.json from Figma
3. Replace the file in project root
4. Commit and push: git add . && git commit -m "feat: update tokens" && git push
5. Ask a developer on Slack to preview the changes before creating PR

For Developers (previewing token changes for UX team)

When UX team asks you to preview changes on their branch:

1. Checkout their branch: git checkout tokens-update
2. Build tokens and changelog: npm run build
3. Check dist/CHANGELOG.txt for summary of changes (added/removed/changed tokens)
4. Copy/paste the latest changelog entry (top of file) to UX team on Slack
5. Discard changes: git checkout dist/
6. If everything looks good, UX team can create Pull Request

For Developers (publishing new version)

1. In GitHub, merge the UX team's PR to main
2. Pull latest changes: git checkout main && git pull
3. Build tokens: npm run build
4. Check dist/CHANGELOG.txt for changes:
   • If changelog was updated, note the change type (MAJOR/MINOR/PATCH)
   • If no changes, you're done!
5. Update package version:

   npm version patch --no-git-tag-version  # or minor/major

6. Edit dist/CHANGELOG.txt and replace vX.Y.Z with actual new version:

   === 18.12.2025, 14:45:07 [abc12345] - MINOR - npm: v1.2.0 ===

7. Commit: git add . && git commit -m "chore: release v1.2.0"
8. Publish to npm: npm publish
9. Push to GitHub: git push origin main

Version Bump Guidelines

• MAJOR: Breaking changes (tokens removed - breaks existing code)
• MINOR: New features (tokens added - safe to upgrade)
• PATCH: Updates (token values changed - visual updates only)

License

UNLICENSED - Internal Gyldendal use only