Consider refining or documenting the current range of opacities

[jonathantneal]

The current opacity tokens represent a particularly narrow range of values; 35%, 40%, 45%, and 50%.

In the current web components library, the 40% value is represented as --disabled-opacity.

• Are all of these tokens used? Are any deprecated? Should any be removed?
• Where does the design system communicate these effects to users? Like:
  • As a consumer of the design system, how should I know which opacity reference is appropriate?
    • Like, is there a range of opacities because there is a range of disabled-ness-es?
    • Or, like, is there a range of opacities because specific colors look better with specific opacities?

Without understanding the effects of this particular range of opacities, I think it will be too difficult to use them effectively.

[markacianfrani]

35% actually has a description "Used in drop shadow for dialogs in light theme" and 45% "Used in drop shadow for dialogs".

50% is used in scrollbar's inner vertical shadow.

I think it will be too difficult to use them effectively.

This is key. Reference tokens themselves aren't meant to be used by the end user. That's what System tokens are for.

For that to work, we need better System tokens. So I would propose from this we create
opacity-disabled, (which I think was my original intention when I added that --disabled-opacity var, that we would promote it up the chain).

The description for 35/45% isn't great because its talking about intent. It should really just be something as dumb as '35% opacity' if we want to be redundant. If we want to know where it's being used, we can easily look up the single component level token that references it.

I would like to know why do we have 35% and 40%? What is it about 40% that isn't good enough to fit the use case of drop shadow for dialogs in light theme? Why 35% and not 30%? Can we maybe consolidate to 30, 40, 50%? or remove 30 altogether?

[jonathantneal]

35% actually has a description

Indeed, it does. Without wading into your question of whether it should, I am glad we have a description of what currently is.

Reference tokens themselves aren't meant to be used by the end user.

If this is true, then we should not ship them.

• Question: Should they be linting rules, instead?

I would propose from this we create opacity-disabled...

Yes, this would effectively be #47.

... why do we have ...

All very good questions. I’ll leave the answers to the design team.

Would you agree to this set of actions?

1. Consider shipping opacity-disabled (Consider system tokens for opacity #47).
2. Consider not shipping reference tokens, if they are not meant to be used by a consumer.
   1. Be certain we have all the system tokens we need for theming web components.

[markacianfrani]

Yep! Let's break out #2 into a separate discush.

I think they should definitely be linting rules, but as an addition not in place of. It gets a little weird because design doesn't have a real concept of linting (yet 😉). So when we talk about "shipping" do we just mean the web output targets?

[jonathantneal]

Yes, for CSS the goal would be to only ship custom properties intended for use.

The bar is high for custom properties, because, unlike shipping stray blocks of HTML or JavaScript, which are rarely accessible to authors, shipping any stray custom property in CSS is automatically a publicly accessible feature.

[markacianfrani]

I should clarify--it's not that Reference tokens shouldn't ever be used/made available, rather,
System tokens are preferred.

We prefer people use our context abstractions to prevent misuse (we want a consistent background color) But there's still going to be things we are missing. For example, what should the background color be if text is highlighted? There's no System guidance so I might grab a Reference yellow

[jonathantneal]

I like that, @markacianfrani. What do you think about, generally, expecting to ship reference tokens that represent scales? These would be things like sizing scales and color scales.

Example: the 15 color scales in Radix

For example, what should the background color be if text is highlighted? There's no System guidance so I might grab a Reference yellow

This is where a reference scales might be especially valuable. Consider this yellow scale. It enforces branding, protects contrast, and won’t bust the design if they switch to dark mode. (Note: the design system is currently limited to dark mode, where reasonably and naturally reaching for a reference yellow that is only absolute yellow might be make marked text illegible.)