Mac design token QA checklist for colors and JSON

The short answer: record the source revision, inspect the authored token and every alias it depends on, compare the generated CSS or platform output, then check the exact UI state. Sampled pixels are render evidence. A JSON diff is structure evidence. Neither one validates the full chain.

Disclosure: I build TeenyApps, including TeenyColor for local color sampling and TeenyTool for local JSON utilities. My bias is toward keeping small review tasks on the Mac. The conservative baseline is still the design system, source control, your app, and a human reviewer who knows the product.

This checklist is for a design token change that touches color values, aliases, JSON exports, component states, SwiftUI or UIKit usage, CSS variables, or documentation. The information gain is a four-artifact acceptance record: authored source, resolved value, generated consumer output, and rendered result.

Design token QA decision table

01Freeze the source revision and requested state

Write down the token file, branch or commit, token path, component, appearance, and interaction state before comparing values. Without that starting record, a later screenshot and a later JSON export can each be correct for different revisions.

Use one bounded request such as button.secondary.disabled.background in dark appearance. Record the before and proposed values, but do not flatten an alias into a literal just to make the note shorter. The relationship can be the design decision.

The Design Tokens Format Module 2025.10 is a stable Community Group report, not a W3C Recommendation. In that format, an object with $value is a token. A token type can be explicit, inherited from the nearest parent group, or resolved through a reference; tools must not guess a missing type from the value. A generic JSON parser cannot enforce those rules.

02Review authored and resolved values separately

An authored token may hold a color object or a reference such as {color.base.blue.600}. The resolved value is what a compliant resolver finds after following that reference. The 2025.10 format allows chained references, requires tools to preserve references when possible, and treats circular references as errors.

Check the authored diff first. Then run the project's real resolver or generation step and capture the resolved result. This catches a small-looking base-token edit that moves several semantic aliases, plus an alias edit that keeps the base palette untouched.

Do not call the resolved value the rendered value. Generated CSS, an Asset Catalog, platform code, opacity, blending, appearance, and component state still sit between resolution and the screen.

03Use a structural diff, then name its boundary

A visual review can catch the wrong blue. A structural token-file review can catch the wrong key, deleted alias, accidental rename, or unrelated change that would reach another component.

TeenyTool's local JSON Diff guide documents the exact implementation. The app parses both sides with Foundation, requires an object or array root, sorts object keys for display, recurses through like-shaped dictionaries and arrays, and uses longest-common-subsequence matching for arrays. Unchanged values are hidden by default.

It does not know the Design Tokens specification. It will show a $value, $type, alias string, or $extensions object as ordinary JSON. It will not resolve references, detect a circular alias, validate a color object, preserve a reviewer-approved semantic relationship, or run the project's generator. Put that boundary in the review note.

04Verify generated output and the rendered state

Open the generated artifact that the consumer actually reads. Record the exact CSS custom property, Asset Catalog entry, Swift constant, or other platform value. If the project does not commit generated output, save the build command and a focused excerpt in the acceptance record.

Then open the named UI state. For a repeat Mac color check, TeenyColor's sRGB design-token guide explains how to sample a stable flat region and compare that observation with the authored and resolved records. TeenyColor converts the sampled color to sRGB. Its palette JSON is a review export of names plus hex, RGB, and HSL strings, not a Design Tokens Format file or alias resolver.

If the state contains translucency, a gradient, antialiased text, an image, or a wide-gamut source, describe the sampled pixel as observed render evidence. Do not silently replace the authored color object with that sRGB sample. Check contrast as a separate decision using the Mac UI color accessibility checklist.

05Write one acceptance record

The final record should be plain enough for another reviewer to rerun:

• Source: file path plus commit or other immutable revision.
• Authored change: token path, old $value, new $value, and any type or group-property movement.
• Resolution: referenced path and the resolved before-and-after value from the project's actual toolchain.
• Consumer: generated identifier and value used by the platform.
• Render: exact screen, appearance, state, build, and sampled observation when that evidence is useful.
• Scope result: expected movement, unexpected movement, and anything not tested.

A pass requires agreement across the relevant artifacts. If one is unavailable, mark it not tested. Do not turn absence of evidence into a pass.

Ten-minute design token QA pass

1. Record the source file, immutable revision, token path, and requested UI state.
2. Diff the authored JSON and inspect adjacent group properties and references.
3. Run the project's token validator or resolver. Record alias and type errors.
4. Generate the consumer output from the same source revision.
5. Inspect the exact CSS, Asset Catalog, or platform identifier that changed.
6. Open the named UI state from the tested build.
7. Sample a stable flat region only when a rendered sRGB observation answers the question.
8. Write expected, unexpected, passed, failed, and not-tested results.

Common questions

What should a Mac design token QA checklist include?

Record the source revision, inspect the authored token and alias, compare the generated output, then verify the exact rendered state. Keep a structural JSON diff separate from token-format and alias-resolution checks.

Should I trust the design token or the rendered screen?

Use both, plus the generated output between them. The source token records the decision, the resolver or build shows how aliases became platform values, and the rendered screen shows the observed result.

Why use a local JSON diff for design tokens?

A local structural diff exposes added, removed, and changed JSON without uploading unreleased token data. It does not resolve aliases, validate the Design Tokens format, or prove the generated app or CSS output.

Sources checked

• TeenyColor claims were checked against the TeenyColor homepage and local Swift source for NSColorSampler, sRGB conversion, copy formats, pasteboard writing, history, pinning, palette export, and contrast checks.
• TeenyTool claims were checked against the TeenyTool homepage and local Swift source for JSON Diff, JSONSerialization parsing, object and array roots, nested key comparison, changed-value summaries, array matching, and unchanged-row filtering.
• Apple NSColorSampler documentation for AppKit color sampling.
• Apple JSONSerialization documentation for JSON parsing behavior.
• RFC 8259 for the JSON data format.
• Design Tokens Format Module 2025.10 for token identity, type inheritance, aliases, reference resolution, circular-reference errors, and its Community Group report status.
• Design Tokens Color Module 2025.10 for structured color values and named color spaces including sRGB.
• W3C Understanding SC 1.4.3: Contrast (Minimum) for the contrast rule that should stay separate from value sampling.