chore: update theme docs #5837

TarunAdobe · 2025-10-28T10:36:20Z

Description

Updated tools/theme/README.md to align with documentation standards which include accessibility.

Motivation and context

This step will help our consumers use components accessibly. Additionally it gives the accessibility auditors, enough context to audit components.

It will ensure the full API is documented, including each property, slot, method, event, CSS property, and tokens in the component and along with accessibility concerns and/or decisions, linking to accessibility team documentation where applicable.

Related issue(s)

fixes SWC-283

Screenshots (if appropriate)

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
~~I have added automated tests to cover my changes.~~ N/A
~~I have included a well-written changeset if my change needs to be published.~~ N/A
I have included updated documentation if my change required it.

Reviewer's checklist

Includes a Github Issue with appropriate flag or Jira ticket number without a link
~~Includes thoughtfully written changeset if changes suggested include patch, minor, or major features~~ N/A
~~Automated tests cover all use cases and follow best practices for writing~~ N/A
Validated on all supported browsers
~~All VRTs are approved before the author can update Golden Hash~~ N/A

Manual review test cases

Theme docs

Review theme docs
Does the documentation follow the recommended heading structure?
Is the documentation accurate?
Are all the examples accessible?
Do the examples demonstrate how to use the components accessibly?
Are there examples to show how to use the component in context of other components, if necessary?

Device review

Did it pass in Desktop?
Did it pass in (emulated) Mobile?
Did it pass in (emulated) iPad?

changeset-bot · 2025-10-28T10:36:23Z

⚠️ No Changeset found

Latest commit: 4c4ee2b

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2025-10-28T10:38:02Z

📚 Branch Preview

🔍 Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-5837

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

github-actions · 2025-10-28T10:41:15Z

Tachometer results

Currently, no packages are changed by this PR...

coveralls · 2025-10-28T10:45:00Z

Pull Request Test Coverage Report for Build 19064794047

Details

0 of 0 changed or added relevant lines in 0 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage decreased (-0.002%) to 97.964%

Totals
Change from base Build 18982870623:	-0.002%
Covered Lines:	34259
Relevant Lines:	34788

💛 - Coveralls

TarunAdobe · 2025-11-03T09:33:14Z

I have removed the system-context-resolution.md from tools/reactive-controllers in this PR as it is being added with correct documentation in #5802 by @Rajdeepc

rubencarvalho

I left some comments! Looks really good :)

rubencarvalho · 2025-11-03T10:48:07Z

tools/theme/README.md

-`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.
+`<sp-theme>` 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:


nit: I see the API tab for Theme is not surfacing the properties / attributes. I recommend looking into it if it is a quick fix.

rubencarvalho · 2025-11-03T10:48:47Z

tools/theme/README.md

+Spectrum offers multiple variants:
+
+- **System**: `spectrum`, `express`, `spectrum-two`
+- **Color**: `light`, `dark` (legacy: `lightest`, `darkest` – deprecated)


wireframe? it is used below in the "What it does" section

what do you mean by wireframe?

rubencarvalho · 2025-11-03T10:49:10Z

tools/theme/README.md

+
+Spectrum offers multiple variants:
+
+- **System**: `spectrum`, `express`, `spectrum-two`


Should we to surface the default values?

rubencarvalho · 2025-11-03T10:50:50Z

tools/theme/README.md

+## Advanced usage

-## System Context (private Beta API - subject to changes)
+### What it does


What it does

This heading sounds a bit cryptic... What does it refer to here? And why is this under "Advanced usage"?

you're right... i want to put it at the top in the overview section with title - How sp-theme works

does that sound better?

Rajdeepc · 2025-11-03T12:19:04Z

tools/theme/README.md

+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


nit: It would be great if you can mention what these imports indicate via a heading rather than a comment?

Rajdeepc · 2025-11-03T12:19:26Z

tools/theme/README.md

-
-updateTheme('light', 'medium');
-```
+### Light theme, medium scale


Suggested change

### Light theme, medium scale

### Light color, medium scale

Rajdeepc · 2025-11-03T12:19:42Z

tools/theme/README.md

-## Dark theme
-
-```html demo
+```html


Suggested change

```html

```html-no-demo

Rajdeepc · 2025-11-03T12:19:54Z

tools/theme/README.md

 ```

-## Large scale
+### Dark theme, large scale


Suggested change

### Dark theme, large scale

### Dark color, large scale

Rajdeepc · 2025-11-03T12:20:39Z

tools/theme/README.md

-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.


Suggested change

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 color system with a left to right text direction that is previewing or editing content that will be displayed in a light color system with a right to left text direction.

Rajdeepc · 2025-11-03T12:20:46Z

tools/theme/README.md

 ```

-## Embedding themes
+### Embedded themes and directional content


Suggested change

### Embedded themes and directional content

### Embedded system and directional content

Rajdeepc · 2025-11-03T12:21:42Z

tools/theme/README.md

+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.

-#### Consuming the System Context in Components
+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.

-Components can consume the system context by using the `SystemResolutionController`. This controller encapsulates the logic for resolving the system context, allowing it to be integrated into any component in few steps.
+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.


A visual approach with some code snippet will add more value to this section.

there is a table that renders below with all color tokens

Rajdeepc · 2025-11-03T12:22:59Z

tools/theme/README.md

+## Accessibility
+
+- **Color and contrast**: Ensure sufficient contrast for any backgrounds you apply when consuming tokens (WCAG 2.1 AA). Components themselves meet Spectrum guidance when themed correctly.
+- **Language**: Set `lang` on `<sp-theme>` to inform number/date formatting and other locale-aware components.
+- **Directionality**: Use `dir` to deliver correct LTR/RTL behavior; embedded themes allow mixing contexts.


Not sure if this section falls under a11y!

There's isn't anything else particularly that came to my mind while thinking of A11y stuff for theme and so I added this

rise-erpelding · 2025-11-03T17:17:53Z

tools/theme/README.md


-```
+```js
 import '@spectrum-web-components/theme/sp-theme.js';


A short comment above this import might be nice (I know the text above the code snippet already kind of explains it, so feel free to disregard!):

Suggested change

import '@spectrum-web-components/theme/sp-theme.js';

// Registers the <sp-theme> custom element

import '@spectrum-web-components/theme/sp-theme.js';

rise-erpelding · 2025-11-03T17:24:22Z

tools/theme/README.md

-        </sp-button-group>
+<sp-theme system="spectrum" color="dark" scale="large">
+    <div id="outer">
+        <sp-field-label for="volume">Volume</sp-field-label>


Kind of a nit but when sp-field-label is included, it shows the same "Volume" label twice:

rise-erpelding · 2025-11-03T17:36:24Z

tools/theme/README.md

+### What it does

-The <sp-theme> element provides a "system" context to its descendants in the DOM. This context indicates the Spectrum design system variant currently in use (e.g., 'spectrum', 'express', or 'spectrum-two').
+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.


Is this content from this section in the old version of the documentation? It feels a little more base-level, and I'm wondering if putting it in the "Advanced usage" section might lead to more users ignoring it?

Hmmm. You're right... What do you think about having it in the overview section? Would that be okay?

rise-erpelding · 2025-11-03T17:40:15Z

tools/theme/README.md

+</script>

-2. Instantiate the `SystemResolutionController`:
+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.


Linking to the styles package here would be good!

chore: update theme docs

93881db

TarunAdobe force-pushed the ttomar/theme-docs branch from 2027dbc to 93881db Compare November 3, 2025 09:23

TarunAdobe marked this pull request as ready for review November 3, 2025 09:28

TarunAdobe requested a review from a team as a code owner November 3, 2025 09:28

TarunAdobe requested a review from Rajdeepc November 3, 2025 09:33

TarunAdobe force-pushed the ttomar/theme-docs branch 2 times, most recently from 2cfaba3 to fa8657b Compare November 3, 2025 09:35

chore: remove system context resolver readme

daf6f70

TarunAdobe force-pushed the ttomar/theme-docs branch from fa8657b to daf6f70 Compare November 3, 2025 09:35

rubencarvalho reviewed Nov 3, 2025

View reviewed changes

Rajdeepc requested changes Nov 3, 2025

View reviewed changes

rise-erpelding reviewed Nov 3, 2025

View reviewed changes

chore: review updates

4c4ee2b

TarunAdobe requested review from Rajdeepc, rise-erpelding and rubencarvalho November 4, 2025 10:20


		Spectrum offers multiple variants:

		- System: `spectrum`, `express`, `spectrum-two`

	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 color system with a left to right text direction that is previewing or editing content that will be displayed in a light color system with a right to left text direction.

	### Embedded themes and directional content
	### Embedded system and directional content

	import '@spectrum-web-components/theme/sp-theme.js';
	// Registers the <sp-theme> custom element
	import '@spectrum-web-components/theme/sp-theme.js';

chore: update theme docs #5837

Are you sure you want to change the base?

chore: update theme docs #5837

Conversation

TarunAdobe commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Related issue(s)

Screenshots (if appropriate)

Author's checklist

Reviewer's checklist

Manual review test cases

Device review

Uh oh!

changeset-bot bot commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview

🔍 Visual Regression Test Results

Uh oh!

github-actions bot commented Oct 28, 2025

Tachometer results

Uh oh!

coveralls commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 19064794047

Details

💛 - Coveralls

Uh oh!

TarunAdobe commented Nov 3, 2025

Uh oh!

rubencarvalho left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Rajdeepc Nov 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

TarunAdobe commented Oct 28, 2025 •

edited

Loading

changeset-bot bot commented Oct 28, 2025 •

edited

Loading

github-actions bot commented Oct 28, 2025 •

edited

Loading

coveralls commented Oct 28, 2025 •

edited

Loading

rubencarvalho left a comment •

edited

Loading

Rajdeepc Nov 3, 2025 •

edited

Loading