Skip to content

Commit 894775f

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

File tree

1 file changed

+112
-126
lines changed

1 file changed

+112
-126
lines changed

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

Lines changed: 112 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -26,172 +26,148 @@ 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
79+
80+
Express also uses a base + override pattern (same as Spectrum above, but with `express/` paths):
7181

7282
```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-
```
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';
7887

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.
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+
```
8093

81-
### Individual theme and scale files
94+
See the "Tokens usage" section below for detailed examples of how to use these tokens in your components.
8295

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.
96+
#### Tokens usage
8497

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

87-
Import a single color option to set color values:
100+
##### V2 tokens
88101

89-
```css
90-
/* Spectrum */
91-
@import '@spectrum-web-components/styles/theme-light.css';
102+
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.
92103

93-
/* Express */
94-
@import '@spectrum-web-components/styles/express/theme-dark.css';
104+
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`).
95105

96-
/* Spectrum 2 */
97-
@import '@spectrum-web-components/styles/spectrum-two/theme-light.css';
98-
```
106+
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);`).
99107

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:
108+
Here's one example of tokens usage in a non-web-component context, showing how custom properties from each file work together:
128109

129110
```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';
111+
/* import appropriate tokens files */
112+
@import '@spectrum-web-components/styles/tokens-v2/light-vars.css';
113+
@import '@spectrum-web-components/styles/tokens-v2/medium-vars.css';
114+
@import '@spectrum-web-components/styles/tokens-v2/global-vars.css';
135115

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

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:
137+
##### Tokens (base + system overrides pattern)
166138

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

169141
```css
170-
@import '@spectrum-web-components/styles/tokens/global-vars.css';
142+
/* import base tokens files */
171143
@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
144+
@import '@spectrum-web-components/styles/tokens/global-vars.css';
178145

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';
146+
/* import express-specific tokens files (replace express/ with spectrum/ for Spectrum system) */
183147
@import '@spectrum-web-components/styles/tokens/express/medium-vars.css';
184-
@import '@spectrum-web-components/styles/tokens/express/large-vars.css';
185-
```
148+
@import '@spectrum-web-components/styles/tokens/express/global-vars.css';
186149

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

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';
154+
/* defined in base global-vars.css */
155+
border-width: var(--spectrum-border-width-100);
156+
color: var(
157+
--spectrum-neutral-subdued-content-color-default
158+
); /* uses --spectrum-gray-700, which is defined differently depending whether light or dark vars are loaded */
159+
160+
/* defined in base light-vars.css, defined differently in dark-vars.css */
161+
background-color: var(--spectrum-gray-50);
162+
border-color: var(--spectrum-gray-700);
163+
164+
/* defined in base medium-vars.css, defined differently in large-vars.css */
165+
padding-inline: var(--spectrum-component-edge-to-text-75);
166+
padding-block: var(--spectrum-component-top-to-text-75);
167+
min-block-size: var(--spectrum-component-height-75);
168+
169+
border-style: solid;
170+
}
195171
```
196172

197173
### Typography
@@ -252,6 +228,16 @@ static styles = [headingStyles];
252228

253229
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.
254230

231+
### Spectrum Vars tokens (deprecated)
232+
233+
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`).
234+
235+
**Recommended alternatives:**
236+
237+
- Use `<sp-theme>` for automatic theme management (recommended)
238+
- Import Spectrum Core tokens directly for granular control (see "Design tokens" section above)
239+
- See the [Spectrum Core tokens migration guide](../theme/core-tokens.md) for help migrating from Spectrum Vars to Spectrum Core tokens
240+
255241
### Migrating to Spectrum 2
256242

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

0 commit comments

Comments
 (0)