How to add tokens?

[alexmeier-19]

Is there a documentation on how to add more tokens to material web (contribute) without deep diving into your whole code? We are missing some customization options here and there (like radio button's thickness, background color for an outlined disabled text field etc.). Injecting those styles via JS feels really awkward and not clean for a big project. We want to keep all styles clean and separated in one place.
Some documentation on this would be amazing.

[asyncLiz]

I posted answer to a similar question on Discord, I'll copy it here! (this is from the lit.dev/discord)

---

It's kind of a long and complicated answer. The tokens framework is built on https://sass-lang.com/, which is a pre-compiler language that turns Sass .scss files into .css files. The CSS then gets embedded into our elements' .js files.

I would recommend starting with the Sass website to get an understanding of the fundamentals for things like Sass functions, mixins, variables, and data structures like maps. Afterwards, this is how it's broken down:

1. The generated tokens are here: https://github.com/material-components/material-web/tree/main/tokens/v0_192

   These come from our design database, which is what you see powering the token sections on https://material.io/. These are auto-generated, so don't modify them. They are the "source of truth" for tokens directly from design.

2. We have an abstraction layer on top of generated tokens here: https://github.com/material-components/material-web/tree/main/tokens

   This is where we transform the raw tokens into something that's more web appropriate. We remove, add, and rename tokens in this layer, as well as build entirely new token sets.

   For example, in chips' tokens, we do a lot of renaming to make the raw token names more consistent and less verbose:

   material-web/tokens/_md-comp-filter-chip.scss

   Lines 160 to 165 in 7f3d9d1

   	$renamed-tokens: (
   	// Remove "unselected-*" and "flat-*" prefix (b/275577569)
   	'elevated-unselected-container-color': 'elevated-container-color',
   	'flat-container-elevation': 'container-elevation',
   	'flat-disabled-unselected-outline-color': 'disabled-outline-color',
   	'flat-disabled-unselected-outline-opacity': 'disabled-outline-opacity',

To add new tokens, you can look at filled button for an example, where we add spacing tokens that aren't tokenified from the design database yet:

material-web/tokens/_md-comp-filled-button.scss

Lines 91 to 97 in 7f3d9d1

	$new-tokens: map.merge(
	shape.get-new-logical-shape-tokens($tokens, 'container-shape'),
	(
	// b/198759625 - Remove once spacing tokens are formally added
	// go/keep-sorted start
	'leading-space': if($exclude-hardcoded-values, null, 24px),
	'trailing-space': if($exclude-hardcoded-values, null, 24px),

To change tokens, you can look at filled text field. We edit an existing token for the focus indicator, which has the wrong value in tokens v0.192:

material-web/tokens/_md-comp-filled-text-field.scss

Lines 168 to 174 in 7f3d9d1

	$tokens: map.merge(
	$tokens,
	(
	// TODO(b/259455114): remove when focus tokens update to 3px
	'focus-active-indicator-height': if($exclude-hardcoded-values, null, 3px)
	)
	);

Hope that helps! 🙂

---

Also yes, we do need to document this. There's a lot we need to set up and write docs for to help others onboard for contributing.