Re: [community-group] Add a `$private` property for tokens (#110)

My org is also in a situation where we want more granularity than private or public. We have:
* Primary tokens that are exposed first in our documentation, autocompletion, etc and exported to code platforms
* Secondary tokens for edge cases (esp. state management) that are hidden by default in the doc to help newcomers focus on the core tokens
* Occasionally, tokens we create only as fixes to rare edge cases _within the DS code library_ (and intended to be temporary)
* Internal tokens that are used as value refs (e.g. raw color tokens) and we don't want to expose to consumers or even define in exported files

I'm not a fan of wording like `private` because it's got very specific semantics in OOP, that differ from the lay understanding of designers. A designer may expect a private token is used inside the DS component library but not exposed to consumers. Another designer may expect it to not be exported. If we map private tokens to a `private` property in Swift color classes (the OOP meaning), neither mental model is correct.

Besides, whether or not a (raw) token is exported is very easy to manage at the moment. One only has to filter their tokens prior to exporting them in Style Dictionary or similar tools. So building a rigid semantic into the standard just to spare ourselves a one-liner filter feels like over-engineering.

So I'm not sure we would benefit from a semantic enforced directly in the standard unless it is extensible or flexible. One way this could be achieved is, instead of using words with a fixed meaning, allowing a `visibility` property with a numerical value, so we can define orders of visibility. All tool makers can easily handle order relations defined by numbers, without having to attribute meaning. And tools like SD or Cobalt can define default semantics that can easily be overridden.

An order relationship would support many cases and allow extending them, e.g.:
* 1: public tokens
* 2: private or internal tokens

Or:
* 1: primary/core public tokens
* 2: secondary/extra public tokens
* 3: DS-only exported tokens
* 4: tokens exported to code but not usable directly (their name's only visible in debugging tools as they are used as value refs)
* 5: tokens that aren't exported at all (their value is always resolved when they're referenced)
* 6: forbidden tokens whose value must not be referenced at all, which might help with error reporting when deprecating tokens in a large distributed system

And anyone would be free to add however many extra layers of visibility they need and to configure their export tools to map the order relation onto concepts supported by the tools.

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


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

Received on Friday, 19 January 2024 12:24:36 UTC