Skip to content

Commit 94c9fd6

Browse files
rise-erpeldingrise-erpelding
committed
docs: update tokens docs
1 parent 4ce3591 commit 94c9fd6

File tree

1 file changed

+111
-127
lines changed

1 file changed

+111
-127
lines changed

‎1st-gen/tools/styles/README.md‎

Lines changed: 111 additions & 127 deletions
Original file line numberDiff line numberDiff line change
@@ -26,172 +26,146 @@ See the `@spectrum-web-components/theme` [documentation](../theme) for more info
2626
yarn add @spectrum-web-components/styles
2727
```
2828

29-
### System variants
29+
### Design tokens
3030

31-
This package provides styles for three Adobe design system variants (referred to as "systems"). Each system has different available color options:
31+
This package provides design token CSS custom properties for three Adobe design system variants (referred to as "systems").
3232

33-
- **Spectrum** (system: `spectrum`) - The original Spectrum design system with four color options: `dark`, `light`, and deprecated `darkest` and `lightest`
34-
- **Express** (system: `express`) - The Adobe Express design system with two color options: `dark` and `light`
35-
- **Spectrum 2** (system: `spectrum-two`) - The next generation Spectrum design system with two color options: `dark` and `light`
33+
**Color options:** Each system has different available color options, but in the future, each will have only `dark` and `light` available.
3634

37-
### Combined theme packages (Spectrum)
35+
**Scales:** Each system has two scale sizes available: `medium` (default) and `large`. The `medium` scale is designed for desktop environments with slightly smaller components and spacing, while the `large` scale is optimized for mobile and touch devices with larger touch targets and spacing.
3836

39-
If you're not using `<sp-theme>`, the styles package provides convenient bundles for Spectrum that combine everything you need in a single import. Each `all-*` file combines core global styles, typography, a color option, and a scale specification. Express and Spectrum 2 do not have equivalent combined packages; use manual theme composition instead (see below).
37+
**Available systems:**
4038

41-
> **Note:** The `darkest` and `lightest` colors are deprecated and will be removed in a future release. Use `dark` or `light` instead.
39+
- **Spectrum** (system: `spectrum`) - The original Spectrum design system
40+
- **Colors:** `dark`, `light`, and deprecated `darkest` and `lightest`
41+
- **Scales:** `medium`, `large`
42+
- **Express** (system: `express`) - The Adobe Express design system
43+
- **Colors:** `dark`, `light`
44+
- **Scales:** `medium`, `large`
45+
- **Spectrum 2** (system: `spectrum-two`) - The next generation Spectrum design system
46+
- **Colors:** `dark`, `light`
47+
- **Scales:** `medium`, `large`
4248

43-
```css
44-
@import '@spectrum-web-components/styles/all-medium-dark.css';
45-
```
49+
#### Spectrum 2 tokens
4650

47-
This file brings together the global variables and font settings with the "Dark" color set and "Medium" scale system specification.
51+
Spectrum 2 uses standalone token files. Pick one color option and one scale option:
4852

4953
```css
50-
@import '@spectrum-web-components/styles/all-medium-light.css';
54+
/* pick a color option */
55+
@import '@spectrum-web-components/styles/tokens-v2/light-vars.css';
56+
/* pick a scale option */
57+
@import '@spectrum-web-components/styles/tokens-v2/medium-vars.css';
58+
/* import global custom properties last */
59+
@import '@spectrum-web-components/styles/tokens-v2/global-vars.css';
5160
```
5261

53-
This file brings together the global variables and font settings with the "Light" color set and "Medium" scale system specification.
54-
55-
Other available combinations: `all-large-dark.css`, `all-large-light.css`, and the deprecated `all-medium-darkest.css`, `all-medium-lightest.css`, `all-large-darkest.css`, `all-large-lightest.css`.
56-
57-
### Manual theme composition (Express and Spectrum 2)
58-
59-
If you're not using `<sp-theme>`, you can manually compose a complete theme for Express or Spectrum 2 (equivalent to the `all-*` convenience packages for Spectrum) by importing four files: core global styles, typography, a color option, and a scale.
62+
#### Spectrum tokens
6063

61-
#### Express example (large, dark)
64+
Spectrum uses a base + override pattern. Import base tokens first, then system-specific overrides:
6265

6366
```css
64-
@import '@spectrum-web-components/styles/express/core-global.css';
65-
@import '@spectrum-web-components/styles/typography.css';
66-
@import '@spectrum-web-components/styles/express/theme-dark.css';
67-
@import '@spectrum-web-components/styles/express/scale-large.css';
67+
/* import base tokens */
68+
@import '@spectrum-web-components/styles/tokens/light-vars.css';
69+
@import '@spectrum-web-components/styles/tokens/medium-vars.css';
70+
@import '@spectrum-web-components/styles/tokens/global-vars.css';
71+
72+
/* import spectrum-specific overrides */
73+
@import '@spectrum-web-components/styles/tokens/spectrum/light-vars.css';
74+
@import '@spectrum-web-components/styles/tokens/spectrum/medium-vars.css';
75+
@import '@spectrum-web-components/styles/tokens/spectrum/global-vars.css';
6876
```
6977

70-
#### Spectrum 2 example (medium, light)
78+
#### Express tokens
7179

72-
```css
73-
@import '@spectrum-web-components/styles/spectrum-two/core-global.css';
74-
@import '@spectrum-web-components/styles/typography.css';
75-
@import '@spectrum-web-components/styles/spectrum-two/theme-light.css';
76-
@import '@spectrum-web-components/styles/spectrum-two/scale-medium.css';
77-
```
80+
Express also uses a base + override pattern (same as Spectrum above, but with `express/` paths):
7881

79-
> **Note:** For most use cases, we recommend using `<sp-theme>` instead of manually managing these imports. The theme element handles composition and switching automatically.
82+
```css
83+
/* import base tokens */
84+
@import '@spectrum-web-components/styles/tokens/light-vars.css';
85+
@import '@spectrum-web-components/styles/tokens/medium-vars.css';
86+
@import '@spectrum-web-components/styles/tokens/global-vars.css';
8087

81-
### Individual theme and scale files
88+
/* import express-specific overrides */
89+
@import '@spectrum-web-components/styles/tokens/express/light-vars.css';
90+
@import '@spectrum-web-components/styles/tokens/express/medium-vars.css';
91+
@import '@spectrum-web-components/styles/tokens/express/global-vars.css';
92+
```
8293

83-
For more control over bundle size or to manually compose themes, you can import color and scale files individually. These provide only the CSS custom properties specific to color or scale, without the combined overhead of the `all-*` packages.
94+
#### Tokens usage
8495

85-
#### Color
96+
Which tokens files you import will depend on which tokens you want to use.
8697

87-
Import a single color option to set color values:
98+
##### V2 tokens
8899

89-
```css
90-
/* Spectrum */
91-
@import '@spectrum-web-components/styles/theme-light.css';
100+
Generally speaking, `light-vars` and `dark-vars` files contain raw color custom property definitions (such as `--spectrum-red-500`), as well as semantic custom property definitions that change depending on which color option you use. For instance, in the v2-tokens, `--spectrum-neutral-subdued-background-color-default` uses different values per theme. It resolves to `--spectrum-gray-700` for light and `--spectrum-gray-500` for dark.
92101

93-
/* Express */
94-
@import '@spectrum-web-components/styles/express/theme-dark.css';
102+
For color, `global-vars` files contain semantic custom property definitions that stay consistent regardless of color option. For instance, `--spectrum-neutral-background-color-default` is always `--spectrum-gray-800`, but `--spectrum-gray-800` is defined differently depending on whether dark or light custom properties have been imported. Component-specific custom properties are split across these files. Some are in `global-vars` (e.g., `--spectrum-swatch-border-color`), while others are in `light-vars`/`dark-vars` (e.g., `--spectrum-assetcard-border-color-selected`).
95103

96-
/* Spectrum 2 */
97-
@import '@spectrum-web-components/styles/spectrum-two/theme-light.css';
98-
```
104+
Similarly, `medium-vars` and `large-vars` files contain custom property definitions for raw spacings and sizes that differ between the two scales, such as `--spectrum-font-size-200` and `--spectrum-component-height-100`. They also contain component-specific custom property definitions that differ between scales, for instance `--spectrum-meter-width`. The `global-vars` file defines custom properties related to sizing or spacing that are consistent regardless of scale (e.g., `--spectrum-corner-radius-100`), or uses custom properties defined in `medium-vars`/`large-vars` (e.g., `--spectrum-meter-default-width: var(--spectrum-meter-width);`).
99105

100-
##### Available color options
101-
102-
<sp-table>
103-
<sp-table-head>
104-
<sp-table-head-cell>System</sp-table-head-cell>
105-
<sp-table-head-cell>Available colors</sp-table-head-cell>
106-
</sp-table-head>
107-
<sp-table-body>
108-
<sp-table-row>
109-
<sp-table-cell><strong>Spectrum</strong></sp-table-cell>
110-
<sp-table-cell><code>theme-dark.css</code>, <code>theme-light.css</code>, <code>theme-darkest.css</code> (deprecated), <code>theme-lightest.css</code> (deprecated)</sp-table-cell>
111-
</sp-table-row>
112-
<sp-table-row>
113-
<sp-table-cell><strong>Express</strong></sp-table-cell>
114-
<sp-table-cell><code>express/theme-dark.css</code>, <code>express/theme-light.css</code></sp-table-cell>
115-
</sp-table-row>
116-
<sp-table-row>
117-
<sp-table-cell><strong>Spectrum 2</strong></sp-table-cell>
118-
<sp-table-cell><code>spectrum-two/theme-dark.css</code>, <code>spectrum-two/theme-light.css</code></sp-table-cell>
119-
</sp-table-row>
120-
</sp-table-body>
121-
</sp-table>
122-
123-
> **Note:** All color theme files automatically set the CSS `color-scheme` property (`light` or `dark`) for accessibility. This helps browsers render native form controls appropriately, adjusts scrollbar colors to match the theme, and improves compatibility with system UI elements.
124-
125-
#### Scale
126-
127-
Import a single scale to set sizing values:
106+
Here's one example of tokens usage in a non-web-component context, showing how custom properties from each file work together:
128107

129108
```css
130-
/* Spectrum */
131-
@import '@spectrum-web-components/styles/scale-medium.css';
132-
133-
/* Express */
134-
@import '@spectrum-web-components/styles/express/scale-medium.css';
109+
/* import appropriate tokens files */
110+
@import '@spectrum-web-components/styles/tokens-v2/light-vars.css';
111+
@import '@spectrum-web-components/styles/tokens-v2/medium-vars.css';
112+
@import '@spectrum-web-components/styles/tokens-v2/global-vars.css';
135113

136-
/* Spectrum 2 */
137-
@import '@spectrum-web-components/styles/spectrum-two/scale-large.css';
114+
.my-component {
115+
/* defined in global-vars.css */
116+
border-radius: var(--spectrum-corner-radius-medium-size-small);
117+
border-width: var(--spectrum-border-width-100);
118+
color: var(
119+
--spectrum-neutral-content-color-default
120+
); /* uses --spectrum-gray-800, which is defined differently depending whether light or dark vars are loaded */
121+
122+
/* defined in light-vars.css, defined differently in dark-vars.css */
123+
background-color: var(--spectrum-gray-100);
124+
border-color: var(--spectrum-gray-800);
125+
126+
/* defined in medium-vars.css, defined differently in large-vars.css */
127+
padding-inline: var(--spectrum-component-edge-to-text-75);
128+
padding-block: var(--spectrum-component-top-to-text-75);
129+
min-block-size: var(--spectrum-component-height-75);
130+
131+
border-style: solid;
132+
}
138133
```
139134

140-
##### Available scales
141-
142-
<sp-table>
143-
<sp-table-head>
144-
<sp-table-head-cell>System</sp-table-head-cell>
145-
<sp-table-head-cell>Available scales</sp-table-head-cell>
146-
</sp-table-head>
147-
<sp-table-body>
148-
<sp-table-row>
149-
<sp-table-cell><strong>Spectrum</strong></sp-table-cell>
150-
<sp-table-cell><code>scale-medium.css</code>, <code>scale-large.css</code></sp-table-cell>
151-
</sp-table-row>
152-
<sp-table-row>
153-
<sp-table-cell><strong>Express</strong></sp-table-cell>
154-
<sp-table-cell><code>express/scale-medium.css</code>, <code>express/scale-large.css</code></sp-table-cell>
155-
</sp-table-row>
156-
<sp-table-row>
157-
<sp-table-cell><strong>Spectrum 2</strong></sp-table-cell>
158-
<sp-table-cell><code>spectrum-two/scale-medium.css</code>, <code>spectrum-two/scale-large.css</code></sp-table-cell>
159-
</sp-table-row>
160-
</sp-table-body>
161-
</sp-table>
162-
163-
### Design tokens
164-
165-
For advanced use cases where you need direct access to design token CSS custom properties, this package exposes token files:
135+
##### Tokens (base + system overrides pattern)
166136

167-
#### Spectrum tokens
137+
These tokens are generally similar to the V2 tokens, but use a base layer plus system-specific overrides that must both be imported.
168138

169139
```css
170-
@import '@spectrum-web-components/styles/tokens/global-vars.css';
140+
/* import base tokens files */
171141
@import '@spectrum-web-components/styles/tokens/light-vars.css';
172-
@import '@spectrum-web-components/styles/tokens/dark-vars.css';
173-
@import '@spectrum-web-components/styles/tokens/medium-vars.css';
174-
@import '@spectrum-web-components/styles/tokens/large-vars.css';
175-
```
176-
177-
#### Express tokens
142+
@import '@spectrum-web-components/styles/tokens/global-vars.css';
178143

179-
```css
180-
@import '@spectrum-web-components/styles/tokens/express/global-vars.css';
181-
@import '@spectrum-web-components/styles/tokens/express/light-vars.css';
182-
@import '@spectrum-web-components/styles/tokens/express/dark-vars.css';
144+
/* import express-specific tokens files (replace express/ with spectrum/ for Spectrum system) */
183145
@import '@spectrum-web-components/styles/tokens/express/medium-vars.css';
184-
@import '@spectrum-web-components/styles/tokens/express/large-vars.css';
185-
```
146+
@import '@spectrum-web-components/styles/tokens/express/global-vars.css';
186147

187-
#### Spectrum 2 tokens
148+
.my-component {
149+
/* defined in express medium-vars.css */
150+
border-radius: var(--spectrum-corner-radius-100);
188151

189-
```css
190-
@import '@spectrum-web-components/styles/tokens-v2/global-vars.css';
191-
@import '@spectrum-web-components/styles/tokens-v2/light-vars.css';
192-
@import '@spectrum-web-components/styles/tokens-v2/dark-vars.css';
193-
@import '@spectrum-web-components/styles/tokens-v2/medium-vars.css';
194-
@import '@spectrum-web-components/styles/tokens-v2/large-vars.css';
152+
/* defined in base global-vars.css */
153+
border-width: var(--spectrum-border-width-100);
154+
color: var(
155+
--spectrum-neutral-subdued-content-color-default
156+
); /* uses --spectrum-gray-700, which is defined differently depending whether light or dark vars are loaded */
157+
158+
/* defined in base light-vars.css, defined differently in dark-vars.css */
159+
background-color: var(--spectrum-gray-50);
160+
border-color: var(--spectrum-gray-700);
161+
162+
/* defined in base medium-vars.css, defined differently in large-vars.css */
163+
padding-inline: var(--spectrum-component-edge-to-text-75);
164+
padding-block: var(--spectrum-component-top-to-text-75);
165+
min-block-size: var(--spectrum-component-height-75);
166+
167+
border-style: solid;
168+
}
195169
```
196170

197171
### Typography
@@ -252,6 +226,16 @@ static styles = [headingStyles];
252226

253227
Each individual export (`body.js`, `heading.js`, etc.) includes the necessary base and language support styles, so you don't need to import them separately. Import `typography.js` for the complete system, or import individual exports to reduce bundle size.
254228

229+
### Spectrum Vars tokens (deprecated)
230+
231+
This package includes some deprecated files that use the older Spectrum Vars token naming convention, including combined theme files (e.g., `all-medium-dark.css`) and individual theme/scale files (e.g., `theme-light.css`, `scale-medium.css`).
232+
233+
**Recommended alternatives:**
234+
235+
- Use `<sp-theme>` for automatic theme management (recommended)
236+
- Import Spectrum Core tokens directly for granular control (see "Design tokens" section above)
237+
- See the [Spectrum Core tokens migration guide](../theme/core-tokens.md) for help migrating from Spectrum Vars to Spectrum Core tokens
238+
255239
### Migrating to Spectrum 2
256240

257241
If you're migrating to Spectrum 2, see the [Spectrum 2 migration guide](../../migrating-to-spectrum2/) for detailed instructions.

0 commit comments

Comments
 (0)