feat(tabs): migrate to spectrum 2 #4003

rise-erpelding · 2025-07-01T01:32:06Z

Description

Tabs Spectrum 2 Migration

Tabs is an S2 migration that is quite pared down compared to its S1 counterpart. Removed features & variants for S2 include:

Removed t-shirt sizing* (see notes section)
Removal of divider line
No quiet variant (S2 is what was previously the quiet variant, with no divider line)
Removal of the emphasized variant (no blue/accent coloring)
Updated use of tokens (see notes)

Other changes and updates for S2:

Use of custom properties has changed within the tabs component. Variants reset the definitions of existing custom properties rather than leveraging their --mod custom props. All --mod custom props are now set at the top level at the initial custom prop definition instead of in line with the styles.
Some custom property names and their mods were changed to give them more accurate names (--mod-tabs-divider-size to --spectrum-tabs-selected-item-thickness to --mod-tabs-selection-indicator-thickness; --mod-tabs-divider-border-radius --> --mod-tabs-selection-indicator-border-radius)
Focus indicator has been updated to include the selection indicator. Looking at the React implementation it appears that focus indicator only appears when also selected.
It sounds as if there is a future plan for vertical and overflow variants, but it's unclear what they will look like. For now, they'll remain mostly unchanged.
Within the overflow variant, compact and regular densities had started to look the same; a small passthrough adjustment was made to the picker to address this, if we keep that variant.

Notes:

Design spec includes t-shirt sizing token specs for font size only - if you look at the comments, this has been noted as a likely mistake. Otherwise, there are no t-shirt sized spacing specs for S2 in the token spec or S2/Desktop spec.
No tokens were updated for tabs, so updated token values and new tokens aren't in spectrum-tokens. Design is aware but it's unclear what the timeline will be for having these tokens added. Instead, custom tokens have been added for the necessary values based on the design spec with the intention of removing them later.
There were no tokens for the selection indicator corner radius or focus indicator corner radius. After receiving some guidance from design, these were updated using the appropriate global token.

How and where has this been tested?

Please tag yourself on the tests you've marked complete to confirm the tests have been run by someone other than the author.

Validation steps

Compare with token spec [Note: we're missing quite a few tokens, maybe skip this step for now]
Check over the Docs page and changeset, is the documentation up to date, grammatically sound, and feeling complete?
Check Windows High Contrast Mode - we don't have design guidance for this, but does anything seem off or unexpected to you? The overflow variant with the picker does look a bit different, but it conforms to picker's WHCM styles. Also the tab widths feel short in WHCM when the selected tab has a different background color, open to thoughts on this although from the design it appears that the tab width has no side spacing.
Check the test coverage - is there anything missing?
Is there anything that might potentially be broken, or doesn't look right?

Regression testing

Validate:

The documentation pages for at least two other components are still loading, including:

The pages render correctly, are accessible, and are responsive.

If components have been modified, VRTs have been run on this branch:

VRTs have been run and looked at.
Any VRT changes have been accepted (by reviewer and/or PR author), or there are no changes.

Screenshots

To-do list

I have read the contribution guidelines.
I have updated relevant storybook stories and templates.
I have tested these changes in Windows High Contrast mode.
If my change impacts other components, I have tested to make sure they don't break.
If my change impacts documentation, I have updated the documentation accordingly.
✨ This pull request is ready to merge. ✨

changeset-bot · 2025-07-01T01:32:10Z

🦋 Changeset detected

Latest commit: aedde76

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@spectrum-css/tabs	Major
@spectrum-css/bundle	Patch
@spectrum-css/preview	Patch

Not sure what this means? Click here to learn what changesets are.

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

github-actions · 2025-07-01T01:37:35Z

📚 Branch preview

PR #4003 has been deployed to Azure Blob Storage: https://spectrumcss.z13.web.core.windows.net/pr-4003/index.html.

github-actions · 2025-07-01T01:42:26Z

File metrics

Summary

Total size: 1.43 MB^*
Total change (Δ): 🔴 ⬆ 1.70 KB (0.12%)

Table reports on changes to a package's main file. Other changes can be found in the collapsed Details section below.

Package	Size	Minified	Gzipped	Δ
tabs	11.82 KB	11.16 KB	2.05 KB	🟢 ⬇ 5.21 KB

File change details

tabs

Filename	Head	Minified	Gzipped	Compared to base
index.css	11.82 KB	11.16 KB	2.05 KB	🟢 ⬇ 5.21 KB
metadata.json	6.96 KB	-	-	🟢 ⬇ 2.28 KB

tokens

Filename	Head	Minified	Gzipped	Compared to base
css/dark-vars.css	46.24 KB	-	-	-
css/global-vars.css	80.22 KB	-	-	-
css/index.css	260.28 KB	-	-	🔴 ⬆ 0.87 KB
css/large-vars.css	44.57 KB	-	-	🔴 ⬆ 0.41 KB
css/light-vars.css	46.24 KB	-	-	-
css/medium-vars.css	44.74 KB	-	-	🔴 ⬆ 0.47 KB
json/tokens.json	410.29 KB	-	-	-

* Size is the sum of all main files for packages in the library.
* An ASCII character in UTF-8 is 8 bits or 1 byte.

rise-erpelding · 2025-07-03T23:15:52Z

components/tabs/index.css

@@ -165,81 +96,97 @@

 	/* Friends should align to the top of the tabs */
 	vertical-align: top;
-
-	background: linear-gradient(to var(--mod-tabs-list-background-direction, var(--spectrum-tabs-list-background-direction)), var(--highcontrast-tabs-divider-background-color, var(--mod-tabs-divider-background-color, var(--spectrum-tabs-divider-background-color))) 0 var(--mod-tabs-divider-size, var(--spectrum-tabs-divider-size)), transparent var(--mod-tabs-divider-size, var(--spectrum-tabs-divider-size)));


I'm not clear on what this linear gradient's purpose was initially, but since we don't have a divider anymore, I pulled it out.

rise-erpelding · 2025-07-03T23:29:59Z

components/tabs/index.css

+	/* @todo: set transition: none for initial positioning */
+	transition: transform var(--spectrum-tabs-animation-duration) var(--spectrum-tabs-animation-ease);


So, I'm not sure about the transition effects here. We don't have a great way to test them because we don't have an implementation here that transitions the selection indicator (the selection indicator should animate as it switches from one selected tab to another). This is pretty much what was here before so I'm hopeful that I didn't break anything.

I also noticed combing through SWC's CSS for Tabs that they're programmatically setting a `first-position' class that has no transition, not sure if that's something we'd eventually want to add here but it seems like we'd want a bit more consensus (or even just a bit more of a feedback loop) to decide on how we'll do this.

rise-erpelding · 2025-07-03T23:34:41Z

components/tabs/index.css

 	}

 	&.spectrum-Tabs--compact {
-		/* The ActionButton is taller than the tabs, so don't push tabs around */
+		/* The overflow ActionButton is taller than the tabs, so don't push tabs around */


The overflow tabs in SWC use an action button for the arrows, I'm assuming that's what's meant here.

It works perfectly fine currently to set --mod custom properties in order to achieve variants, but since we've previously spoken of removing --mods, it seems more wise to use a different pattern. This pattern, similar to what's seen in button and actionbutton, is to change the definition of the custom property in order to achieve the variant.

As the variants are setting mods at the top level, it feels more natural to set mods for the default variant at the top as well. This is helped by the fact that there are no longer t-shirt sizes for tabs.

- Rename some custom properties: - --spectrum-tabs-selected-item-thickness/--mod-tabs-selected-item-thickness --> --spectrum/--mod-tabs-selection-indicator-thickness - --mod-tabs-divider-border-radius --> --mod-tabs-selection-indicator-border-radius - change the order of some custom properties - add intended token values for undefined/misdefined tokens, including for mobile - add a .spectrum--large selector to override some tokens for large viewports

- Adjusts the calcs for the focus indicator to match the token spec - Switches inset-inline to margin to better align the approach with what's seen in the breadcrumb component - Adds some light adjustments to the template (roles, tabindex)

- Simplify selection indicator markup in template - Moves inline selection indicator styles from template to index.css

@todo

- add a passthrough for picker so compact and regular overflow look different instead of exactly the same - change the corner radius for the focus indicator because there wasn't one on the spec but it looks like it's 6px, not 4px... the comment about calcs in the figma spec doesn't make sense to me so @todo I'll have to ask about that later - changed ::before inset-inline-start for the default variant, so updates it in --vertical variants as well - fixes undefined icon that was showing up as a circle in stories.js - add tests to grid for hover colors, with necessary support in template - add tests to grid for focus indicator, with necessary support in template - add gap rather than confusing margin-inline-start rule - add notes within the comments to clarify things that may not be as obvious within the context of css only - moves selection indicator margin-block-start to scope only to horizontal variant

Looking at WHCM revealed a few issues: - disabled selection indicator color was not being applied; instead disabled selected tab text was a different color - would have been great to have a test for disabled items, better late than never - we were setting an unneeded margin-inline-start on the focus indicator for the vertical variant that made WHCM look a little off - other refactoring and simplificaion of WHCM styles

- moves custom properties that we needed out of the index.css file and into custom tokens, with added changeset - minor refactoring to use shorthand properties - updating the year - incorporating the feedback received from design about corner-rounding for selection indicator and focus indicator

rise-erpelding added wip This is a work in progress, don't judge. S2 Spectrum 2 labels Jul 1, 2025

rise-erpelding force-pushed the rise-erpelding/css-1161-tabs-s2 branch 4 times, most recently from b0c1a1b to 0d1f3f9 Compare July 3, 2025 17:27

rise-erpelding added the size-3 M ~18-30hrs; moderate effort or complexity, several work days needed. label Jul 3, 2025

rise-erpelding commented Jul 3, 2025

View reviewed changes

rise-erpelding self-assigned this Jul 7, 2025

rise-erpelding force-pushed the rise-erpelding/css-1161-tabs-s2 branch 2 times, most recently from 0a9875f to aedde76 Compare July 8, 2025 20:16

rise-erpelding added 14 commits July 14, 2025 13:34

feat(tabs): remove t-shirt sizing

cfcb280

docs(tabs): storybook cleanup

034ace3

chore(tabs): remove quiet variant

7ec615e

chore(tabs): remove emphasized variant

13b83aa

refactor(tabs): set --mods and --highcontrast at top level

888e492

As the variants are setting mods at the top level, it feels more natural to set mods for the default variant at the top as well. This is helped by the fact that there are no longer t-shirt sizes for tabs.

feat(tabs): use new tokens for s2 tabs

fb878a2

feat(tabs): refactor focus indicator

2e4abcf

- Adjusts the calcs for the focus indicator to match the token spec - Switches inset-inline to margin to better align the approach with what's seen in the breadcrumb component - Adds some light adjustments to the template (roles, tabindex)

refactor(tabs): selection indicator touch-ups

82ecba2

- Simplify selection indicator markup in template - Moves inline selection indicator styles from template to index.css

chore(tabs): changeset

9ab4c1a

rise-erpelding force-pushed the rise-erpelding/css-1161-tabs-s2 branch from aedde76 to aeb0c2f Compare July 15, 2025 00:22

rise-erpelding removed the wip This is a work in progress, don't judge. label Jul 15, 2025

rise-erpelding marked this pull request as ready for review July 15, 2025 00:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(tabs): migrate to spectrum 2 #4003

feat(tabs): migrate to spectrum 2 #4003

rise-erpelding commented Jul 1, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Jul 1, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Jul 1, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Jul 1, 2025 •

edited

Loading

tabs

tokens

Uh oh!

rise-erpelding Jul 3, 2025

Uh oh!

rise-erpelding Jul 3, 2025

Uh oh!

rise-erpelding Jul 3, 2025

Uh oh!

Uh oh!

		/* @todo: set transition: none for initial positioning */
		transition: transform var(--spectrum-tabs-animation-duration) var(--spectrum-tabs-animation-ease);

feat(tabs): migrate to spectrum 2 #4003

Are you sure you want to change the base?

feat(tabs): migrate to spectrum 2 #4003

Conversation

rise-erpelding commented Jul 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Tabs Spectrum 2 Migration

Other changes and updates for S2:

Notes:

How and where has this been tested?

Validation steps

Regression testing

Screenshots

To-do list

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

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

Uh oh!

📚 Branch preview

Uh oh!

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

Uh oh!

File metrics

Summary

tabs

tokens

Uh oh!

rise-erpelding Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

rise-erpelding Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

rise-erpelding Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rise-erpelding commented Jul 1, 2025 •

edited

Loading

changeset-bot bot commented Jul 1, 2025 •

edited

Loading

github-actions bot commented Jul 1, 2025 •

edited

Loading

github-actions bot commented Jul 1, 2025 •

edited

Loading