How to validate DTCG design tokens: what a validator pass proves

For an approval decision, the question "Is this DTCG file valid?" is too broad. You may need to establish that the file parses, follows selected Format rules, uses valid Color values, contains references a particular implementation handles, transforms into the expected output, or appears correctly in a named application. Each claim needs its own evidence.

Write the intended approval sentence before you test. For example: "Accept tokens.json against the tested rules from the recorded 2025.10 Format and Color reports, and accept the generated web artifact for the consumers, environments, and modes listed in this record." Anything outside that sentence remains unverified unless the record says otherwise.

You can't reliably reproduce a green screenshot without its version and execution context. Specifications change. Hosted validators change too, and the same tool may accept more than one input form. Keep the authority and execution details beside the result.

• Published report URL, title, status, and report date.
• Capture date for the report and, when available, a content hash or archived copy.
• Validator name, URL, version, release identifier, or commit. Use "unresolved" when none is exposed.
• The validator's claimed DTCG target and claimed modules.
• Execution timestamp and environment, including browser, runtime, package context, or hosted interface as applicable.
• Accepted input form, such as JSON or JSON5, plus the exact submitted file hash.
• Raw validator output, exported result, or a stable evidence reference. If no export exists, preserve the visible result and observation time.
• Documented exclusions, deviations, unsupported behavior, and unresolved authority questions.

Be precise about status. The published 2025.10 Format and Color pages are Final Community Group Reports, and the pages state that they are neither W3C Standards nor on the W3C Standards Track. A tool may call itself a W3C DTCG validator, but your record should preserve the status stated by the report.

Start with the source file and work outward. If a required layer fails, don't carry its claim forward. A successful render cannot repair an invalid source, and a valid source cannot vouch for a broken transformation.

1. 1

   1. Parse the submitted bytes

   Hash the exact file and record whether the tool read JSON, JSON5, or another accepted form. A parse pass establishes that this parser read this input. It does not establish DTCG conformance.

2. 2

   2. Check the published Format rules in scope

   Test the structures and features the project relies on, such as tokens, groups, types, values, reserved names, inheritance, and reference forms. Cite the applicable section of the recorded published report for every expected result.

3. 3

   3. Check published Color rules where applicable

   For color tokens, cover the value structure, declared color space, component forms and ranges, alpha handling, and any other relied-on requirements from the recorded published Color report.

4. 4

   4. Exercise Format-defined references

   Use bounded cases for the reference behaviors your project needs. Direct, chained, missing, circular, and composite-position cases may be relevant. Keep document acceptance distinct from successful value resolution.

5. 5

   5. Record claimed Resolver checks separately

   When a validator claims Resolver Module support, preserve the exact claim and its exclusions. The frozen evidence doesn't contain a captured published Resolver report, so a tool's Resolver claim isn't treated here as normative proof.

6. 6

   6. Inspect generated artifacts

   Record the transformer and version, hash every output, inspect expected symbols and mode values, and verify the intended reference results. A source validator doesn't cover this layer unless its documented scope explicitly says it does.

7. 7

   7. Observe named consumers

   Record each consumer's identity, version, mode, environment, loaded artifact, and inspected surface. Check the values and states included in the approval claim, along with any protected surfaces that must remain unchanged.

The two captured validator pages expose different amounts of scope information. That makes them useful examples of evidence quality, but the dossier contains no executed benchmark. The comparison below records only what their captured interfaces say.

Detailed scope claims are easier to bound. Detail alone, however, isn't independent proof, and a shorter description may still belong to a capable implementation. In either case, controlled fixtures connect a tool's claim to the specific rules your project needs.

Begin with one known-valid control that contains only the features under test. Copy it once per rule, change one relevant property, and write the expected outcome before running the validator. With one change per fixture, disagreements are easier to assign.

Don't turn a few fixture runs into a validator leaderboard. Passing the set establishes only that those cases behaved as recorded in that environment. It doesn't establish complete conformance, coverage of untested token types, or future behavior after the service or package changes.

When results disagree, reduce the case to the smallest fixture and route it to the layer that owns the behavior. "The validators disagree" describes a symptom. It isn't a diagnosis yet.

• Source defect: the submitted file violates the recorded published rule.
• Unsupported rule or module: the validator does not claim the behavior being tested.
• Stale target: the fixture and validator rely on different report versions.
• Validator implementation issue: the observed behavior conflicts with a rule and scope the tool claims to implement.
• Transformation issue: the source passes, but an output contains the wrong symbol, value, mode, or reference result.
• Consumer mapping issue: the artifact is correct, but the application loads the wrong symbol, file, mode, or version.
• Unresolved result: the available evidence cannot assign ownership safely. Block the affected scope or exclude it explicitly.

Before assigning a suspected implementation issue, confirm that each tool received identical bytes and input forms. Make sure no cached, formatted, converted, or generated copy replaced the hashed fixture. Record the execution time and environment for both observations.

A token source normally feeds one or more generated artifacts. If the delivery claim includes those outputs, validation isn't complete until the transformation and named consumers have their own observations.

• Record the transformer name, version or release, execution environment, source hash, and command or configuration reference.
• Record each generated artifact path and hash.
• Check that expected symbols exist and unintended or obsolete symbols do not.
• Compare representative light and dark values rather than checking only that two files exist.
• Trace at least one primitive-to-semantic reference and one composite value when the system uses them.
• Inspect representative consumers that expose foreground and background pairings, borders, focus states, disabled states, and mode changes.
• Record consumer identity, version, mode, environment, loaded artifact, test content, inspected surface, observed result, and evidence reference.
• Confirm that one controlled token change reaches its intended surfaces and that named protected surfaces remain unchanged.
• Keep every exception and unresolved observation visible instead of folding them into a general pass.

A visual observation can't establish an exact generated value, while a generated-file diff can't establish that an application loaded the file. When the approval sentence covers rendered behavior, use both forms of evidence and connect them through the recorded artifact identity.

Keep the decision data-oriented. Any field you didn't observe should say "unresolved" instead of disappearing or inheriting an optimistic default. Another developer should be able to identify the inputs, repeat the execution, find the preserved results, and understand why you chose the disposition.

{
  "decisionId": "dtcg-validation-YYYY-MM-DD-01",
  "executedAt": "YYYY-MM-DDTHH:mm:ssZ_OR_UNRESOLVED",
  "environment": {
    "kind": "hosted_ui_package_or_cli",
    "browserOrRuntime": "RECORD_OR_UNRESOLVED",
    "operatingSystem": "RECORD_OR_UNRESOLVED"
  },
  "scope": {
    "sourceFiles": [
      {
        "path": "tokens.json",
        "sha256": "RECORD_HASH",
        "acceptedInputForm": "json_json5_or_unresolved"
      }
    ],
    "targetReports": [
      {
        "title": "Design Tokens Format Module 2025.10",
        "url": "RECORD_PUBLISHED_REPORT_URL",
        "status": "Final Community Group Report",
        "reportDate": "2025-10-28",
        "capturedAt": "YYYY-MM-DD"
      }
    ],
    "validator": {
      "name": "RECORD_TOOL",
      "url": "RECORD_URL",
      "versionOrRelease": "RECORD_OR_UNRESOLVED",
      "claimedTarget": "RECORD_OR_UNRESOLVED",
      "claimedModules": [],
      "documentedExclusions": [],
      "rawResultEvidence": {
        "kind": "export_log_screenshot_or_unresolved",
        "reference": "RECORD_STABLE_REFERENCE_OR_UNRESOLVED"
      }
    }
  },
  "fixtures": [
    {
      "id": "format-valid-control",
      "inputSha256": "RECORD_HASH",
      "ruleCitation": "RECORD_PUBLISHED_SECTION",
      "expected": "pass",
      "observed": "RECORD_AFTER_RUN_OR_UNRESOLVED",
      "evidenceStatus": "observed_or_unresolved",
      "rawEvidenceReference": "RECORD_OR_UNRESOLVED"
    }
  ],
  "transformation": {
    "transformerIdentity": "RECORD_OR_UNRESOLVED",
    "transformerVersion": "RECORD_OR_UNRESOLVED",
    "environment": "RECORD_OR_UNRESOLVED",
    "configurationReference": "RECORD_OR_UNRESOLVED"
  },
  "generatedArtifacts": [
    {
      "path": "RECORD_OUTPUT_OR_UNRESOLVED",
      "sha256": "RECORD_HASH_OR_UNRESOLVED",
      "checks": []
    }
  ],
  "consumerObservations": [
    {
      "consumerIdentity": "RECORD_OR_UNRESOLVED",
      "consumerVersion": "RECORD_OR_UNRESOLVED",
      "mode": "light_dark_or_other",
      "environment": "RECORD_OR_UNRESOLVED",
      "loadedArtifactSha256": "RECORD_OR_UNRESOLVED",
      "surfaceAndState": "RECORD_OR_UNRESOLVED",
      "testContent": "RECORD_OR_UNRESOLVED",
      "inspectionCriteria": [],
      "observed": "RECORD_OR_UNRESOLVED",
      "evidenceReference": "RECORD_OR_UNRESOLVED"
    }
  ],
  "exceptions": [],
  "unresolved": [],
  "owner": "RECORD_OWNER_OR_UNRESOLVED",
  "disposition": "accept_revise_or_block",
  "approvedScope": "STATE_THE_NARROW_SUPPORTED_CLAIM"
}

Prefer raw validator output or a stable export. If a hosted tool exposes only an interactive result, preserve the input hash, execution time, environment, visible result, and tool identity. A screenshot can support the record, but it shouldn't replace the structured fields.

An accepted file may still have exceptions. Each exception must sit outside the promised scope, carry explicit ownership and tolerance, or be harmless to the required delivery. If an unresolved item could change a required artifact or consumer, use Block.

Identity Forge ships DTCG token exports, but that doesn't establish compatibility with every validator, transformer, or consumer. Treat the export as a source artifact: hash it, name the published authority, run the controlled fixtures your project needs, inspect the generated files, and observe the named consumers.

Start with one known-valid control and the smallest invalid cases for the published rules your project relies on. Run them against an identified validator in a recorded environment, preserve the raw evidence, and approve only after the required generated artifacts and named consumers support the same narrow claim.

• Design Tokens Format Module 2025.10: The page identifies the Format Module 2025.10 as a Final Community Group Report dated 28 October 2025 and states that it is not a W3C Standard or on the W3C Standards Track.
• Design Tokens Color Module 2025.10: The page identifies the Color Module 2025.10 as a Final Community Group Report dated 28 October 2025 and documents the DTCG color type and supported color spaces.
• Design Tokens Format Module preview: The captured draft identifies itself as a preview, warns readers not to implement or cite it as authoritative, and links to the latest published Format report.
• Design Token Validator: The captured interface accepts pasted or uploaded JSON or JSON5, reports live validity, and makes a general DTCG compatibility claim without displaying a specific target version or module breakdown.
• DTCG Validator: The captured interface claims DTCG 2025.10 Format, Color, and Resolver coverage, lists implemented areas, and states that runtime input resolution is outside its Resolver scope.
• Tools that support the DTCG format: The community discussion catalogs tools associated with different kinds of DTCG support, making tool identity and purpose material to a validation record.
• The design tokens spec (DTCG) explained: The captured explainer describes structural validation and linting as benefits of using a standardized design-token format.
• Identity Forge: Identity Forge publicly lists DTCG token exports as part of its implementation-ready design-kit handoff.