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.

Sign up for GitHub

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

[ADR] Add prefix to design tokens #1104

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+36 −0
Open

[ADR] Add prefix to design tokens #1104

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cf9fde0
prefix adr
lukasoppermann Dec 5, 2024
796f139
Update ADR-005 with decision rationale and questions
lukasoppermann Dec 9, 2024
af2f31d
Update ADR-005 with additional implementation details
lukasoppermann Dec 9, 2024
1eba2b6
fix format
lukasoppermann Dec 9, 2024
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
36 changes: 36 additions & 0 deletions contributor-docs/adrs/adr-005-token-prefix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Prefix for primitives

## Status

| Stage | Status |
| -------- | ----------- |
| Approved | 🚧 |
| Adopted | <!-- 🚧 --> |

## Context

Currently primitives have no prefix, which means once converted to css they can be used like `--fgColor-default`. This is very convenient but could lead to naming collisions or confusion if folks use their own css variables e.g. is `--button-fgColor-default` a token coming from primitive or a local variable?

To solve this we could add a prefix like `primer` or `product` to our tokens, resulting in css variables like `--primer-fgColor-default`.

To decide this, the following questions need to be answered:

1. Do we think that this is a legit problem that is serious enough to invest somewhat significant resources into?
-> No, because we did not get any issues or other reports of complications with token naming collisions. We also have not had any reports of people running into issues where they have a hard time differentiating between their own tokens and primitives.

~2. If yes, what is an appropriate prefix?~

3. If no, do we need some kind of guidance in primer.style, or are we good without it?
Copy link
Contributor

Choose a reason for hiding this comment

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

What would the guidance be? I don't think CSS variable collisions are specific enough to Primer to need documentation.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

What would the guidance be? I don't think CSS variable collisions are specific enough to Primer to need documentation.

Idk. Maybe suggesting using a custom prefix if you create your own tokens? Or outlining all the token types we have so that people can avoid conflicts.

But as I mentioned above, I am not necessarily a "fan" of adding a prefix (mainly because of the significant resource demand). And I also don't really have a point for 3. yet. Just wondering if there is any.

-> Without specific issues there is no specific need for guidance.

## Decision

We will not add a prefix to our primitives at this time. The main reason being that we have no reports of issues and the effort required to implement it, specifically to update usage on github.com, will be quite significant.

### Impact

- We will need to a) keep both prefixed and non-prefixed tokens for quite a while and b) work on removing all non-prefixed tokens from dotCom doing PRs and using stylelint.

### Alternatives

Not using a prefix and keeping it as is.
Loading