Working in different explorations and iterations and talking in some meetings with @Volker_E and @Sarai-WMDE I move forward with this proposal for the Shadow tokens (Globals and Decisions).

The following tokens have been defined:

Global shadows:

• Drop shadows
• Inset shadows

Decision tokens:

• Elevation
• Focus

👇Decision: Do we want to call the drop shadows decision tokens "Elevations"? I have been thinking in more options but I think it's the best name since what it really does is raise the cards or popups.

@iamjessklein we need your confirmation to close this task.

You can view the Figma file here.

Are the elevations actually 1 line descriptions of the title of the shadow type? If so, I am not sure that it's a term that designers usually associate with drop shadows (so it adds unnecessary complexity).

The “Drop” and “Inset” names are currently hindering final implementation. From a multi-theme perspective it's hindering to already define the drop/inset attribute on the theme-level token name.

@Volker_E can you clarify what you mean here? Do you have a proposal for renaming the tokens?

In T297003#7875853, @Volker_E wrote:

The “Drop” and “Inset” names are currently hindering final implementation. From a multi-theme perspective it's hindering to already define the drop/inset attribute on the theme-level token name.

@Volker_E I don't understand what you are mean. Could you clarify or give me an example of how should we name shadows?

The current proposal (v6 2022-02-16) features names like “Drop 500” or “Inset 200” as theme option tokens. Those two attributes already carries a quality of the token value. But we can't know if in a different theme the Inset 200 is really turning inset.
Hence we should call them something like Shadow 1000-1900 for outset/drop and Shadow 0-900 for inset or similar.

In T297003#7883475, @Volker_E wrote:

The current proposal (v6 2022-02-16) features names like “Drop 500” or “Inset 200” as theme option tokens. Those two attributes already carries a quality of the token value. But we can't know if in a different theme the Inset 200 is really turning inset.
Hence we should call them something like Shadow 1000-1900 for outset/drop and Shadow 0-900 for inset or similar.

@Volker_E updated option tokens from drop and inset to simply shadow with numbers from 100-900 and from 100-0 for inset (I've used 0-900 instead of 0-1900 since we are also using 0-100 for other tokens). We will still using drop and inset for decision tokens nomenclature.

Change 800084 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] tokens: Use design-first `box-shadow` tokens

https://gerrit.wikimedia.org/r/800084

Change 802441 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] styles: Apply design-first `box-shadow` tokens

https://gerrit.wikimedia.org/r/802441

@Volker_E I add here the new spec sheet version created with your last feedback in Figma so you can update the shadow tokens with the following:

1. Options:
   • Opacities unified to 0.2 (instead of 0.15, 0.2 and 0.25)
2. Decisions:
   • State decisions will be documented as legacy since they are shorthands (combination of different values from Shadows + Colors) and we decided to document all shorthands in our system as legacy.
   • We’ll use drop and inset for names and we’ll revisit them if we have problems with theming.

Moving from sprint board to backlog per our defined goals at sprint planning; please holler if there's a reason to bump up the priority.

Change 804261 had a related patch set uploaded (by VolkerE; author: VolkerE):

[oojs/ui@master] styles: Rename vars to be forward-compatible with Codex tokens

https://gerrit.wikimedia.org/r/804261

Change 804261 merged by jenkins-bot:

[oojs/ui@master] styles: Rename vars to be forward-compatible with Codex tokens

https://gerrit.wikimedia.org/r/804261

Change 807056 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] tokens: Introduce `box-shadow-color` decision tokens

https://gerrit.wikimedia.org/r/807056

Change 800084 merged by jenkins-bot:

[design/codex@main] tokens: Use design-first `box-shadow` tokens

https://gerrit.wikimedia.org/r/800084

Change 802441 merged by jenkins-bot:

[design/codex@main] styles: Apply design-first `box-shadow` tokens

https://gerrit.wikimedia.org/r/802441

Change 807056 merged by jenkins-bot:

[design/codex@main] tokens: Introduce `box-shadow-color` decision tokens

https://gerrit.wikimedia.org/r/807056

Change 813630 had a related patch set uploaded (by Jforrester; author: Jforrester):

[mediawiki/core@master] Update OOUI to v0.44.1

https://gerrit.wikimedia.org/r/813630

Change 813630 merged by jenkins-bot:

[mediawiki/core@master] Update OOUI to v0.44.1

https://gerrit.wikimedia.org/r/813630

@bmartinezcalvo One small missing detail is, we need transparent as box-shadow-color as well. We need it for a smooth transition between states.

In T297003#8094865, @Volker_E wrote:

@bmartinezcalvo One small missing detail is, we need transparent as box-shadow-color as well. We need it for a smooth transition between states.

@Volker_E updated Figma proposal with box-shadow-color-transparent

Change 816020 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] tokens: Replace legacy `@box-shadow` tokens with new combination tokens

https://gerrit.wikimedia.org/r/816020

Change 816020 merged by jenkins-bot:

[design/codex@main] tokens: Replace legacy `@box-shadow` tokens with new combination tokens

https://gerrit.wikimedia.org/r/816020

@Volker_E design sign off done and box-shadows created as Figma styles in the new Design Tokens library.

@bmartinezcalvo I think in this case, it would make sense to jump over QTE sign-off, don't you think? cc: @EUdoh-WMF

In T297003#8108581, @Volker_E wrote:

@bmartinezcalvo I think in this case, it would make sense to jump over QTE sign-off, don't you think? cc: @EUdoh-WMF

If @EUdoh-WMF agrees we can jump to Product sign off then.

@bmartinezcalvo @Volker_E I completely agree!

Looks great! Before I sign off quick question: does it make sense to simply replace the Codex doc section with a link to Figma and simply add a description of the token?

We can use this as a practical example of how to start differentiating documentation and land on sources of truth for specific info...

Currently we have 2 locations for token documentation:

• FIGMA: https://www.figma.com/file/mRvSsFD2Kwh8AZNjlx7rIl/%E2%9C%A8-Design-Tokens?node-id=207%3A2335
• CODEX Doc: https://783871--wikimedia-codex.netlify.app/design-tokens/box-shadow.html

We should keep both resources. We need to make tokens available in the Codex demo site, so they remain directly and easily accessible for developers (this is an automated process). We also need to keep documenting tokens (manually) in Figma because:

• We use the visual representation of tokens to create reusable styles (when possible). For example, each base color token in the design palette is recorded as a reusable color style in Figma. These styles are then consumed by design components in the library.

• This increases findability and consultation for designers, as they can 1. see the design tokens used in context via the mentioned styles (vs. having to check SFCs), 2. access to usage descriptions (which we could/should also document in the token visualization pages in the Codex, of course)

• Some tokens can be reused as components for specification, which supports consistency. For example, documenting the individual spacing tokens from the scale as reusable elements would facilitate the application of system compliant spacing in compositions.

But, it might be worth exploring if there are ways to keep both resources automatically aligned. I never found a solution that really worked, but Figma and its community are growing quickly, and design tokens are more and more common. As a con, implementing some sort of automated solution will probably mean that we'll have to redefine our token "publication" workflow, and probably reshape all our current documentation, though.

Agree with @Sarai-WMDE. That's one of the challenges with the design system, we need to cater to both audiences, designers and developers slightly differently (and the PMs somewhere in between on a more zoomed out level ;) ). See also T295605.

We have been trying to keep the documentation as slim as possible in order to not so easily go out of sync between Figma and Codex demo site by keeping walls of text aligned.

Further options would besides Figma automated token assets output also be stronger IDE support (similar to TypeScript), but currently such options are very immature and under constant change.

All good. Product sign-off complete.

We'll look at documentation in the documentation epic.