You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Primer color design tokens are made available within data-attribute selectors on the `body` tag or other high level dom element. There are three distinct data-attributes used to handle theming: `data-color-mode`, `data-light-theme`, and `data-dark-theme`.
57
+
58
+
### Color mode
59
+
60
+
The `data-color-mode` attribute is used to set the color mode of the theme. The value of the attribute should be either `auto`, `light`, or `dark`. When set to `auto`, the theme will automatically switch between light and dark based on the user's system preferences.
61
+
62
+
### Color theme
63
+
64
+
The `data-light-theme` and `data-dark-theme` attributes are used to set the theme. The value of the attribute should be the name of the theme file, replacing dashes `-` with underscore `_`. For example, to use the light theme, set the `data-light-theme` attribute to `light`.
Copy file name to clipboardexpand all lines: content/foundations/primitives/token-names.mdx
+60-20
Original file line number
Diff line number
Diff line change
@@ -1,44 +1,44 @@
1
1
---
2
2
title: Token names
3
3
description:
4
-
An explanation of Primer's design token naming convention.
4
+
An explanation of Primer's design token naming convention
5
5
---
6
6
7
7
## Intro
8
8
9
9
Naming things is hard. Primer design tokens are named using a consistent convention to make it easier to understand what they do and how they should be used at a glance.
10
10
11
-
img of token breakdown
11
+
<imgwidth="960"alt="a design token broken down by property, variant, and scale"src="https://github.com/primer/react/assets/18661030/85ec0655-0426-4a79-9ac0-0bee97e5e9b1" />
12
12
13
13
## Categories
14
14
15
-
Our naming convention is broken down into three categories: **base, component/pattern, functional**. Each category is a subset of the over-arching convention.
15
+
<imgwidth="960"alt="graphic listing out prefix, namespace, pattern, variant, property, variant, and scale all color coded to match help illustrate the differences between them"src="https://github.com/primer/react/assets/18661030/d89da86b-5b9d-43f2-b745-126fe35ea500" />
16
16
17
-
Across all categories, the `property` value is always required. This value specifies exactly how a token is indended to be applied to a UI.
17
+
This naming convention is broken down into three categories: **base, component/pattern, functional**. Each category is a subset of the over-arching convention.
18
18
19
-
<imgwidth="960"alt="graphic listing out namespace, pattern, variant, property, variant, and scale all color coded to match ADR docs"src="https://github.com/primer/react/assets/18661030/d89da86b-5b9d-43f2-b745-126fe35ea500" />
19
+
Across all categories, the [property](#property-required) value is always required. This value specifies exactly how a token is indended to be applied to a UI.
20
20
21
21
### Base
22
22
23
23
Base tokens are the lowest level tokens and map directly to a raw value.
24
24
25
-
<imgwidth="960"alt="a graphic illustrating five words, uniquely colored and displayed left to right in a horizontal direction. Words are prefix, namespace (with an asterix), property (with an asterix), variant and scale. Followed by color coded tokens, which will be described in the next section."src="https://github.com/primer/react/assets/18661030/3bffcdaf-60f1-4824-b30c-25951f2d5156" />
25
+
<imgwidth="960"alt="a graphic illustrating five words, uniquely colored and displayed left to right in a horizontal direction. Words are prefix, namespace, pattern, variant, property, variant and scale. The pattern and variant words are dimmed to signify their exclusions from this pattern. Followed by color coded tokens, which will be described in the next section."src="https://github.com/primer/react/assets/18661030/3bffcdaf-60f1-4824-b30c-25951f2d5156" />
26
26
27
27
28
28
#### Example `base` tokens
29
29
30
30
```
31
-
brand-base-color-lime-5
32
31
base-size-4
33
32
base-color-green-5
33
+
brand-base-color-lime-5
34
34
base-fontWeight-semibold
35
35
```
36
36
37
37
### Functional
38
38
39
39
Functional tokens represent global UI patterns.
40
40
41
-
<imgwidth="960"alt="a graphic illustrating six words, each uniquely color coded and displayed left to right in a horizontal direction. Words are prefix, type, property (with an asterix), variant and scale. Followed by example tokens that are similarly color coded and will be described again in the next section."src="https://github.com/primer/react/assets/18661030/7124ced5-96d1-4479-996a-641579a2cd4c" />
41
+
<imgwidth="960"alt="a graphic illustrating five words, uniquely colored and displayed left to right in a horizontal direction. Words are prefix, namespace, pattern, variant, property, variant and scale. The namespace, pattern and variant words are dimmed to signify their exclusions from this pattern. Followed by color coded tokens, which will be described in the next section."src="https://github.com/primer/react/assets/18661030/7124ced5-96d1-4479-996a-641579a2cd4c" />
42
42
43
43
#### Example `functional` tokens
44
44
@@ -51,62 +51,62 @@ boxShadow-inset-thick
51
51
52
52
### Component/pattern
53
53
54
-
Component/pattern represents component and pattern specific tokens which should only be used in component CSS.
54
+
Component/pattern tokens should only be used in component CSS.
55
55
56
-
<imgwidth="960"alt="a graphic illustrating six words, each uniquely color coded and displayed left to right in a horizontal direction. Words are prefix, pattern, variant, type, property (with an asterix) and scale. Followed by similarly color coded tokens, which will be described again in the next section."src="https://github.com/primer/react/assets/18661030/d1d77c2f-e8c4-4d38-b295-1231bc82648f" />
56
+
<imgwidth="960"alt="a graphic illustrating five words, uniquely colored and displayed left to right in a horizontal direction. Words are prefix, namespace, pattern, variant, property, variant and scale. The namespace word is dimmed to signify its exclusion from this pattern. Followed by color coded tokens, which will be described in the next section."src="https://github.com/primer/react/assets/18661030/d1d77c2f-e8c4-4d38-b295-1231bc82648f" />
Prefix provides top-level encapsulation of a particular flavor of Primer, such as Primer Brand. It can be used for protected base tokens like Brand color scales, or value overrides for traditional Primer tokens in order to avoid collisions.
75
75
76
76
`brand`: used for marketing/brand specific tokens.
Namespace creates a scope used to identify how a token may be used. For example, `base` tokens are the lowest level and are generally used as a reference for functional tokens (the next step above).
83
83
84
84
`base`: represents global, constant values. These are the lowest level tokens and map directly to a raw value.
Pattern represents a group of design decisions, or a specific Primer component. Whenever possible, aim to use a name that is generic enough to influence related components. In the example below, the item`control` can be used for multiple types of controls like buttons, inputs, or interactive action list items.
90
+
Pattern represents a group of design decisions, or a specific Primer component. Whenever possible, aim to use a name that is generic enough to influence related components. For example, the pattern`control` can be used for multiple types of controls like buttons, inputs, or interactive action list items.
91
91
92
92
For pattern and component names that are multi-word, use camelCase to separate each word.
Variant can be used to either modify the **pattern** or **property**. Only one variant is allowed per token. It typically represents a stylistic variant of a token such as color (danger) or size (small).
Property is used to represent an item’s style. It usually matches a [CSS property](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference#index), but it can also store other conceptual definitions such as `size`, `minTarget`, etc. Use camelCase for multi-word properties.
Scale represents ordinals to describe things like state, density, thickness, range, and speed. Scale names strive to follow our [size naming convention standards](https://github.com/github/primer/blob/main/adrs/2022-02-09-size-naming-guidelines.md).
112
112
@@ -132,3 +132,43 @@ Individual name blocks for each token should be separated with a single characte
132
132
<Caption>Don't use other characters to separate words.</Caption>
133
133
</Dont>
134
134
</DoDontContainer>
135
+
136
+
## Color modifiers
137
+
138
+
We use the following values to modify the color [variant](#variant):
139
+
140
+
-`default` - The default color variant for a given token. Example: `fgColor-default`
141
+
-`muted` - The secondary color variant for a given token. Example: `fgColor-muted`
142
+
-`emphasis` - The opposite of "muted", emphasis is a stronger color variant. Example: `bgColor-accent-emphasis`
143
+
144
+
## Size modifiers
145
+
146
+
Size modifiers are often found as part of the [scale](#scale) block. The following describes how we name size modifiers for each category.
147
+
148
+
### General-purpose t-shirt sizes
149
+
150
+
```
151
+
xsmall | small | medium | large | xlarge | xxlarge
0 commit comments