# Design Token Migration Review (`immemorial_sarinda/design-token-migration-review`) Actor

Compare design-token snapshots for additions, removals, value changes and alias-reference issues. Get one deterministic JSON report with affected alias paths. Supports a bounded number, dimension and duration profile; no automatic fixes.

- **URL**: https://apify.com/immemorial_sarinda/design-token-migration-review.md
- **Developed by:** [Picknotes](https://apify.com/immemorial_sarinda) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$100.00 / 1,000 completed reports

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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:

```json
{"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:

```json
{
  "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.

# Actor input Schema

## `authorizedNonpersonalNonconfidentialData` (type: `boolean`):

Required to be true for own mode: confirm you are authorized to submit these nonpersonal, nonconfidential token files. Apify stores INPUT before execution; reports retain identifiers and values. This is not anonymization or secret scanning.

## `baselineTokensJson` (type: `string`):

Own mode only. Leave absent in demo. Runtime enforces exact profile and UTF-8 byte limits.

## `candidateTokensJson` (type: `string`):

Own mode only. Leave absent in demo. Runtime enforces exact profile and UTF-8 byte limits.

## `tokenProfile` (type: `string`):

Own mode only. Leave absent in demo. Runtime enforces exact profile and UTF-8 byte limits.

## `useDemo` (type: `boolean`):

Use the bundled synthetic baseline and candidate. When true, leave tokenProfile, baselineTokensJson and candidateTokensJson absent. Set false to supply authorized nonpersonal, nonconfidential files.

## Actor input object example

```json
{
  "authorizedNonpersonalNonconfidentialData": false,
  "useDemo": true
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "useDemo": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("immemorial_sarinda/design-token-migration-review").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "useDemo": True }

# Run the Actor and wait for it to finish
run = client.actor("immemorial_sarinda/design-token-migration-review").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "useDemo": true
}' |
apify call immemorial_sarinda/design-token-migration-review --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,immemorial_sarinda/design-token-migration-review"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/IZ9qs6hN0L64KcZPv/builds/9DI8Fkxp72dCdPi6b/openapi.json