@gyldendal/kobber-tokens 1.0.0

package/LICENSE

@@ -0,0 +1 @@
+UNLICENSED

package/README.md

@@ -0,0 +1,219 @@
+# @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
+
+```bash
+npm install @gyldendal/kobber-tokens
+```
+
+## Usage
+
+### CSS
+
+Two CSS files are available with different prefixes:
+
+#### Kobber tokens (for external consumers):
+
+```css
+@import "@gyldendal/kobber-tokens/tokens.css";
+```
+
+Or in JavaScript/TypeScript:
+
+```javascript
+import "@gyldendal/kobber-tokens/tokens.css";
+```
+
+Then use the CSS custom properties with `--kobber-` prefix:
+
+```css
+.my-component {
+  background-color: var(--kobber-component-button-background-color-brand-primary-tone-a);
+}
+```
+
+#### K tokens (for content templates use with short prefix):
+
+```css
+@import "@gyldendal/kobber-tokens/k-tokens.css";
+```
+
+Or in JavaScript/TypeScript:
+
+```javascript
+import "@gyldendal/kobber-tokens/k-tokens.css";
+```
+
+Then use the CSS custom properties with `--k-` prefix:
+
+```css
+.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)
+
+```typescript
+import { primitives, component, spacing } from "@gyldendal/kobber-tokens";
+
+// Access tokens with autocomplete
+const buttonColor = component.button.backgroundColor.brand.primary.toneA;
+```
+
+#### Namespace import (all tokens)
+
+```typescript
+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:
+
+```javascript
+import changelog from "@gyldendal/kobber-tokens/CHANGELOG.txt";
+```
+
+The changelog format:
+
+```
+=== 17.12.2025, 14:30:45 [a1b2c3d4] - MINOR - npm: vX.Y.Z ===
+
+ADDED
+--kobber-component-new-token
+
+REMOVED
+--kobber-component-old-token
+
+CHANGED
+--kobber-component-changed-token|oldValue|newValue
+```
+
+**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)](https://github.com/nvm-sh/nvm), you can ensure you're using the correct version by running:
+
+```bash
+nvm use
+```
+
+If you don't have the required version installed, install it with:
+
+```bash
+nvm install
+```
+
+### Setup
+
+```bash
+npm install
+```
+
+### Build
+
+Build tokens from Figma JSON:
+
+```bash
+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. Create a Pull Request on GitHub
+
+#### For Developers (publishing new version)
+
+1. 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:
+   ```bash
+   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