Skip to content

Commit 75ff964

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

File tree

1 file changed

+146
-60
lines changed

1 file changed

+146
-60
lines changed

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

Lines changed: 146 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,210 @@
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+
| System | Available colors |
103+
| ------------------- | -------------------------------------------------------------------------------------------------------- |
104+
| **Spectrum Legacy** | `theme-dark.css`, `theme-light.css`, `theme-darkest.css` (deprecated), `theme-lightest.css` (deprecated) |
105+
| **Express** | `express/theme-dark.css`, `express/theme-light.css` |
106+
| **Spectrum 2** | `spectrum-two/theme-dark.css`, `spectrum-two/theme-light.css` |
77107

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

84-
### Light
112+
Import a single scale to set sizing values:
85113

86-
```
87-
@import '@spectrum-web-components/styles/theme-light.css';
114+
```css
115+
/* Spectrum Legacy */
116+
@import '@spectrum-web-components/styles/scale-medium.css';
117+
118+
/* Express */
119+
@import '@spectrum-web-components/styles/express/scale-medium.css';
120+
121+
/* Spectrum 2 */
122+
@import '@spectrum-web-components/styles/spectrum-two/scale-large.css';
88123
```
89124

90-
This file provides only the variables needed to power a color palette featuring colors found in the "Light" theme.
125+
**Available scales:**
91126

92-
### Lightest
127+
| System | Available scales |
128+
| ------------------- | --------------------------------------------------------------- |
129+
| **Spectrum Legacy** | `scale-medium.css`, `scale-large.css` |
130+
| **Express** | `express/scale-medium.css`, `express/scale-large.css` |
131+
| **Spectrum 2** | `spectrum-two/scale-medium.css`, `spectrum-two/scale-large.css` |
93132

94-
```
95-
@import '@spectrum-web-components/styles/theme-lightest.css';
133+
## Typography
134+
135+
```ts
136+
@import '@spectrum-web-components/styles/typography.css';
96137
```
97138

98-
This file provides only the variables needed to power a color palette featuring colors found in the "Lightest" theme.
139+
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).
99140

100-
## Scale
141+
**What's included:**
101142

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

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

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

110-
### Large
155+
```ts
156+
import typographyStyles from '@spectrum-web-components/styles/typography.js';
157+
import bodyStyles from '@spectrum-web-components/styles/body.js';
158+
import headingStyles from '@spectrum-web-components/styles/heading.js';
159+
import detailStyles from '@spectrum-web-components/styles/detail.js';
160+
import codeStyles from '@spectrum-web-components/styles/code.js';
111161

112-
```
113-
@import '@spectrum-web-components/styles/scale-large.css';
162+
// Use in your component's static styles
163+
static styles = [typographyStyles];
114164
```
115165

116-
This file provides only the variables needed to power the "Large" scale system specification.
166+
- **`typography.js`** - Complete typography system with all classes
167+
- **`body.js`** - Body text styles only (base + lang + body classes)
168+
- **`heading.js`** - Heading styles only (base + lang + heading classes)
169+
- **`detail.js`** - Detail/label styles only (base + lang + detail classes)
170+
- **`code.js`** - Code styles only (base + lang + code classes)
117171

118-
## Typography
172+
Import individual exports when you only need specific typography components to reduce bundle size.
173+
174+
## Design tokens
119175

176+
For advanced use cases where you need direct access to design token CSS custom properties, this package exposes token files:
177+
178+
### Spectrum Legacy tokens
179+
180+
```ts
181+
@import '@spectrum-web-components/styles/tokens/global-vars.css';
182+
@import '@spectrum-web-components/styles/tokens/light-vars.css';
183+
@import '@spectrum-web-components/styles/tokens/dark-vars.css';
184+
@import '@spectrum-web-components/styles/tokens/medium-vars.css';
185+
@import '@spectrum-web-components/styles/tokens/large-vars.css';
120186
```
121-
@import '@spectrum-web-components/styles/typography.css';
187+
188+
### Express tokens
189+
190+
```ts
191+
@import '@spectrum-web-components/styles/tokens/express/global-vars.css';
192+
@import '@spectrum-web-components/styles/tokens/express/light-vars.css';
193+
@import '@spectrum-web-components/styles/tokens/express/dark-vars.css';
194+
@import '@spectrum-web-components/styles/tokens/express/medium-vars.css';
195+
@import '@spectrum-web-components/styles/tokens/express/large-vars.css';
196+
```
197+
198+
### Spectrum 2 tokens
199+
200+
```ts
201+
@import '@spectrum-web-components/styles/tokens-v2/global-vars.css';
202+
@import '@spectrum-web-components/styles/tokens-v2/light-vars.css';
203+
@import '@spectrum-web-components/styles/tokens-v2/dark-vars.css';
204+
@import '@spectrum-web-components/styles/tokens-v2/medium-vars.css';
205+
@import '@spectrum-web-components/styles/tokens-v2/large-vars.css';
122206
```
123207

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).
208+
## Migrating to Spectrum 2
209+
210+
If you're migrating to Spectrum 2, see the [Spectrum 2 migration guide](../../projects/documentation/content/migrating-to-spectrum2.md) for detailed instructions.

0 commit comments

Comments
 (0)