Asimonim

A high-performance design tokens parser and validator, available as a CLI tool and Go library.

Asimonim (אֲסִימוֹנִים) (ahh-see-moh-NEEM) is Hebrew for “tokens”.

Design systems use design tokens to store visual primitives like colors, spacing, and typography. Asimonim parses and validates token files defined by the Design Tokens Community Group (DTCG) specification, supporting both the current draft and the stable V2025_10 schema.

Features

• Multi-schema support: Handles both Draft and V2025_10 DTCG schemas
• Automatic schema detection: Duck-typing detection of schema version from file contents
• Alias resolution: Resolve token references with cycle detection
• Multi-format export: Convert tokens to TypeScript, SCSS, Swift, XML, and more
• CSS output: Generate CSS custom properties from tokens
• Search: Find tokens by name, value, or type with regex support
• Validation: Check files for schema compliance and circular references

Installation

Gentoo Linux

Enable the bennypowers overlay, then install:

eselect repository enable bennypowers
emaint sync -r bennypowers
emerge dev-util/asimonim

From Source

go install bennypowers.dev/asimonim@latest

Quick Start

Validate your design token files:

# Validate token files
asimonim validate tokens.json

# List all tokens
asimonim list tokens.json

# Output as CSS custom properties
asimonim list tokens.json --format css

# Search for color tokens
asimonim search "primary" tokens.json --type color

CLI Reference

asimonim validate

Validate design token files for correctness and schema compliance.

Usage:
  asimonim validate [files...]

Flags:
  -s, --schema string    Force schema version (draft, v2025.10)
      --strict           Fail on warnings
      --quiet            Only output errors

Examples:

# Validate multiple files
asimonim validate colors.json spacing.json typography.json

# Force a specific schema version
asimonim validate tokens.json --schema v2025.10

# Quiet mode for CI
asimonim validate tokens.json --quiet

asimonim list

List all tokens from design token files with optional filtering and formatting.

Usage:
  asimonim list [files...]

Flags:
  -s, --schema string    Force schema version (draft, v2025.10)
      --type string      Filter by token type
      --resolved         Show resolved values (follow aliases)
      --format string    Output format: table, json, css (default "table")
      --css              Shorthand for --format css

Examples:

# List all tokens as a table
asimonim list tokens.json

# Output as JSON
asimonim list tokens.json --format json

# Generate CSS custom properties
asimonim list tokens.json --format css

# Show only color tokens with resolved values
asimonim list tokens.json --type color --resolved

asimonim search

Search design tokens by name, value, or type.

Usage:
  asimonim search <query> [files...]

Flags:
  -s, --schema string    Force schema version (draft, v2025.10)
      --name             Search names only
      --value            Search values only
      --type string      Filter by token type
      --regex            Treat query as a regular expression
      --format string    Output format: table, json, names (default "table")

Examples:

# Search by name or value
asimonim search "blue" tokens.json

# Search names only with regex
asimonim search "^color\." tokens.json --name --regex

# Find all dimension tokens containing "spacing"
asimonim search "spacing" tokens.json --type dimension

# Output matching token names only
asimonim search "primary" tokens.json --format names

asimonim convert

Convert and combine DTCG token files between formats.

Usage:
  asimonim convert [files...]

Flags:
  -o, --output string      Output file (default: stdout)
  -f, --format string      Output format (default "dtcg")
  -p, --prefix string      Prefix for output variable names
      --flatten            Flatten to shallow structure (dtcg/json formats only)
  -d, --delimiter string   Delimiter for flattened keys (default "-")
  -s, --schema string      Force output schema version (draft, v2025.10)
  -i, --in-place           Overwrite input files with converted output

Output Formats:

JS Format Options:

Examples:

# Flatten tokens to shallow structure
asimonim convert --flatten tokens/*.yaml -o flat.json

# Convert from Editor's Draft to v2025.10 (stable)
asimonim convert --schema v2025.10 tokens.yaml -o stable.json

# In-place schema conversion
asimonim convert --in-place --schema v2025.10 tokens/*.yaml

# Combine multiple files
asimonim convert colors.yaml spacing.yaml -o combined.json

# Generate TypeScript ESM module (default JS output)
asimonim convert --format js -o tokens.ts tokens/*.yaml

# Generate TypeScript CommonJS module
asimonim convert --format js --js-module cjs -o tokens.cts tokens/*.yaml

# Generate JavaScript with JSDoc types
asimonim convert --format js --js-types jsdoc -o tokens.js tokens/*.yaml

# Generate TokenMap class for typed token access
asimonim convert --format js --js-export map -o tokens.ts tokens/*.yaml

# Generate SCSS variables with prefix
asimonim convert --format scss --prefix rh -o _tokens.scss tokens/*.yaml

# Generate Android XML resources
asimonim convert --format android -o values/tokens.xml tokens/*.yaml

# Generate iOS Swift constants
asimonim convert --format swift -o DesignTokens.swift tokens/*.yaml

# Generate CSS custom properties
asimonim convert --format css -o tokens.css tokens/*.yaml

# Generate CSS with :host selector (for shadow DOM)
asimonim convert --format css --css-selector :host -o tokens.css tokens/*.yaml

# Generate Lit CSS module
asimonim convert --format css --css-module lit -o tokens.css.ts tokens/*.yaml

# Generate VSCode snippets
asimonim convert --format snippets -o tokens.code-snippets tokens/*.yaml

# Generate TextMate snippets
asimonim convert --format snippets --snippet-type textmate -o tokens.tmSnippet tokens/*.yaml

# Generate Zed editor snippets
asimonim convert --format snippets --snippet-type zed -o css.json tokens/*.yaml

asimonim version

Display version information.

Usage:
  asimonim version

Flags:
      --format string    Output format: text, json (default "text")

Configuration

Asimonim reads configuration from .config/design-tokens.{yaml,yml,json}:

# .config/design-tokens.yaml
prefix: "rh"
resolvers:
  - ./tokens.resolver.json
  - npm:@acme/tokens/tokens.resolver.json
files:
  - ./tokens.json
  - ./tokens/**/*.yaml
  - path: npm:@rhds/tokens/json/rhds.tokens.json
    prefix: rh
groupMarkers: ["_", "@", "DEFAULT"]
schema: draft
cdn: unpkg  # CDN for network fallback (unpkg, esm.sh, esm.run, jspm, jsdelivr)

When running commands without file arguments, files from config are used:

asimonim list      # Uses files from config
asimonim validate  # Uses files from config

Resolvers

The resolvers field accepts DTCG resolver documents — JSON files that declare how to compose multiple token files via sets, modifiers, and resolution order. Each entry can be a local path (relative or absolute) or an npm:/jsr: package specifier.

Resolver documents are distinct from token files — they reference and orchestrate token files rather than containing tokens directly.

Auto-Discovery

DiscoverResolvers scans the project’s root package.json and inspects each direct dependency (the dependencies map) for resolver files. Only direct dependencies are checked — devDependencies, peerDependencies, and transitive dependencies are not scanned.

Dependencies are processed in sorted order for deterministic results. Each dependency’s package.json is checked for a resolver declaration using either:

designTokens field (recommended, checked first):

{
  "name": "@acme/tokens",
  "designTokens": {
    "resolver": "tokens.resolver.json"
  }
}

designTokens export condition (fallback):

{
  "name": "@acme/tokens",
  "exports": {
    ".": {
      "designTokens": "./tokens.resolver.json",
      "import": "./dist/index.js"
    }
  }
}

When both are present, the designTokens field takes priority over the export condition.

Group Markers (Editor’s Draft only)

The Editor’s Draft schema has no built-in way for a token to also act as a group. The groupMarkers option works around this by treating certain token names as group names. For example, with groupMarkers: ["DEFAULT"]:

{
  "color": {
    "DEFAULT": { "$value": "#000" },
    "light": { "$value": "#fff" }
  }
}

This produces --prefix-color (from DEFAULT) and --prefix-color-light. The v2025.10 stable schema uses $root instead, so groupMarkers is ignored for that schema.

This configuration is also consumed by dtls and cem.

CSS Output

The css format generates CSS custom properties from tokens:

asimonim convert --format css -o tokens.css tokens/*.yaml

Options:

Examples:

# Shadow DOM components
asimonim convert --format css --css-selector :host -o tokens.css tokens/*.yaml

# Lit CSS tagged template literal
asimonim convert --format css --css-module lit -o tokens.css.ts tokens/*.yaml

Editor Snippets

The snippets format generates editor snippets for autocompleting CSS custom properties:

asimonim convert --format snippets -o tokens.code-snippets tokens/*.yaml

Snippet Types:

Use --snippet-type to select the output format:

# VSCode snippets (default)
asimonim convert --format snippets -o tokens.code-snippets tokens/*.yaml

# TextMate snippets
asimonim convert --format snippets --snippet-type textmate -o tokens.tmSnippet tokens/*.yaml

# Zed editor snippets
asimonim convert --format snippets --snippet-type zed -o css.json tokens/*.yaml

Each snippet includes multiple prefix triggers:

• Kebab-case: color-primary
• CamelCase: colorPrimary
• Snake_case: color_primary
• Value (for colors): FF6B35

Schema Versions

Asimonim supports multiple DTCG schema versions:

Schema version is automatically detected from file contents, or can be forced with the --schema flag.

License

GPLv3