In the Design Tokens Community Group format, how does one token reference another's value, and what can a curly-brace reference point at?

## What a reference is In the **Design Tokens Community Group format**, a token's value can be another token's value. The draft treats **alias** and **reference** as synonyms. References let a file state a relationship - this progress fill is the palette's green - instead of copying the literal, so a change to the target flows to everything that references it. How many layers of references a system should have is a design question in its own right; this answer is about the syntax and the rules every tool applies. ## Curly-brace syntax A reference is a string in `$value`: the target's **path** wrapped in braces. - The path is built by joining group names and the token name with periods: a token `fill` inside group `progress` inside group `campaign` has the path `campaign.progress.fill`. - The reference `{campaign.progress.fill}` resolves to the **entire** `$value` of that token - for a color, the whole color object. - If the referencing token has no `$type` of its own, it takes the resolved type of its target. - The period's role in paths is why token and group names may not contain `.`, `{` or `}`. ## What a curly-brace reference can and cannot target | Target | Allowed? | |---|---| | a complete token (an object with `$value`) | yes | | a group (an object without `$value`) | no - the reference is invalid | | one property inside a value, such as a color's alpha | not with braces | | a token that is itself a reference | yes - the chain is followed | For the third row the current draft adds a second syntax: a `$ref` property holding a **JSON Pointer**, which can address a specific property inside a token's value, such as one component of a color. The draft requires tools to support it, but it is newer than the brace syntax and still settling, so check what your tools implement before relying on it. ## Chains and cycles 1. **Chains are allowed.** A token may reference a token that is itself a reference. Tools must follow each hop until they reach a token with an explicit value. 2. **Cycles are forbidden.** If `a` references `b`, `b` references `c` and `c` references `a`, no value can be found. The draft says the value of **every** token in the loop is unknown and tools must report an error covering all of them, not just the one that closed the loop. ## How a tool resolves a brace reference The procedure every conforming tool follows is short, which is what makes the syntax portable across design editors, build tools and documentation sites: 1. Strip the braces and split the path on periods into segments. 2. Walk the file from its root, one segment per nesting level. 3. Check that the object reached has a `$value`; if it is a group, the reference is invalid. 4. If that `$value` is itself a reference, repeat, remembering every token visited so a revisit is detected as a cycle. 5. Return the literal value found, and give the original token the target's type if it declared none. Because resolution starts at the root, a reference means the same thing wherever it is written. ## References inside composite values Composite tokens such as `typography`, `shadow` and `border` are made of sub-values, and each sub-value may be a reference to a token of the matching type. A charity site's `chip.border.default` can take its `color` from `{color.palette.slate.300}` and its `width` from `{size.border.thin}`. In an array value, such as a multi-layer shadow, a reference resolves to a single element and is not flattened into the array. ## A charity example The donation progress bar uses `campaign.progress.fill` with `$value` `{color.palette.green.600}`. The 'goal reached' badge uses `campaign.goal.badge` with `$value` `{campaign.progress.fill}`, a two-hop chain that tools resolve to the palette green. When a contributor accidentally points `color.palette.green.600` back at `campaign.goal.badge`, validation reports all three tokens as unresolvable - and the change is caught before any platform output is built. ## Common mistakes - Referencing a group path and expecting a default value from it. - Writing a partial path relative to the current group; references use the full path from the file's root. - Using braces to reach inside a value, which braces cannot do. - Assuming a cycle only breaks the token that closed it.