Re: [community-group] Progressive Token Variant Specificity (#135)

## Idea 2: group $token prop

1. A group is any JSON object that DOES NOT contain a `$value` property.
    * same/similar to current spec
2. A token is any JSON object that CONTAINS a `$value` property.
    * same/similar to current spec
3. An _explicit_ token is one defined using the `$token` property, all other tokens are considered _implicit_.
    * All tokens defined by the _current_ spec are considerd implicit.
    * Explicit tokens are necessary if a JSON path cannot reliably identify a token vs a group.
4. The path of an _implicit_ token is defined by the parent path of the `$value` property.
5. The path of an _explicit_ token is defined by the parent path of the `$token` property.
6. All tokens inherit shared properties defined by their ancestor groups (e.g., `$type`, `$extensions`, etc.)



### Example:
```javascript
{
  "color": {
    "$description": "All the colors",
    "$type": "color",

    "background": {
      "$token": {
        "$value": "#eaeaea"
      },

      "highContrast": {
        "$value": "#ffffff"
      },

      "dark": {
        "$token": {
          "$value": "#555555"
        },

        "highContrast": {
          "$value": "#000000"
        }
      },
    }
  }
}
```
should resolve to the following, flattened token hierarchy:

```json
{
  "color.background": {
    "$type": "color",
    "$value": "#eaeaea"
  },
  "color.background.highContrast": {
    "$type": "color",
    "$value": "#ffffff"
  },
  "color.background.dark": {
    "$type": "color",
    "$value": "#555555"
  },
  "color.background.dark.highContrast": {
    "$type": "color",
    "$value": "#000000"
  }
}
```





## Walkthrough

Task: Define the following tokens

- [ ] `foo.bar = '#abcabc'`
- [ ] `foo.bar.fizz = '#defdef'`


### Step 1: `foo.bar.fizz`

```json
{
  "foo": {
    "bar": {
      "fizz": {
        "$type": "color",
        "$value": "#defdef"
      }
    }
  }
}
```

#### Step 1 Progress

- [ ] `foo.bar = '#abcabc'`
- [x] `foo.bar.fizz = '#defdef'`



### Step 2: `foo.bar`
Now let's define `foo.bar`...

```json
{
  "foo": {
    "bar": {
      "$type": "color",
      "$value": "#abcabc",
      
      "fizz": {
        "$type": "color",
        "$value": "#defdef"
      }
    }
  }
}
```

#### Step 2 Progress

- [x] `foo.bar = '#abcabc'`
- [ ] `foo.bar.fizz = '#defdef'`



### Step 3: Correct definitions
Uh oh!  By defining `#/foo/bar/$value` in step 2, the token discovery algorithm stopped looking for tokens once `foo.bar` was found.

Let's use the `$token` group property to fix this issue.

```json
{
  "foo": {
    "bar": {
      "$token": {
        "$type": "color",
        "$value": "#abcabc"
      },
      
      "fizz": {
        "$type": "color",
        "$value": "#defdef"
      }
    }
  }
}
```

#### Step 3 Progress

- [x] `foo.bar = '#abcabc'`
- [x] `foo.bar.fizz = '#defdef'`


### Step 4: Optimize JSON
We were able to define both tokens, but we can simplify the JSON structure by having both tokens inherit `$type` from the `#/foo/bar` group.

```json
{
  "foo": {
    "bar": {
      "$type": "color",
      
      "$token": {
        "$value": "#abcabc"
      },
      
      "fizz": {
        "$value": "#defdef"
      }
    }
  }
}
```


-- 
GitHub Notification of comment by CITguy
Please view or discuss this issue at https://github.com/design-tokens/community-group/issues/135#issuecomment-1150447442 using your GitHub account


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

Received on Wednesday, 8 June 2022 21:47:36 UTC