[community-group] Pull Request: Groups and Aliases Specification Updates

ilikescience has just submitted a new pull request for https://github.com/design-tokens/community-group:

== Groups and Aliases Specification Updates ==
## 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.

```json
{
  "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.

```jsonc
{
  "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.

```jsonc
{
  "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
- **#97**: Default tokens in groups (resolved with `$root` approach)
- **#116**: Group inheritance (resolved with `$extends`)
- **#225**: Dollar prefix necessity (maintained for clarity and conflict prevention)
- **#235**: Empty groups (explicitly permitted)

#### Use Cases Enabled

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

**Semantic color relationships**:
```jsonc
{
  "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?_


See https://github.com/design-tokens/community-group/pull/298


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Tuesday, 19 August 2025 01:21:15 UTC