sp-theme
NPM
0.48.1
0.48.1 (2024-10-01) #
Bug Fixes #
- add file extension to Theme imports and respective eslint rule (
#4771 ) (a2b6bea )
0.48.0 (2024-09-17) #
Note: Version bump only for package @spectrum-web-components/theme
0.47.2 (2024-09-03) #
Note: Version bump only for package @spectrum-web-components/theme
0.47.1 (2024-08-27) #
Note: Version bump only for package @spectrum-web-components/theme
0.47.0 (2024-08-20) #
Features #
- breadcrumbs: add Breadcrumbs component (
#4578 ) (acd4b5e )
0.46.0 (2024-08-08) #
Note: Version bump only for package @spectrum-web-components/theme
0.45.0 (2024-07-30) #
Note: Version bump only for package @spectrum-web-components/theme
0.44.0 (2024-07-15) #
Note: Version bump only for package @spectrum-web-components/theme
0.43.0 (2024-06-11) #
Note: Version bump only for package @spectrum-web-components/theme
0.42.5 (2024-05-24) #
Note: Version bump only for package @spectrum-web-components/theme
0.42.4 (2024-05-14) #
Bug Fixes #
- styles,theme: add S2 tokens and theme (
#4241 ) (a29e4a2 ), closes#4232 #4228 - theme: deprecate
theme
property forsystem
(#4230 ) (ac26168 )
0.42.3 (2024-05-01) #
Bug Fixes #
- theme: deprecate
theme
property forsystem
(#4230 ) (ac26168 )
0.42.2 (2024-04-03) #
Note: Version bump only for package @spectrum-web-components/theme
0.42.1 (2024-04-02) #
Note: Version bump only for package @spectrum-web-components/theme
0.42.0 (2024-03-19) #
Bug Fixes #
- styles, theme: surface exports that omit Spectrum Vars proactively (
#4142 ) (5b524c1 ) - theme: deprecate lightest and darkest color stops (
#4179 ) (0c01a66 )
0.41.2 (2024-03-05) #
Note: Version bump only for package @spectrum-web-components/theme
0.41.1 (2024-02-22) #
Note: Version bump only for package @spectrum-web-components/theme
0.41.0 (2024-02-13) #
Note: Version bump only for package @spectrum-web-components/theme
0.40.5 (2024-02-05) #
Bug Fixes #
- theme: expose version property (
#3978 ) (d42bb71 ) - theme: include custom Spectrum color tokens in Express color tokens (
370a1f1 )
0.40.4 (2024-01-29) #
Note: Version bump only for package @spectrum-web-components/theme
0.40.3 (2024-01-11) #
Note: Version bump only for package @spectrum-web-components/theme
0.40.2 (2023-12-18) #
Note: Version bump only for package @spectrum-web-components/theme
0.40.1 (2023-12-05) #
Note: Version bump only for package @spectrum-web-components/theme
0.40.0 (2023-11-16) #
Note: Version bump only for package @spectrum-web-components/theme
0.39.4 (2023-11-02) #
Note: Version bump only for package @spectrum-web-components/theme
0.39.3 (2023-10-18) #
Note: Version bump only for package @spectrum-web-components/theme
0.39.2 (2023-10-13) #
Note: Version bump only for package @spectrum-web-components/theme
0.39.1 (2023-10-06) #
Note: Version bump only for package @spectrum-web-components/theme
0.39.0 (2023-09-25) #
Note: Version bump only for package @spectrum-web-components/theme
0.38.0 (2023-09-05) #
Note: Version bump only for package @spectrum-web-components/theme
0.37.0 (2023-08-18) #
Note: Version bump only for package @spectrum-web-components/theme
0.36.0 (2023-08-18) #
Note: Version bump only for package @spectrum-web-components/theme
0.35.0 (2023-07-31) #
Note: Version bump only for package @spectrum-web-components/theme
0.34.0 (2023-07-11) #
Note: Version bump only for package @spectrum-web-components/theme
0.33.2 (2023-06-14) #
Note: Version bump only for package @spectrum-web-components/theme
0.33.0 (2023-06-08) #
Note: Version bump only for package @spectrum-web-components/theme
0.32.0 (2023-06-01) #
Note: Version bump only for package @spectrum-web-components/theme
0.31.0 (2023-05-17) #
Note: Version bump only for package @spectrum-web-components/theme
0.30.0 (2023-05-03) #
Bug Fixes #
- theme: stop language resolution propagation and demo using local languages (
6b81391 )
Features #
- styles: update typography to leverage Core Tokens (
2f86560 )
0.15.0 (2023-04-24) #
Features #
- styles: update typography to leverage Core Tokens (
2f86560 )
0.14.14 (2023-04-05) #
Bug Fixes #
- theme: stop language resolution propagation and demo using local languages (
6b81391 )
0.14.13 (2023-03-22) #
Note: Version bump only for package @spectrum-web-components/theme
0.14.12 (2023-03-08) #
Note: Version bump only for package @spectrum-web-components/theme
0.14.11 (2023-02-08) #
Note: Version bump only for package @spectrum-web-components/theme
0.14.10 (2023-01-23) #
Note: Version bump only for package @spectrum-web-components/theme
0.14.9 (2023-01-09) #
Note: Version bump only for package @spectrum-web-components/theme
0.14.8 (2022-12-08) #
Note: Version bump only for package @spectrum-web-components/theme
0.14.7 (2022-11-21) #
Note: Version bump only for package @spectrum-web-components/theme
0.14.6 (2022-11-14) #
Note: Version bump only for package @spectrum-web-components/theme
0.14.5 (2022-10-28) #
Note: Version bump only for package @spectrum-web-components/theme
0.14.4 (2022-10-17) #
Note: Version bump only for package @spectrum-web-components/theme
0.14.3 (2022-10-10) #
Bug Fixes #
- convert the langage resolution workflow to a Reactive Controller (
b7781db ) - correct theme calculation for triggering warnings (
5576329 )
0.14.2 (2022-09-14) #
Bug Fixes #
- add docs and address PR comments (
568062a )
0.14.1 (2022-08-24) #
Note: Version bump only for package @spectrum-web-components/theme
0.14.0 (2022-08-09) #
Features #
- include all Dev Mode files in side effects (
f70817c )
0.13.0 (2022-08-04) #
Features #
- delivery dev mode messages in various packages (
62370a1 )
0.12.0 (2022-07-18) #
Features #
- support Spectrum Token consumption and update Action Button to use them (
743ab16 )
0.11.3 (2022-06-29) #
Note: Version bump only for package @spectrum-web-components/theme
0.11.2 (2022-06-07) #
Note: Version bump only for package @spectrum-web-components/theme
0.11.1 (2022-05-12) #
Note: Version bump only for package @spectrum-web-components/theme
0.11.0 (2022-04-21) #
Bug Fixes #
- ensure all theme data is exported and listed for side effects (
14efdc7 )
Features #
- add support for Spectrum Express (
12bfe99 )
0.10.2 (2022-03-30) #
Note: Version bump only for package @spectrum-web-components/theme
0.10.1 (2022-03-08) #
Note: Version bump only for package @spectrum-web-components/theme
0.10.0 (2022-03-04) #
Features #
- leverage latest Spectrum button API (
9caf2f6 )
0.9.4 (2022-02-22) #
Note: Version bump only for package @spectrum-web-components/theme
0.9.3 (2022-01-26) #
Note: Version bump only for package @spectrum-web-components/theme
0.9.2 (2022-01-07) #
Note: Version bump only for package @spectrum-web-components/theme
0.9.1 (2021-12-13) #
Bug Fixes #
- use local declaration of ShadowRoot.adoptedStyleSheets (
43f1c63 )
0.9.0 (2021-11-08) #
Features #
- update lit-* dependencies, wip (
377f3c8 )
0.8.16 (2021-11-08) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.15 (2021-11-02) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.14 (2021-09-20) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.13 (2021-08-24) #
Bug Fixes #
- correct
@element jsDoc listing across library (c97a632 )
0.8.12 (2021-08-03) #
Bug Fixes #
- resolve "updateComplete" with a boolean like LitElement (
2ebcd44 )
0.8.11 (2021-07-22) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.10 (2021-07-01) #
Bug Fixes #
- manage "lang" via context provided by "sp-theme" (
b1e3457 )
0.8.9 (2021-06-16) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.8 (2021-06-07) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.7 (2021-05-12) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.6 (2021-04-15) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.5 (2021-04-09) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.4 (2021-03-29) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.3 (2021-03-22) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.2 (2021-03-22) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.1 (2021-03-05) #
Note: Version bump only for package @spectrum-web-components/theme
0.8.0 (2021-03-04) #
Features #
- use latest exports specification (
a7ecf4b )
0.7.4 (2021-02-11) #
Note: Version bump only for package @spectrum-web-components/theme
0.7.3 (2021-02-02) #
Note: Version bump only for package @spectrum-web-components/theme
0.7.2 (2021-01-28) #
Note: Version bump only for package @spectrum-web-components/theme
0.7.1 (2021-01-21) #
Bug Fixes #
- include the "types" entry in package.json files (
b432f59 ) - use latest @spectrum-css/* versions (
c35eb86 )
0.7.0 (2021-01-13) #
Bug Fixes #
- include the "types" entry in package.json files (
b432f59 ) - use latest @spectrum-css/* versions (
c35eb86 )
0.6.3 (2020-10-12) #
Note: Version bump only for package @spectrum-web-components/theme
0.6.2 (2020-10-12) #
Bug Fixes #
- include default export in the "exports" fields (
f32407d )
0.6.1 (2020-09-25) #
Bug Fixes #
- update side effect listings (
8160d3a )
0.6.0 (2020-08-31) #
Features #
- allow dir management by sp-theme elements (
2d10158 )
0.5.2 (2020-07-24) #
Bug Fixes #
- ensure browser understandable extensions (
f4e59f7 )
0.5.1 (2020-07-22) #
Bug Fixes #
- theme: Use correct filename in exports field (
d5da506 )
0.5.0 (2020-07-17) #
Features #
- leverage "exports" field in package.json (
321abd7 )
0.4.1 (2020-06-08) #
Bug Fixes #
- theme: prevent property sets attribute set property stack overflow (
28d8a07 ) - theme: support lazily loading theme fragments (
3c3b634 )
0.4.0 (2020-04-16) #
Bug Fixes #
- ensure themes are registered before adopting (
a7ffb84 )
Features #
- rule: add Spectrum rule pattern and apply to docs (
f4c52ae )
Performance Improvements #
- use "sideEffects" listing in package.json (
7271614 )
0.3.2 (2020-04-07) #
Note: Version bump only for package @spectrum-web-components/theme
0.3.1 (2020-03-16) #
Bug Fixes #
- theme: make typescript happy (
a9aa377 ) - theme: track default theme values dynamically (
a0c306c )
0.3.0 (2020-03-11) #
Features #
- add "darkest" theme styles (
fe38025 )
0.2.0 (2020-01-30) #
Bug Fixes #
- theme: include "large" scale (
67577e7 )
Features #
- rework overlays to use popper (
e17d1bb )
0.1.1 (2020-01-06) #
Bug Fixes #
- factor theme to use a single DOM node (
7641228 ), closes#154 - get theme element working in storybook (
4c5e478 )
0.2.3 (2019-12-02) #
Note: Version bump only for package @spectrum-web-components/themes
0.2.2 (2019-11-27) #
Bug Fixes #
- include "type" in package.json, generate custom-elements.json (
1a8d716 )
0.2.1 (2019-11-19) #
Note: Version bump only for package @spectrum-web-components/themes
0.2.0 (2019-11-19) #
Features #
- use @adobe/spectrum-css@2.15.1 (
3918888 )
0.1.4 (2019-10-14) #
Performance Improvements #
- use imported TypeScript helpers instead of inlining them (
cc2bd0a )
0.1.3 (2019-10-03) #
Note: Version bump only for package @spectrum-web-components/themes
Slots #
default slot
Description #
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.
Usage #
yarn add @spectrum-web-components/theme
Quick start #
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 <sp-theme>
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'; 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 <sp-theme>
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.
<sp-theme system="spectrum" color="light" scale="medium" style="background-color: var(--spectrum-gray-100)" > <sp-button onclick="spAlert(this, 'Themed <sp-button> clicked!')"> Click me! </sp-button> </sp-theme>
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 #
/** * Power a site using * * <sp-theme * system="classic" * color="darkest" * scale="large" * > **/ import '@spectrum-web-components/theme/theme-darkest.js'; import '@spectrum-web-components/theme/scale-large.js'; import '@spectrum-web-components/theme/sp-theme.js';
Express #
/** * Power a site using * * <sp-theme * system="express" * color="light" * scale="medium" * > **/ 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';
When subsequent theme variants are needed, you can ensure those are lazily loaded by leveraging dynamic imports via something like:
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');
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 #
<style type="text/css"> #example { max-width: 500px; padding: 3em; background-color: var(--spectrum-gray-100); color: var(--spectrum-gray-800); } #buttons { margin-top: 2em; } </style> <sp-theme system="express" color="light" scale="medium"> <hzn-app-stuff></hzn-app-stuff> </sp-theme> <express-app> <hzn-app-stuff></hzn-app-stuff> </express-app>
Dark theme #
<style type="text/css"> #example { max-width: 500px; padding: 3em; background-color: var(--spectrum-gray-100); color: var(--spectrum-gray-800); } #buttons { margin-top: 2em; } </style> <sp-theme system="express" color="dark" scale="large"> <hzn-app-stuff></hzn-app-stuff> </sp-theme> <express-app> <hzn-app-stuff></hzn-app-stuff> </express-app>
Large scale #
The large scale of <sp-theme>
will switch to using Spectrum's larger mobile
<style type="text/css"> #example { max-width: 500px; padding: 1em; background-color: var(--spectrum-gray-100); color: var(--spectrum-gray-800); } #buttons { margin-top: 2em; } </style> <sp-theme color="darkest" scale="large"> <div id="example"> <div> <sp-slider value="5" step="1" min="1" max="11" label="Volume" id="volume-slider" ></sp-slider> </div> <div><sp-switch>Overdrive</sp-switch></div> <sp-button-group id="buttons"> <sp-button variant="primary">Cancel</sp-button> <sp-button variant="accent">Continue</sp-button> </sp-button-group> </div> </sp-theme>
Embedding themes #
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.
<style type="text/css"> #outer { max-width: 500px; padding: 1em; background-color: var(--spectrum-gray-100); color: var(--spectrum-gray-800); } #inner { margin-top: 2em; padding: 1em; background-color: var(--spectrum-gray-100); color: var(--spectrum-gray-800); } #buttons { margin-top: 2em; } </style> <sp-theme color="dark" dir="ltr"> <div id="outer"> <div> <sp-slider value="5" step="1" min="1" max="11" label="Volume" id="volume-slider" ></sp-slider> </div> <div><sp-switch>Overdrive</sp-switch></div> <sp-button-group id="buttons"> <sp-button variant="primary">Cancel</sp-button> <sp-button variant="accent">Continue</sp-button> </sp-button-group> <sp-theme color="light" dir="rtl"> <div id="inner"> <div> <sp-slider value="5" step="1" min="1" max="11" label="Volume" id="volume-slider" ></sp-slider> </div> <div><sp-switch>Overdrive</sp-switch></div> <sp-button-group id="buttons"> <sp-button variant="primary">Cancel</sp-button> <sp-button variant="accent">Continue</sp-button> </sp-button-group> </div> </sp-theme> </div> </sp-theme>
Language Context #
The <sp-theme>
element provides a language context for its descendents in the DOM. Descendents can resolve this context by dispatching an sp-language-context
DOM event and supplying a callback(lang: string) => void
method in the detail
entry of the Custom Event. These callbacks will be reactively envoked when the lang
attribute on the <sp-theme>
element is updated. This way, you can control the resolved language in <sp-number-field>
<sp-slider>