From a7d69c3143f60d791ca229771d54b41aa26b6d61 Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Wed, 5 Nov 2025 19:33:28 -0600 Subject: [PATCH 01/16] docs: update styles docs --- 1st-gen/tools/styles/README.md | 238 ++++++++++++++++++++++++--------- 1 file changed, 177 insertions(+), 61 deletions(-) diff --git a/1st-gen/tools/styles/README.md b/1st-gen/tools/styles/README.md index 3f37e42ed3c..85abf4435c4 100644 --- a/1st-gen/tools/styles/README.md +++ b/1st-gen/tools/styles/README.md @@ -1,124 +1,240 @@ -## Description +## Overview -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. +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. -The easiest way to consume these values is via the `` 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. +### Relationship to `` + +The `` 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. + +**For most applications**, we recommend using `` 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., ``). + +**Use this styles package directly** when you need: + +- Fine-grained control over which CSS files are loaded +- To integrate Spectrum styles into non-web component contexts +- To build custom components outside the `` wrapper +- Direct access to unthemed design tokens for advanced use cases + +See the `@spectrum-web-components/theme` [documentation](../theme) for more information about using the theme element. ### Usage [![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) [![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) -``` +```zsh yarn add @spectrum-web-components/styles ``` -## Theme packages +## System variants -``` -@import '@spectrum-web-components/styles/all-medium-darkest.css'; -``` +This package provides styles for three Adobe design system variants (referred to as "systems"). Each system has different available color options: -This file brings together the global variables and font settings with the "Darkest" color set and "Medium" scale system specification. +- **Spectrum Legacy** (system: `spectrum`) - The original Spectrum design system with four color options: `dark`, `light`, and deprecated `darkest` and `lightest` +- **Express** (system: `express`) - The Adobe Express design system with two color options: `dark` and `light` +- **Spectrum 2** (system: `spectrum-two`) - The next generation Spectrum design system with two color options: `dark` and `light` -``` +## Combined theme packages (Spectrum Legacy) + +If you're not using ``, 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). + +> **Note:** The `darkest` and `lightest` colors are deprecated and will be removed in a future release. Use `dark` or `light` instead. + +```ts @import '@spectrum-web-components/styles/all-medium-dark.css'; ``` This file brings together the global variables and font settings with the "Dark" color set and "Medium" scale system specification. -``` +```ts @import '@spectrum-web-components/styles/all-medium-light.css'; ``` This file brings together the global variables and font settings with the "Light" color set and "Medium" scale system specification. -``` -@import '@spectrum-web-components/styles/all-medium-lightest.css'; -``` +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`. -This file brings together the global variables and font settings with the "Lightest" color set and "Medium" scale system specification. +## Manual theme composition (Express and Spectrum 2) -``` -@import '@spectrum-web-components/styles/all-large-darkest.css'; -``` +If you're not using ``, 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. -This file brings together the global variables and font settings with the "Darkest" color set and "Large" scale system specification. +**Express example (large, dark):** -``` -@import '@spectrum-web-components/styles/all-large-dark.css'; +```css +@import '@spectrum-web-components/styles/express/core-global.css'; +@import '@spectrum-web-components/styles/typography.css'; +@import '@spectrum-web-components/styles/express/theme-dark.css'; +@import '@spectrum-web-components/styles/express/scale-large.css'; ``` -This file brings together the global variables and font settings with the "Dark" color set and "Large" scale system specification. +**Spectrum 2 example (medium, light):** -``` -@import '@spectrum-web-components/styles/all-large-light.css'; +```css +@import '@spectrum-web-components/styles/spectrum-two/core-global.css'; +@import '@spectrum-web-components/styles/typography.css'; +@import '@spectrum-web-components/styles/spectrum-two/theme-light.css'; +@import '@spectrum-web-components/styles/spectrum-two/scale-medium.css'; ``` -This file brings together the global variables and font settings with the "Light" color set and "Large" scale system specification. +> **Note:** For most use cases, we recommend using `` instead of manually managing these imports. The theme element handles composition and switching automatically. -``` -@import '@spectrum-web-components/styles/all-large-lightest.css'; -``` +## Individual theme and scale files -This file brings together the global variables and font settings with the "Lightest" color set and "Large" scale system specification. +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. -## Color sets +### Color -### Darkest +Import a single color option to set color values: -``` -@import '@spectrum-web-components/styles/theme-darkest.css'; +```css +/* Spectrum Legacy */ +@import '@spectrum-web-components/styles/theme-light.css'; + +/* Express */ +@import '@spectrum-web-components/styles/express/theme-dark.css'; + +/* Spectrum 2 */ +@import '@spectrum-web-components/styles/spectrum-two/theme-light.css'; ``` -This file provides only the variables needed to power a color palette featuring colors found in the "Darkest" theme. +**Available color options:** -### Dark + + + System + Available colors + + + + Spectrum Legacy + theme-dark.css, theme-light.css, theme-darkest.css (deprecated), theme-lightest.css (deprecated) + + + Express + express/theme-dark.css, express/theme-light.css + + + Spectrum 2 + spectrum-two/theme-dark.css, spectrum-two/theme-light.css + + + -``` -@import '@spectrum-web-components/styles/theme-dark.css'; -``` +> **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. -This file provides only the variables needed to power a color palette featuring colors found in the "Dark" theme. +### Scale -### Light +Import a single scale to set sizing values: -``` -@import '@spectrum-web-components/styles/theme-light.css'; -``` +```css +/* Spectrum Legacy */ +@import '@spectrum-web-components/styles/scale-medium.css'; -This file provides only the variables needed to power a color palette featuring colors found in the "Light" theme. +/* Express */ +@import '@spectrum-web-components/styles/express/scale-medium.css'; + +/* Spectrum 2 */ +@import '@spectrum-web-components/styles/spectrum-two/scale-large.css'; +``` + +**Available scales:** + + + + System + Available scales + + + + Spectrum Legacy + scale-medium.css, scale-large.css + + + Express + express/scale-medium.css, express/scale-large.css + + + Spectrum 2 + spectrum-two/scale-medium.css, spectrum-two/scale-large.css + + + -### Lightest +## Typography -``` -@import '@spectrum-web-components/styles/theme-lightest.css'; +```ts +@import '@spectrum-web-components/styles/typography.css'; ``` -This file provides only the variables needed to power a color palette featuring colors found in the "Lightest" theme. +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). -## Scale +**What's included:** -### Medium +- **Heading** styles (`.spectrum-Heading`) - Multiple sizes from XXS to XXXL with weight variants (light, regular, heavy) and serif options +- **Body** styles (`.spectrum-Body`) - Multiple sizes from XS to XXXL with serif options for body copy and longer text +- **Detail** styles (`.spectrum-Detail`) - Uppercase labels and metadata text in sizes S through XL with light weight option +- **Code** styles (`.spectrum-Code`) - Monospace inline code snippets in sizes XS through XL +- **Language support** - Automatic font family selection for Arabic (`:lang(ar)`), Hebrew (`:lang(he)`), and CJK languages (Chinese, Japanese, Korean) +- **Emphasis and strong** - Proper italic and bold styling for `` and `` elements within each typography class +- **High contrast mode support** - Ensures text remains readable when Windows High Contrast Mode is enabled -``` -@import '@spectrum-web-components/styles/scale-medium.css'; -``` +### TypeScript/JavaScript exports for Lit components -This file provides only the variables needed to power the "Medium" scale system specification. +For use in Lit-based components, you can import typography styles as JavaScript modules: -### Large +```ts +import typographyStyles from '@spectrum-web-components/styles/typography.js'; +import bodyStyles from '@spectrum-web-components/styles/body.js'; +import headingStyles from '@spectrum-web-components/styles/heading.js'; +import detailStyles from '@spectrum-web-components/styles/detail.js'; +import codeStyles from '@spectrum-web-components/styles/code.js'; -``` -@import '@spectrum-web-components/styles/scale-large.css'; +// Use in your component's static styles +static styles = [typographyStyles]; ``` -This file provides only the variables needed to power the "Large" scale system specification. +- **`typography.js`** - Complete typography system with all classes +- **`body.js`** - Body text styles only (base + lang + body classes) +- **`heading.js`** - Heading styles only (base + lang + heading classes) +- **`detail.js`** - Detail/label styles only (base + lang + detail classes) +- **`code.js`** - Code styles only (base + lang + code classes) -## Typography +Import individual exports when you only need specific typography components to reduce bundle size. + +## Design tokens +For advanced use cases where you need direct access to design token CSS custom properties, this package exposes token files: + +### Spectrum Legacy tokens + +```ts +@import '@spectrum-web-components/styles/tokens/global-vars.css'; +@import '@spectrum-web-components/styles/tokens/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/dark-vars.css'; +@import '@spectrum-web-components/styles/tokens/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens/large-vars.css'; ``` -@import '@spectrum-web-components/styles/typography.css'; + +### Express tokens + +```ts +@import '@spectrum-web-components/styles/tokens/express/global-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/dark-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/large-vars.css'; +``` + +### Spectrum 2 tokens + +```ts +@import '@spectrum-web-components/styles/tokens-v2/global-vars.css'; +@import '@spectrum-web-components/styles/tokens-v2/light-vars.css'; +@import '@spectrum-web-components/styles/tokens-v2/dark-vars.css'; +@import '@spectrum-web-components/styles/tokens-v2/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens-v2/large-vars.css'; ``` -This file provides a `lit-html` compliant version of the [Spectrum Typography classes](https://opensource.adobe.com/spectrum-css/?path=/docs/components-typography--docs). +## Migrating to Spectrum 2 + +If you're migrating to Spectrum 2, see the [Spectrum 2 migration guide](../../migrating-to-spectrum2/) for detailed instructions. From 5228fc3328cd81757a58a1095f082ab26e5ab4d3 Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Fri, 7 Nov 2025 12:47:54 -0600 Subject: [PATCH 02/16] docs: improve typography section, syntax --- 1st-gen/tools/styles/README.md | 109 ++++++++++++++++++--------------- 1 file changed, 61 insertions(+), 48 deletions(-) diff --git a/1st-gen/tools/styles/README.md b/1st-gen/tools/styles/README.md index 85abf4435c4..8de8c9a71dd 100644 --- a/1st-gen/tools/styles/README.md +++ b/1st-gen/tools/styles/README.md @@ -26,27 +26,27 @@ See the `@spectrum-web-components/theme` [documentation](../theme) for more info yarn add @spectrum-web-components/styles ``` -## System variants +### System variants This package provides styles for three Adobe design system variants (referred to as "systems"). Each system has different available color options: -- **Spectrum Legacy** (system: `spectrum`) - The original Spectrum design system with four color options: `dark`, `light`, and deprecated `darkest` and `lightest` +- **Spectrum** (system: `spectrum`) - The original Spectrum design system with four color options: `dark`, `light`, and deprecated `darkest` and `lightest` - **Express** (system: `express`) - The Adobe Express design system with two color options: `dark` and `light` - **Spectrum 2** (system: `spectrum-two`) - The next generation Spectrum design system with two color options: `dark` and `light` -## Combined theme packages (Spectrum Legacy) +### Combined theme packages (Spectrum) -If you're not using ``, 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). +If you're not using ``, 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). > **Note:** The `darkest` and `lightest` colors are deprecated and will be removed in a future release. Use `dark` or `light` instead. -```ts +```css @import '@spectrum-web-components/styles/all-medium-dark.css'; ``` This file brings together the global variables and font settings with the "Dark" color set and "Medium" scale system specification. -```ts +```css @import '@spectrum-web-components/styles/all-medium-light.css'; ``` @@ -54,11 +54,11 @@ This file brings together the global variables and font settings with the "Light 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`. -## Manual theme composition (Express and Spectrum 2) +### Manual theme composition (Express and Spectrum 2) -If you're not using ``, 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. +If you're not using ``, 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. -**Express example (large, dark):** +#### Express example (large, dark) ```css @import '@spectrum-web-components/styles/express/core-global.css'; @@ -67,7 +67,7 @@ If you're not using ``, you can manually compose a complete theme for @import '@spectrum-web-components/styles/express/scale-large.css'; ``` -**Spectrum 2 example (medium, light):** +#### Spectrum 2 example (medium, light) ```css @import '@spectrum-web-components/styles/spectrum-two/core-global.css'; @@ -78,16 +78,16 @@ If you're not using ``, you can manually compose a complete theme for > **Note:** For most use cases, we recommend using `` instead of manually managing these imports. The theme element handles composition and switching automatically. -## Individual theme and scale files +### Individual theme and scale files 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. -### Color +#### Color Import a single color option to set color values: ```css -/* Spectrum Legacy */ +/* Spectrum */ @import '@spectrum-web-components/styles/theme-light.css'; /* Express */ @@ -97,7 +97,7 @@ Import a single color option to set color values: @import '@spectrum-web-components/styles/spectrum-two/theme-light.css'; ``` -**Available color options:** +##### Available color options @@ -106,7 +106,7 @@ Import a single color option to set color values: - Spectrum Legacy + Spectrum theme-dark.css, theme-light.css, theme-darkest.css (deprecated), theme-lightest.css (deprecated) @@ -122,12 +122,12 @@ Import a single color option to set color values: > **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. -### Scale +#### Scale Import a single scale to set sizing values: ```css -/* Spectrum Legacy */ +/* Spectrum */ @import '@spectrum-web-components/styles/scale-medium.css'; /* Express */ @@ -137,7 +137,7 @@ Import a single scale to set sizing values: @import '@spectrum-web-components/styles/spectrum-two/scale-large.css'; ``` -**Available scales:** +##### Available scales @@ -146,7 +146,7 @@ Import a single scale to set sizing values: - Spectrum Legacy + Spectrum scale-medium.css, scale-large.css @@ -160,15 +160,11 @@ Import a single scale to set sizing values: -## Typography - -```ts -@import '@spectrum-web-components/styles/typography.css'; -``` +### Typography -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). +The [Spectrum Typography system](https://opensource.adobe.com/spectrum-css/?path=/docs/components-typography--docs) provides a complete set of text styles. The typography system is shared across all design systems (Spectrum, Express, and Spectrum 2). -**What's included:** +#### What's included - **Heading** styles (`.spectrum-Heading`) - Multiple sizes from XXS to XXXL with weight variants (light, regular, heavy) and serif options - **Body** styles (`.spectrum-Body`) - Multiple sizes from XS to XXXL with serif options for body copy and longer text @@ -178,36 +174,53 @@ This file provides the complete [Spectrum Typography system](https://opensource. - **Emphasis and strong** - Proper italic and bold styling for `` and `` elements within each typography class - **High contrast mode support** - Ensures text remains readable when Windows High Contrast Mode is enabled -### TypeScript/JavaScript exports for Lit components +#### CSS imports + +For stylesheet use, import the complete typography system: + +```css +@import '@spectrum-web-components/styles/typography.css'; +``` + +#### TypeScript/JavaScript exports for Lit components + +For use in Lit-based components, you can import typography styles as JavaScript modules. Import the complete system or individual components depending on your needs: -For use in Lit-based components, you can import typography styles as JavaScript modules: +##### Import everything -```ts +```js import typographyStyles from '@spectrum-web-components/styles/typography.js'; -import bodyStyles from '@spectrum-web-components/styles/body.js'; -import headingStyles from '@spectrum-web-components/styles/heading.js'; -import detailStyles from '@spectrum-web-components/styles/detail.js'; -import codeStyles from '@spectrum-web-components/styles/code.js'; -// Use in your component's static styles static styles = [typographyStyles]; ``` -- **`typography.js`** - Complete typography system with all classes -- **`body.js`** - Body text styles only (base + lang + body classes) -- **`heading.js`** - Heading styles only (base + lang + heading classes) -- **`detail.js`** - Detail/label styles only (base + lang + detail classes) -- **`code.js`** - Code styles only (base + lang + code classes) +##### Import only what you need + +For smaller bundle sizes, import individual components: + +```js +import headingStyles from '@spectrum-web-components/styles/heading.js'; + +static styles = [headingStyles]; +``` -Import individual exports when you only need specific typography components to reduce bundle size. +##### Available JavaScript exports -## Design tokens +- **`typography.js`** - Complete typography system with all styles (heading, body, detail, code) +- **`body.js`** - Body text styles only (includes base + lang + body) +- **`heading.js`** - Heading styles only (includes base + lang + heading) +- **`detail.js`** - Detail/label styles only (includes base + lang + detail) +- **`code.js`** - Code styles only (includes base + lang + code) + +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. + +### Design tokens For advanced use cases where you need direct access to design token CSS custom properties, this package exposes token files: -### Spectrum Legacy tokens +#### Spectrum tokens -```ts +```css @import '@spectrum-web-components/styles/tokens/global-vars.css'; @import '@spectrum-web-components/styles/tokens/light-vars.css'; @import '@spectrum-web-components/styles/tokens/dark-vars.css'; @@ -215,9 +228,9 @@ For advanced use cases where you need direct access to design token CSS custom p @import '@spectrum-web-components/styles/tokens/large-vars.css'; ``` -### Express tokens +#### Express tokens -```ts +```css @import '@spectrum-web-components/styles/tokens/express/global-vars.css'; @import '@spectrum-web-components/styles/tokens/express/light-vars.css'; @import '@spectrum-web-components/styles/tokens/express/dark-vars.css'; @@ -225,9 +238,9 @@ For advanced use cases where you need direct access to design token CSS custom p @import '@spectrum-web-components/styles/tokens/express/large-vars.css'; ``` -### Spectrum 2 tokens +#### Spectrum 2 tokens -```ts +```css @import '@spectrum-web-components/styles/tokens-v2/global-vars.css'; @import '@spectrum-web-components/styles/tokens-v2/light-vars.css'; @import '@spectrum-web-components/styles/tokens-v2/dark-vars.css'; @@ -235,6 +248,6 @@ For advanced use cases where you need direct access to design token CSS custom p @import '@spectrum-web-components/styles/tokens-v2/large-vars.css'; ``` -## Migrating to Spectrum 2 +### Migrating to Spectrum 2 If you're migrating to Spectrum 2, see the [Spectrum 2 migration guide](../../migrating-to-spectrum2/) for detailed instructions. From 81ec273e168c689bd4d7387114a4db7088ef3ef7 Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Tue, 11 Nov 2025 06:10:39 -0600 Subject: [PATCH 03/16] docs: include tokens in typography examples --- 1st-gen/tools/styles/README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/1st-gen/tools/styles/README.md b/1st-gen/tools/styles/README.md index 8de8c9a71dd..199729b948b 100644 --- a/1st-gen/tools/styles/README.md +++ b/1st-gen/tools/styles/README.md @@ -176,9 +176,11 @@ The [Spectrum Typography system](https://opensource.adobe.com/spectrum-css/?path #### CSS imports -For stylesheet use, import the complete typography system: +For stylesheet use, import the complete typography system, with tokens: ```css +@import '@spectrum-web-components/styles/tokens/index.css'; /* import base tokens */ +@import '@spectrum-web-components/styles/tokens/dark-vars.css'; /* import any theme tokens */ @import '@spectrum-web-components/styles/typography.css'; ``` @@ -189,6 +191,7 @@ For use in Lit-based components, you can import typography styles as JavaScript ##### Import everything ```js +// tokens also need to be imported to define CSS custom properties import typographyStyles from '@spectrum-web-components/styles/typography.js'; static styles = [typographyStyles]; From 5b48b48a444495af6b1cf1f2bb241db1ca9aac8d Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Tue, 11 Nov 2025 06:21:35 -0600 Subject: [PATCH 04/16] docs: move tokens above typography --- 1st-gen/tools/styles/README.md | 68 +++++++++++++++++----------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/1st-gen/tools/styles/README.md b/1st-gen/tools/styles/README.md index 199729b948b..47bb4c811b1 100644 --- a/1st-gen/tools/styles/README.md +++ b/1st-gen/tools/styles/README.md @@ -160,6 +160,40 @@ Import a single scale to set sizing values: +### Design tokens + +For advanced use cases where you need direct access to design token CSS custom properties, this package exposes token files: + +#### Spectrum tokens + +```css +@import '@spectrum-web-components/styles/tokens/global-vars.css'; +@import '@spectrum-web-components/styles/tokens/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/dark-vars.css'; +@import '@spectrum-web-components/styles/tokens/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens/large-vars.css'; +``` + +#### Express tokens + +```css +@import '@spectrum-web-components/styles/tokens/express/global-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/dark-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/large-vars.css'; +``` + +#### Spectrum 2 tokens + +```css +@import '@spectrum-web-components/styles/tokens-v2/global-vars.css'; +@import '@spectrum-web-components/styles/tokens-v2/light-vars.css'; +@import '@spectrum-web-components/styles/tokens-v2/dark-vars.css'; +@import '@spectrum-web-components/styles/tokens-v2/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens-v2/large-vars.css'; +``` + ### Typography The [Spectrum Typography system](https://opensource.adobe.com/spectrum-css/?path=/docs/components-typography--docs) provides a complete set of text styles. The typography system is shared across all design systems (Spectrum, Express, and Spectrum 2). @@ -217,40 +251,6 @@ static styles = [headingStyles]; 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. -### Design tokens - -For advanced use cases where you need direct access to design token CSS custom properties, this package exposes token files: - -#### Spectrum tokens - -```css -@import '@spectrum-web-components/styles/tokens/global-vars.css'; -@import '@spectrum-web-components/styles/tokens/light-vars.css'; -@import '@spectrum-web-components/styles/tokens/dark-vars.css'; -@import '@spectrum-web-components/styles/tokens/medium-vars.css'; -@import '@spectrum-web-components/styles/tokens/large-vars.css'; -``` - -#### Express tokens - -```css -@import '@spectrum-web-components/styles/tokens/express/global-vars.css'; -@import '@spectrum-web-components/styles/tokens/express/light-vars.css'; -@import '@spectrum-web-components/styles/tokens/express/dark-vars.css'; -@import '@spectrum-web-components/styles/tokens/express/medium-vars.css'; -@import '@spectrum-web-components/styles/tokens/express/large-vars.css'; -``` - -#### Spectrum 2 tokens - -```css -@import '@spectrum-web-components/styles/tokens-v2/global-vars.css'; -@import '@spectrum-web-components/styles/tokens-v2/light-vars.css'; -@import '@spectrum-web-components/styles/tokens-v2/dark-vars.css'; -@import '@spectrum-web-components/styles/tokens-v2/medium-vars.css'; -@import '@spectrum-web-components/styles/tokens-v2/large-vars.css'; -``` - ### Migrating to Spectrum 2 If you're migrating to Spectrum 2, see the [Spectrum 2 migration guide](../../migrating-to-spectrum2/) for detailed instructions. From b7ae0990deabac50b39ae7d780a5b24c629e90fc Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Tue, 11 Nov 2025 06:31:19 -0600 Subject: [PATCH 05/16] docs: typography updates --- 1st-gen/tools/styles/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/1st-gen/tools/styles/README.md b/1st-gen/tools/styles/README.md index 47bb4c811b1..db402123f3e 100644 --- a/1st-gen/tools/styles/README.md +++ b/1st-gen/tools/styles/README.md @@ -213,8 +213,9 @@ The [Spectrum Typography system](https://opensource.adobe.com/spectrum-css/?path For stylesheet use, import the complete typography system, with tokens: ```css -@import '@spectrum-web-components/styles/tokens/index.css'; /* import base tokens */ -@import '@spectrum-web-components/styles/tokens/dark-vars.css'; /* import any theme tokens */ +@import '@spectrum-web-components/styles/tokens-v2/dark-vars.css'; /* import color tokens */ +@import '@spectrum-web-components/styles/tokens-v2/large-vars.css'; /* import scale tokens */ +@import '@spectrum-web-components/styles/tokens-v2/global-vars.css'; /* import global tokens */ @import '@spectrum-web-components/styles/typography.css'; ``` From 4171df47bcfac8d2c200a5d24147a06b1fe50585 Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Tue, 11 Nov 2025 15:49:18 -0600 Subject: [PATCH 06/16] docs: update tokens docs --- 1st-gen/tools/styles/README.md | 238 +++++++++++++++------------------ 1 file changed, 111 insertions(+), 127 deletions(-) diff --git a/1st-gen/tools/styles/README.md b/1st-gen/tools/styles/README.md index db402123f3e..575e651bb93 100644 --- a/1st-gen/tools/styles/README.md +++ b/1st-gen/tools/styles/README.md @@ -26,172 +26,146 @@ See the `@spectrum-web-components/theme` [documentation](../theme) for more info yarn add @spectrum-web-components/styles ``` -### System variants +### Design tokens -This package provides styles for three Adobe design system variants (referred to as "systems"). Each system has different available color options: +This package provides design token CSS custom properties for three Adobe design system variants (referred to as "systems"). -- **Spectrum** (system: `spectrum`) - The original Spectrum design system with four color options: `dark`, `light`, and deprecated `darkest` and `lightest` -- **Express** (system: `express`) - The Adobe Express design system with two color options: `dark` and `light` -- **Spectrum 2** (system: `spectrum-two`) - The next generation Spectrum design system with two color options: `dark` and `light` +**Color options:** Each system has different available color options, but in the future, each will have only `dark` and `light` available. -### Combined theme packages (Spectrum) +**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. -If you're not using ``, 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). +**Available systems:** -> **Note:** The `darkest` and `lightest` colors are deprecated and will be removed in a future release. Use `dark` or `light` instead. +- **Spectrum** (system: `spectrum`) - The original Spectrum design system + - **Colors:** `dark`, `light`, and deprecated `darkest` and `lightest` + - **Scales:** `medium`, `large` +- **Express** (system: `express`) - The Adobe Express design system + - **Colors:** `dark`, `light` + - **Scales:** `medium`, `large` +- **Spectrum 2** (system: `spectrum-two`) - The next generation Spectrum design system + - **Colors:** `dark`, `light` + - **Scales:** `medium`, `large` -```css -@import '@spectrum-web-components/styles/all-medium-dark.css'; -``` +#### Spectrum 2 tokens -This file brings together the global variables and font settings with the "Dark" color set and "Medium" scale system specification. +Spectrum 2 uses standalone token files. Pick one color option and one scale option: ```css -@import '@spectrum-web-components/styles/all-medium-light.css'; +/* pick a color option */ +@import '@spectrum-web-components/styles/tokens-v2/light-vars.css'; +/* pick a scale option */ +@import '@spectrum-web-components/styles/tokens-v2/medium-vars.css'; +/* import global custom properties last */ +@import '@spectrum-web-components/styles/tokens-v2/global-vars.css'; ``` -This file brings together the global variables and font settings with the "Light" color set and "Medium" scale system specification. - -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`. - -### Manual theme composition (Express and Spectrum 2) - -If you're not using ``, 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. +#### Spectrum tokens -#### Express example (large, dark) +Spectrum uses a base + override pattern. Import base tokens first, then system-specific overrides: ```css -@import '@spectrum-web-components/styles/express/core-global.css'; -@import '@spectrum-web-components/styles/typography.css'; -@import '@spectrum-web-components/styles/express/theme-dark.css'; -@import '@spectrum-web-components/styles/express/scale-large.css'; +/* import base tokens */ +@import '@spectrum-web-components/styles/tokens/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens/global-vars.css'; + +/* import spectrum-specific overrides */ +@import '@spectrum-web-components/styles/tokens/spectrum/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/spectrum/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens/spectrum/global-vars.css'; ``` -#### Spectrum 2 example (medium, light) +#### Express tokens -```css -@import '@spectrum-web-components/styles/spectrum-two/core-global.css'; -@import '@spectrum-web-components/styles/typography.css'; -@import '@spectrum-web-components/styles/spectrum-two/theme-light.css'; -@import '@spectrum-web-components/styles/spectrum-two/scale-medium.css'; -``` +Express also uses a base + override pattern (same as Spectrum above, but with `express/` paths): -> **Note:** For most use cases, we recommend using `` instead of manually managing these imports. The theme element handles composition and switching automatically. +```css +/* import base tokens */ +@import '@spectrum-web-components/styles/tokens/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens/global-vars.css'; -### Individual theme and scale files +/* import express-specific overrides */ +@import '@spectrum-web-components/styles/tokens/express/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/global-vars.css'; +``` -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. +#### Tokens usage -#### Color +Which tokens files you import will depend on which tokens you want to use. -Import a single color option to set color values: +##### V2 tokens -```css -/* Spectrum */ -@import '@spectrum-web-components/styles/theme-light.css'; +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. -/* Express */ -@import '@spectrum-web-components/styles/express/theme-dark.css'; +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`). -/* Spectrum 2 */ -@import '@spectrum-web-components/styles/spectrum-two/theme-light.css'; -``` +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);`). -##### Available color options - - - - System - Available colors - - - - Spectrum - theme-dark.css, theme-light.css, theme-darkest.css (deprecated), theme-lightest.css (deprecated) - - - Express - express/theme-dark.css, express/theme-light.css - - - Spectrum 2 - spectrum-two/theme-dark.css, spectrum-two/theme-light.css - - - - -> **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. - -#### Scale - -Import a single scale to set sizing values: +Here's one example of tokens usage in a non-web-component context, showing how custom properties from each file work together: ```css -/* Spectrum */ -@import '@spectrum-web-components/styles/scale-medium.css'; - -/* Express */ -@import '@spectrum-web-components/styles/express/scale-medium.css'; +/* import appropriate tokens files */ +@import '@spectrum-web-components/styles/tokens-v2/light-vars.css'; +@import '@spectrum-web-components/styles/tokens-v2/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens-v2/global-vars.css'; -/* Spectrum 2 */ -@import '@spectrum-web-components/styles/spectrum-two/scale-large.css'; +.my-component { + /* defined in global-vars.css */ + border-radius: var(--spectrum-corner-radius-medium-size-small); + border-width: var(--spectrum-border-width-100); + color: var( + --spectrum-neutral-content-color-default + ); /* uses --spectrum-gray-800, which is defined differently depending whether light or dark vars are loaded */ + + /* defined in light-vars.css, defined differently in dark-vars.css */ + background-color: var(--spectrum-gray-100); + border-color: var(--spectrum-gray-800); + + /* defined in medium-vars.css, defined differently in large-vars.css */ + padding-inline: var(--spectrum-component-edge-to-text-75); + padding-block: var(--spectrum-component-top-to-text-75); + min-block-size: var(--spectrum-component-height-75); + + border-style: solid; +} ``` -##### Available scales - - - - System - Available scales - - - - Spectrum - scale-medium.css, scale-large.css - - - Express - express/scale-medium.css, express/scale-large.css - - - Spectrum 2 - spectrum-two/scale-medium.css, spectrum-two/scale-large.css - - - - -### Design tokens - -For advanced use cases where you need direct access to design token CSS custom properties, this package exposes token files: +##### Tokens (base + system overrides pattern) -#### Spectrum tokens +These tokens are generally similar to the V2 tokens, but use a base layer plus system-specific overrides that must both be imported. ```css -@import '@spectrum-web-components/styles/tokens/global-vars.css'; +/* import base tokens files */ @import '@spectrum-web-components/styles/tokens/light-vars.css'; -@import '@spectrum-web-components/styles/tokens/dark-vars.css'; -@import '@spectrum-web-components/styles/tokens/medium-vars.css'; -@import '@spectrum-web-components/styles/tokens/large-vars.css'; -``` - -#### Express tokens +@import '@spectrum-web-components/styles/tokens/global-vars.css'; -```css -@import '@spectrum-web-components/styles/tokens/express/global-vars.css'; -@import '@spectrum-web-components/styles/tokens/express/light-vars.css'; -@import '@spectrum-web-components/styles/tokens/express/dark-vars.css'; +/* import express-specific tokens files (replace express/ with spectrum/ for Spectrum system) */ @import '@spectrum-web-components/styles/tokens/express/medium-vars.css'; -@import '@spectrum-web-components/styles/tokens/express/large-vars.css'; -``` +@import '@spectrum-web-components/styles/tokens/express/global-vars.css'; -#### Spectrum 2 tokens +.my-component { + /* defined in express medium-vars.css */ + border-radius: var(--spectrum-corner-radius-100); -```css -@import '@spectrum-web-components/styles/tokens-v2/global-vars.css'; -@import '@spectrum-web-components/styles/tokens-v2/light-vars.css'; -@import '@spectrum-web-components/styles/tokens-v2/dark-vars.css'; -@import '@spectrum-web-components/styles/tokens-v2/medium-vars.css'; -@import '@spectrum-web-components/styles/tokens-v2/large-vars.css'; + /* defined in base global-vars.css */ + border-width: var(--spectrum-border-width-100); + color: var( + --spectrum-neutral-subdued-content-color-default + ); /* uses --spectrum-gray-700, which is defined differently depending whether light or dark vars are loaded */ + + /* defined in base light-vars.css, defined differently in dark-vars.css */ + background-color: var(--spectrum-gray-50); + border-color: var(--spectrum-gray-700); + + /* defined in base medium-vars.css, defined differently in large-vars.css */ + padding-inline: var(--spectrum-component-edge-to-text-75); + padding-block: var(--spectrum-component-top-to-text-75); + min-block-size: var(--spectrum-component-height-75); + + border-style: solid; +} ``` ### Typography @@ -252,6 +226,16 @@ static styles = [headingStyles]; 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. +### Spectrum Vars tokens (deprecated) + +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`). + +**Recommended alternatives:** + +- Use `` for automatic theme management (recommended) +- Import Spectrum Core tokens directly for granular control (see "Design tokens" section above) +- See the [Spectrum Core tokens migration guide](../theme/core-tokens.md) for help migrating from Spectrum Vars to Spectrum Core tokens + ### Migrating to Spectrum 2 If you're migrating to Spectrum 2, see the [Spectrum 2 migration guide](../../migrating-to-spectrum2/) for detailed instructions. From 602ac19958eb9d16fe546de8a4667860dadc59a5 Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Tue, 11 Nov 2025 06:14:56 -0600 Subject: [PATCH 07/16] chore: add deprecation notice --- 1st-gen/tools/styles/package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/1st-gen/tools/styles/package.json b/1st-gen/tools/styles/package.json index 6921a57bb6c..2819d010b94 100755 --- a/1st-gen/tools/styles/package.json +++ b/1st-gen/tools/styles/package.json @@ -125,6 +125,7 @@ "lit": "^2.5.0 || ^3.1.3" }, "customElements": "custom-elements.json", + "deprecationNotice": "Color 'lightest' and 'darkest' are deprecated. Spectrum Vars token files (all-*.css, theme-*.css, scale-*.css, core-global.css) are deprecated in favor of Spectrum Core tokens. These deprecations will be removed in a future release. See the Spectrum Core tokens migration guide for help migrating.", "sideEffects": [ "./**/*.css" ], From 6586cb27aa64bb4b86f9c78bc7682d4da23e473e Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Tue, 11 Nov 2025 16:04:59 -0600 Subject: [PATCH 08/16] chore: make the linter happy --- 1st-gen/tools/styles/package.json | 98 +++++++++++++++---------------- 1 file changed, 49 insertions(+), 49 deletions(-) diff --git a/1st-gen/tools/styles/package.json b/1st-gen/tools/styles/package.json index 2819d010b94..bdcfd972750 100755 --- a/1st-gen/tools/styles/package.json +++ b/1st-gen/tools/styles/package.json @@ -1,27 +1,21 @@ { "name": "@spectrum-web-components/styles", "version": "1.10.0", - "publishConfig": { - "access": "public" - }, "description": "", "license": "Apache-2.0", + "author": "Adobe", + "homepage": "https://opensource.adobe.com/spectrum-web-components/tools/styles", "repository": { + "directory": "1st-gen/tools/styles", "type": "git", - "url": "https://github.com/adobe/spectrum-web-components.git", - "directory": "1st-gen/tools/styles" + "url": "https://github.com/adobe/spectrum-web-components.git" }, - "author": "Adobe", - "homepage": "https://opensource.adobe.com/spectrum-web-components/tools/styles", "bugs": { "url": "https://github.com/adobe/spectrum-web-components/issues" }, - "main": "./src/index.js", - "module": "./src/index.js", "type": "module", "exports": { ".": "./src/spectrum-base.css.js", - "./package.json": "./package.json", "./all-large-dark.css": "./all-large-dark.css", "./all-large-darkest.css": "./all-large-darkest.css", "./all-large-light.css": "./all-large-light.css", @@ -30,21 +24,6 @@ "./all-medium-darkest.css": "./all-medium-darkest.css", "./all-medium-light.css": "./all-medium-light.css", "./all-medium-lightest.css": "./all-medium-lightest.css", - "./core-global.css": "./core-global.css", - "./express/core-global.css": "./express/core-global.css", - "./scale-large.css": "./scale-large.css", - "./express/scale-large.css": "./express/scale-large.css", - "./scale-medium.css": "./scale-medium.css", - "./express/scale-medium.css": "./express/scale-medium.css", - "./theme-dark.css": "./theme-dark.css", - "./express/theme-dark.css": "./express/theme-dark.css", - "./theme-darkest.css": "./theme-darkest.css", - "./express/theme-darkest.css": "./express/theme-darkest.css", - "./theme-light.css": "./theme-light.css", - "./express/theme-light.css": "./express/theme-light.css", - "./theme-lightest.css": "./theme-lightest.css", - "./express/theme-lightest.css": "./express/theme-lightest.css", - "./typography.css": "./typography.css", "./body.js": { "development": "./body.dev.js", "default": "./body.js" @@ -53,52 +32,67 @@ "development": "./code.dev.js", "default": "./code.js" }, + "./core-global.css": "./core-global.css", "./detail.js": { "development": "./detail.dev.js", "default": "./detail.js" }, + "./express/core-global.css": "./express/core-global.css", + "./express/scale-large.css": "./express/scale-large.css", + "./express/scale-medium.css": "./express/scale-medium.css", + "./express/theme-dark.css": "./express/theme-dark.css", + "./express/theme-darkest.css": "./express/theme-darkest.css", + "./express/theme-light.css": "./express/theme-light.css", + "./express/theme-lightest.css": "./express/theme-lightest.css", "./heading.js": { "development": "./heading.dev.js", "default": "./heading.js" }, - "./typography.js": { - "development": "./typography.dev.js", - "default": "./typography.js" - }, + "./package.json": "./package.json", + "./scale-large.css": "./scale-large.css", + "./scale-medium.css": "./scale-medium.css", + "./src/body-overrides.css": "./src/body-overrides.css", "./src/body-overrides.css.js": "./src/body-overrides.css.js", + "./src/code-overrides.css": "./src/code-overrides.css", "./src/code-overrides.css.js": "./src/code-overrides.css.js", + "./src/detail-overrides.css": "./src/detail-overrides.css", "./src/detail-overrides.css.js": "./src/detail-overrides.css.js", + "./src/heading-overrides.css": "./src/heading-overrides.css", "./src/heading-overrides.css.js": "./src/heading-overrides.css.js", + "./src/lang-overrides.css": "./src/lang-overrides.css", "./src/lang-overrides.css.js": "./src/lang-overrides.css.js", "./src/spectrum-base.css": "./src/spectrum-base.css", "./src/spectrum-body.css": "./src/spectrum-body.css", - "./src/body-overrides.css": "./src/body-overrides.css", "./src/spectrum-code.css": "./src/spectrum-code.css", - "./src/code-overrides.css": "./src/code-overrides.css", "./src/spectrum-detail.css": "./src/spectrum-code.css", - "./src/detail-overrides.css": "./src/detail-overrides.css", "./src/spectrum-heading.css": "./src/spectrum-heading.css", - "./src/heading-overrides.css": "./src/heading-overrides.css", "./src/spectrum-lang.css": "./src/spectrum-lang.css", - "./src/lang-overrides.css": "./src/lang-overrides.css", "./src/spectrum-typography.css": "./src/spectrum-typography.css", - "./tokens/*": "./tokens/*", + "./theme-dark.css": "./theme-dark.css", + "./theme-darkest.css": "./theme-darkest.css", + "./theme-light.css": "./theme-light.css", + "./theme-lightest.css": "./theme-lightest.css", "./tokens-v2/*": "./tokens-v2/*", + "./tokens-v2/spectrum/custom-dark-vars.css": "./tokens-v2/dark-vars.css", + "./tokens-v2/spectrum/custom-large-vars.css": "./tokens-v2/large-vars.css", + "./tokens-v2/spectrum/custom-light-vars.css": "./tokens-v2/light-vars.css", + "./tokens-v2/spectrum/custom-medium-vars.css": "./tokens-v2/medium-vars.css", + "./tokens-v2/spectrum/custom-vars.css": "./tokens-v2/global-vars.css", + "./tokens/*": "./tokens/*", "./tokens/express/custom-large-vars.css": "./tokens/express/large-vars.css", "./tokens/express/custom-medium-vars.css": "./tokens/express/medium-vars.css", "./tokens/express/custom-vars.css": "./tokens/express/global-vars.css", "./tokens/spectrum/custom-large-vars.css": "./tokens/spectrum/large-vars.css", "./tokens/spectrum/custom-medium-vars.css": "./tokens/spectrum/medium-vars.css", "./tokens/spectrum/custom-vars.css": "./tokens/spectrum/global-vars.css", - "./tokens-v2/spectrum/custom-large-vars.css": "./tokens-v2/large-vars.css", - "./tokens-v2/spectrum/custom-medium-vars.css": "./tokens-v2/medium-vars.css", - "./tokens-v2/spectrum/custom-vars.css": "./tokens-v2/global-vars.css", - "./tokens-v2/spectrum/custom-dark-vars.css": "./tokens-v2/dark-vars.css", - "./tokens-v2/spectrum/custom-light-vars.css": "./tokens-v2/light-vars.css" - }, - "scripts": { - "test": "echo \"Error: run tests from mono-repo root.\" && exit 1" + "./typography.css": "./typography.css", + "./typography.js": { + "development": "./typography.dev.js", + "default": "./typography.js" + } }, + "main": "./src/index.js", + "module": "./src/index.js", "files": [ "**/*.css", "**/*.d.ts", @@ -108,6 +102,16 @@ "!stories/", "!test/" ], + "scripts": { + "test": "echo \"Error: run tests from mono-repo root.\" && exit 1" + }, + "sideEffects": [ + "./**/*.css" + ], + "dependencies": { + "@spectrum-web-components/base": "1.10.0", + "lit": "^2.5.0 || ^3.1.3" + }, "keywords": [ "design-system", "spectrum", @@ -120,14 +124,10 @@ "component", "css" ], - "dependencies": { - "@spectrum-web-components/base": "1.10.0", - "lit": "^2.5.0 || ^3.1.3" + "publishConfig": { + "access": "public" }, "customElements": "custom-elements.json", "deprecationNotice": "Color 'lightest' and 'darkest' are deprecated. Spectrum Vars token files (all-*.css, theme-*.css, scale-*.css, core-global.css) are deprecated in favor of Spectrum Core tokens. These deprecations will be removed in a future release. See the Spectrum Core tokens migration guide for help migrating.", - "sideEffects": [ - "./**/*.css" - ], "style": "all-medium-lightest.css" } From 41430b4ae355b117b3243e522206f7e1ad4a5bc8 Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Wed, 12 Nov 2025 11:31:29 -0600 Subject: [PATCH 09/16] docs: pr fixes - Indentation fixes - Core tokens link fix - Use "Spectrum 2 tokens" rather than "v2-tokens" or "tokens-v2" - Adjust imports and comments in example --- 1st-gen/tools/styles/README.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/1st-gen/tools/styles/README.md b/1st-gen/tools/styles/README.md index 575e651bb93..4b359cae33b 100644 --- a/1st-gen/tools/styles/README.md +++ b/1st-gen/tools/styles/README.md @@ -95,9 +95,9 @@ Express also uses a base + override pattern (same as Spectrum above, but with `e Which tokens files you import will depend on which tokens you want to use. -##### V2 tokens +##### Spectrum 2 tokens (tokens-v2) -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. +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 Spectrum 2 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. 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`). @@ -139,6 +139,7 @@ These tokens are generally similar to the V2 tokens, but use a base layer plus s ```css /* import base tokens files */ @import '@spectrum-web-components/styles/tokens/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/medium-vars.css'; @import '@spectrum-web-components/styles/tokens/global-vars.css'; /* import express-specific tokens files (replace express/ with spectrum/ for Spectrum system) */ @@ -149,8 +150,10 @@ These tokens are generally similar to the V2 tokens, but use a base layer plus s /* defined in express medium-vars.css */ border-radius: var(--spectrum-corner-radius-100); - /* defined in base global-vars.css */ + /* defined in express global-vars.css */ border-width: var(--spectrum-border-width-100); + + /* defined in base global-vars.css */ color: var( --spectrum-neutral-subdued-content-color-default ); /* uses --spectrum-gray-700, which is defined differently depending whether light or dark vars are loaded */ @@ -234,7 +237,7 @@ This package includes some deprecated files that use the older Spectrum Vars tok - Use `` for automatic theme management (recommended) - Import Spectrum Core tokens directly for granular control (see "Design tokens" section above) -- See the [Spectrum Core tokens migration guide](../theme/core-tokens.md) for help migrating from Spectrum Vars to Spectrum Core tokens +- See the [Spectrum Core tokens migration guide](../core-tokens) for help migrating from Spectrum Vars to Spectrum Core tokens ### Migrating to Spectrum 2 From 8d6c8eb6203dd0560996fbf51f3fec2072e0a16c Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Wed, 12 Nov 2025 12:04:11 -0600 Subject: [PATCH 10/16] docs: use tabs instead of h5s --- 1st-gen/tools/styles/README.md | 69 ++++++++++++++++++++++++++-------- 1 file changed, 53 insertions(+), 16 deletions(-) diff --git a/1st-gen/tools/styles/README.md b/1st-gen/tools/styles/README.md index 4b359cae33b..c1a9788dea8 100644 --- a/1st-gen/tools/styles/README.md +++ b/1st-gen/tools/styles/README.md @@ -95,7 +95,9 @@ Express also uses a base + override pattern (same as Spectrum above, but with `e Which tokens files you import will depend on which tokens you want to use. -##### Spectrum 2 tokens (tokens-v2) + +Spectrum 2 tokens (tokens-v2) + 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 Spectrum 2 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. @@ -132,9 +134,11 @@ Here's one example of tokens usage in a non-web-component context, showing how c } ``` -##### Tokens (base + system overrides pattern) + +Tokens (base + system overrides pattern) + -These tokens are generally similar to the V2 tokens, but use a base layer plus system-specific overrides that must both be imported. +These tokens are generally similar to the Spectrum 2 tokens, but use a base layer plus system-specific overrides that must both be imported. ```css /* import base tokens files */ @@ -171,6 +175,9 @@ These tokens are generally similar to the V2 tokens, but use a base layer plus s } ``` + + + ### Typography The [Spectrum Typography system](https://opensource.adobe.com/spectrum-css/?path=/docs/components-typography--docs) provides a complete set of text styles. The typography system is shared across all design systems (Spectrum, Express, and Spectrum 2). @@ -187,6 +194,10 @@ The [Spectrum Typography system](https://opensource.adobe.com/spectrum-css/?path #### CSS imports + +Import everything + + For stylesheet use, import the complete typography system, with tokens: ```css @@ -196,11 +207,41 @@ For stylesheet use, import the complete typography system, with tokens: @import '@spectrum-web-components/styles/typography.css'; ``` -#### TypeScript/JavaScript exports for Lit components + +Import only what you need + + +You can also import only the typography elements that you need: + +```css +/* tokens also need to be imported to define CSS custom properties */ +@import '@spectrum-web-components/styles/src/spectrum-heading.css'; +``` + + + + +#### TypeScript/JavaScript imports for Lit components + +For use in Lit-based components, you can import typography styles as JavaScript modules. + +Available JavaScript exports include: + +- **`typography.js`** - Complete typography system with all styles (heading, body, detail, code) +- **`body.js`** - Body text styles only (includes base + lang + body) +- **`heading.js`** - Heading styles only (includes base + lang + heading) +- **`detail.js`** - Detail/label styles only (includes base + lang + detail) +- **`code.js`** - Code styles only (includes base + lang + code) + +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. -For use in Lit-based components, you can import typography styles as JavaScript modules. Import the complete system or individual components depending on your needs: +Import the complete system or individual components depending on your needs: -##### Import everything + +Import everything + + +To import the full typography system: ```js // tokens also need to be imported to define CSS custom properties @@ -209,25 +250,21 @@ import typographyStyles from '@spectrum-web-components/styles/typography.js'; static styles = [typographyStyles]; ``` -##### Import only what you need + +Import only what you need + For smaller bundle sizes, import individual components: ```js +// tokens also need to be imported to define CSS custom properties import headingStyles from '@spectrum-web-components/styles/heading.js'; static styles = [headingStyles]; ``` -##### Available JavaScript exports - -- **`typography.js`** - Complete typography system with all styles (heading, body, detail, code) -- **`body.js`** - Body text styles only (includes base + lang + body) -- **`heading.js`** - Heading styles only (includes base + lang + heading) -- **`detail.js`** - Detail/label styles only (includes base + lang + detail) -- **`code.js`** - Code styles only (includes base + lang + code) - -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. + + ### Spectrum Vars tokens (deprecated) From c2a2e4efcf87a2f2feb7ed4c5a46a12c1e1f6157 Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Wed, 12 Nov 2025 12:30:35 -0600 Subject: [PATCH 11/16] docs: update typography guidance --- 1st-gen/tools/styles/README.md | 21 ++------------------- 1 file changed, 2 insertions(+), 19 deletions(-) diff --git a/1st-gen/tools/styles/README.md b/1st-gen/tools/styles/README.md index c1a9788dea8..11603f174f7 100644 --- a/1st-gen/tools/styles/README.md +++ b/1st-gen/tools/styles/README.md @@ -184,6 +184,7 @@ The [Spectrum Typography system](https://opensource.adobe.com/spectrum-css/?path #### What's included +- **Typography wrapper** (`.spectrum-Typography`) - Wrap your content with this class to apply proper spacing, margins, and base font settings to typography elements - **Heading** styles (`.spectrum-Heading`) - Multiple sizes from XXS to XXXL with weight variants (light, regular, heavy) and serif options - **Body** styles (`.spectrum-Body`) - Multiple sizes from XS to XXXL with serif options for body copy and longer text - **Detail** styles (`.spectrum-Detail`) - Uppercase labels and metadata text in sizes S through XL with light weight option @@ -194,11 +195,7 @@ The [Spectrum Typography system](https://opensource.adobe.com/spectrum-css/?path #### CSS imports - -Import everything - - -For stylesheet use, import the complete typography system, with tokens: +For stylesheet use, the recommended approach is to import the complete typography system, with tokens. This ensures that all required files are included. ```css @import '@spectrum-web-components/styles/tokens-v2/dark-vars.css'; /* import color tokens */ @@ -207,20 +204,6 @@ For stylesheet use, import the complete typography system, with tokens: @import '@spectrum-web-components/styles/typography.css'; ``` - -Import only what you need - - -You can also import only the typography elements that you need: - -```css -/* tokens also need to be imported to define CSS custom properties */ -@import '@spectrum-web-components/styles/src/spectrum-heading.css'; -``` - - - - #### TypeScript/JavaScript imports for Lit components For use in Lit-based components, you can import typography styles as JavaScript modules. From d23fffa721f1700abb72bee0d82230d8e20222de Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Wed, 12 Nov 2025 12:31:12 -0600 Subject: [PATCH 12/16] chore: correct package exports order for token wildcards --- 1st-gen/tools/styles/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/1st-gen/tools/styles/package.json b/1st-gen/tools/styles/package.json index bdcfd972750..b7393acd924 100755 --- a/1st-gen/tools/styles/package.json +++ b/1st-gen/tools/styles/package.json @@ -72,19 +72,19 @@ "./theme-darkest.css": "./theme-darkest.css", "./theme-light.css": "./theme-light.css", "./theme-lightest.css": "./theme-lightest.css", - "./tokens-v2/*": "./tokens-v2/*", "./tokens-v2/spectrum/custom-dark-vars.css": "./tokens-v2/dark-vars.css", "./tokens-v2/spectrum/custom-large-vars.css": "./tokens-v2/large-vars.css", "./tokens-v2/spectrum/custom-light-vars.css": "./tokens-v2/light-vars.css", "./tokens-v2/spectrum/custom-medium-vars.css": "./tokens-v2/medium-vars.css", "./tokens-v2/spectrum/custom-vars.css": "./tokens-v2/global-vars.css", - "./tokens/*": "./tokens/*", + "./tokens-v2/*": "./tokens-v2/*", "./tokens/express/custom-large-vars.css": "./tokens/express/large-vars.css", "./tokens/express/custom-medium-vars.css": "./tokens/express/medium-vars.css", "./tokens/express/custom-vars.css": "./tokens/express/global-vars.css", "./tokens/spectrum/custom-large-vars.css": "./tokens/spectrum/large-vars.css", "./tokens/spectrum/custom-medium-vars.css": "./tokens/spectrum/medium-vars.css", "./tokens/spectrum/custom-vars.css": "./tokens/spectrum/global-vars.css", + "./tokens/*": "./tokens/*", "./typography.css": "./typography.css", "./typography.js": { "development": "./typography.dev.js", From 7ddd70093d2ee6c27d42a723b5d16ee2c67d6f3b Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Wed, 12 Nov 2025 12:36:33 -0600 Subject: [PATCH 13/16] Revert "chore: correct package exports order for token wildcards" This reverts commit 6a63a69eebb42f879ac3bc2870430c49d1a5dc15. --- 1st-gen/tools/styles/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/1st-gen/tools/styles/package.json b/1st-gen/tools/styles/package.json index b7393acd924..bdcfd972750 100755 --- a/1st-gen/tools/styles/package.json +++ b/1st-gen/tools/styles/package.json @@ -72,19 +72,19 @@ "./theme-darkest.css": "./theme-darkest.css", "./theme-light.css": "./theme-light.css", "./theme-lightest.css": "./theme-lightest.css", + "./tokens-v2/*": "./tokens-v2/*", "./tokens-v2/spectrum/custom-dark-vars.css": "./tokens-v2/dark-vars.css", "./tokens-v2/spectrum/custom-large-vars.css": "./tokens-v2/large-vars.css", "./tokens-v2/spectrum/custom-light-vars.css": "./tokens-v2/light-vars.css", "./tokens-v2/spectrum/custom-medium-vars.css": "./tokens-v2/medium-vars.css", "./tokens-v2/spectrum/custom-vars.css": "./tokens-v2/global-vars.css", - "./tokens-v2/*": "./tokens-v2/*", + "./tokens/*": "./tokens/*", "./tokens/express/custom-large-vars.css": "./tokens/express/large-vars.css", "./tokens/express/custom-medium-vars.css": "./tokens/express/medium-vars.css", "./tokens/express/custom-vars.css": "./tokens/express/global-vars.css", "./tokens/spectrum/custom-large-vars.css": "./tokens/spectrum/large-vars.css", "./tokens/spectrum/custom-medium-vars.css": "./tokens/spectrum/medium-vars.css", "./tokens/spectrum/custom-vars.css": "./tokens/spectrum/global-vars.css", - "./tokens/*": "./tokens/*", "./typography.css": "./typography.css", "./typography.js": { "development": "./typography.dev.js", From 0e205c1cebd8e4362bf2a4d07da3f2e75ede9310 Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Thu, 20 Nov 2025 15:26:23 -0600 Subject: [PATCH 14/16] docs: rework organization --- 1st-gen/tools/styles/README.md | 128 +++++++++++++++++++++++++-------- 1 file changed, 100 insertions(+), 28 deletions(-) diff --git a/1st-gen/tools/styles/README.md b/1st-gen/tools/styles/README.md index 11603f174f7..844d3720fe2 100644 --- a/1st-gen/tools/styles/README.md +++ b/1st-gen/tools/styles/README.md @@ -28,27 +28,98 @@ yarn add @spectrum-web-components/styles ### Design tokens -This package provides design token CSS custom properties for three Adobe design system variants (referred to as "systems"). +This package provides design token CSS custom properties for three Adobe design system variants (referred to as "systems"). These tokens are organized by system, as well as color option and scale. There is also a set of global tokens for each system that do not vary with color option or scale. + +#### Global tokens + +Global token files (`global-vars.css`) define design values that remain constant across color options and scales, as well as semantic tokens that reference color- or scale-specific values: + +- **Fixed constants** - Values that never change regardless of color or scale: + - Opacity values (e.g., `--spectrum-opacity-disabled: 0.3`) + - Font families (Adobe Clean, for instance) + - Font weights (300, 400, 500, 700, 800, 900) + - Line heights and font styles + - Transparent white and black color definitions + - Base spacing scale (`--spectrum-spacing-50` through `--spectrum-spacing-1000`) + - Semantically-named component constants (e.g., `--spectrum-swatch-border-color`, `--spectrum-button-minimum-width-multiplier`) + +- **Semantic color aliases** - Named by purpose, referencing values that change depending on the color option: + - `--spectrum-disabled-background-color` (in tokens-v2, references `--spectrum-gray-100`, which has different values for light and dark) + - `--spectrum-focus-indicator-color` + - `--spectrum-neutral-content-color-default` + +- **Semantic component tokens** - Named by purpose, referencing scale-specific values: + - `--spectrum-breadcrumbs-height: var(--spectrum-component-height-300)` (where `component-height-300` is 48px in medium, 60px in large) + - `--spectrum-meter-default-width: var(--spectrum-meter-width)` (where `meter-width` is 192px in medium, 240px in large) + +#### Color options + +Each system makes a `dark` and `light` color option available. Currently, the Spectrum system also offers `darkest` and `lightest` color options, but these will be deprecated in the future. + +Color option files (`light-vars.css` and `dark-vars.css`) contain raw color definitions that differ between themes, as well as semantic color mappings that reference different colors based on the selected theme: + +- **Raw color definitions** - Color scale values that differ between light and dark themes: + - `--spectrum-gray-50` is white (`255, 255, 255`) in light theme, but dark gray (`29, 29, 29`) in dark theme + - `--spectrum-gray-900` is black (`0, 0, 0`) in light theme, but white (`255, 255, 255`) in dark theme + - Full color scales for gray, blue, red, orange, yellow, green, and other semantic color families + +- **Semantic color mappings** - Named by purpose, referencing different raw colors based on theme: + - `--spectrum-background-base-color` references `--spectrum-gray-200` in light, but `--spectrum-gray-50` in dark + - `--spectrum-neutral-subdued-background-color-default` references `--spectrum-gray-600` in light, but `--spectrum-gray-400` in dark + - Component-specific colors like `--spectrum-neutral-visual-color`, background colors, and visual indicators + +#### Scales + +Each system has two scale sizes available: `medium` (default) and `large`. The `medium` scale is designed for desktop environments, while `large` is optimized for mobile and touch devices with larger touch targets. Scale files (`medium-vars.css` and `large-vars.css`) contain raw size and spacing definitions that differ between scales, as well as component-specific sizing values: + +- **Raw size and spacing definitions** - Values that differ between medium and large scales: + - `--spectrum-font-size-200` is `16px` in medium, but `19px` in large + - `--spectrum-component-height-100` is `32px` in medium, but `40px` in large + - Icon sizes, spacing values, and other dimensional tokens that scale up for larger/touch interfaces + +- **Component-specific sizing** - Tokens for component dimensions that vary by scale: + - `--spectrum-meter-width` is `192px` in medium, but `240px` in large + - `--spectrum-breadcrumbs-height-multiline` is `72px` in medium, but `84px` in large + - Component-specific measurements like button heights, field widths, and icon positioning + +#### Available systems + +Here is a summary of each system and the options available on each: + + + + System + Scales + Color options + + + + Spectrum + medium, large + light, dark, lightest, darkest + + + Express + medium, large + light, dark + + + Spectrum 2 + medium, large + light, dark + + + + +#### Tokens imports + +Here are some examples of CSS token imports for each of the three systems: -**Color options:** Each system has different available color options, but in the future, each will have only `dark` and `light` available. - -**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. - -**Available systems:** - -- **Spectrum** (system: `spectrum`) - The original Spectrum design system - - **Colors:** `dark`, `light`, and deprecated `darkest` and `lightest` - - **Scales:** `medium`, `large` -- **Express** (system: `express`) - The Adobe Express design system - - **Colors:** `dark`, `light` - - **Scales:** `medium`, `large` -- **Spectrum 2** (system: `spectrum-two`) - The next generation Spectrum design system - - **Colors:** `dark`, `light` - - **Scales:** `medium`, `large` - -#### Spectrum 2 tokens + +Spectrum 2 tokens (tokens-v2) + -Spectrum 2 uses standalone token files. Pick one color option and one scale option: +Spectrum 2 uses standalone token files (in contrast to Spectrum and Express's base + override pattern). Pick one color option and one scale option: ```css /* pick a color option */ @@ -59,7 +130,9 @@ Spectrum 2 uses standalone token files. Pick one color option and one scale opti @import '@spectrum-web-components/styles/tokens-v2/global-vars.css'; ``` -#### Spectrum tokens + +Spectrum tokens + Spectrum uses a base + override pattern. Import base tokens first, then system-specific overrides: @@ -75,9 +148,11 @@ Spectrum uses a base + override pattern. Import base tokens first, then system-s @import '@spectrum-web-components/styles/tokens/spectrum/global-vars.css'; ``` -#### Express tokens + +Express tokens + -Express also uses a base + override pattern (same as Spectrum above, but with `express/` paths): +Express also uses a base + override pattern (same as Spectrum, but with `express/` paths): ```css /* import base tokens */ @@ -91,6 +166,9 @@ Express also uses a base + override pattern (same as Spectrum above, but with `e @import '@spectrum-web-components/styles/tokens/express/global-vars.css'; ``` + + + #### Tokens usage Which tokens files you import will depend on which tokens you want to use. @@ -99,12 +177,6 @@ Which tokens files you import will depend on which tokens you want to use. Spectrum 2 tokens (tokens-v2) -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 Spectrum 2 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. - -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`). - -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);`). - Here's one example of tokens usage in a non-web-component context, showing how custom properties from each file work together: ```css From f2939d574bc5c2be0d06b11961bd704cd3530f80 Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Thu, 20 Nov 2025 15:52:19 -0600 Subject: [PATCH 15/16] docs: eliminate available options table --- 1st-gen/tools/styles/README.md | 85 ++++++++++++++++++---------------- 1 file changed, 45 insertions(+), 40 deletions(-) diff --git a/1st-gen/tools/styles/README.md b/1st-gen/tools/styles/README.md index 844d3720fe2..1f69c9c3641 100644 --- a/1st-gen/tools/styles/README.md +++ b/1st-gen/tools/styles/README.md @@ -82,36 +82,7 @@ Each system has two scale sizes available: `medium` (default) and `large`. The ` - `--spectrum-breadcrumbs-height-multiline` is `72px` in medium, but `84px` in large - Component-specific measurements like button heights, field widths, and icon positioning -#### Available systems - -Here is a summary of each system and the options available on each: - - - - System - Scales - Color options - - - - Spectrum - medium, large - light, dark, lightest, darkest - - - Express - medium, large - light, dark - - - Spectrum 2 - medium, large - light, dark - - - - -#### Tokens imports +#### Token imports Here are some examples of CSS token imports for each of the three systems: @@ -122,10 +93,14 @@ Here are some examples of CSS token imports for each of the three systems: Spectrum 2 uses standalone token files (in contrast to Spectrum and Express's base + override pattern). Pick one color option and one scale option: ```css -/* pick a color option */ +/* pick a color option from: */ @import '@spectrum-web-components/styles/tokens-v2/light-vars.css'; -/* pick a scale option */ +@import '@spectrum-web-components/styles/tokens-v2/dark-vars.css'; + +/* pick a scale option from: */ @import '@spectrum-web-components/styles/tokens-v2/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens-v2/large-vars.css'; + /* import global custom properties last */ @import '@spectrum-web-components/styles/tokens-v2/global-vars.css'; ``` @@ -137,14 +112,30 @@ Spectrum 2 uses standalone token files (in contrast to Spectrum and Express's ba Spectrum uses a base + override pattern. Import base tokens first, then system-specific overrides: ```css -/* import base tokens */ +/* import a color option from base tokens: */ @import '@spectrum-web-components/styles/tokens/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/lightest-vars.css'; +@import '@spectrum-web-components/styles/tokens/dark-vars.css'; +@import '@spectrum-web-components/styles/tokens/darkest-vars.css'; + +/* import a scale option from base tokens: */ @import '@spectrum-web-components/styles/tokens/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens/large-vars.css'; + +/* import global base tokens: */ @import '@spectrum-web-components/styles/tokens/global-vars.css'; -/* import spectrum-specific overrides */ +/* import a color option from spectrum-specific overrides: */ @import '@spectrum-web-components/styles/tokens/spectrum/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/spectrum/lightest-vars.css'; +@import '@spectrum-web-components/styles/tokens/spectrum/dark-vars.css'; +@import '@spectrum-web-components/styles/tokens/spectrum/darkest-vars.css'; + +/* import a scale option from spectrum-specific overrides: */ @import '@spectrum-web-components/styles/tokens/spectrum/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens/spectrum/large-vars.css'; + +/* import global spectrum-specific overrides: */ @import '@spectrum-web-components/styles/tokens/spectrum/global-vars.css'; ``` @@ -155,30 +146,44 @@ Spectrum uses a base + override pattern. Import base tokens first, then system-s Express also uses a base + override pattern (same as Spectrum, but with `express/` paths): ```css -/* import base tokens */ +/* import a color option from base tokens: */ @import '@spectrum-web-components/styles/tokens/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/lightest-vars.css'; +@import '@spectrum-web-components/styles/tokens/dark-vars.css'; +@import '@spectrum-web-components/styles/tokens/darkest-vars.css'; + +/* import a scale option from base tokens: */ @import '@spectrum-web-components/styles/tokens/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens/large-vars.css'; + +/* import global base tokens: */ @import '@spectrum-web-components/styles/tokens/global-vars.css'; -/* import express-specific overrides */ +/* import a color option from spectrum-specific overrides: */ @import '@spectrum-web-components/styles/tokens/express/light-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/lightest-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/dark-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/darkest-vars.css'; + +/* import a scale option from spectrum-specific overrides: */ @import '@spectrum-web-components/styles/tokens/express/medium-vars.css'; +@import '@spectrum-web-components/styles/tokens/express/large-vars.css'; + +/* import global spectrum-specific overrides: */ @import '@spectrum-web-components/styles/tokens/express/global-vars.css'; ``` -#### Tokens usage +#### Token usage example -Which tokens files you import will depend on which tokens you want to use. +Which tokens files you import will depend on which tokens you want to use. Here's one example of tokens usage in a non-web-component context, showing how custom properties from each file work together. This will vary slightly depending on which system's tokens are being used. Spectrum 2 tokens (tokens-v2) -Here's one example of tokens usage in a non-web-component context, showing how custom properties from each file work together: - ```css /* import appropriate tokens files */ @import '@spectrum-web-components/styles/tokens-v2/light-vars.css'; From b78c1f37804218fe1551a27bb6b8bf910a033df5 Mon Sep 17 00:00:00 2001 From: Rise Erpelding Date: Thu, 20 Nov 2025 15:53:01 -0600 Subject: [PATCH 16/16] chore: change mapped typography path --- 1st-gen/tools/styles/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/1st-gen/tools/styles/package.json b/1st-gen/tools/styles/package.json index bdcfd972750..cd55cb611ff 100755 --- a/1st-gen/tools/styles/package.json +++ b/1st-gen/tools/styles/package.json @@ -64,7 +64,7 @@ "./src/spectrum-base.css": "./src/spectrum-base.css", "./src/spectrum-body.css": "./src/spectrum-body.css", "./src/spectrum-code.css": "./src/spectrum-code.css", - "./src/spectrum-detail.css": "./src/spectrum-code.css", + "./src/spectrum-detail.css": "./src/spectrum-detail.css", "./src/spectrum-heading.css": "./src/spectrum-heading.css", "./src/spectrum-lang.css": "./src/spectrum-lang.css", "./src/spectrum-typography.css": "./src/spectrum-typography.css",