CONCEPT Cited by 1 source

Design token as named reference¶

Definition¶

A design token serialised as named reference is a wire-format representation of a design-system token (colour, icon, gradient, shadow, typography value) as a record that carries both the token's semantic name and its resolved raw value for the target platform:

{
  "name": "<token-semantic-name>",
  "raw_value": <platform-resolved-value>
}

The name is stable across platforms; the raw_value is what the client can render directly without needing to resolve the token itself.

Canonical wiki instance (Yelp Cookbook + Konbini)¶

Yelp serialises design tokens via Konbini:

def serialize_color(value):
    return {
        "name": value,
        "raw_value": CookbookResources.instance().colors[value]["default"],
    }

Wire format for a colour:

"color": {
  "name": "ref-color-black-100",
  "raw_value": {"a": 1, "b": 0, "g": 0, "r": 0}
}

Yelp: "Each token is serialized as a simple string representing its name, and when exported, includes a raw_value field containing its actual value." Tokens are curated in a separate repository by designers and published as JSON.

Why carry both name and raw value¶

Name is the stable identifier. ref-color-black-100 means the same thing to iOS, Android, web, and backend codebases even if its numerical value changes in a future token release. Clients can log by name, override by name, and match the "current theme's version of this token" instead of matching a literal RGBA.
Raw value is the fallback and the render payload. A client that doesn't have the token resolvable locally can still render the correct pixel; a client that does have the token locally can ignore the raw_value and render the locally-resolved version (which may be newer or theme-adjusted).
Designers own the token repo, not engineers. Because the wire format carries the raw_value, the client doesn't need a round-trip to a token-resolution service. Designers can publish new token values without coordinating with client engineers.

Contrast with alternatives¶

Raw literal on the wire (just the RGBA, no name) — loses semantic meaning; clients can't theme; rename of the token source requires coordinated backend + client deploy.
Named reference only (just the name, no raw_value) — requires every client to have an up-to-date local token table; old clients break when new tokens ship.
StyleX-style build-time resolution — see concepts/design-token-cross-platform-theming. Zalando's approach: tokens are language-level identifiers that resolve at build time to CSS variables (web) or native style primitives (mobile). Different approach, different tradeoffs — StyleX tokens don't travel the wire at all, so they're cheaper for static styling but don't work for server-authored UI where the wire IS the UI.

The Yelp {name, raw_value} shape is specifically suited to server-driven UI with heterogeneous clients: the backend can express tokens semantically; the client can render them literally; both can evolve the token table independently.

Extends to other token categories¶

The post mentions four token categories used in the Button example: colours, icons, gradients, shadows. The {name, raw_value} shape works uniformly for all; raw_value varies in structure ({r,g,b,a} for colours, other shapes for icons/gradients/shadows).

Seen in¶

sources/2026-04-22-yelp-how-yelp-keeps-server-driven-ui-consistent-across-four-platforms — canonical wiki first source. Yelp Cookbook's colour, icon, gradient, shadow tokens are serialised via Konbini as {name, raw_value} records. Sample ref-color-black-100 → {"name":"ref-color-black-100", "raw_value":{"a":1, "b":0, "g":0, "r":0}}.