Mac design handoff checklist for colors and JSON

For a single component or screen state, send five things: the state name, visual evidence, the intended color role, a parseable data snippet, and the path to the source of truth. A bare hex code and a pretty JSON block look tidy, but neither explains what should change.

This guide is for a small design-to-development handoff, such as one button state, alert, chart series, or settings panel. If you are reviewing a token package across platforms, use the separate Mac design token QA checklist. That page checks a system change. This one prepares a clear packet for one bounded UI decision.

My bias is disclosed: I build TeenyApps. The two focused tools here are TeenyColor for sampled sRGB values and TeenyTool for local JSON formatting. The built-in Digital Color Meter and your editor may already cover the job; the dedicated apps help when the same small handoff repeats.

Copy-ready handoff packet

01Name the state before copying a color

"Use this gray" is not enough. Record the component, appearance, interaction state, and surface. A disabled button in dark appearance may intentionally differ from the same button in light appearance. A sampled pixel cannot carry that meaning by itself.

Start with a short state label such as Checkout / Primary button / Disabled / Dark. Add the screenshot or design-frame link, then note the exact point you sampled. If the color came from a shadow, antialiased text edge, translucent overlay, gradient, or image, say so. Those pixels may be composites rather than source colors.

Apple describes SwiftUI Color as context-dependent and supports named Asset Catalog colors with appearance variants. That is why a rendered sample should be treated as evidence, not an automatic replacement for a semantic or adaptive color.

02Separate observation, intent, and representation

A color handoff has three layers. The observation is the rendered pixel. The intent is the role, such as surface.warning or text.secondary. The representation is the string you paste, such as hex, CSS rgb(), or a SwiftUI initializer.

Do not collapse those layers. Two states can render the same sRGB value today and still need separate semantic names. One semantic color can also resolve differently by appearance or environment. The copied code helps with implementation; it does not define the product decision.

For one-off screen inspection, Apple's Digital Color Meter can display and copy the color under the pointer. For repeat work, TeenyColor's source uses NSColorSampler, converts the result to sRGB, saves it locally, and lets you copy one of nine formats. The detailed spoke explains which Mac color code to copy and documents the rounding and color-space limits of each output.

03Copy the representation the destination accepts

Use hex when the destination expects an sRGB solid color and the compact form is useful. Use CSS rgb() or rgba() when CSS is the destination and alpha needs to remain visible. Use a SwiftUI or UIKit initializer for a quick constant in Apple-platform code.

Do not use an initializer when the real destination is a named Asset Catalog color or token. Put the semantic name in the handoff and treat the initializer as a temporary implementation aid. Likewise, do not label a sampled sRGB value as Display P3. CSS Color 4 defines Display P3 as a separate color space with explicit color(display-p3 ...) syntax.

This boundary prevents a common handoff mistake: a developer receives a convenient value, pastes it into source, and the convenient value quietly becomes the permanent source of truth.

04Format JSON without changing its role

A formatter should make a payload readable and confirm that it parses. It does not validate a token schema, prove that a field name is correct, or authorize the pasted copy as a source file.

RFC 8259 defines a JSON object as an unordered collection of name/value pairs, while arrays are ordered. If a formatter sorts object keys, the JSON meaning should remain the same. If a downstream system treats object-member order as significant, document that dependency because it is outside the interoperable model.

TeenyTool's JSON Formatter validates with Apple's JSONSerialization. Pretty mode sorts object keys and adds indentation. Compact mode removes insignificant whitespace without sorting. The implementation tokenizes the original input and re-emits number tokens verbatim, which avoids adding a floating-point artifact during formatting. The refreshed offline JSON formatter for Mac guide covers those behaviors and its limits.

Keep private product payloads local. A web formatter can be reasonable for fake samples or public documentation, but unreleased tokens, customer data, internal IDs, and support logs should not be pasted into an unvetted page.

05Name the source of truth and the check

End the handoff with one sentence that names the authoritative file or design object. For example: "Update tokens/color.json; the JSON below is a review copy." If the source is an Asset Catalog, name the color set. If it is a component property in a design file, link that exact component rather than the project home.

Then write the acceptance check in observable terms:

1. Open the named screen in the stated appearance and component state.
2. Compare the rendered result with the attached evidence.
3. Confirm the semantic color name still matches the role.
4. Check any adjacent state that shares the same token or asset.

A screenshot alone cannot prove the source changed. A source diff alone cannot prove the expected state rendered. The handoff needs both sides of that comparison.

What belongs in a larger token review

Move to the token QA workflow when one change affects multiple aliases, appearances, platforms, generated outputs, or schemas. That review should compare the source token file, generated CSS or platform code, and representative rendered states.

Stay with this smaller checklist when the task is to explain one bounded UI decision without losing the state, color role, data shape, or authoritative location.

Sources checked

• TeenyColor claims were checked against the local homepage and source files for NSColorSampler, sRGB conversion, its nine copy formats, pasteboard writing, and local history.
• TeenyTool claims were checked against the local homepage and JSONFormatterView.swift for validation, Pretty and Compact modes, key sorting, whitespace handling, and number-token preservation.
• Apple Digital Color Meter User Guide for built-in color inspection and copy behavior.
• Apple SwiftUI Color documentation for component colors, named Asset Catalog colors, and context-dependent appearance.
• W3C CSS Color 4 for sRGB, Display P3, alpha, and explicit color-space syntax.
• RFC 8259 for JSON object order, arrays, whitespace, and number interoperability.
• Apple JSONSerialization documentation for Foundation JSON conversion and validation.