Tokens Vocabulary.md

Design Tokens Vocabulary

Term	Definition	Example(s)
Platform Styling Language (PSL)	A programming language responsible for styling UI on a specific platform.	CSS (Web) XML (Android) Objective-C (iOS) Swift (iOS) Javascript (SketchAPI)
Property Context	The portion of a UI to which style values will be applied.	CSS .heading-level-1 #id h1 XML <TextView style="@style/HeadingLevel1"> Swift Text.font(.system()) Javascript sharedTextStyles[{name: 'Heading Level 1'}])
Property Key	A predefined label belonging to an End State Styling Language	CSS font-size opacity z-index XML android:textSize Swift .font(.system(size)) Javascript (SketchAPI) style.textSize
Variable Key	An arbitrary label assigned to a value	color-background-default space-inset-1-x size-medium
Assignment	Mapping a key to a value	Property Assignment font-size: 2rem; color: var(--color-success); android:textSize="32" Variable Assignment primary-text-color = "#000000"
Token	A language-agnostic assignment of a variable key and a value	color-text-primary = "#000000" size-1-x = "24px" z-index-ceiling = 999
Variable Assignment	A language-specific assignment of a variable key to a value	CSS --color-danger: #ff0000; SCSS $font-size-large: 2rem; XML <item name="android:textColor">#00ff00</item> Javascript const space1x = '44px'; // JS
Property Assignment	An PSL-Specific assignment of a property key and a value. Property Assignments only exist in PSLs.	CSS font-size: 2rem; color: var(--color-danger); XML android:textSize="32"
Token Assignment	A Property Assignment within a Property Context where the value is a token.	CSS .ds-alert { color: var(--color-danger); } XML <TextView style="@style/ColorDanger"/>

Token Transformation Tools

Current token transformation tooling (Style Dictionary, Theo, Diez, Specify) transforms Tokens into Variable Assignments. Essentially converting language-agnostic assignments to language-specific assignments.

Token Assignment

Token Assignments are authored manually. Either directly in an PSL (assigning CSS variables to CSS properties) or in a preprocessor (SCSS, CSS-in-JS) and generating the PSL result.

Automated Token Assignment

In order for token transformation tooling to automatically generate Token Assignments, token definitions must contain data describing the correct Property Context and Property Assignment for each target PSL.

Composite Tokens

Term	Definition	Example(s)
Composite Token	A language-agnostic assignment between a variable key and multiple values	heading-level-1 = {    size: 2rem,    weight: bold,    line-height: 1.5 } border-error = {    width: 1px,    color: "#ff0000",    style: solid }

Supporting image for cross-platform Property Context

End State Styling Language (ESSL)
I like the notion and the name. However the "end state" part is blurry to me. Is it necessary? If not, could we remove it?

Variable Key
To me it's a design token name. So why not "Variable name"?

Assignment
This may be "broad". What about "style assignment"?

Discrete value
Why is named like this? The word "discrete" confuses me.

Token Transformation Tools
Could you add Specify in the list?

...token definitions must contain data describing the correct Property Context and Property Assignment for each target ESSL.
What are token definitions? Do you mean the design token itself?

Besides that, hats off for your work! It really helps understanding and explaining styling across platforms 👏

However the "end state" part is blurry to me. Is it necessary?

This is to distinguish it from SCSS, LESS, or CSS-in-JS solutions. Perhaps "Platform Styling Language" makes more sense. No matter what frameworks you use, Web will always be CSS, iOS will always be Swift/Objective-C (I think), Android will always be XML (I think).

To me it's a design token name. So why not "Variable name"?

I've commonly heard the phrase "key/value pair", so that's why I went with "key."

Assignment
This may be "broad". What about "style assignment"?

Assignment is intentionally broad. It's more specific when paired with Token Assignment or Variable Assignment.

Great feedback, I'll incorporate and make some changes.