From 93881db4e912b5533a7b5c57a153189a3cd1439d Mon Sep 17 00:00:00 2001 From: TarunAdobe Date: Tue, 28 Oct 2025 16:04:44 +0530 Subject: [PATCH 1/6] chore: update theme docs --- tools/reactive-controllers/README.md | 16 +- .../system-context-resolution.md | 62 +++ tools/theme/README.md | 398 ++++++------------ 3 files changed, 191 insertions(+), 285 deletions(-) create mode 100644 tools/reactive-controllers/system-context-resolution.md diff --git a/tools/reactive-controllers/README.md b/tools/reactive-controllers/README.md index 98d8609685d..537cfaab9fd 100644 --- a/tools/reactive-controllers/README.md +++ b/tools/reactive-controllers/README.md @@ -4,11 +4,11 @@ ### Reactive controllers -- [ColorController](../color-controller) -- [ElementResolutionController](../element-resolution) -- FocusGroupController -- LanguageResolutionController -- [MatchMediaController](../match-media) -- [RovingTabindexController](../roving-tab-index) -- [PendingStateController](../pending-state) -- SystemContextResolutionController +- [ColorController](../color-controller) +- [ElementResolutionController](../element-resolution) +- FocusGroupController +- LanguageResolutionController +- [MatchMediaController](../match-media) +- [RovingTabindexController](../roving-tab-index) +- [PendingStateController](../pending-state) +- [SystemContextResolutionController](../system-context-resolution) diff --git a/tools/reactive-controllers/system-context-resolution.md b/tools/reactive-controllers/system-context-resolution.md new file mode 100644 index 00000000000..6b737382069 --- /dev/null +++ b/tools/reactive-controllers/system-context-resolution.md @@ -0,0 +1,62 @@ +## Description + +System context (private beta API — subject to change) + +The `` element provides a private beta “system” context. Components can consume it via a controller that resolves the current system (e.g. `spectrum`, `express`, `spectrum-two`) and notifies on change. + +### Usage + +[![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/reactive-controllers?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/reactive-controllers) +[![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/reactive-controllers?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/reactive-controllers) + +``` +yarn add @spectrum-web-components/reactive-controllers +``` + +Import the controller and symbol via: + +``` +import { + SystemResolutionController, + systemResolverUpdatedSymbol, +} from '@spectrum-web-components/reactive-controllers/src/SystemContextResolution.js'; +import type { SystemVariant } from '@spectrum-web-components/theme'; +``` + +## Example + +Consume the system context and respond to updates in a LitElement host: + +```js +import { html, LitElement } from 'lit'; +import { + SystemResolutionController, + systemResolverUpdatedSymbol, +} from '@spectrum-web-components/reactive-controllers/src/SystemContextResolution.js'; + +class MyComponent extends LitElement { + systemResolver = new SystemResolutionController(this); + + protected update(changes) { + super.update(changes); + if (changes.has(systemResolverUpdatedSymbol)) { + this.handleSystemChange(); + } + } + + handleSystemChange() { + const currentSystem = this.systemResolver.system; // "spectrum" | "express" | "spectrum-two" + // react to system updates: adjust styles, state, or rendering + } + + render() { + return html`Current system: ${this.systemResolver.system}`; + } +} +``` + +## Notes + +- This is a private beta API and may change. +- If no `` is present, `system` remains `"spectrum"` until a provider appears. +- Pair with explicit `` to avoid fallback behavior and ensure predictable theming. diff --git a/tools/theme/README.md b/tools/theme/README.md index c4d0ca9cbe8..5bdaddf0a77 100644 --- a/tools/theme/README.md +++ b/tools/theme/README.md @@ -1,271 +1,99 @@ -## Description +## Overview -`sp-theme` applies a Spectrum theme by using CSS custom properties to set default sizes & colors for all of the components in its scope. The Spectrum design system provides four color themes (`lightest`, `light`, `dark`, and `darkest`) and two different scales (`medium` and `large`) to support desktop & mobile UI. +`` provides Spectrum design tokens (CSS custom properties) to everything in its DOM scope. Components inside a theme use these tokens to render correctly. The element itself does not visually “apply” styles to your app; it exposes the tokens so your components (and any of your CSS) can consume them. + +Spectrum offers multiple variants: + +- **System**: `spectrum`, `express`, `spectrum-two` +- **Color**: `light`, `dark` (legacy: `lightest`, `darkest` – deprecated) +- **Scale**: `medium`, `large` ### Usage [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/theme?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/theme) [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/theme?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/theme) -``` +```bash yarn add @spectrum-web-components/theme ``` -#### Quick start +Register the element and load the theme fragments you intend to use: -``` +```js import '@spectrum-web-components/theme/sp-theme.js'; -import '@spectrum-web-components/theme/src/themes.js'; -``` - -The above import statements do two things: the first will get you started using the `` wrapper element, and the second includes all four (4) color options (`lightest`, `light`, `dark`, and `darkest`) and both (2) scale options (`medium` and `large`) for the Spectrum Classic theme. Having all of these options available together is the easiest way to get a handle on the theming possibilities offered by the package and empowers you to prototype and test various deliveries of your application. However, reserving the download and parse time for all of the variants may not be required for all applications. See the "Advanced usage" section below for instructions on tuning the performance of an application that leverages this package. - -Below are more ways to import the different scale and color options individually, in case you didn't want to import all of them as we did above. You'll use these statements in combination with the side effectful registration import statement `import '@spectrum-web-components/theme/sp-theme.js'`. - -The various Classic themes can be imported en masse, as in the example above: - -``` -import '@spectrum-web-components/theme/src/themes.js'; -``` -The various Spectrum Express themes can also be imported en masse: - -``` -import '@spectrum-web-components/theme/src/express/themes.js'; -``` - -Or you can import the themes and scales individually: - -``` -import '@spectrum-web-components/theme/theme-darkest.js'; -import '@spectrum-web-components/theme/theme-dark.js'; +// Load the specific variants you will use (recommended) import '@spectrum-web-components/theme/theme-light.js'; -import '@spectrum-web-components/theme/theme-lightest.js'; import '@spectrum-web-components/theme/scale-medium.js'; -import '@spectrum-web-components/theme/scale-large.js'; -import '@spectrum-web-components/theme/express/theme-darkest.js'; -import '@spectrum-web-components/theme/express/theme-dark.js'; -import '@spectrum-web-components/theme/express/theme-light.js'; -import '@spectrum-web-components/theme/express/theme-lightest.js'; -import '@spectrum-web-components/theme/express/scale-medium.js'; -import '@spectrum-web-components/theme/express/scale-large.js'; -``` - -When looking to leverage the `Theme` base class as a type and/or for extension purposes, do so via: - -``` -import { Theme } from '@spectrum-web-components/theme'; -``` - -## What it's doing - -Visually, all Spectrum Web Components are an expression of the design tokens specified by Spectrum, Adobe's design system. On the web, these tokens are made available as CSS Custom Properties. Using `sp-theme` as a parent element for your components ensures that those CSS Custom Properties can be leveraged by the elements within your application. This ensures consistent delivery of not only the color and scale you've specified in your particular instance, but for _all_ the other color, scale, and content direction specifications across Spectrum. - -Additionally, the `sp-theme` element manages the content direction applied to the elements in its DOM scope. By default, an `sp-theme` element resolves its initial content direction from the value specified by its first `sp-theme` or `document` ancestor; otherwise, it uses the value `dir="ltr"` if a content direction isn't present in those elements. When a value for `dir` is manually supplied to `sp-theme`, the default value is overridden. In all cases, though, `sp-theme` manages the `dir` value of its `SpectrumElement` descendents, unless another `sp-theme` element is placed into its scope and overrides that management. - -To make the above concepts a little more concrete, take a look at the table below. Try selecting another `color` in the picker, and notice how that changes the values of the colors. The token names for the variables persist, but the RGB values under the hood change! Considering that `sp-theme` also manages all the other theme and size options, `sp-theme` reveals itself to be a pretty powerful component. - - - - - -When you're ready to look into more advanced usage of the components and themes in your application, there are vanilla CSS implementations of these tokens available in the `@spectrum-web-components/styles` package. - -## Example - -An `` element expects a value for each of its `color` and `scale` attributes to be provided on the element. While not required, you can also use the `system` attribute to specify whether the theme you're using is Spectrum Classic (the default), Spectrum 2 (upcoming release) or Spectrum Express. - -```html - - - Click me! - - -``` - -## Advanced usage - -Once you've moved beyond the prototype phase of an application, it is likely that you will only use one combination of `color` and `scale` in your application, and even if not, you'll likely benefit from lazily loading the variants you don't leverage by default. For single combination applications, or to power a _default_ theme, the following imports can be used to ensure only the code your application requires is loaded: - -### Classic - -```js -/** - * Power a site using - * - * - **/ -import '@spectrum-web-components/theme/theme-darkest.js'; -import '@spectrum-web-components/theme/scale-large.js'; - -import '@spectrum-web-components/theme/sp-theme.js'; +// Optionally choose a different system +// import '@spectrum-web-components/theme/express/theme-light.js'; +// import '@spectrum-web-components/theme/express/scale-medium.js'; ``` -### Express +If you’re prototyping and want everything available: ```js -/** - * Power a site using - * - * - **/ -import '@spectrum-web-components/theme/express/theme-light.js'; -import '@spectrum-web-components/theme/express/scale-medium.js'; - import '@spectrum-web-components/theme/sp-theme.js'; +import '@spectrum-web-components/theme/src/themes.js'; // spectrum +import '@spectrum-web-components/theme/src/express/themes.js'; // express +import '@spectrum-web-components/theme/src/spectrum-two/themes.js'; // spectrum-two ``` -When subsequent theme variants are needed, you can ensure those are lazily loaded by leveraging dynamic imports via something like: +## Examples -```js -const themeElement = document.querySelector('sp-theme'); - -const updateTheme = async (color, scale) => { - Promise.all([ - import(`@spectrum-web-components/theme/theme-${color}.js`), - import(`@spectrum-web-components/theme/scale-${scale}.js`), - ]).then(() => { - themeElement.color = color; - themeElement.scale = scale; - }); -}; - -updateTheme('light', 'medium'); -``` +### Light theme, medium scale -When bundling your application, be sure to consult the documentation of your bundler for the correct way to ensure proper packaging of the programatic dependency graph that this will create. - -## Light theme - -```html demo - - - - - - - - -``` - -## Dark theme - -```html demo +```html - - + +
+ Email + + We’ll only use this to send a receipt. + + Submit + Cancel + +
- - - - ``` -## Large scale +### Dark theme, large scale -The large scale of `` will switch to using Spectrum's larger mobile [Platform Scale](https://spectrum.adobe.com/page/platform-scale/) +The large scale of `` will switch to using Spectrum's larger mobile Platform Scale. -```html demo +```html - -
-
- -
-
Overdrive
- - Cancel - Continue - + +
+ Volume + + Overdrive
``` -## Embedding themes +### Embedded themes and directional content -There are a few cases where it is necessary to embed one theme within another. -For example, if you have an application that is using a dark theme with a left to right text direction that is -previewing or editing content that will be displayed in a light theme with a right to left text direction. +There are a few cases where it is necessary to embed one theme within another. For example, if you have an application that is using a dark theme with a left to right text direction that is previewing or editing content that will be displayed in a light theme with a right to left text direction. ```html