Mac design token QA checklist for colors and JSON

The short answer: start from the screen people will ship, sample the rendered color, normalize the value in sRGB, compare the old and new token JSON, then write a short handoff note with the token path, value, decision, and reviewer.

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 design token changes that touch color values, aliases, JSON exports, component states, SwiftUI or UIKit usage, CSS variables, docs, or a design handoff where one wrong value can spread through multiple screens.

Design token QA decision table

01Start from the rendered state, not the token name

A token name can be right while the screen is wrong. Aliases, state styles, opacity, dark mode, platform defaults, and old code paths can all sit between the source value and the pixel a user sees.

Open the exact state you want to ship: hover, pressed, disabled, selected, dark mode, light mode, empty state, error state, or the actual app screen. Then sample the color from that rendered state before arguing about the token.

For a repeat Mac workflow, TeenyColor is the app in this network that fits the job. Its source uses AppKit's NSColorSampler, converts sampled colors to sRGB, copies the selected format to the pasteboard, keeps local history, supports pinned colors, and exports palettes as text or JSON. That matters when you need the same value in design notes, code, QA comments, and a token review.

02Normalize the color value before it becomes a token

Do not let a review bounce between "looks right" and "the number changed." Pick the target representation first. Web teams often need hex, RGB, HSL, or CSS rgba. Mac app teams may need SwiftUI Color or UIColor. Design systems may want a normalized JSON value with a name, description, mode, or semantic alias.

For color tokens, sRGB is usually the least surprising review language because it lines up with common CSS values and many app handoff notes. If your team uses a different color space or a design-token spec, write that down and keep the conversion rule with the token source.

If contrast is part of the decision, split that into its own check. A sampled color proves the value. A contrast ratio proves whether text and background meet the target. The Mac UI color accessibility checklist covers that review in more detail.

03Diff the token file before you hand it off

A visual review catches the wrong blue. A token-file review catches the wrong key, deleted alias, accidental rename, or unrelated change that will affect another screen next week.

TeenyTool includes a JSON Diff tool for this local pass. The current source parses each side with Foundation's JSONSerialization, requires the root to be a JSON object or array, compares nested dictionary keys, tracks added, removed, changed, and unchanged values, and uses an LCS pass for arrays. Unchanged rows are hidden by default so the review starts with the real movement.

That local behavior is useful because token files can contain unreleased product names, customer-specific brand values, internal aliases, or feature-flagged components. Do the diff locally, then paste only the final summary into the issue or pull request.

04Keep YAML, JSON, CSS, and code roles separate

A valid JSON file does not prove a valid token change. It only proves the syntax can be parsed. The schema, naming convention, alias behavior, generated output, platform code, and design-system rules are separate decisions.

Keep each role visible in the note: source token file, generated CSS or platform output, rendered screen, and final consumer. If the source of truth is YAML, export or convert only for review. Do not let the review file become the source by accident.

The broader Mac design handoff utilities guide covers the surrounding handoff kit: copied color formats, URL work, JSON formatting, screenshots, and temporary files. Use this page when the specific risk is a token change.

05Write the handoff note

The handoff note should be boring and hard to misread. A good one takes one minute:

• Screen or component state: "Settings billing card, dark mode, disabled secondary button."
• Token path: color.action.secondary.disabled.background.
• Before and after value: #6B7280 to #4B5563.
• Rendered sample: the value sampled from the app or browser state.
• Diff summary: one changed token, no deleted aliases, no unrelated JSON movement.
• Reviewer request: approve the value, the state, or the naming change.

If the note needs a screenshot, attach the smallest useful evidence. If it needs a token diff, paste the changed path and value rather than the whole file.

Ten-minute design token QA pass

1. Open the screen state that will ship.
2. Sample the visible foreground, background, border, and state colors that changed.
3. Copy the needed values in the format the next file requires.
4. Compare the old and new token JSON locally.
5. Check for added, removed, changed, renamed, and unrelated keys.
6. Confirm contrast separately when the token affects text or controls.
7. Write the token path, before value, after value, screen state, and reviewer request.
8. Link to the source file or pull request. Do not rely on chat history.

Common questions

What should a Mac design token QA checklist include?

Check the rendered state, sample the visible color, normalize the value in sRGB, compare old and new token JSON, confirm the token path, then send a short handoff note with the value and risk.

Should I trust the design token or the rendered screen?

Use both. The token is the source of intent, but the rendered screen proves what users will see after color spaces, aliases, styles, and platform code apply that value.

Why use a local JSON diff for design tokens?

Token files can include unreleased names, brand values, customer context, and feature flags. A local JSON diff keeps that review on the Mac while still showing added, removed, and changed values.

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.
• W3C Understanding SC 1.4.3: Contrast (Minimum) for the contrast rule that should stay separate from value sampling.