Design Token Interchange Format (DTIF)

Status: Experimental Editor's Draft · Read the documentation

DTIF is a vendor-neutral JSON specification for exchanging design tokens—colour, typography, spacing, motion, and more—between design tools and codebases. It standardises how tokens are described and referenced without dictating how they are authored or consumed.

Use DTIF when you need:

• a single, versioned definition of design tokens that designers and engineers can share;
• predictable token payloads validated by an official JSON Schema; and
• a registry-documented naming catalogue that helps teams coordinate custom extensions.

Documentation

Browse the deployed documentation at dtif.lapidist.net. Key sections include:

• Specification – normative chapters covering the format, token types, and conformance rules.
• Guides – implementation playbooks and tooling workflows.
• Using the DTIF parser – configure the canonical parser, CLI, and plugin system.
• DTIFx Toolkit – automation-ready workflows and plugins for DTIF, with the open-source suite.
• Examples – schema-valid token documents you can reuse in tests.
• Governance – processes for proposing changes and managing the registry.
• Roadmap – current focus areas and forward-looking drafts.

Runtime & support policy

• Node.js: 22 or newer (aligns with CI and published workspace engines fields)
• pnpm: 10 or newer

The repository follows semantic versioning across workspaces. When contributing, run the workspace-specific scripts referenced in CONTRIBUTING.md to match CI: pnpm run lint, pnpm run lint:ts, pnpm test, and the workspace build/test commands noted in AGENTS.md.

Quick example

{
  "$schema": "https://dtif.lapidist.net/schema/core.json",
  "$version": "1.0.0",
  "button": {
    "background": {
      "$type": "color",
      "$value": {
        "$ref": "#/color/brand/primary"
      }
    }
  },
  "color": {
    "brand": {
      "primary": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0.18, 0.28, 0.94]
        }
      }
    }
  },
  "spacing": {
    "small": {
      "$type": "dimension",
      "$value": {
        "dimensionType": "length",
        "value": 8,
        "unit": "px"
      }
    }
  }
}

Validate a token file

1. Install the tooling

   git clone https://github.com/bylapidist/dtif.git
   cd dtif
   pnpm install

2. Run the JSON Schema

   npx ajv validate --spec=draft2020 --strict=true --data=true -c ajv-formats \
     -s schema/core.json -d path/to/tokens.json

   Load schema/core.json with Ajv or another JSON Schema validator if you want to integrate validation into your build pipeline.

   Prefer installing the published schema when you do not need the full repository:

   npm install --save-dev @lapidist/dtif-schema
   npx ajv validate --spec=draft2020 --strict=true --data=true -c ajv-formats \
     -s node_modules/@lapidist/dtif-schema/core.json -d path/to/tokens.json

   For programmatic validation, install @lapidist/dtif-validator to wrap Ajv with the published schema and sensible defaults:

   npm install --save-dev @lapidist/dtif-validator

   import { validateDtif } from '@lapidist/dtif-validator';
   
   const { valid, errors } = validateDtif(tokens);
   if (!valid) {
     console.error(errors);
   }

3. Exercise the project checks

   pnpm run lint
   pnpm test
   pnpm run docs:dev   # optional: preview the docs locally

Parse DTIF documents

Use the canonical parser package to cache decoded documents, resolve pointers, and drive extension plugins.

1. Install the parser

   npm install @lapidist/dtif-parser

2. Create a reusable parse session

   import { createSession } from '@lapidist/dtif-parser';
   
   const session = createSession({ allowHttp: false, maxDepth: 32 });
   const result = await session.parseDocument('tokens/base.tokens.json');
   
   if (result.diagnostics.hasErrors()) {
     console.error(result.diagnostics.toArray());
   }
   
   const resolution = result.resolver?.resolve('#/color/brand/primary');
   if (resolution?.token) {
     console.log(resolution.token.value);
   }

   Sessions expose the decoded document, normalised AST, document graph, diagnostic bag, and resolver so tooling can perform repeated lookups efficiently.

3. Inspect documents from the command line

   npx dtif-parse tokens/base.tokens.json --resolve "#/color/brand/primary" --format json

   Run dtif-parse --help to view all CLI switches. The parser guide covers cache configuration, loader overrides, and plugin registration in more detail.

Packages at a glance

Package	Description
@lapidist/dtif-schema	Canonical JSON Schema, bundled TypeScript declarations, and supporting metadata.
@lapidist/dtif-validator	Programmatic validation utilities that wrap the schema with Ajv best practices.
@lapidist/dtif-parser	A streaming parser that builds pointer graphs, resolver APIs, and diagnostics for tooling.
@lapidist/dtif-language-server	Language Server Protocol (LSP) implementation that powers diagnostics and editor workflows for DTIF projects.

Each workspace shares formatting, linting, and test infrastructure so upgrades remain consistent across the ecosystem.

DTIF language server

Embed the @lapidist/dtif-language-server package in any editor that hosts Node.js-based LSP servers. Core capabilities include:

• JSON parsing with schema-backed diagnostics and precise ranges.
• Jump-to-definition, hover documentation, and pointer-aware navigation for $ref targets.
• Rename refactors that update pointer declarations alongside every in-memory reference.
• Quick fixes for common schema violations such as missing $type or $ref members.
• Contextual completions for $type identifiers sourced from the registry, plus measurement units and $extensions namespace suggestions from reverse-DNS snippets and workspace context.

See the language server guide for client configuration, workspace settings, and transport options.

TypeScript support

@lapidist/dtif-schema bundles TypeScript declarations so editors and build tooling can understand DTIF documents:

import type { DesignTokenInterchangeFormat } from '@lapidist/dtif-schema';

declare const tokens: DesignTokenInterchangeFormat;

Repository reference

• schema/ – JSON Schema definitions used by validators.
• examples/ – schema-valid token sets shared across docs and tests.
• registry/ – canonical metadata for registered $type identifiers used by docs and tooling.
• tests/ – conformance fixtures and the test harness invoked by CI.
• CONTRIBUTING.md – contribution workflow, coding standards, and release process expectations.
• .changeset/ – Changesets configuration for tracking package releases.

Release & versioning

DTIF is published as a pnpm workspace that groups the schema (with bundled TypeScript declarations) and validator packages under a shared version. The Changesets workflow powers automated changelog generation and release pull requests:

• Run pnpm run changeset to document changes. The command prompts for the release type and writes a markdown entry under .changeset/.
• Run pnpm run version-packages locally to update package versions and regenerate changelog entries before publishing.
• CI uses changesets/action to open release pull requests and run pnpm run release once they land on main.

Release history lives alongside each published workspace:

• schema/CHANGELOG.md
• validator/CHANGELOG.md
• parser/CHANGELOG.md
• language-server/CHANGELOG.md

Contributing & community

Contributions follow the guidance in CONTRIBUTING.md and the Code of Conduct, which is based on the W3C Code of Ethics and Professional Conduct. Discuss proposals in GitHub Issues or Discussions. Suggested changes to the registry or specification should reference the governance processes.

License

DTIF is distributed under the MIT License. Portions derive from the Design Tokens Community Group format specification and are restructured to describe a JSON-focused interchange format with an accompanying registry and conformance tooling.