feat(tooltip): s2 fidelity by 5t3ph · Pull Request #6331 · adobe/spectrum-web-components

5t3ph · 2026-05-20T20:18:57Z

Description

Implements the 2nd-gen <swc-tooltip> Phase 5 — Styling: full S2 token stylesheet, RTL-aware placement margins and open-state animations, directional tip geometry (physical right/left, logical start/end), forced-colors block, scaffold Storybook stories

Notable API change from the feature branch plan

This is not style impacting or demonstrated yet in this work, but was discovered during this phase

The delayed: boolean (default false, opt-in) property has been replaced with delay: number (default 1500, warm-up inherent). Setting delay="0" opts out of warm-up delay. This aligns with Spectrum's intent that warm-up is the default behavior for tooltips, not an add-on. The 1st-gen behavioral difference is called out in the migration plan.

Infrastructure and Docs/Skills Changes

These will be moved to a new PR to merge into main ASAP

stylelint.config.js — All CSS system color keywords (CanvasText, ButtonFace, etc.) added to the scale-unlimited/declaration-strict-value allowlist so forced-colors overrides can assign system colors without triggering the design token lint rule.
linters/stylelint-property-order.js — Missing transition property added to order definition.

Motivation and context

Continues the Spectrum 2 component migration workstream. This branch delivers the full implementation through styling.

Related issue(s)

SWC-2023

Manual review test cases

Pixel-accurate anchoring requires PlacementController (additive phase) and the HoverController for events; these stories temporarily use Floating UI directly to verify visual appearance across placements and clicks for toggling.

Variant colors are correct
1. In the Variants story, validate that:
  - "Save" uses the neutral default color
  - "Upload" uses the blue informative color
  - "Delete" uses the red negative color
Handles text wrapping, matching tooltip content size
1. In the Anatomy story, validate:
  - Action" tooltip shrinks to fit the content size
  - "Another action" tooltip content wraps after reaching the max allowed inline size
Placement margins and tip direction are correct for all six placements
1. Inspect each placement (top, bottom, left, right, start, end)
2. Expect the tip arrow to point toward the trigger, and the body margin to space correctly
RTL placement is correct for logical placements
1. In the Placements story, set "RTL" from the Storybook toolbar
2. Inspect start and end placements
3. Expect tip direction and animation direction to flip correctly for RTL
Forced-colors (high contrast mode) renders correctly
1. Enable high contrast mode in OS or DevTools forced-colors emulation
2. Toggle open the tooltip
3. Expect no loss of shape or tooltip visibility

Device review

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

Accessibility testing checklist

Keyboard (required)
1. Press Tab to focus the trigger button
2. Press Enter to toggle the tooltip (temporary until HoverController available)
Screen reader (required)
- Fully correct connection is pending the HoverController

…web-components into seckles/tooltip-s2-fidelity

changeset-bot · 2026-05-20T20:19:04Z

⚠️ No Changeset found

Latest commit: e64f33e

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 · 2026-05-20T20:24:29Z

📚 Branch Preview Links

🔍 First Generation 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-6331

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.

aramos-adobe · 2026-05-21T13:59:26Z

+ * Pixel-accurate anchoring requires `PlacementController` (additive phase); these stories
+ * temporarily use Floating UI directly to verify visual appearance across placements.
+ */
+export const Placements: Story = {


Love this display here ✨

rise-erpelding · 2026-05-22T15:22:56Z

+:host([placement="bottom-start"]) .swc-Tooltip,
+:host([placement="bottom-end"]) .swc-Tooltip {


Let's talk about these compound placement variants (bottom-start, bottom-end, right-top, etc. etc.)! Will they stay or go in 2nd-gen?

It feels reasonable to keep the placements simple (top, bottom, left, right, start, end only) as you have demonstrated currently, and that's what matches the design and React. This would definitely be something we'd want to communicate to consumers at the appropriate phase in the migration.

I also see that React has a cool crossOffset property that allows you to adjust tip placement, which could be something we think about eventually? Seems like that would be different than our current offset.

If we have no plans to implement compound placement variants later, can we cut out the selectors?

rise-erpelding · 2026-05-22T17:30:10Z

+- [x] Copy S2 source from `spectrum-css/components/tooltip/index.css` (`spectrum-two` branch, not `/dist`) into `tooltip.css` as baseline
+- [x] Map Spectrum CSS selectors to SWC equivalents following CSS selector guidance in CONTRIBUTOR_DOCS
+- [x] Remove `.spectrum-Tooltip-typeIcon` styles (no icon in S2)
+- [x] Add all six logical placement classes, consolidated with their non-logical equivalents: `start`, `start-top`, `start-bottom`, `end`, `end-top`, `end-bottom`


I asked about this in a different comment, but are we implementing the combined/compound placements like start-top, start-bottom, etc.?

rise-erpelding · 2026-05-22T17:36:17Z

+
+  position: absolute;
+  inset: auto;
+  max-inline-size: min(100%, token("tooltip-maximum-width"));


The reason we add these extra styles to the :host here is because we need them on the popover, is that right? Could be worth documenting the exception in the style guide docs for future work.

rise-erpelding · 2026-05-22T18:33:50Z

+```css
+.swc-Tooltip {
+  --_swc-tooltip-border-radius: token("corner-radius-400");
+  --_swc-tooltip-tip-corner-offset: var(--_swc-tooltip-border-radius);
+
+  border-radius: var(--_swc-tooltip-border-radius);
+}
+
+:host([placement="top-start"]) .swc-Tooltip-tip {
+  inset-inline-start: var(--_swc-tooltip-tip-corner-offset);
+}
+```


I can see this example becoming confusing for the agent, since we aren't really doing this in tooltip.css, is there another example in a shipped component we could use to illustrate this instead?

rise-erpelding · 2026-05-22T18:36:40Z

+/* ─────────────────────────────────────────────────────────────────────────────
+   HOST
+   Reset browser UA popover styles. All visual styles live on .swc-Tooltip.
+   PlacementController (additive phase) will apply inset/left/top for
+   positioning.
+   ───────────────────────────────────────────────────────────────────────────── */


I like these banner comments, could be a place to expand documentation on comment conventions and section headers

rise-erpelding · 2026-05-22T18:38:51Z

+}
+
+/* ─────────────────────────────────────────────────────────────────────────────
+   BASE TOOLTIP


A nit, but this could mention these are styles for top placement, I know you mention it above styles for placement margins but initially I didn't see that one.

rise-erpelding · 2026-05-22T20:45:55Z

+
+@media (forced-colors: active) {
+  .swc-Tooltip {
+    border: 1px solid CanvasText;


Checking AssistivLabs the tip is sometimes slightly oddly positioned:

I'm wondering if throwing the border in here (which is definitely needed, no arguments there) is throwing off the tip math and if we should try to adjust for that?

5t3ph added 9 commits May 15, 2026 16:08

feat(tooltip): phase 1 - init files

5e8410b

feat(tooltip): phase 3 - API, events, Gen1 warnings

9ed12c0

feat(tooltip): phase 4 - a11y validation

e738236

feat(tooltip): init S2 styles, temp placement

76bcdd9

feat(tooltip): resolve event sequencing

197604f

feat(tooltip): resolve RTL placement

d64cd17

feat(docs): handle host nesting, other TL;DR additions

cf036da

feat(tooltip): add WHCM; adjust plan for delay / HoverController

c917ee3

Merge branch 'swc-2017/tooltip' of https://github.com/adobe/spectrum-…

e64f33e

…web-components into seckles/tooltip-s2-fidelity

5t3ph requested a review from a team as a code owner May 20, 2026 20:18

5t3ph added Component:Tooltip Status:Ready for review PR ready for review or re-review. 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. labels May 20, 2026

aramos-adobe reviewed May 21, 2026

View reviewed changes

aramos-adobe approved these changes May 21, 2026

View reviewed changes

rise-erpelding self-assigned this May 22, 2026

rise-erpelding reviewed May 22, 2026

View reviewed changes

rise-erpelding removed their assignment May 22, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(tooltip): s2 fidelity#6331

feat(tooltip): s2 fidelity#6331
5t3ph wants to merge 9 commits into
swc-2017/tooltipfrom
seckles/tooltip-s2-fidelity

5t3ph commented May 20, 2026

Uh oh!

changeset-bot Bot commented May 20, 2026

Uh oh!

github-actions Bot commented May 20, 2026

Uh oh!

aramos-adobe May 21, 2026

Uh oh!

rise-erpelding May 22, 2026

Uh oh!

rise-erpelding May 22, 2026

Uh oh!

rise-erpelding May 22, 2026

Uh oh!

rise-erpelding May 22, 2026

Uh oh!

rise-erpelding May 22, 2026

Uh oh!

rise-erpelding May 22, 2026

Uh oh!

rise-erpelding May 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		:host([placement="bottom-start"]) .swc-Tooltip,
		:host([placement="bottom-end"]) .swc-Tooltip {

Conversation

5t3ph commented May 20, 2026

Description

Notable API change from the feature branch plan

Infrastructure and Docs/Skills Changes

Motivation and context

Related issue(s)

Manual review test cases

Device review

Accessibility testing checklist

Uh oh!

changeset-bot Bot commented May 20, 2026

⚠️ No Changeset found

Uh oh!

github-actions Bot commented May 20, 2026

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants