Adds new token property (`$private`) #172

TremayneChrist · 2022-09-26T15:10:37Z

Adds support for private tokens, to make defining tokens easier, without bloating any token outputs.

A simple use case could be using internal color palettes to create gradients, for example:

{
  "color": {
    "$private": true,
    "red": {
      "$value": "red"
    },
    "orange": {
      "$value": "orange"
    },
    "yellow": {
      "$value": "yellow"
    },
    "green": {
      "$value": "green"
    },
    "blue": {
      "$value": "blue"
    },
    "indigo": {
      "$value": "indigo"
    },
    "violet": {
      "$value": "violet"
    }
  },
  "gradient": {
    "$type": "gradient",
    "rainbow": {
      "$value": [
        {
          "color": "{color.red}",
          "position": "0"
        },
        {
          "color": "{color.orange}",
          "position": "0.166"
        },
        {
          "color": "{color.yellow}",
          "position": "0.333"
        },
        {
          "color": "{color.green}",
          "position": "0.5"
        },
        {
          "color": "{color.blue}",
          "position": "0.666"
        },
        {
          "color": "{color.indigo}",
          "position": "0.833"
        },
        {
          "color": "{color.violet}",
          "position": "1"
        }
      ]
    }
  }
}

Adds support for private tokens

netlify · 2022-09-26T15:10:42Z

✅ Deploy Preview for dtcg-tr ready!

Name	Link
🔨 Latest commit	`46f9e1d`
🔍 Latest deploy log	https://app.netlify.com/sites/dtcg-tr/deploys/6331c0ef1ea83d0007ee3c78
😎 Deploy Preview	https://deploy-preview-172--dtcg-tr.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 site settings.

romainmenke · 2022-09-26T15:41:04Z

technical-reports/format/design-token.md

+
+Marks a token as private.
+
+Private tokens can be used to create aliases and other token combinations, reducing duplication and simplifying token outputs. Tools can resolve private tokens internally, but should not look to make them publicly available by default.


This effectively makes this a write-only storage.

Once someone marks a token as private it would become invisible to them because their tool would need to honour the flag.

It might be more interesting to have "filter" tools that teams can use to convert one or more "source" token files into a "filtered" final token file.

🤔 Tools could be required to have a setting to show or hide private tokens.

It depends on how you see these files being used. A token editor tool, could consume the input JSON and would be able to see all tokens and allow you to see/modify the private flag.

A translator on the other hand, would resolve private tokens, but would not export them to any output files (e.g. CSS, XML, JSON etc.)

I feel designers and developers should be consuming a processed output and see the input JSON as the source of truth, which only a certain set of designers modify. This could be an alternative approach to filter tools.

So this wording would need to change to be clearer around different types of tooling.

Would it then not be better to have a token management app/service which stores this information under $extension. Team members would use this app/service to configure/compose different exports for certain other teams to consume.

Team A needs tokens 1,2,3

Team B needs tokens x,y,z

....

I don't think this requires a spec change.

which only a certain set of designers modify.

I don't think it makes sense to encode a hierarchy of control over tokens in the spec. (what if tokens are created by developers with dev tools in a certain org?)

I do think it can be useful to have a filter to reduce clutter.

Also see #110

The issue that I'm facing is that I want to use tokens to create tokens. However, I don't want the tokens I used to create the tokens to be pomoted for use - They are used for computing other tokens, and I want to pass this information to translators so that they can choose how to handle them. An option could be passed to a translator to include them in the output. It's a way to structure tokens.json and inform translators which tokens are relevant and should be exported by default. It may only be a single token that is marked as private, but is used to create many other token values.

The example in the description is probably not the best. It hides colors from designers, which is not ideal.

Double checking because private has a very strong association with access control and that is a different thing.

$hidden?

Classes in certain programming languages also have to concepts of abstract and final. I think that has some overlap.

abstract -> only intended to be used to construct other tokens
final -> never intended to be used to construct other tokens

Tokens with $abstract :

can only be used via an alias

never possible to access their value directly

Tokens with $final :

can never be aliased

You don't need both concepts.

After thinking about this a bit more, I don't think we need to go that far, we're not designing a new programming language here - it's essentially a configuration file. $abstract and $final feel a bit too much.

I agree that $private is the wrong name, however, and I would suggest it to be more like a visibility state, hidden/visible. Token editing tools would be able to see all tokens and modify the visibility state for translators.

$hidden seems like a good option.

kaelig · 2022-11-02T22:18:30Z

Thank you so much for this contribution!

Note: this is my opinion and this isn't a DTCG decision as I haven't discussed it with other editors: I'd be in favor of shelving this for now, and see if this becomes a strong need that would make sense to provide as part of the spec.

My assumption is that people who want "private" tokens could use a prefix like underscore (_myPrivateToken) or a metadata extension field, so that the appropriate part of their toolchain knows when to omit a token in the output.

TremayneChrist · 2022-11-21T13:38:32Z

Hi @kaelig,

Thanks for your reply!

After discussing with @romainmenke. I think $private feels like the wrong property name. I'm actually thinking this is more of a visibility state, so $hidden would be more appropriate. Token editing tools would be able to see all tokens and modify this visibility state for translators.

My assumption is that people who want "private" tokens could use a prefix like underscore (_myPrivateToken) or a metadata extension field, so that the appropriate part of their toolchain knows when to omit a token in the output.

Underscores are only used when these sort of features are not supported - I don't feel this is a good solution. Using extension for this seems overkill, too.

Token references and alias are very powerful. However, they create duplication. Some of which, you may want to omit from the translated result. If there was a way to say these tokens should be hidden when translated, you provide a simplified and clear set of tokens for use in other platforms.

kaelig · 2022-12-13T01:33:35Z

I totally see the need for "omit from output" functionality, but not sure it should be in the core grammar of the spec right now.

For example, you may want to output a certain token for a particular case, and omit it in another (iOS vs Android). This could be achieved using multi-file token sets.
We haven't tackled multi-file token sets yet, and I have the feeling this is when private/public tokens will become very relevant (in a similar fashion as ES imports).

kevinmpowell · 2023-01-23T14:08:45Z

I'm in agreement with @kaelig on this. I don't think this is something needed right now.

Adds new token property ($private)

46f9e1d

Adds support for private tokens

romainmenke reviewed Sep 26, 2022

View reviewed changes

TremayneChrist closed this Jan 26, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adds new token property (`$private`) #172

Adds new token property (`$private`) #172

TremayneChrist commented Sep 26, 2022

netlify bot commented Sep 26, 2022 •

edited

romainmenke Sep 26, 2022 •

edited

romainmenke Sep 26, 2022

TremayneChrist Sep 26, 2022

TremayneChrist Sep 26, 2022

romainmenke Sep 26, 2022 •

edited

romainmenke Sep 26, 2022

TremayneChrist Sep 26, 2022

TremayneChrist Sep 26, 2022

romainmenke Sep 26, 2022

TremayneChrist Nov 21, 2022

kaelig commented Nov 2, 2022

TremayneChrist commented Nov 21, 2022

kaelig commented Dec 13, 2022 •

edited

kevinmpowell commented Jan 23, 2023


		Marks a token as private.

		Private tokens can be used to create aliases and other token combinations, reducing duplication and simplifying token outputs. Tools can resolve private tokens internally, but should not look to make them publicly available by default.

Adds new token property ($private) #172

Adds new token property ($private) #172

Conversation

TremayneChrist commented Sep 26, 2022

netlify bot commented Sep 26, 2022 • edited

✅ Deploy Preview for dtcg-tr ready!

romainmenke Sep 26, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

romainmenke Sep 26, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kaelig commented Nov 2, 2022

TremayneChrist commented Nov 21, 2022

kaelig commented Dec 13, 2022 • edited

kevinmpowell commented Jan 23, 2023

Adds new token property (`$private`) #172

Adds new token property (`$private`) #172

netlify bot commented Sep 26, 2022 •

edited

romainmenke Sep 26, 2022 •

edited

romainmenke Sep 26, 2022 •

edited

kaelig commented Dec 13, 2022 •

edited