Token schema

[NateBaldwinDesign]

Data model for multi-modal values

Context:

Design tokens represent a single idea, design concept, or use case. These use cases persist across a variety of current and future modes, such as light, dark, low contrast, regular contrast, and high contrast. Generally speaking a token has one value, but the value is based on conditions (such as mode or mode combinations).

For example, blue-100 is a single "idea" about color, which has a value of rgb(245, 249, 255) in light mode and rgb(14, 23, 63) in dark mode. Other tokens may support additional, combinatory modes such as "light + high contrast" or "dark + low contrast".

The problem:

Today in design-data, the data model for tokens follows the idea that every value has a unique data object and UUID. Effectively this means that a single token is repeated in the data for as many times as it has values, each time with a unique identifier.

What that means is that a token, or design use case such as "The default, accent background color" has no singular identifier. There is no way to clearly identify this concept as a single token, because it's implemented three times:

  {
    "name": {
      "colorRole": "accent",
      "property": "color",
      "state": ["default"],
      "colorScheme": "light",
      "legacyKey": "accent-background-color-default",
      "object": "background"
    },
    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
    "$ref": "90d82778-1cbb-47c0-aab9-b6e38a9cdc54",
    "uuid": "d9d8488d-9b38-47e0-9660-dcad040f3ca8",
    "set_uuid": "e05251ac-d64a-4157-9b20-224f0392269e",
    "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json"
  },
  {
    "name": {
      "colorRole": "accent",
      "property": "color",
      "state": ["default"],
      "colorScheme": "dark",
      "legacyKey": "accent-background-color-default",
      "object": "background"
    },
    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
    "$ref": "87a2c8f0-54fd-4939-8f42-3124fde1e49e",
    "uuid": "f24eb871-6419-4cef-88a2-cca8548ae31e",
    "set_uuid": "e05251ac-d64a-4157-9b20-224f0392269e",
    "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json"
  },
  {
    "name": {
      "colorRole": "accent",
      "property": "color",
      "state": ["default"],
      "colorScheme": "wireframe",
      "legacyKey": "accent-background-color-default",
      "object": "background"
    },
    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
    "$ref": "90d82778-1cbb-47c0-aab9-b6e38a9cdc54",
    "uuid": "1f4f6c48-633c-4eb5-b7d6-bf5a9a7fde18",
    "set_uuid": "e05251ac-d64a-4157-9b20-224f0392269e",
    "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json"
  }

Proposed solution

In order to model the data in a way that aligns to the conceptual ideas and methods of design tokens, I propose that we alter this approach so that:

1. There are no duplicate design use case classifications (ie "tokens")
2. A single design use case (token) can have multiple values
3. Values are based on modes or mode combinations when they exist.

What this might look like instead:

  {
  "uuid": "d9d8488d-9b38-47e0-9660-dcad040f3ca8",
  "displayName": "Accent background color default",
  "classification": {
    "colorRole": "accent",
    "property": "color",
    "state": ["default"],
    "legacyKey": "accent-background-color-default",
    "object": "background"
  },
  "valuesByMode": [
    {
      "modes": [
        {
          "colorScheme": "light",
          "set_uuid": "e05251ac-d64a-4157-9b20-224f0392269e",
          "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json"
        }
      ],
      "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
      "$ref": "90d82778-1cbb-47c0-aab9-b6e38a9cdc54"
    },
    {
      "modes": [
        {
          "colorScheme": "dark",
          "set_uuid": "e05251ac-d64a-4157-9b20-224f0392269e",
          "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json"
        }   
      ],
      "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
      "$ref": "87a2c8f0-54fd-4939-8f42-3124fde1e49e"
    },
    {
      "modes": [
        {
          "colorScheme": "wireframe",
          "set_uuid": "e05251ac-d64a-4157-9b20-224f0392269e",
          "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json"
        }        
      ],
      "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
      "$ref": "90d82778-1cbb-47c0-aab9-b6e38a9cdc544"
    }
  ]
}

There are several changes in this proposal, so I will begin with the items that actually support and strengthen the schema and its mirroring of the mental model of tokens for design.

Merging all three tokens into one

Rather than 3 unique "tokens" (unique identifiers with highly duplicative data), the key differentiators are:

1. The mode of the token's value
2. The value itself

Because of that, there's no need for redundancies. Combining it into a single token with a single UUID makes referencing this data simpler.

The valuesByMode array

This could be an array but it could be an object too. What's important is that each object within the valuesByMode field have the following information:

1. modes array, which can house multiple child objects (combinatory modes)
2. The mode object contains the colorScheme, set_uuid, and set_schema so that this information is closer together
3. $schema and $ref are at the same level within a single valuesByMode object, as any mode (or combination of modes) could result in a design value that is either an alias or a hardcoded value.

How this could scale

Here's an example of how combinatory modes could be captured within this model of the JSON

"valuesByMode": [
  {
    "modes": [
      {
        "colorScheme": "light",
        "set_uuid": "e05251ac-d64a-4157-9b20-224f0392269e",
        "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json"
      },
      {
        "contrast": "high",
        "set_uuid": "0000000-00000-000-000-00000000000",
        "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/contrast-set.json"
      }
    ],
    "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
    "$ref": "90d82778-1cbb-47c0-aab9-b6e38a9cdc54"
  }
]

---

There are less-important enhancements that I've included in this proposal. They don't particularly impact the challenge of mode-based values, but I felt they were worth including. These are described below.

Changing name to classification

Since we are no longer using string names for tokens, and they're broken apart into cleaner object structures, this model directly represents that of a classification system (our formal taxonomy approach). None of this data is a "name" per se, despite it being used to generate names. The term "classification" for this object seems more fitting.

Adding a displayName field

Humans will particularly refer to tokens by a name of some sort. If tokens emerge in the future that do not have a legacyKey, then it's difficult to infer from the data itself what a particular token is called (the classification object may not necessarily be ordered in the way they're referred to). Adding this field as optional seems like a nice way to surface a tokens' "name" without the overhead of platform-specific formatting or the nuance of how platforms may abbreviate or alter naming. This is a way for tools and humans to quickly identify what a token is in a human-friendly way.

[GarthDB]

Thanks for writing this up, @NateBaldwinDesign. The core problem you're pointing at is real. Right now, a token as a design concept has no canonical identifier. The only thing tying the light, dark, and wireframe rows together is a shared legacyKey, and that field is both non-canonical and already on our list to remove (it's marked transitional in relationship-format.md). So "there is no single identifier for the token" is a fair read of what we ship today.

Let me go through all four parts and then say where I think we should take it.

1. Merging per-mode duplicates into one object with a valuesByMode array

This is the big change, and I have three reservations worth putting on the table first.

We have been here before. RFC #646 proposed a nested, grouped token shape, and during Phase 2 the spec deliberately moved to flat per-value objects after we hit real problems implementing the grouped version (the history is in token-format.md). Your valuesByMode shape, especially with set_uuid and set_schema living inside each mode entry, drifts back toward the color-set/scale-set model we walked away from. Those two set_* fields are legacy bridge fields we are trying to delete, so folding them into the core structure moves us the wrong way.

The per-value UUID is also doing more work than it looks like. It is the target for $ref aliasing, the identity anchor for diffs and rename tracking, the thing replacedBy points at in the lifecycle rules, and the key Figma and registry sync map against. If a token collapses to one UUID per concept, an alias can no longer point at one specific mode's value, so we would be redesigning resolution and aliasing, not just the file layout.

The part I keep coming back to is the platform manifest. Our whole manifest model rests on layered cascade resolution: every value from every layer (foundation, platform, product) is an independent record that competes, and a platform adds records instead of editing foundation ones. Per-platform custom modes (the extensions.modeSets work that's in flight) fall out of that for free, because the cascade doesn't care how many modes exist. valuesByMode collapses the per-value records that layering depends on. If iOS wants to add one mode's value for an existing foundation token, it either has to reach inside a foundation-owned array (which breaks the layer isolation the manifest is built on) or keep a shadow object (which reintroduces the duplication you're trying to eliminate).

2. The valuesByMode structure itself (combinatory modes)

This is where your model is genuinely nicer. Expressing "light + high-contrast" as a single entry with a modes array reads better than what we do now, which is to author an explicit combination token whose name object sets two non-default mode fields and lets specificity sort it out. If we don't adopt the full structure, this is the piece I'd most want to steal.

3. Renaming name to classification

Agreed, and it's overdue. The SDK and TUI already call this structure "classification" internally (forms.rs, classification.rs); the spec's name is the odd one out. It's a breaking rename that touches the schema, the SDK, and every data file, so it needs its own tracked change, but I don't think it's controversial.

4. Optional displayName

Also agreed. It's cheap and additive, and it solves the real gap where a future token with no legacyKey has no human-readable handle at all.

Where I want to take this

Instead of accepting or rejecting the structure in this thread, I want to compare three options properly and bring the findings back here:

	keeps concept identity	manifest / per-platform custom modes	migration cost
What we ship today	no (only the shared legacyKey)	clean; each mode is its own competing record	none
Your valuesByMode	yes, one UUID per concept	strained; platform values want to live inside a foundation-owned array	high; touches schema, cascade, aliasing, diff, Figma sync, every data file
Concept id on the current shape	yes, add a stable conceptId field	clean; unchanged from today	low; additive field

That third row is the middle path I want to take seriously. Keep the per-value records and the cascade exactly as they are, and add a stable conceptId (or groupId) so the concept has one canonical identifier. That gets us the identity win you're after without redesigning resolution or straining the manifest. The one thing it doesn't give us is your cleaner combinatory-mode syntax, which we'd keep handling with explicit combination tokens.

I've set up a spike to work through all three against the same sample tokens, covering manifest and custom-mode behavior, aliasing and diff identity, Figma sync, combinatory modes, and migration cost, and I'll post the full comparison back here. The classification rename and displayName don't depend on any of that, so we can pick those up separately whenever you're ready.

[GarthDB]

Spike results are in. I ran all three shapes against the same sample tokens (a real multi-mode color alias, a dark plus high-contrast combinatory case, and a cross-token alias) and scored them on 13 criteria across two dimensions: platform manifest and cascade behavior, and identity plus migration cost. Full write-up with the worked samples is in proposal 013 in the repo. The short version:

Manifest and cascade (6 criteria). valuesByMode comes out ahead on exactly one, the combinatory-mode syntax, and strained on the other five (overrides, extensions.tokens, modeSetRestrictions, extensions.modeSets, and cascade layer isolation). They all reduce to the same thing: collapsing the per-mode records into one concept object means a platform can no longer add or override a single mode's value as an independent record without reaching into a foundation-owned array. The current shape and the concept-id middle path behave identically here, and both stay clean.

Identity and migration (7 criteria). valuesByMode wins exactly one, concept identity, which is the same and only criterion the concept-id middle path also wins. On the other six, concept-id keeps aliasing granularity, diff continuity, replacedBy, and Figma sync byte for byte identical to today, leaves the legacy setUuid and setSchema fields as removable as they are now instead of promoting them into the core structure, and costs one additive field instead of a schema, cascade, aliasing, and sync rewrite plus a rewrite of every data file.

So across all 13 criteria, the only thing valuesByMode wins that the middle path doesn't is the combinatory-mode syntax. That's a real win and I still like it, but it's separable from the identity problem you raised, and it doesn't require the full restructure.

Here's what that looks like concretely. Take accent-background-color-default in light mode as it exists today:

{
  "name": {
    "colorRole": "accent",
    "property": "color",
    "state": ["default"],
    "colorScheme": "light",
    "legacyKey": "accent-background-color-default",
    "object": "background"
  },
  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
  "$ref": "90d82778-1cbb-47c0-aab9-b6e38a9cdc54",
  "uuid": "d9d8488d-9b38-47e0-9660-dcad040f3ca8",
  "set_uuid": "e05251ac-d64a-4157-9b20-224f0392269e",
  "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json"
}

The middle path leaves every field alone and adds one:

{
  "name": { "...": "..." },
  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
  "$ref": "90d82778-1cbb-47c0-aab9-b6e38a9cdc54",
  "uuid": "d9d8488d-9b38-47e0-9660-dcad040f3ca8",
  "conceptId": "accent-background-color-default",
  "set_uuid": "e05251ac-d64a-4157-9b20-224f0392269e",
  "set_schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/color-set.json"
}

The dark and wireframe rows get the same conceptId, and now all three share one canonical identifier without anything else changing.

For the combinatory case (dark plus high-contrast), the current shape needs a new row with both fields set in the name object:

{
  "name": {
    "colorRole": "accent",
    "property": "color",
    "state": ["default"],
    "colorScheme": "dark",
    "contrast": "high",
    "legacyKey": "accent-background-color-default",
    "object": "background"
  },
  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/token-types/alias.json",
  "$ref": "<high-contrast-dark-target>",
  "uuid": "<new-uuid>",
  "conceptId": "accent-background-color-default"
}

valuesByMode handles it more directly, as an entry inside the existing concept object:

{
  "modes": [
    { "colorScheme": "dark", "set_uuid": "e05251ac-d64a-4157-9b20-224f0392269e" },
    { "contrast": "high", "set_uuid": "<high-contrast-set-uuid>" }
  ],
  "$ref": "<high-contrast-dark-target>"
}

That's the one place your shape is genuinely nicer than mine.

Where I land:

• I'd decline the full valuesByMode restructure. It solves concept identity but redesigns resolution, aliasing, diff, and Figma sync to do it, and it moves the wrong way on the set_* fields we're retiring.
• I'd adopt the concept-id middle path: a stable conceptId on the current per-value shape. It gives you the canonical identifier you're after, it's an additive field we can backfill from the existing legacyKey, and nothing else in the pipeline has to change.
• I'd like to look at the combinatory-mode syntax as its own separate enhancement on the current shape, since that's the one piece of your proposal worth stealing on its own merits.
• classification and displayName are unaffected and can proceed whenever.

Happy to walk through the proposal 013 write-up if any of the per-criterion calls are worth digging into.

[NateBaldwinDesign]

Thank you for taking a look at this @GarthDB. I'm certain there's a tremendous amount of detail and context I'm missing, so the proposal is really high-level concept rather than explicit recommendation.

I think that adding the conceptId field is a good compromise. I'm curious about whether or not that still warrants separation from the remaining data types for a token as a way of abstracting common information that currently is duplicative. Also, if it's abstracted, we could just use a consistent uuid field for that type of data too. That's a similar approach to Figma variable's REST API payload, where the variable is one thing (with an ID, name, description, codeSyntax, scoping, etc), and the mode-based values are completely separate data objects. Basically my curiosity would be about "why not just have it be the tokens' uuid instead of calling it something different?" but it's not a big deal mostly curiosity.

I see the benefit of having uuids for each mode-based value. I must have overlooked it and omitted it from my proposal. I'm curious how the Figma workflow maps to these since the API post data for creating or updating a mode value of a variable consists of the variableId (equivalent of the conceptId) and the modeId (equivalent to the set_uuid) rather than having their own unique ID.

I'm also curious about this:

The per-value UUID is [...] is the target for $ref aliasing

If that's the case, are there guardrails to ensure there is no cross-modal referencing? For example, we have blue-800 that has both a light and dark mode value. We would never want to support the idea that an alias can reference "the dark mode value of blue-800 for it's light value" or vice versa. If alias $refs aren't universally bound to a system of modality, and can independently be mapped to different mode-values of a separate token, then we've opened the doors to a potential future mess (assuming tooling itself isn't also providing some guardrails). I tend to prefer the more purist approach where it's not possible to cross-reference modes, and that what's actually being referenced is just the concept-- the mode value is determined by the mode of the alias itself.

Let me show a real world example:
The token celery-background-color-default is an alias with light and dark values. In light mode, it points to celery-600; in dark mode it points to celery-900. Every celery color in the palette has its own light and dark mode values. But the mapping from designers is always under the context of a single mode per decision.

Token name	Light mode ref	Dark mode ref
celery-background-color-default	celery-600 (light mode value implied)	celery-900 (dark mode value implied)

I worry that if people can cross-referentially map to independent modes for their values, the design aspect of the system could become fragile.

For that, I'd wonder if there's an alternative that ensures you can have the mode-specific value level of diff'ing and history without the potential for disintegrating a conceptual framework like system-level contexts (modes)?

As for combinatory mode values, maybe we can create an example to work with? There's some simple examples for text colors we could devise even just to see how the current setup works. For example, this would be directionally close to what we might come up with in the future:

accent-background-color-default

	Light value	Dark value
Regular contrast	accent-color-900	accent-color-800
Low contrast	accent-color-800	accent-color-700
High contrast	accent-color-1000	accent-color-900

[NateBaldwinDesign]

Shared my comment before seeing that you already replied - reviewing your latest comment now, I see you have a combinatory mode example 👍

[GarthDB]

Thanks, @NateBaldwinDesign. A few of these are new questions, so let me take them one at a time.

On not just using the token's uuid: the per-value uuid already carries a lot of weight, it's the diff unit, the replacedBy anchor, the thing platform sync keys off. conceptId is a second, concept-level anchor sitting alongside it on purpose, so those per-value identities stay untouched. If conceptId collapsed onto the value's own uuid, we'd lose the ability to say "these six objects are the same design decision across modes" without also merging their individual histories.

On abstracting it into a separate object (Figma-variable style) and the workflow mapping: that full separation is basically what valuesByMode does: one concept object, mode values as entries underneath. The spike found it strains against manifest/cascade layering, because per-value records are exactly what platform layers compete over during resolution. conceptId gets you the identity/de-dup win without breaking that. For the Figma crosswalk: conceptId lines up with variableId, the name object's mode-set fields line up with modeId, and our per-value UUID is extra, something Figma's model doesn't really have, since a mode value there has no ID of its own. That extra anchor is what lets us track one mode-value's history independently. Happy to go deeper on the sync mapping separately if that's useful.

On the guardrail itself: you're right that the abstract model doesn't stop it. SPEC-001/SPEC-002/SPEC-003 check that a $ref target exists, type-matches, and doesn't cycle; none of them check mode. So, in principle, nothing stops an alias from pointing at "the dark value of blue-800" while itself being a light token.

But when I went and checked the actual corpus, it's already working the way you want. Zero cross-mode references across all 710 aliases, and it's not close; none of them target a per-mode leaf value at all. They target either a set (resolved against the alias's own context) or a mode-agnostic anchor. Your own celery-background-color-default example turns out to be the set case, and I pulled the actual objects to make that concrete:

{
  "name": { "colorFamily": "celery", "state": ["default"], "colorScheme": "light", "legacyKey": "celery-background-color-default", "object": "background" },
  "$ref": "b908fb61-f581-4942-9d00-57a828a0660b",
  "uuid": "d4fd682d-4bef-4a92-bf14-90ce02b534e6",
  "set_uuid": "5bd340a5-45fc-4666-82b2-827f9f17d6e4"
}

{
  "name": { "colorFamily": "celery", "state": ["default"], "colorScheme": "dark", "legacyKey": "celery-background-color-default", "object": "background" },
  "$ref": "363508bf-9c3a-4e8e-9865-2b4915d2f097",
  "uuid": "a9ab7a59-9cab-47fb-876d-6f0af93dc5df",
  "set_uuid": "5bd340a5-45fc-4666-82b2-827f9f17d6e4"
}

Light $refs the celery-600 set, dark $refs the celery-900 set, and each set expands into private light/dark/wireframe leaves behind it, resolved against the alias's own colorScheme. No cross-referencing, but it's leaning on the same set_uuid mechanism I mention below, not a plain mode-agnostic anchor.

One catch: valuesByMode wouldn't actually enforce the purity you want either. Its entries still carry a bare $ref UUID each, so the same cross-mode pointer is just as possible inside that shape. What's actually doing the enforcing is how $ref gets resolved, context-aware against a concept or set anchor, and that's already true today for the SDK's alias resolution path. It's orthogonal to which shape we store values in.

The real gap is that this safety currently rides on set_uuid/set_schema, which are marked for removal. So the actual work is making sure context-aware resolution gets normalized against conceptId as those fields go away, plus a cheap validation rule as a backstop, something like SPEC-059 (alias-mode-context-compatibility), flagging any alias whose target's mode contradicts its own. Per-value UUID keeps you the mode-specific diff and history; context-aware resolution plus the guardrail rule keeps you mode-safe. You get both, not one or the other.

One more thing on the combinatory table you posted: I worked your exact 2x3 into Sample D in doc 013, all three shapes side by side. Only new wrinkle: contrast.json only declares regular and high today, so the low row is illustrative until that's added as a foundation change.

Your guardrail push sharpened the recommendation rather than changing it: the SPEC-059 backstop and normativizing context-aware resolution as set_uuid/set_schema come out. Doc 013 has it written up: Part 7 for the guardrail analysis and Sample D for the matrix.

[NateBaldwinDesign]

This sounds good, although I'm still unclear on the specifics and resolution to my concern of cross mode referencing (dark mode value of an alias referencing the UUID of the light mode value of another token). Adding that set_uuid and set_schema are marked for removal only has me more confused about what the actual end-result schema would look like and whether or not my concern would be resolved in that state.

My top concerns are:

1. A "token" as an abstract concept / design use case has a singular UUID (concept_id)
2. Combinatory modes can be supported
3. Mode-dependent values are systemically enforced and cannot be cross-referenced (light mode value of celery-600 cannot be used for the dark mode value of an alias)

So long as the current direction fulfills these, then I'm happy. The appearance of redundant data is another concern I have but may not have functional implications or impact design directly, so I'll lean on your recommendation considering all other scenarios you're working towards that I may not be not aware of or fully understand.

[GarthDB]

These three are the right things to pin down, so let me take them one at a time against the actual repo state. On a couple of them the honest answer is "not yet, but here's the path," and your worry about the post-set_* end state is exactly the right thing to be worried about.

1. One singular identifier for a concept, as a UUID. Agreed, and a UUID rather than the human-readable string I'd been sketching. There end up being two identifiers doing two different jobs, and both should stay:

• the existing per-value uuid is unchanged. It's still the $ref target, the diff unit, the replacedBy anchor, and the key platform and Figma sync map against.
• a new concept-level UUID is minted once per design decision and shared by every mode row of that concept.

That's the real answer to your earlier "why not just reuse the token's uuid." If the per-value uuid collapsed onto the concept, we'd lose the ability to track one mode-value's history on its own. So it's two UUIDs on purpose, which lines up with the Figma model you cited: the concept UUID is your variableId, and the per-value uuid is the extra anchor Figma's model doesn't have. We backfill the concept UUID by grouping today's rows on their shared legacyKey (one UUID per group) and it's stable after that. Tracked as DNA-1937. One heads-up: proposal 013 currently writes this up as a string, so I owe it a small edit to match the UUID decision.

2. Combinatory modes are supported. On the current and concept-id shape they're authored as explicit combination tokens, a row that sets two mode-set fields (colorScheme: dark plus contrast: high) and lets cascade specificity sort it out. I worked your exact 2x3 matrix as Sample D in doc 013. It works, it's just wordier than your valuesByMode modes array, which really is the nicer syntax for this case. That's why I want to keep the combinatory syntax alive as its own optional enhancement instead of dropping it. One foundation caveat: contrast.json only declares regular and high today, so low in your table isn't real until it's added as a mode.

3. Mode values can't be cross-referenced, and here's the honest status. Right now the corpus is clean: 0 cross-mode references across all 710 aliases. I don't want to oversell that, though, because it's safe by construction, not by enforcement:

• the normative spec is mode-blind. cascade.md treats $ref as an opaque UUID resolved after cascade, and SPEC-001/002/003 check existence, type, and cycles, but not mode.
• what's actually keeping us safe is context-aware resolution against the set_uuid bridge, and that's SDK behavior riding on the exact fields we're removing.

So turning your concern #3 into a systemic guarantee (not just a happy accident of the current data) needs three things to land as set_uuid/set_schema retire:

1. the concept UUID above becomes the alias anchor, so an alias points at the concept, not a per-mode leaf (DNA-1937).
2. context-aware $ref resolution gets promoted from SDK-only behavior into a normative rule, resolved against that concept anchor and the referencing token's own mode. This is the piece that structurally makes "the alias determines the mode, and you can't cross-reference" true, which is the purist property you're after (DNA-1934).
3. a validation backstop (SPEC-059, alias-mode-context-compatibility) that flags any alias whose resolved target's mode contradicts its own, advisory to start since the scan finds zero violations today (DNA-1935).

Worth saying plainly: switching to valuesByMode wouldn't buy you this either. Its entries still carry bare $ref UUIDs, so a light entry can still be mis-authored to a dark target. The guarantee comes from how $ref resolves, not from where the values are stored. So #3 is answered by the resolution semantics plus the guardrail, on either shape.

On the redundant-looking data. Fair, and I won't wave it away. The concept-id shape does repeat the classification object on every mode row. That repetition is the deliberate price of keeping per-value records, which is what diff and rename tracking, per-value aliasing, lifecycle replacedBy, and manifest layer isolation all lean on. valuesByMode removes the repetition but breaks those (spike criteria 8 through 13). The concept UUID removes the part that actually bites, which is the identity ambiguity, even though the field values still repeat. If the repetition turns out to have real tooling cost down the line, that's a separate optimization we can make without touching identity.

So: #1 yes as a UUID (DNA-1937), #2 yes (verbose today, cleaner syntax tracked on its own), #3 yes as a committed direction with two concrete pieces to build (DNA-1934, DNA-1935). classification and displayName are unaffected and can go whenever you're ready.

[NateBaldwinDesign]

Awesome, this sounds good and thank you for the additional clarification. Since there are already tickets for the remaining work that would resolve anything that was not already demonstrated to be supported, I'll close out this RFC/Discussion.

[GarthDB]

@NateBaldwinDesign this landed, so here's where things stand on your three points:

1. Every token concept now gets one UUID (conceptId), shared across all its mode rows, backfilled across the whole corpus. Proposal 013 is updated too. It used to sketch this as a string; now it says UUID, per your concern. (DNA-1937)
2. Combinatory modes needed no schema change. Sample D already showed the 2x3 accent-background-color-default matrix working in all three candidate shapes (doc 013, Part 7).
3. Cross-mode referencing: cascade.md and token-format.md now spell out context-aware $ref resolution as the normative rule instead of something the SDK just happened to do. It resolves against the conceptId anchor plus the referencing token's own mode (DNA-1934). There's also a new validation rule, SPEC-059 (alias-mode-context-compatibility), that flags an alias if its target's mode doesn't match its own (DNA-1935).

Everything's merged: #1428 has the conceptId work plus the resolution rule and SPEC-059, #1426 updates proposal 013, #1427 is the version bump. set_uuid/set_schema are gone now that conceptId and the resolution rule cover what they used to do.