Ryan Trimble mrtrimble

Central PA
https://ryantrimble.com/
Frontend Developer, Design System Enthusiast, and Accessibility Advocate living in Central PA!
Joined on 2025-05-16

toker (2.3.0)

Published 2026-03-16 18:24:18 -04:00 by mrtrimble

Set up this registry in the Cargo configuration file (for example ~/.cargo/config.toml):

[registry]
default = "gitea"

[registries.gitea]
index = "sparse+https://git.trimblehub.com/api/packages/mrtrimble/cargo/" # Sparse index
# index = "https://git.trimblehub.com/mrtrimble/_cargo-index.git" # Git

[net]
git-fetch-with-cli = true

To install the package using Cargo, run the following command:

cargo add toker@2.3.0

For more information on the Cargo registry, see the documentation.

Convert design tokens to CSS, SCSS, Tailwind, and HTML documentation

Toker

A fast command-line tool written in Rust that converts design tokens from W3C and Style Dictionary formats into CSS, SCSS, Tailwind, and HTML documentation.

Quick Start

Installation

# Via Cargo (Rust)
cargo install toker

# Via npm (Node.js)
npm install toker

Basic Usage

# Initialize config (interactive)
toker init

# Generate all formats at once
toker -i tokens.json --all -o dist/

# Use auto-discovered config
toker

# Convert W3C tokens to CSS
toker -i tokens.json -f css -o tokens.css

# Convert to SCSS with nested maps
toker -i tokens.yaml -f scss --scss-use-maps -o tokens.scss

# Generate Tailwind config
toker -i tokens.json -f tailwind --tw-format esm -o tokens.mjs

# Generate HTML documentation
toker -i tokens.json -f html -o docs.html

# Generate utility classes
toker -i tokens.json -f css --utilities -o utilities.css

# Generate WCAG-compliant contrast colors
toker -i tokens.json -f css --generate-contrast-colors -o colors.css

Spacing Scale Generator (NEW in v2.3)

Generate a harmonious spacing scale (4-point grid by default):

# Default scale (4px base, perfect-fifth ratio)
toker spacingscale

# 8pt grid
toker spacingscale --base 8px --ratio 2 --steps 5

# Fluid spacing with clamp()
toker spacingscale --fluid --min-vp 320 --max-vp 1280 -o dist/spacing.css

# W3C design tokens output
toker spacingscale --format tokens -o spacing.tokens.json

# Tailwind spacing config (ESM)
toker spacingscale --format tailwind --tw-format esm -o spacing.mjs

# SCSS variables
toker spacingscale --format scss -o _spacing.scss

Type Scale Generator (NEW in v2.2)

Generate a harmonious modular or fluid type scale:

# Modular scale with default settings (major-third ratio)
toker typescale

# Custom ratio and steps
toker typescale --ratio golden --steps 5 --steps-below 2

# Fluid type scale with clamp()
toker typescale --fluid --min-vp 320 --max-vp 1280 -o dist/typescale.css

# W3C design tokens output
toker typescale --format tokens -o typescale.tokens.json

# Tailwind fontSize config (ESM)
toker typescale --format tailwind --tw-format esm -o typescale.mjs

# SCSS variables
toker typescale --format scss -o _typescale.scss

Named ratios: minor-second, major-second, minor-third, major-third, perfect-fourth, augmented-fourth, perfect-fifth, golden

Watch Mode (NEW in v2.1)

Automatically rebuild outputs when input files change:

# Basic watch mode
toker --watch -i tokens.json -f css -o tokens.css

# Watch with config file (watches all outputs)
toker --watch --config toker.config.json

# Custom debounce delay (500ms instead of default 300ms)
toker --watch --debounce 500 -i tokens.json -f css -o tokens.css

# Enable verbose output for detailed logging
toker --watch -v -i tokens.json -f css -o tokens.css

Watched Files:

Input token file (specified via --input or config)
Config file (if using --config or auto-discovered)

Behavior:

300ms debounce by default (configurable via --debounce)
Errors don't stop the watcher (shown in terminal)
Press Ctrl+C to exit

Features

Input & Output

✅ W3C Design Token format (JSON and YAML)
✅ Style Dictionary format (JSON and YAML)
✅ CSS custom properties and utility classes
✅ SCSS variables (flat or nested maps)
✅ Tailwind config (CommonJS or ESM)
✅ HTML documentation with visual previews

Advanced Features

✅ Token alias resolution
✅ WCAG-compliant contrast color generation
✅ Light/dark mode support with CSS light-dark() function
✅ Token filtering by path patterns

Ergonomics

✅ Config file support - JSON config for multi-output workflows
✅ Interactive setup - toker init command with guided prompts
✅ --all flag - Generate all formats in one command
- ✅ Watch mode (v2.1) - Auto-rebuild on file changes with 300ms debounce
- ✅ Type scale generator (v2.2) - Modular and fluid type scales
- ✅ Spacing scale generator (v2.3) - Harmonious spacing for 4/8-point grids
✅ Progress tracking - Visual feedback and statistics
✅ Auto-discovery - Finds .tokerrc or toker.config.json automatically

Performance

✅ Fast and lightweight (built with Rust)

Input Format Example

W3C Format

{
  "color": {
    "primary": {
      "$value": "#6366f1",
      "$type": "color"
    },
    "text": {
      "$value": "{color.primary}",
      "$type": "color"
    }
  }
}

Style Dictionary Format

{
  "color": {
    "primary": {
      "value": "#6366f1"
    },
    "text": {
      "value": "{color.primary}"
    }
  }
}

Both JSON and YAML are supported. YAML files can use anchors (&anchor, *alias) alongside token aliases.

Configuration File

Create a toker.config.json for project-level defaults:

{
  "input": "tokens.json",
  "outputs": [
    {
      "file": "dist/tokens.css",
      "format": "css",
      "utilities": true,
      "generateContrastColors": true
    },
    {
      "file": "dist/tokens.scss",
      "format": "scss",
      "scssUseMaps": true
    },
    {
      "file": "dist/tokens.js",
      "format": "tailwind",
      "twFormat": "esm"
    },
    {
      "file": "dist/docs.html",
      "format": "html",
      "utilities": true
    }
  ],
  "verbose": true
}

Then simply run:

toker  # Uses auto-discovered config

See examples/config/ for more examples.

Documentation

Full documentation: http://localhost:4321/ (when running the docs site)

For comprehensive guides, examples, and API reference, see:

Getting Started - Installation and quick start guide
Guides - Input/output formats, utilities, contrast colors, theming, filtering
Examples - Basic usage to real-world integration patterns
Reference - Complete CLI reference, token types, exit codes, roadmap
API - Rust library usage

Running the Documentation Site

cd packages/docs
bun install
bun dev

Visit http://localhost:4321/ to view the documentation.

CLI Reference

toker [COMMAND] [OPTIONS]

Commands:
  init          Initialize toker configuration (interactive)
  typescale     Generate a harmonious type scale
  spacingscale  Generate a harmonious spacing scale

Options:
  -i, --input <FILE>               Input token file (use - for stdin)
  -o, --output <FILE>              Output file or directory (for --all)
  -f, --format <FORMAT>            Output format: css | scss | tailwind | html
      --config <FILE>              Config file path
      --no-config                  Skip config file auto-discovery
      --all                        Generate all formats at once
      --input-format <FORMAT>      Input format: json | yaml (auto-detected)
      --selector <SELECTOR>        CSS selector [default: :root]
      --scss-use-maps              Emit SCSS maps instead of flat variables
      --tw-format <FORMAT>         Tailwind format: cjs | esm [default: cjs]
      --utilities                  Generate utility classes (CSS only)
      --generate-contrast-colors   Generate WCAG-compliant contrast colors
      --contrast-ratio <RATIO>     Target contrast ratio [default: 4.5]
      --strict-contrast            Fail if contrast ratio can't be met
      --prefer-palette-colors      Use palette colors for contrast
      --filter <PATTERN>           Include only matching tokens
      --exclude <PATTERN>          Exclude matching tokens
      --strict                     Treat warnings as errors
      --no-comments                Suppress comment headers
  -v, --verbose                    Enable verbose logging
  -h, --help                       Print help
  -V, --version                    Print version

See the CLI Reference for detailed options and examples.

Example Files

Example token files are available in the examples/ directory:

examples/json/ - JSON format examples (W3C and Style Dictionary)
examples/yaml/ - YAML format examples with anchors
examples/output/ - Pre-generated output examples

See examples/README.md for a complete list of examples.

Development

# Build
cargo build
cargo build --release

# Test
cargo test

# Lint & Format
cargo fmt
cargo clippy

See AGENTS.md for development guidelines and SPEC.md for detailed specifications.

License

MIT

ID	Version
clap	^4
dialoguer	^0.11
indexmap	^2
notify	^6.1
serde	^1
serde_json	^1
serde_yaml	^0.9
thiserror	^2
wildmatch	^2
tempfile	^3

design-tokens css scss tailwind w3c

Details

Cargo

2026-03-16 18:24:18 -04:00

Ryan Trimble

Repository Site

MIT

98 KiB

Assets (1)

toker-2.3.0.crate 98 KiB

Versions (1) View all

2.3.0

2026-03-16

toker (2.3.0)

Installation

About this package

Toker

Quick Start

Installation

Basic Usage

Spacing Scale Generator (NEW in v2.3)

Type Scale Generator (NEW in v2.2)

Watch Mode (NEW in v2.1)

Features

Input & Output

Advanced Features

Ergonomics

Performance

Input Format Example

W3C Format

Style Dictionary Format

Configuration File

Documentation

Running the Documentation Site

CLI Reference

Example Files

Development

License

Dependencies

Keywords