Design Token Migration Review

Compare two design-token snapshots before a migration. Get a deterministic JSON report of added, removed and changed tokens, alias-reference issues, and potentially affected alias paths.

This Actor supports the bounded dtcg-2025.10-scalar-alias/1 profile described below. It is a review tool: it does not modify your files or automatically fix a migration.

Quick start

Run the bundled synthetic example with this input:

{"useDemo": true}

Leave tokenProfile, baselineTokensJson and candidateTokensJson absent in demo mode. The demo uses the same report and pricing path as your own inputs; it is not a free preview.

For your own token files, use the five fields below. The two catalogs must be JSON-encoded strings, not nested objects in the Actor input:

{
  "useDemo": false,
  "authorizedNonpersonalNonconfidentialData": true,
  "tokenProfile": "dtcg-2025.10-scalar-alias/1",
  "baselineTokensJson": "{\"spacing\":{\"$type\":\"dimension\",\"small\":{\"$value\":{\"value\":8,\"unit\":\"px\"}},\"button\":{\"$type\":\"dimension\",\"$value\":\"{spacing.small}\"}}}",
  "candidateTokensJson": "{\"spacing\":{\"$type\":\"dimension\",\"small\":{\"$value\":{\"value\":10,\"unit\":\"px\"}},\"button\":{\"$type\":\"dimension\",\"$value\":\"{spacing.small}\"}}}"
}

This example changes spacing.small from 8px to 10px. The report also identifies the changed resolved value of spacing.button and includes that alias in the affected paths for spacing.small.

Only submit data you are authorized to send to Apify, and only nonpersonal, nonconfidential material. Set the authorization field to true only when that statement is accurate. Extra input fields are rejected.

Supported token format

Each catalog is a UTF-8 JSON object containing named groups and tokens.

• Types: number, dimension and duration only.
• A number literal uses a JSON number as $value.
• A dimension literal uses {"value": 8, "unit": "px"} or unit rem.
• A duration literal uses {"value": 100, "unit": "ms"} or unit s.
• An alias uses the whole-string form "{spacing.small}". Each alias must declare its own $type explicitly.
• Literal tokens may inherit $type from an enclosing group.
• Tokens allow only $type, $value and optional $description. Groups may contain child groups/tokens, $type and $description.
• Names start with an ASCII letter or underscore, followed by ASCII letters, digits, underscores or hyphens. Dots separate path segments; they are not allowed within names.

Descriptions are counted as ignored metadata and do not produce token-change findings. Duplicate JSON keys, unsupported properties or types, malformed values and unsupported syntax are rejected.

This is a limited profile, not full DTCG compatibility. Color, typography, shadow, gradient and other composite tokens are not supported. There is no unit conversion: 100ms and 0.1s are reported as numeric and unit changes rather than treated as equivalent.

What the report checks

• Added, removed, changed and unchanged token paths
• Type, literal/alias representation and alias-target changes
• Changes to normalized numeric values, units and resolution state or terminal target
• Missing alias targets, references to groups, type mismatches, cycles and unresolved dependencies
• Transitive alias paths affected by each changed token, traced separately in the baseline and candidate snapshots

Impact paths describe token-reference relationships, not proven UI breakage. The Actor does not inspect application code, render components, test accessibility or infer the intent of a change. It does not fetch URLs or follow external references from token input.

Output

A successfully delivered report is one item in the run's default dataset, not one item per token. The item contains:

• reportJson: the complete report as a JSON string; parse this string to inspect the report
• reportSha256 and reportBytes: the hash and UTF-8 byte length of that exact report string
• inputManifest: each catalog's role, byte length and SHA-256 hash
• Run, contract, delivery and source-version identifiers, plus a receipt

The parsed report contains summary, per-token results, reference_issues, ignored_metadata, all_values_resolved, limits and input hashes. Each result includes the baseline and candidate token state, change_codes and impacted_alias_paths.

status: "issues" means there are changes or reference issues in either snapshot. It does not mean the Actor failed. status: "ok" means no token changes or reference issues were found within the supported profile. Determinism applies to report content for identical input bytes; run and delivery identifiers vary between runs.

Limits

• Each catalog: at most 1,048,576 UTF-8 bytes
• Each snapshot: at most 1,000 tokens and 1,000 groups, including the root group
• JSON nesting: at most 32 levels
• Paths: at most 16 segments, 64 ASCII characters per segment and 512 ASCII characters total
• Alias chains: at most 32 edges
• Each description: at most 1,024 Unicode code points
• Numbers: at most 28 significant digits, 128 ASCII characters, and exponent bounds of ±12, including the adjusted exponent for nonzero values
• Report: at most 2,097,152 bytes, 2,000 changed rows and 2,000 total changed-token/affected-alias pairs
• Entire serialized Actor input: at most 4,500,000 UTF-8 bytes, including escaping and whitespace

Inputs within individual size limits can still exceed the combined graph, report-size or processing-time limits. Unsupported or oversized inputs are rejected rather than silently truncated.

Pricing and reruns

The configured price is USD 0.10 per delivered report, with platform usage included. One dataset-item event is configured per report; both demo and own-input runs use this path.

The receipt records expected pricing and delivery consistency. It is not proof of platform billing or owner settlement; its settlementStatus is not_verified.

If a run fails after attempting delivery, inspect its dataset and billing status before rerunning. An accepted report may remain present or billable even when the final run status indicates a failure. A rerun is a separate run and may incur another charge.

Data handling

Apify stores Actor input before execution and stores output under your Apify account's access settings and the platform's retention rules. Full reports retain token identifiers, normalized values and alias relationships. This is not a local-only workflow or a promise of private storage.

No anonymization, secret scanning or automatic deletion is provided. The processing region has not been verified. Review your account's storage access and retention settings before submitting data, and use only authorized nonpersonal, nonconfidential input.