php

activetwist/jsonm-php

Reference PHP implementation of the JSONM v1 design-grammar spec.

JSONM is a universal portable design-system grammar. A JSONM payload authored in one compatible environment is applicable in another product that implements the spec, not necessarily with identical rendered output but with the same brand intent. Per-app variance is handled by transpiler targets, not by schema branching.

This package is the reference implementation. It provides:

• A universal Validator that confirms a payload conforms to JSONM v1.
• A Transpiler interface for per-target output emission.
• A bundled CssCustomPropertiesTarget that emits CSS-custom-property output with a configurable prefix. Consumers can supply their own prefix or implement their own target.

Install

From a JSONM repository checkout:

cd reference/php
composer install

The activetwist/jsonm-php package name is reserved in repository metadata, but Packagist publication is not the canonical adoption path yet. Use the source in this directory as the current PHP reference implementation.

Usage

Validate a payload

use Activetwist\Jsonm\Validator;
use Activetwist\Jsonm\JsonmProfile;

$payload  = json_decode(file_get_contents('reference-baseline.jsonm'), true);
$tokenMap = json_decode(file_get_contents('maps/token-map.json'), true);
$profile  = new JsonmProfile(); // defaults: corpus = activetwist-design-corpus/v1, prefix = jsonm

$errors = Validator::validate($payload, $tokenMap, $profile);
if ($errors !== []) {
    foreach ($errors as $err) echo "- {$err}\n";
}

Compile to CSS using CssCustomPropertiesTarget

use Activetwist\Jsonm\Targets\CssCustomPropertiesTarget;

$css = (new CssCustomPropertiesTarget())->transpile($payload, $tokenMap, $profile);
file_put_contents('runtime-tokens.css', $css);

Use your own prefix

$exampleProfile = new JsonmProfile(
    allowedCorpusIds: ['activetwist-design-corpus/v1'],
    cssVarPrefix: 'example',
);

$css = (new CssCustomPropertiesTarget())->transpile($payload, $tokenMap, $exampleProfile);
// Emits --example-* CSS variables.

Build your own transpiler target

use Activetwist\Jsonm\Transpiler;
use Activetwist\Jsonm\JsonmProfile;

final class DesignTokensJsonTarget implements Transpiler
{
    public function transpile(array $definition, array $tokenMap, JsonmProfile $profile): string
    {
        // Emit Style Dictionary–shaped JSON, or Tailwind config, or whatever
        // your runtime consumes. Use Validator::resolveSemanticColors(),
        // Validator::resolveDefaultMode() for mode-aware lookups.
        return json_encode([...]);
    }

    public function transpileFontRoles(array $definition, JsonmProfile $profile): string
    {
        return '...';
    }
}

Spec

The canonical JSONM v1 spec lives at the activetwist/jsonm repository (see spec/v1.md there). Schema is bundled with this package under schema/style-definition.schema.json.

Tests

From the standalone JSONM repository:

cd reference/php
composer install
php tests/ValidatorTest.php
php tests/CssCustomPropertiesTargetTest.php

The same tests also run from a host project source tree. They resolve schema, token map, examples, and conformance fixtures from the standalone layout first, with host-project paths as a development fallback.

License

Copyright 2026 Active Twist.

JSONM was created by Stanton Brooks and is owned, maintained, and stewarded by Active Twist. The reference PHP implementation is released under Apache-2.0. See LICENSE.