I send you the final proposal for Border tokens (Stroke, Style and Radius):

They have the following:

• All the Global tokens have numerical nomenclature (0-infinite)
• All the Decision tokens have names related with their use cases.
• Border Radius will be documented with percentage in the spec sheets (although Figma uses px for radius) since radius are documented with percentage in code.

Here you can view the final proposal.

Have provided feedback on Figma file to sort out some misses and misunderstandings, a.o. addition of dotted border style and addition of 100% for circle, while 9999px rounded border radius is.

@Volker_E updated Border tokens applying feedback from your last comments in Figma.

1. Updated border width and radius with spacing tokens. I've used decision tokens (widths) for border-width and global dimensions for border-radius.

2. Added border-radius-800 with 100% radius (to create border-radius-pill and use it for a full rounded radius like on toggle switches). Although I've added this new token because you commented it during our last DS sync, I think we could use 9999px to both circles (radio buttons) and pills (switches) since with 9999px it's possible to create both shapes (view this code example). Are you ok with removing it or do we need 100% for a specific reason?

1. Great. Works for me.
2. Having rounded rectangular objects and not very common, more like an exception in our current theme environment (Tag Pills are the only ones AFAIAO). Web devs know about 100% border-radius, but they often don't know about that fancy trick. Therefore it would simplify debugging and quicker understanding if we offer them separately.

ToggleSwitch code is a great example. See next patch.

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

[design/codex@main] tokens: Update border radius decision tokens

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

I think this is easier readable and debuggable. A small concern remains around themeing limitations.

&__switch {
	order: 2;
	.force-gpu-composite-layer();
	background-color: @background-color-framed;
	display: inline-block;
	// Grip will be positioned absolutely relative to the switch.
	position: relative;
	box-sizing: @box-sizing-base;
	// These sizes are relative so the toggle switch will scale with font
	// size (e.g. it's slightly larger on mobile).
	width: @width-toggle-switch;
	height: @height-toggle-switch;
	border: @border-input-binary;
	border-radius: @border-radius-pill; //<= APPLIED HERE
	overflow: hidden;
	transition-property: @transition-property-base;
	transition-duration: @transition-ease-medium;

	// Focus outline.
	&::before {
		content: '';
		display: block;
		position: absolute;
		top: @position-offset-toggle-switch-outline;
		right: @position-offset-toggle-switch-outline;
		bottom: @position-offset-toggle-switch-outline;
		left: @position-offset-toggle-switch-outline;
		z-index: 1;
		border: @border-width-base @border-style-base transparent;
		border-radius: @border-radius-pill; //<= APPLIED HERE
		transition-property: @transition-property-toggle-switch-outline;
		transition-duration: @transition-ease-medium;
	}

	// The moving element of the switch.
	&__grip {
		position: absolute;
		// Position and size values differ on smaller screens but aren't
		// exactly scaled relative to font size, so we need separate values.
		top: @start-toggle-switch-grip--mobile;
		left: @start-toggle-switch-grip--mobile;
		box-sizing: @box-sizing-base;
		width: @size-toggle-switch-grip--mobile;
		height: @size-toggle-switch-grip--mobile;
		border: @border-input-binary;
		border-radius: @border-radius-circle; //<= APPLIED HERE
		[…]

Collecting here pending decisions related to border tokens (+ adding my take inline):

1. Do we need theme border-width and border-radius tokens? We recently decided to use spacing tokens instead of discrete px values to define border-radius and border-widths. In principle, that would give said tokens the status of base/decision tokens. In this context, the only global/theme token remaining would be border-style-100, which could be documented as border-width-base in our base tokens file.

Options:

a. Recording border-width-200, border-width-100, border-radius-1000 (etc) as base/decisions tokens that use global spacing tokens as values. We could even give these a more semantic name, such as border-width-thin (inline with border-radius-sharp). If we followed this direction, the Figma file should be updated (these tokens should be documented as decisions).

b. In case we do need gobal/theme border-width and border-radius tokens (e.g. for backwards compatibility reasons?) we should then document these tokens as such, and use specific (px) values instead of referencing to spacing tokens.

2. (Done) Do we need to document both 100% and 9999px border radius given that the latter could be used to create circular shapes? Yes. We'll document the 100% border-radius + the 9999px border radius to simplify developers' experience.

3. "Border stroke and style":

• Our base tokens file records a set of border styles that combine width, style and color: border-base, border-error, border-warning... These are not yet documented in our border tokens' Figma file: should they be included?

• Figma documents the combined border style border-focus: the values of this token are incorrect, since focus styles are obtained by styling two different properties: border-color and an inset box-shadow. We should either: 1. Remove this from Figma; 2. Document it as a Figma style, but indicate that this refers to two different tokens.

4. Should we document border-radius-0 (aka border-radius-sharp), given that – in general – we agreed to avoid documenting 'none' and/or '0' values? My take: Yes. As discussed before, it makes sense to include 'none' or '0' values when these belong to a scale, as we did with opacity tokens.

In T300562#7876447, @Sarai-WMDE wrote:

Collecting here pending decisions related to border tokens (+ adding my take inline):

1. Do we need global border-width and border-radius tokens? We recently decided to use spacing tokens instead of discrete px values to define border-radius and border-widths. In principle, that would give said tokens the status of base/decision tokens. In this context, the only global/theme token remaining would be border-style-100, which could be documented as border-width-base in our base tokens file.

@Sarai-WMDE I think we need to define our global borders although we are using spacings to create them. I would create them and hide them in Codex demo as we are doing with the rest of tokens.

Options:

a. Recording border-width-200, border-width-100, border-radius-1000 (etc) as base/decisions tokens that use global spacing tokens as values. We could even give these a more semantic name, such as border-width-thin (inline with border-radius-sharp). If we followed this direction, the Figma file should be updated (these tokens should be documented as decisions).

@Sarai-WMDE as we are trying to use numerical nomenclature for all our global tokens, I would still using it here. Also, remember that our relevant nomenclature is the one for our decision tokens since global tokens will be hidden in Codex demos.

"Border stroke and style":

• Our base tokens file records a set of border styles that combine width, style and color: border-base, border-error, border-warning... These are not yet documented in our border tokens' Figma file: should they be included?

@Sarai-WMDE I wouldn't document border-colors here since we've already documented them as color tokens.

• Figma documents the combined border style border-focus: the values of this token are incorrect, since focus styles are obtained by styling two different properties: border-color and an inset box-shadow. We should either: 1. Remove this from Figma; 2. Document it as a Figma style, but indicate that this refers to two different tokens.

@Sarai-WMDE deleted border-focus from decision borders in the last Figma version. Also, added dashed border as border-drag to document the use of dashed borders for drag&drop components like SelectFileInput.

4. Should we document border-radius-0 (aka border-radius-sharp), given that – in general – we agreed to avoid documenting 'none' and/or '0' values? My take: Yes. As discussed before, it makes sense to include 'none' or '0' values when these belong to a scale, as we did with opacity tokens.

I agree with @Sarai-WMDE , we should document 0 when it's part of a scale.

In T300562#7875817, @Volker_E wrote:

1. Great. Works for me.
2. Having rounded rectangular objects and not very common, more like an exception in our current theme environment (Tag Pills are the only ones AFAIAO). Web devs know about 100% border-radius, but they often don't know about that fancy trick. Therefore it would simplify debugging and quicker understanding if we offer them separately.

ToggleSwitch code is a great example. See next patch.

@Volker_E would it be possible to use a rectangle shape instead of a square to create the border-pill in the Codex demo? Currently border-radius-pill and border-radius-circle use a circle shape and we should visually differentiate what each one is used for.

Thanks for your answers, @bmartinezcalvo. Just some clarifications:

Option a. Recording border-width-200, border-width-100, border-radius-1000 (etc) as base/decisions tokens that use global spacing tokens as values. We could even give these a more semantic name, such as border-width-thin (inline with border-radius-sharp). If we followed this direction, the Figma file should be updated (these tokens should be documented as decisions).
Option b. In case we do need gobal/theme border-width and border-radius tokens (e.g. for backwards compatibility reasons?) we should then document these tokens as such, and use specific (px) values instead of referencing to spacing tokens.

@Sarai-WMDE I think we need to define our global borders although we are using spacings to create them. I would create them and hide them in Codex demo as we are doing with the rest of tokens.
@Sarai-WMDE as we are trying to use numerical nomenclature for all our global tokens, I would still using it here. Also, remember that our relevant nomenclature is the one for our decision tokens since global tokens will be hidden in Codex demos.

This would contradict our token architecture, where global tokens consume concrete values (e.g. 2px) instead of other tokens (@width-12). The latter is what characterizes base/decision tokens. If we want to use spacing tokens as values for these border properties, then they need to be base tokens,
On the other hand, hiding border width tokens might be counter productive: users would be unaware of their choice to apply 2px borders if they only looked at our currently documented decisions.
Also, please note that I was only suggesting the change of nomenclature in case we went for option A above, and document widths and radius as base tokens.

"Border stroke and style":

• Our base tokens file records a set of border styles that combine width, style and color: border-base, border-error, border-warning... These are not yet documented in our border tokens' Figma file: should they be included?

@Sarai-WMDE I wouldn't document border-colors here since we've already documented them as color tokens.

These styles do not only define border colors, they are complete border styles specifications (see code). If we decided to keep them, they should be documented as borders styles in Figma. If we decided to break them down, then we'd need to delete these styles from base.

Change 785392 merged by jenkins-bot:

[design/codex@main] tokens: Update `border-radius` design-first tokens

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

Hey @Volker_E 👋🏻

@bmartinezcalvo and I decided to create a couple of new versions of the border tokens in Figma to try to solve the pending open questions:

1. Do we need/ want to document border-width and border-radius tokens as options/theme tokens? In that case, they should consume concrete values instead of spacing tokens

2. Should we capture shorthands in Figma?

We tried to represent the available alternatives in the following options:

• Option 1 contains: Width, style and border-radius theme tokens that consume specific CSS values (e.g. px) instead of spacing tokens + Decision tokens for "Border strokens and style" (shorthands without colors) that consume these theme tokens.

• Option 2 contains: Border styles as the only Option/Theme tokens. Border styles are documented again as decisions, together with border width and border radius, which consume spacing tokens. Border styles/shorthands, including colors, are also documented.

• Option 3 contains: Style, width and radius tokens as Options that consume specific CSS values (e.g. px). These option/theme tokens are then consumed by their corresponding Decision tokens. Border styles/shorthands, including colors, are also documented.

We'd like to hear your take! Please leave any comments in Figma. Thank you!

1. Would margins and paddings be based on spacing tokens? In my understanding yes. If someone decides that the smallest dimension isn't 1px, but 2px, they'd be confronted with all 1px margins/paddings/widths changing, but the borders remain? Seems contraintuitive to me.
2. I seems we could do without shorthands on borders as well. It's a lil inconvenience, but might make tokens definition much simpler

A few border shorthands would remain as legacy tokens though for the time being.

1. I'm not sure how those decisions would be easily or necessarily related? 🤔 But, in any case, the goal here is not deciding whether it makes sense to use sizing tokens as values to define border-widths or radius: what we're looking for is agreement regarding the fact that, if we do that, then said tokens shouldn't be created as theme tokens, but only as base tokens (see Option 2).

2. Roger that! We could get rid of those shorthands and find a different way to document Figma border styles if necessary. What do you think, @bmartinezcalvo? Shorthands are quite handy, but the alternative is also quite modular.

Do I interpret correctly that your preference would then be for Option 2 without shortcuts? Thanks, @Volker_E !

1. Because as theme author, I decide that dimension.6 is 3px instead of 1px. And I want to scale up all dimension.6 in one go.
2. I believe I've gotten to a conclusion that will satisfy both of us and become handy for devs. For everything that is only a repetition of pure spacing/size tokens like padding: 8px 12px; a shorthand makes sense. For a property that mixes different token categories, like border: 1px solid #36c or background: #fff url(…) no-repeat shorthands are problematic in token land.

After the last meeting with @Volker_E and @Sarai-WMDE to discuss about the different proposals to create our Border tokens, we have decided to move forward with this final proposal in which we'll defined the following:

• We'll use spacing tokens to create the border options (except for styles that cannot be measured with spacing scales)
• We won’t finally document shorthands for these border tokens since we will only create shorthands with tokens from the same family (e.g. spacings) but we won't create shorthands combining tokens from different families (e.g. borders + colors).

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

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

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

Change 799168 merged by jenkins-bot:

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

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

Design sign-off done. All tokens have been added successfully as we have in design.

2 things to have into account:

• Spacing tokens will be updated there when they have been created in Codex
• Same with colors, they need to be updated when the colors decisions have been created since now they don't match with the design.

About the demo, I would update 2 small things:

• We need to reflect in the demo that pill and circle are visually different, so I would add pill with a rectangle if possible
• I would move Radius before Colors since Colors is a combination of Border+Colors and not simply borders.

@Volker_E I assign to you the task so you can have a look to these 2 corrections.

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

[design/codex@main] docs: Update border-radius-pill demo

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

In T300562#7978614, @bmartinezcalvo wrote:

About the demo, I would update 2 small things:

• We need to reflect in the demo that pill and circle are visually different, so I would add pill with a rectangle if possible

Done in latest patch linked above.

• I would move Radius before Colors since Colors is a combination of Border+Colors and not simply borders.

Not sure I can follow, border-colors are specific tokens, or do you mean the presentation?
The order width, style and color follows our code, where border: @border-width-base @border-style-base @border-color-base.

@bmartinezcalvo This ticket requires your input

In T300562#8018309, @Volker_E wrote:

In T300562#7978614, @bmartinezcalvo wrote:

About the demo, I would update 2 small things:

• We need to reflect in the demo that pill and circle are visually different, so I would add pill with a rectangle if possible

Done in latest patch linked above.

@Volker_E thank you, checked in the list ✅

• I would move Radius before Colors since Colors is a combination of Border+Colors and not simply borders.

Not sure I can follow, border-colors are specific tokens, or do you mean the presentation?
The order width, style and color follows our code, where border: @border-width-base @border-style-base @border-color-base.

Regarding this, I meant to reorder these sections in the demo to reflect the same order we have in the Figma spec (which I think is more suitable for the users to understand the token when they read the demo):

1. Style
2. Width
3. Radius
4. Color

Tell me if it's possible. This wouldn't be a blocker to solve this task.

Change 807205 merged by jenkins-bot:

[design/codex@main] docs: Update border-radius-pill demo

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

In T300562#8084892, @Volker_E wrote:

@bmartinezcalvo The border-radius-pill special appearance is now ready for your review (demos are currently updating on server, should be visible any minute).

@Volker_E perfect, design sign off done ✅

I'd recommend not to put Border Radius before Color.
The Wikimedia CSS coding guidelines (and also the CSS standard itself) is seeing width, color and style as combinable. Radius should always come after and can't be combined. For developer orientation/satisfaction I'd recommend to leave the order as is.

@Volker_E ok, I understand the reasons so I've updated the Figma spec sheet with the same order as in the Codex demo, moving Radius section at the end.

Moving it, as the Design review has been done and the documentation exists on Demo, as expected.

All good. Product sign-off complete.