Re: [community-group] Toughts on the Use of "$" Prefix in the DTCG Token Standard (#240)

Thanks for going into a discussion so quickly and sharing your thoughts on that, @ddamato. Let me try to reply in detail and also trying to challenge a little bit on what you said:

> I'm reasonably sure the $ convention used here is based on the variable naming convention originating in Sass. The jQuery usage is less relevant, as the entire library was meant to exist under that one namespace. Design tokens are more closely related to styling variables than DOM manipulation. I'm not familiar with RxJS observables, but there will be plenty of $ among other languages, just like there is plenty of usage of different characters for other reasons. I don't know how the RxJS ecosystem clashes with what is expected to be used in this specification.

- Using SASS naming conventions as an archetype for a design token naming conventions feels odd, because the SSOT for design tokens will be JSON, right? Why not stick to common naming patterns from the Javascript world then, which IMO would make more sense then having dollar signs and a lot of kebab-case variable names?
- The jQuery example should just show, where this special character was already been used. Of course I know that it is the alias for the whole library object, but my point is that parts of the web community back then already disliked the `$` for it.
- Further the RxJS example should just show, that there already have been times, where people introduced the `$` prefix for observables, in oderer to mark those variables as a stream of data, but there has ever since been controversial thoughts about that in the community.
- I think it took me a while until I understood your statement "Design tokens are more closely related to styling variables than DOM manipulation". Do not get mislead by my examples, that I am mixing up what design tokens are and what DOM manipulation is. But as the design token definitions and SSOTs of these design tokens will be in the JSON format, I have a strong focus on how these design token definitions will later be used as the input of some Javascript tooling and maybe a whole ecosystem around it. 
- You are right that plenty of $ signs have been used in other languages, but with JSON we just are in the realm of Javascript. From my experience it has never been good advice to work against a framework or programming language, in regard of the controversies in past and common practices within Javascript. 

> Regardless of the history, what I find beneficial in the $ prefix here has to do with JSON's restrictions. While yes it would be great to have all of these enhancements to help the developer experience, the core of the specification is expected to align with JSON's limitations, AFAICT. We have used _ to denote private because the language used doesn't support the concept of private (until it does). This isn't necessarily meant for someone to edit in an IDE but for systems to ingest and transform into styles.

- I know that the JSON restrictions sometimes are pretty tight. Probably this is the reason for things like JSON5 gaining more and more popularity, but they are not solving the kinds of restrictions you are referring to.
- For defining private things I actually can live with an underscore "_", because of the JSON restrictions I also see no other possibility here. Furthermore this is common knowledge among developers. I still have the opinion that things like that should be avoided if possible, cause in fact this is coming from legacy programming times, where no IDEs existed and there has been no other possibility to indicate to developers, that this should be treated as private. Today though with the modern IDEs this is not an issue anymore, but is reducing the code readability.
- Another disadvantage of a special character prefix is, which btw we already have been faced a lot with in SASS variables, is that you will always miss selecting the $ sign, when simply double clicking on the variable name, which might result in an annoying DX:
![double click word selection](https://github.com/user-attachments/assets/ecf5bb9a-36ae-4600-a3e3-ce3106c25e4e)

> Further, I find that the $ provides more clarity as a "special" field than if special keys were to exist without needing to dive into documentation. It should raise the question, "Why do these keys have this prefix?" as opposed to if keys look like any other keys. However, given that you've raised the idea, I'd like to know what you suggest as alternatives, knowing the limitations.

- Only thing here is that I could not see how the `$` special character is helping more here, compared to just a written word prefix like "token" for example. If you say a developer who sees the `$` sign should ask himself "Why do these keys have this prefix?", doesn't he then have to look into the documentation, opposed to when we would actually have a speakable variable name with a prefix that marks these properties, but you already understand while reading it, for what this property stands for?



> specialness in human review is a big sell for the $ - and I don't see the $ translating to tokens in CSS or in places where it'll clash with a JQuery or equivalent.

- IMO it would be a big sell for using speakable property names, that are easier to review by humans, compared the special character prefixes, @nesquarx !?
- I am aware, that the actual token names, except they are compiled to i.e. SCSS web platform output format, will have no dollar sign in it. I am very well differentiating this, but there are use cases where the original SSOT design token definition might be used as a source, for example to have a dynamic design token documentation on a website, which is displaying the design token value, depending on its type in different ways and also wants to show the description maybe. I am not recommending that someone should build such a documentation with jQuery :D but I am convinced that this could be a common use case and in theory, there it could clash with jQuery or RxJS. Like I already said, the design token SSOT definitions in the JSON files, will not only be the source for the actual design token output files for different platforms in different formats, it will also be the source for a whole ecosystem of tools around design tokens, which will have to rely on this standard in the end.



## So here is my innocent take on this

Referring to your example from https://design-tokens.github.io/community-group/format/#description-0

```json
{
  "brand": {
    "$description": "Design tokens from our brand guidelines",
    "color": {
      "$description": "Our brand's primary color palette",
      "acid green": {
        "$value": "#00ff66"
      },
      "hot pink": {
        "$value": "#dd22cc"
      }
    }
  }
}

```

`$description` but also `$type` can be used on a group level. If one concern is to prevent conflictes between the property names of the design token standard and possible design token names, then it would also help if there are no conflicts of properties that are on different levels in the object hierachy of the design token definitions. While the description on the group level also is description just like a description for a single design token, there is still the difference for what these descriptions stand for. One for a group of tokens and one for a single token. Therfore I suggest that we actually name these descriptions for what they actually stand for: `tokenGroupDescription` and `tokenDescription`

I would suggest the following:
```json
{
  "brand": {
    "tokenGroupDescription": "Design tokens from our brand guidelines",
    "color": {
      "tokenGroupDescription": "Our brand's primary color palette",
      "acid green": {
        "tokenValue": "#00ff66",
        "tokenType": "color",
        "tokenDescription": "Really ugly green",
      },
      "hot pink": {
        "tokenValue": "#dd22cc",
        "tokenType": "color",
        "tokenDescription": "Really hot pink",
      }
    }
  }
}

```
with the following exemplary JSON naming schema:
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "patternProperties": {
    ".*": {
      "type": "object",
      "properties": {
        "tokenGroupDescription": {
          "type": "string"
        },
        ".*": {
          "type": "object",
          "properties": {
            "tokenGroupDescription": {
              "type": "string"
            },
            ".*": {
              "type": "object",
              "properties": {
                "tokenValue": {
                  "type": "string",
                  "pattern": "^#[0-9a-fA-F]{6}$"
                },
                "tokenType": {
                  "type": "string",
                  "enum": ["color"]
                },
                "tokenDescription": {
                  "type": "string"
                }
              },
              "required": ["tokenValue", "tokenType"]
            }
          }
        }
      }
    }
  }
}

```

I am on vacation for the next time, but I sure will pick up any discussion for when I am back in September.

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


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

Received on Thursday, 15 August 2024 01:35:21 UTC