Skip to content

Commit 4f6c32e

Browse files
rise-erpeldingrise-erpelding
committed
docs: update styles docs
1 parent 1691e33 commit 4f6c32e

File tree

1 file changed

+177
-61
lines changed

1 file changed

+177
-61
lines changed

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

Lines changed: 177 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,240 @@
1-
## Description
1+
## Overview
22

3-
Spectrum Web Components are a [`LitElement`](https://lit-element.polymer-project.org)-powered web component library of patterns built on top of the [Spectrum CSS](https://opensource.adobe.com/spectrum-css) specification. Styles for these components are made available (and, in some cases, customizable) via CSS Custom Properties, e.g. `var(--spectrum-black)`. In this package, you will find the CSS Custom Properties that power the various color and size themes defined by Spectrum CSS.
3+
Spectrum Web Components are a [`LitElement`](https://lit-element.polymer-project.org)-powered web component library implementing Adobe's Spectrum design system. This package defines the CSS custom properties that implement design tokens from [Spectrum Tokens](https://github.com/adobe/spectrum-tokens). Spectrum Web Components consume these properties in their styles. These include colors, spacing, typography, and sizing values like `--spectrum-gray-100`, `--spectrum-component-height-200`, and `--spectrum-font-size-100`. In this package, you will find the CSS custom properties that Spectrum Web Components reference in their stylesheets, with values that vary across different system variants, color options, and scales.
44

5-
The easiest way to consume these values is via the `<sp-theme>` element. However, in some cases, it can be useful to have direct access to the files outlining the CSS Custom Properties, on top of which the rest of the component system is built.
5+
### Relationship to `<sp-theme>`
6+
7+
The `<sp-theme>` element is built on top of this styles package. It consumes the CSS custom properties provided here and wraps them in a Web Component that manages theme switching, directionality, and other runtime behaviors.
8+
9+
**For most applications**, we recommend using `<sp-theme>` rather than directly importing these CSS files. The theme element provides a more flexible and maintainable way to manage systems, colors, and scales using attributes like `system="spectrum"`, `color="dark"`, and `scale="medium"` (e.g., `<sp-theme system="spectrum" color="dark" scale="medium">`).
10+
11+
**Use this styles package directly** when you need:
12+
13+
- Fine-grained control over which CSS files are loaded
14+
- To integrate Spectrum styles into non-web component contexts
15+
- To build custom components outside the `<sp-theme>` wrapper
16+
- Direct access to unthemed design tokens for advanced use cases
17+
18+
See the `@spectrum-web-components/theme` [documentation](../theme) for more information about using the theme element.
619

720
### Usage
821

922
[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/styles?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/styles)
1023
[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/styles?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/styles)
1124

12-
```
25+
```zsh
1326
yarn add @spectrum-web-components/styles
1427
```
1528

16-
## Theme packages
29+
## System variants
1730

18-
```
19-
@import '@spectrum-web-components/styles/all-medium-darkest.css';
20-
```
31+
This package provides styles for three Adobe design system variants (referred to as "systems"). Each system has different available color options:
2132

22-
This file brings together the global variables and font settings with the "Darkest" color set and "Medium" scale system specification.
33+
- **Spectrum Legacy** (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`
2336

24-
```
37+
## Combined theme packages (Spectrum Legacy)
38+
39+
If you're not using `<sp-theme>`, the styles package provides convenience bundles for Spectrum Legacy 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).
40+
41+
> **Note:** The `darkest` and `lightest` colors are deprecated and will be removed in a future release. Use `dark` or `light` instead.
42+
43+
```ts
2544
@import '@spectrum-web-components/styles/all-medium-dark.css';
2645
```
2746

2847
This file brings together the global variables and font settings with the "Dark" color set and "Medium" scale system specification.
2948

30-
```
49+
```ts
3150
@import '@spectrum-web-components/styles/all-medium-light.css';
3251
```
3352

3453
This file brings together the global variables and font settings with the "Light" color set and "Medium" scale system specification.
3554

36-
```
37-
@import '@spectrum-web-components/styles/all-medium-lightest.css';
38-
```
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`.
3956

40-
This file brings together the global variables and font settings with the "Lightest" color set and "Medium" scale system specification.
57+
## Manual theme composition (Express and Spectrum 2)
4158

42-
```
43-
@import '@spectrum-web-components/styles/all-large-darkest.css';
44-
```
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 Legacy) by importing four files: core global styles, typography, a color option, and a scale.
4560

46-
This file brings together the global variables and font settings with the "Darkest" color set and "Large" scale system specification.
61+
**Express example (large, dark):**
4762

48-
```
49-
@import '@spectrum-web-components/styles/all-large-dark.css';
63+
```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';
5068
```
5169

52-
This file brings together the global variables and font settings with the "Dark" color set and "Large" scale system specification.
70+
**Spectrum 2 example (medium, light):**
5371

54-
```
55-
@import '@spectrum-web-components/styles/all-large-light.css';
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';
5677
```
5778

58-
This file brings together the global variables and font settings with the "Light" color set and "Large" scale system specification.
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.
5980
60-
```
61-
@import '@spectrum-web-components/styles/all-large-lightest.css';
62-
```
81+
## Individual theme and scale files
6382

64-
This file brings together the global variables and font settings with the "Lightest" color set and "Large" scale system specification.
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.
6584

66-
## Color sets
85+
### Color
6786

68-
### Darkest
87+
Import a single color option to set color values:
6988

70-
```
71-
@import '@spectrum-web-components/styles/theme-darkest.css';
89+
```css
90+
/* Spectrum Legacy */
91+
@import '@spectrum-web-components/styles/theme-light.css';
92+
93+
/* Express */
94+
@import '@spectrum-web-components/styles/express/theme-dark.css';
95+
96+
/* Spectrum 2 */
97+
@import '@spectrum-web-components/styles/spectrum-two/theme-light.css';
7298
```
7399

74-
This file provides only the variables needed to power a color palette featuring colors found in the "Darkest" theme.
100+
**Available color options:**
75101

76-
### Dark
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 Legacy</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>
77122

78-
```
79-
@import '@spectrum-web-components/styles/theme-dark.css';
80-
```
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.
81124
82-
This file provides only the variables needed to power a color palette featuring colors found in the "Dark" theme.
125+
### Scale
83126

84-
### Light
127+
Import a single scale to set sizing values:
85128

86-
```
87-
@import '@spectrum-web-components/styles/theme-light.css';
88-
```
129+
```css
130+
/* Spectrum Legacy */
131+
@import '@spectrum-web-components/styles/scale-medium.css';
89132

90-
This file provides only the variables needed to power a color palette featuring colors found in the "Light" theme.
133+
/* Express */
134+
@import '@spectrum-web-components/styles/express/scale-medium.css';
135+
136+
/* Spectrum 2 */
137+
@import '@spectrum-web-components/styles/spectrum-two/scale-large.css';
138+
```
139+
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 Legacy</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>
91162

92-
### Lightest
163+
## Typography
93164

94-
```
95-
@import '@spectrum-web-components/styles/theme-lightest.css';
165+
```ts
166+
@import '@spectrum-web-components/styles/typography.css';
96167
```
97168

98-
This file provides only the variables needed to power a color palette featuring colors found in the "Lightest" theme.
169+
This file provides the complete [Spectrum Typography system](https://opensource.adobe.com/spectrum-css/?path=/docs/components-typography--docs). The typography system is shared across all design systems (Spectrum Legacy, Express, and Spectrum 2).
99170

100-
## Scale
171+
**What's included:**
101172

102-
### Medium
173+
- **Heading** styles (`.spectrum-Heading`) - Multiple sizes from XXS to XXXL with weight variants (light, regular, heavy) and serif options
174+
- **Body** styles (`.spectrum-Body`) - Multiple sizes from XS to XXXL with serif options for body copy and longer text
175+
- **Detail** styles (`.spectrum-Detail`) - Uppercase labels and metadata text in sizes S through XL with light weight option
176+
- **Code** styles (`.spectrum-Code`) - Monospace inline code snippets in sizes XS through XL
177+
- **Language support** - Automatic font family selection for Arabic (`:lang(ar)`), Hebrew (`:lang(he)`), and CJK languages (Chinese, Japanese, Korean)
178+
- **Emphasis and strong** - Proper italic and bold styling for `<em>` and `<strong>` elements within each typography class
179+
- **High contrast mode support** - Ensures text remains readable when Windows High Contrast Mode is enabled
103180

104-
```
105-
@import '@spectrum-web-components/styles/scale-medium.css';
106-
```
181+
### TypeScript/JavaScript exports for Lit components
107182

108-
This file provides only the variables needed to power the "Medium" scale system specification.
183+
For use in Lit-based components, you can import typography styles as JavaScript modules:
109184

110-
### Large
185+
```ts
186+
import typographyStyles from '@spectrum-web-components/styles/typography.js';
187+
import bodyStyles from '@spectrum-web-components/styles/body.js';
188+
import headingStyles from '@spectrum-web-components/styles/heading.js';
189+
import detailStyles from '@spectrum-web-components/styles/detail.js';
190+
import codeStyles from '@spectrum-web-components/styles/code.js';
111191

112-
```
113-
@import '@spectrum-web-components/styles/scale-large.css';
192+
// Use in your component's static styles
193+
static styles = [typographyStyles];
114194
```
115195

116-
This file provides only the variables needed to power the "Large" scale system specification.
196+
- **`typography.js`** - Complete typography system with all classes
197+
- **`body.js`** - Body text styles only (base + lang + body classes)
198+
- **`heading.js`** - Heading styles only (base + lang + heading classes)
199+
- **`detail.js`** - Detail/label styles only (base + lang + detail classes)
200+
- **`code.js`** - Code styles only (base + lang + code classes)
117201

118-
## Typography
202+
Import individual exports when you only need specific typography components to reduce bundle size.
203+
204+
## Design tokens
119205

206+
For advanced use cases where you need direct access to design token CSS custom properties, this package exposes token files:
207+
208+
### Spectrum Legacy tokens
209+
210+
```ts
211+
@import '@spectrum-web-components/styles/tokens/global-vars.css';
212+
@import '@spectrum-web-components/styles/tokens/light-vars.css';
213+
@import '@spectrum-web-components/styles/tokens/dark-vars.css';
214+
@import '@spectrum-web-components/styles/tokens/medium-vars.css';
215+
@import '@spectrum-web-components/styles/tokens/large-vars.css';
120216
```
121-
@import '@spectrum-web-components/styles/typography.css';
217+
218+
### Express tokens
219+
220+
```ts
221+
@import '@spectrum-web-components/styles/tokens/express/global-vars.css';
222+
@import '@spectrum-web-components/styles/tokens/express/light-vars.css';
223+
@import '@spectrum-web-components/styles/tokens/express/dark-vars.css';
224+
@import '@spectrum-web-components/styles/tokens/express/medium-vars.css';
225+
@import '@spectrum-web-components/styles/tokens/express/large-vars.css';
226+
```
227+
228+
### Spectrum 2 tokens
229+
230+
```ts
231+
@import '@spectrum-web-components/styles/tokens-v2/global-vars.css';
232+
@import '@spectrum-web-components/styles/tokens-v2/light-vars.css';
233+
@import '@spectrum-web-components/styles/tokens-v2/dark-vars.css';
234+
@import '@spectrum-web-components/styles/tokens-v2/medium-vars.css';
235+
@import '@spectrum-web-components/styles/tokens-v2/large-vars.css';
122236
```
123237

124-
This file provides a `lit-html` compliant version of the [Spectrum Typography classes](https://opensource.adobe.com/spectrum-css/?path=/docs/components-typography--docs).
238+
## Migrating to Spectrum 2
239+
240+
If you're migrating to Spectrum 2, see the [Spectrum 2 migration guide](../../migrating-to-spectrum2/) for detailed instructions.

0 commit comments

Comments
 (0)