Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add glossary page #7

Draft
wants to merge 7 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
node_modules
.astro/
.history/
dist/
.DS_Store
.history/
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/public/spectrum-adaptive-ui-concept.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
55 changes: 55 additions & 0 deletions docs/src/content/docs/Reference/glossary.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
---
title: Glossary
---

![Resolver spec visual draft](./docs/public/resolver-spec-food-analogy-drawing.jpg)

:::note
Creating tokens is like cooking. You can cook an infinity of dishes (final tokens) by following recipes (sources) which are a combination of different types (dimension) of food (modifiers).
:::

## Token set

A token set is a group of tokens. You have 2 types of token sets:

1. [modifier](#modifier) token sets
2. [source](#source) token sets

## Dimension

Dimensions are categories used to organize your tokens. See them as contexts in which token values might change:

- Brands
- Surface
- Language direction
- Themes
- Platform
- Screen size
- Density
- Component
- State
- Variant
- Contrast
- ...

## Modifier

A modifier token set is a group of token used by source token set(s). You'll usually want to organize them in different [dimensions](#dimension).

![Dimension examples](./docs/public/spectrum-adaptive-ui-concept.png)

## Source

A source set is combination of one or several modifier set used to match a specific use case. For instance, generating a themes token sets based on several modifier sets.

## Resolver

A design token resolver is a function responsible for creating design tokens respecting [the DTCG spec](https://first-editors-draft.tr.designtokens.org/format/) from another source of data or logic.

## Token space

TBD
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this is in reference to

The references to the tokens used in this styling are tied to a single addressable token space

I was referring to a single large token set that then forms the final set of tokens you can address with keys like

colors.foo.500

It essentially is your plate in your cooking analogy holding the final dish with items in it , though it refers to any set really with the tokens it holds and what is addressable

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks I'll add this to the glossary and add the plate analogy to another visual then :)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done ✅


## Resolution request

TBD
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This would be the request for to get some final tokens , so its the ordering of the dish in your cooking analogy.

I mention in the docs that it would likely be async as the token sets files might need to be read from some storage before the actual processing can be done

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok thanks. Do you think it's important enough to add this to the glossary?