Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adds new token property ($private) #172

Closed
wants to merge 1 commit into from
Closed

Adds new token property ($private) #172

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
30 changes: 30 additions & 0 deletions technical-reports/format/design-token.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,36 @@ For example:

</aside>

## Private

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also see #110

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

$hidden?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


A token's visibility can be specified by the optional `$private` property. If the `$private` property is not set to `true` on a token, then the token's visibility is visible.

The `$private` property can be set on different levels:

- at the group level
- at the token level

The value of the `$private` property MUST be a boolean, whose value is either `true` or `false`.

For example:

<aside class="example">

```json
{
"Button background": {
"$value": "#777777",
"$private": true
}
}
```

</aside>

## Extensions

The optional **`$extensions`** property is an object where tools MAY add proprietary, user-, team- or vendor-specific data to a design token. When doing so, each tool MUST use a vendor-specific key whose value MAY be any valid JSON data.
Expand Down