Groups and Aliases Specification Updates

[ilikescience]

Changes

Groups and Aliases Specification Updates

This PR introduces significant updates to the Groups and Aliases sections of the design tokens specification, addressing key community requests while maintaining backward compatibility and aligning with established JSON standards.

Summary of Changes

Groups Specification

• Root tokens: Added support for $root tokens within groups to enable default values alongside variants
• Group inheritance: Introduced $extends property for group inheritance with deep merge semantics
• JSON Schema alignment: Defined $extends as syntactic sugar over JSON Schema $ref to leverage existing specifications
• Clear parsing rules: Resolved ambiguity between tokens and groups with explicit validation requirements

Aliases Specification

• Dual reference syntax: Maintained curly brace syntax for token references while adding required JSON Pointer support
• Property-level references: Enabled fine-grained references to token properties using JSON Pointer syntax
• Clear semantic distinction: Differentiated between token-to-token references ({token}) and document references ($ref)

Key Design Decisions and Tradeoffs

1. Root Tokens: $root vs Alternatives

Decision: Use $root as a reserved token name for default values within groups.

Considered alternatives:

• Empty string ("") - rejected due to reference ambiguity
• Token-group hybrid - rejected as it violates token/group distinction
• $default - rejected as less semantically neutral

Tradeoff: Slightly more verbose syntax ({color.accent.$root}) in exchange for unambiguous references and conflict prevention.

{
  "color": {
    "accent": {
      "$root": { "$type": "color", "$value": "#dd0000" },
      "light": { "$type": "color", "$value": "#ff2222" },
      "dark": { "$type": "color", "$value": "#aa0000" }
    }
  }
}

2. Group Inheritance: Deep Merge Semantics

Decision: Define $extends with deep merge behavior where local properties override inherited ones.

Rationale: Addresses community need for component inheritance (issue #116) while avoiding specification complexity by deferring to JSON Schema $ref semantics.

Tradeoff: Added complexity in implementation vs. powerful inheritance capabilities for design systems.

{
  "input": {
    "field": {
      "width": { "$value": "100%" },
      "background": { "$value": "#ffffff" }
    }
  },
  "input-amount": {
    "$extends": "{input}",
    "field": {
      "width": { "$value": "100px" }  // Overrides inherited width
    }
  }
}
// Result: input-amount gets background from input, but custom width

Note

The curly-brace syntax in this instance refers to the object at that pointer, whereas in resolving aliases the curly braces refer to the object in the $value property. I see this being potentially confusing; I think we should resolve this before merging.

3. Reference Syntax: Complementary Approaches

Decision: Maintain curly brace syntax for token references, require JSON Pointer support for property references.

Rationale: Originally attempted to make syntaxes equivalent, but discovered fundamental incompatibility - curly braces implicitly target $value while JSON Pointer provides direct path access.

Tradeoff: Two reference systems to learn vs. appropriate tools for different use cases.

{
  "base": {
    "blue": {
      "$value": {
        "colorSpace": "srgb", 
        "components": [0.2, 0.4, 0.9]
      }
    }
  },
  "derived": {
    "whole-token": { "$value": "{base.blue}" },           // Token reference
    "just-hue": { "$ref": "#/base/blue/$value/components/0" }  // Property reference
  }
}

4. Standards Alignment: JSON Schema Integration

Decision: Define $extends as syntactic sugar over JSON Schema 2020-12 $ref with sibling properties.

Benefits:

• Leverages battle-tested specifications rather than inventing new semantics
• Enables use of existing JSON Schema tooling
• Future-proof as JSON Schema evolves
• Reduces specification maintenance burden

Tradeoff: Some complexity in explaining the relationship vs. simpler custom merge rules.

Community Impact

Addresses Key Issues

• How to do tokens that share a name with a group #97: resolved with $root approach
• Tokens group $extends property proposal #116: resolved with $extends
• The $ property name prefix should be unnecessary with a well-structured schema #225: maintained for clarity and conflict prevention
• Be explicit about whether or not empty groups are allowed #235: explicitly permitted

Use Cases Enabled

Component inheritance:

{
  "button": {
    "$type": "color",
    "background": { "$value": "#0066cc" },
    "text": { "$value": "#ffffff" }
  },
  "button-primary": {
    "$extends": "{button}",
    "background": { "$value": "#cc0066" }  // Override just background
  }
}

Semantic color relationships:

{
  "brand": {
    "blue": { "$value": { "components": [0.2, 0.4, 0.9] } }
  },
  "semantic": {
    "primary": {
      "$value": {
        "components": [
          { "$ref": "#/brand/blue/$value/components/0" },  // Same hue
          { "$ref": "#/brand/blue/$value/components/1" },  // Same saturation  
          0.7  // Different lightness
        ]
      }
    }
  }
}

Migration Path

• Backward compatible: Existing token files continue to work unchanged
• Incremental adoption: New features are opt-in
• Tool flexibility: Multiple implementation approaches supported

Implementation Requirements

Tools implementing this specification must:

1. Support both curly brace and JSON Pointer reference syntax
2. Implement deep merge semantics for $extends
3. Validate token vs group distinctions
4. Detect circular references in both inheritance and aliases
5. Follow JSON Schema $ref patterns for extension resolution

This update significantly enhances the design tokens specification's expressiveness while maintaining the simplicity and clarity that makes it accessible to design system teams.

How to Review

How can a reviewer review your changes? What should be kept in mind for this review?

[netlify]

✅ Deploy Preview for designtokensorg ready!

Name	Link
🔨 Latest commit	933b574
🔍 Latest deploy log	https://app.netlify.com/projects/designtokensorg/deploys/68c06521240793000868930c
😎 Deploy Preview	https://deploy-preview-298--designtokensorg.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[drwpow]

Love this! Thanks for putting this together

[drwpow]

Question: A related concept in OpenAPI schema is allOf, where it can provide an array of items to compose, e.g.:

{
  "Cat": {
    "description": "A representation of a cat. Note that `Cat` will be used as the discriminating value.",
    "allOf": [
      { "$ref": "#/components/schemas/Mammal" },
      { "$ref": "#/components/schemas/Pet" },
      …
    ]

This is not JSON Schema; this is OpenAPI which is an extension.

I’m just anticipating someone will ask for this. Because at least in OpenAPI land, this is used a surprising number of times. Do we want to support $extends as an array? Which would move it away from JSON Schema and closer to this OpenAPI concept. Just curious if this enables something, or if this just overcomplicates it (and if the latter, it would be nice to have some example that this breaks etc).

[ilikescience]

I'm struggling to think of a case where you'd want to extend multiple groups; I'm certainly open to using an array here but would rather wait for someone to ask before introducing it.

[Sidnioulz]

Super happy to see $root and $extends, those are both concepts I've needed in the past. I've definitely baked my own support for $root in past SD pipelines.

Decision: Maintain curly brace syntax for token references, require JSON Pointer support for property references.

Rationale: Originally attempted to make syntaxes equivalent, but discovered fundamental incompatibility - curly braces implicitly target $value while JSON Pointer provides direct path access.

@ilikescience I think it's a problem that this shorthand exists. I've wanted to resolve aliases to whole tokens in the past (because they were identical), and not being allowed to do prevented me from reducing my maintenance surface; aliasing individual properties still meant that adding properties in the source required adding aliases in the targets.

Very happy to have $extends as an escape hatch now, but I still don't get why $value should get preferential treatment in aliasing, forcing other use cases to use an alternate syntax. I'd personally prefer a breaking change that brings both syntaxes on a feature parity level. Though I understand this is in the realm of my personal preferences and I expect the vast majority would prefer for the $value shorthand to be preserved :)

I'd curious if curly brackets shorthands could instead resolve to the same property as the one making use of an alias (e.g. "$value": "{my.token}" points to my.token.$value but "$type": "{my.token}" points to its type) ? That would maintain retrocompatibility for the common use case (value -> value aliasing) whilst allowing more coherence and flexibility.

[ilikescience]

I'd personally prefer a breaking change that brings both syntaxes on a feature parity level.

@Sidnioulz yeah, I think there's probably a lot of arguments on both sides of this. The proposed $ref + JSON pointer syntax gives a common syntax that can replace the syntactic sugar of $extends and curly-brace aliases; I see a future where we might be able to deprecate the syntactic sugar and restrict token authors to $ref + JSON pointers only.

Having both in the short/medium term increases tool complexity a bit, but I think it's a necessary evil to atone for the sin of introducing curly-brace aliases in the earliest versions of the draft without the deep thinking that we're doing now.

[Sidnioulz]

I'd personally prefer a breaking change that brings both syntaxes on a feature parity level.

@Sidnioulz yeah, I think there's probably a lot of arguments on both sides of this. The proposed $ref + JSON pointer syntax gives a common syntax that can replace the syntactic sugar of $extends and curly-brace aliases; I see a future where we might be able to deprecate the syntactic sugar and restrict token authors to $ref + JSON pointers only.

Having both in the short/medium term increases tool complexity a bit, but I think it's a necessary evil to atone for the sin of introducing curly-brace aliases in the earliest versions of the draft without the deep thinking that we're doing now.

Good point! It'll be easier to deprecate either of curly brackets or specifically the value shorthand if most folks have been exposed to a new syntax and if major tools encourage the new syntax by default. It would be more painful to community members to make the breaking change now.