I'd love to stick with a px token scale, I think the decisive moment here is the documentation though. Most folks think in pixel and will continue to do so. With the decision tokens we can aim for a translation depending on which property between original px and aimed for unit.

Spacing tokens are ready to move to code iteration. Feel free to assign the task to yourself any time @Volker_E

hei @Volker_E if you give me some guidance on the dev expectation and naming I can help you here.

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

[design/codex@main] tokens: Add size and spacing design-first tokens

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

Hey @SimoneThisDot I've just stumbled on your message. Would appreciate closer look on patch review and possibly also at latest Figma from you or other devs now that we're coming close.

Assuming that a few sequential patches where we apply the tokens might surface possible issues even better.

Can we please have an update on this task status please? Is it still "in progress" or "in development"?

With deeper thoughts after dust has settled on the scale in designs, I still think that we have an option to provide a Style Dictionary step to output around our three needs, dev experience, free unit decision in theme and accessibility:
If we're introducing the helper unit and use it as flag in transforms per category.
So say we've got in theme*.json

"size": {
  "unit": "{ unit.user }"
},
"min-width": {
  "unit": "{ unit.system }"
},

Basically having the helper unit category as token category type flag and SD calculates with (custom) transforms and on condition which unit is used dependently what the themer had in mind. With that we could still live in a one dimension category in px equivalent values and leave the control in one file.

OK, that makes sense to me and I think it could be a good way forward.

Could you explain what your example means exactly? I'm guessing all values would be given in pixels, but would then be transformed to the specified target unit?

In other words, given this input:

"size": {
    "unit": "{ unit.user }",
    "6": { "value": "1" },
    "12": { "value": "2" },
    "absolute-9999": { "value": "9999px" }
},
"min-width": {
    "unit": "{ unit.system }",
    "mobile": { "value": "320" },
    "tablet": { "value": "640" }
},
"unit": {
    "system": "px",
    "user": "em"
}

the output would be this?

@size-6: 0.0625em;
@size-12: 0.125em;
@absolute-9999: 9999px;
@min-width-mobile: 320px;
@min-width-tablet: 640px;

Writing a transform that does that seems very feasible. It's possible that SD might try to interpret unit as a token, but we could filter it out. We would also have to define the exact transformation rules. I'm thinking of something like:

• Only unitless values are transformed. If a value already has a unit (e.g. 50%, 100vh, but also 9999px), it is not transformed
• A value of 0 is never transformed
• Transforming to px means: just add px after the number
• Transforming to rem means: divide by the font size (typically 16), then add rem
• Transforming to em means: divide by the font size (should this be a different font size than is used for rem?), then add em
• Transforming to any other unit is an error

Change 791479 merged by jenkins-bot:

[design/codex@main] tokens, styles: Add `size` and `spacing` design-first tokens

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

In T297000#8353604, @Catrope wrote:

Writing a transform that does that seems very feasible. It's possible that SD might try to interpret unit as a token, but we could filter it out. We would also have to define the exact transformation rules. I'm thinking of something like:

• Only unitless values are transformed. If a value already has a unit (e.g. 50%, 100vh, but also 9999px), it is not transformed
• A value of 0 is never transformed
• Transforming to px means: just add px after the number
• Transforming to rem means: divide by the font size (typically 16), then add rem
• Transforming to em means: divide by the font size (should this be a different font size than is used for rem?), then add em
• Transforming to any other unit is an error

Haha, I'm glad I don't have to write out what I've had in mind, as you've just went ahead with it.
All of above, with one addition. Are there just the main categories that could see the unit choice or are we enabling fine-tuning further…?
Thinking of something hypothetically like

"size": {
    "unit": "{ unit.user }",
    "6": { "value": "1" },
    "12": { "value": "2" },
    "icon": { 
         "unit": "{ unit.system }",
         "small": { "value": "1" },
         "medium": { "value": "2" }
    },
    "absolute-9999": { "value": "9999px" }
},
"unit": {
    "system": "px",
    "user": "em"
}

@Volker_E regarding the Spacing demo, what if we use always blue to represent our token values? I mean, blue for the spacing between the boxes in the demo and blue for the padding representation. We use the blue color to represent other tokens such as animation and we should always use the same visual solution in all our token demos.

@bmartinezcalvo Hmm, as Blue 600 is our interaction accent color, I'd feel better with a different color from our color palette to keep it simpler signaling to users of the Codex demos.

@Sarai-WMDE On the open question of position (top/left/bottom/right) “offset” values.

The more I've thought about it, it makes most sense to feature those as relative (user) sizes. We don't have a big number of them, but all are better to be user scalable or are ok with it without a negative impact of relative sizes.
Currently we feature

@position-offset-border-width-base: -1px;
@position-offset-input-radio--focus: -4px;

First one could remain as absolute. Second one (component token) should turn into using a relative dimension output token.

Additionally there's a few left: 50%; values, which are right now covered by just size tokens. It's not the best dev exp to have size and position-offset tokens mixed, with that I could consider removing position-offset and go with only size again.

The more I've thought about it, it makes most sense to feature those as relative (user) sizes

Sounds great.

It's not the best dev exp to have size and position-offset tokens mixed, with that I could consider removing position-offset and go with only size again.

My first inkling is actually the opposite, but I'm not the target user, so take it with a grain of salt: Position is an entirely different dimension affecting an element (slightly related to spacing, but completely different from size). It makes sense to document it individually, as a separate category. My proposal would be to group known common/shared position values as decision tokens (position-offset, position-left). These could still consume dimension tokens, but be more obvious and aligned with the end CSS properties that will consume them. What do you think?

In T297000#8355756, @Volker_E wrote:

Haha, I'm glad I don't have to write out what I've had in mind, as you've just went ahead with it.
All of above, with one addition. Are there just the main categories that could see the unit choice or are we enabling fine-tuning further…?
Thinking of something hypothetically like

"size": {
    "unit": "{ unit.user }",
    "6": { "value": "1" },
    "12": { "value": "2" },
    "icon": { 
         "unit": "{ unit.system }",
         "small": { "value": "1" },
         "medium": { "value": "2" }
    },
    "absolute-9999": { "value": "9999px" }
},
"unit": {
    "system": "px",
    "user": "em"
}

Yes, I think we should support that (allowing lower levels to override the unit of a higher level) as well.

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

[design/codex@main] tokens: Replace `max-width.breakpoint` token refs with `size.absolute-1`

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

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

[design/codex@main] tokens: Add `spacing-400` token

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

Change 853073 merged by jenkins-bot:

[design/codex@main] tokens: Replace `max-width.breakpoint` token refs with `size.absolute-1`

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

Change 853418 merged by jenkins-bot:

[design/codex@main] tokens: Add `spacing-400` token

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

Change 856707 had a related patch set uploaded (by Catrope; author: Catrope):

[design/codex@main] [WIP] tokens: Add automatic unit transform based on font size

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

Change 856708 had a related patch set uploaded (by Catrope; author: Catrope):

[design/codex@main] [WIP] tokens: Use relative units for some token categories

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

In T297000#8394561, @gerritbot wrote:

Change 856707 had a related patch set uploaded (by Catrope; author: Catrope):

[design/codex@main] [WIP] tokens: Add automatic unit transform based on font size

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

This patch implements the transform described in T297000#8353572. However, writing this has made me think that maybe we should use pixel values with explicit px units instead of unitless numbers (i.e. the value of dimension-100 should be 16px, not 16). I think that would be better because:

• It makes it more obvious what the number means
• The dimension tokens on their own would no longer be meaningless / unable to be used directly
• If the transform doesn't work or isn't applied (e.g. because the theme forgets to set a unit for that token category, which I think is going to happen sometimes, especially when we add a new unit category), the output is something safe that will work (4px) rather than something that will break (4)
• It removes the requirement that themes explicitly specify "unit" properties for each token category. A theme could not provide any "unit"s at all, and it would still get something functional (everything would be in pixels)

Thoughts? (Especially @Volker_E)

Will need code review + conceptual review from @Volker_E

Discussion topic for next Engineering Enclave

Change 859597 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[mediawiki/core@master] Update Codex from v0.2.2 to v0.3.0

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

Change 859597 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v0.2.2 to v0.3.0

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

With more of @Catrope's and some of mine “build, tokens, styles: Introduce simple stylesheet unit transform“ patch we've got requirements of correct scale as tokens of this task fulfilled.

I'd propose to design sign-off and resolve this task and tackle further quest on themeability at T296689 and subsequent tasks. @bmartinezcalvo @Sarai-WMDE

I'd propose to design sign-off and resolve this task and tackle further quest on themeability at T296689 and subsequent tasks. @bmartinezcalvo @Sarai-WMDE

Agreed. The foundational scale was defined and translated into design tokens. The only inconsistency found is @spacing-6, a token with a value of 1px that we documented in Figma, but it's not available in our library. I assume this is not needed after all?

I've created this task T328042 to represent the px values in the Size Codex demo.

In T297000#8558500, @Sarai-WMDE wrote:

I'd propose to design sign-off and resolve this task and tackle further quest on themeability at T296689 and subsequent tasks. @bmartinezcalvo @Sarai-WMDE

Agreed. The foundational scale was defined and translated into design tokens. The only inconsistency found is @spacing-6, a token with a value of 1px that we documented in Figma, but it's not available in our library. I assume this is not needed after all?

If you search for size-absolute-1 in the codebase, you'll see that having 1px is only used outside of spacing and I'd suggest not adding it if it's not absolutely needed, as it might be misused and would end up in providing us with uneven numbers in numerous ways.

If you search for size-absolute-1 in the codebase, you'll see that having 1px is only used outside of spacing and I'd suggest not adding it if it's not absolutely needed, as it might be misused and would end up in providing us with uneven numbers in numerous ways.

Good. Will be removed from the designs. This task can be signed-off from a design pov.

Change #856708 abandoned by Catrope:

[design/codex@main] tokens: Use relative units for some token categories

Reason:

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

Change #856707 abandoned by Catrope:

[design/codex@main] tokens: Add automatic unit transform based on font size

Reason:

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