[DO NOT MERGE]: Conversation AI Pattern

.changeset/fix-double-tab-navigation.md

@@ -0,0 +1,7 @@
+---
+'@spectrum-web-components/button': patch
+---
+
+**Fixed** issue where clicking `sp-button` or `sp-action-button` with `href` and `target="_blank"` opened two tabs in Chrome instead of one.
+
+The fix checks if the anchor element is already in the click event's composed path before triggering a proxy click. When the user clicks directly on the button, the absolutely-positioned anchor naturally receives the click, so no proxy is needed. The proxy click is now only triggered for keyboard activation and VoiceOver, where the anchor isn't in the click path.

.changeset/friendly-tables-travel.md

@@ -0,0 +1,21 @@
+---
+'@spectrum-web-components/base': minor
+'@spectrum-web-components/core': minor
+---
+
+Refactored size mixin exports and badge type naming for consistency.
+
+**@spectrum-web-components/base (1st-gen)**
+
+- **Added**: New exports `ELEMENT_SIZES` and `DEFAULT_ELEMENT_SIZES` for typed size arrays
+- **Deprecated**: `ElementSizes` record is now deprecated in favor of `ELEMENT_SIZES`. The export is preserved for backward compatibility but will be removed in a future major release.
+
+**@spectrum-web-components/core (2nd-gen)**
+
+- **Changed**: Replaced `ElementSizes` record with `ELEMENT_SIZES` const array and `DEFAULT_ELEMENT_SIZES`
+- **Changed**: `VALID_SIZES` arrays are now typed as `readonly ElementSize[]` for better type safety
+- **Changed**: Badge type exports renamed for consistency:
+  - `BADGE_VARIANTS_S2` → `BADGE_VARIANTS`
+  - `BADGE_VARIANTS_COLOR_S2` → `BADGE_VARIANTS_COLOR`
+  - `BadgeVariantS2` → `BadgeVariant`
+  - `BadgeColorVariantS2` → `BadgeColorVariant`

.changeset/some-horses-shine.md

@@ -0,0 +1,16 @@
+---
+'@spectrum-web-components/overlay': patch
+'@spectrum-web-components/textfield': patch
+'@spectrum-web-components/number-field': patch
+---
+
+**Added**: Added truncated-value tooltip behavior for single-line text inputs.
+
+- `<sp-textfield>` now shows a tooltip with the full value when the displayed value is visually truncated (via `TruncatedValueTooltipController`).
+- Tooltip placement can be controlled with the `tooltip-placement` attribute on `<sp-textfield>` or `<sp-number-field>`
+- `<sp-number-field>` inherits the same truncation tooltip behavior from `TextfieldBase`, including formatted numeric/currency values.
+- `type="password"` textfields no longer use ellipsis truncation styling (`text-overflow: clip`) to avoid awkward visual truncation.
+
+**Changed**: `sp-overlay` (internal)
+
+- Added internal property `describeTrigger` (`'auto' | 'none'`, default `'auto'`). When set to `'none'`, the overlay does not set `aria-describedby` on the trigger when open (handled in `HoverController` and `LongpressController`), avoiding double announcement for screen readers when the overlay content duplicates the trigger (e.g. truncated-value tooltips). Textfield’s truncated-value tooltip uses this so the tooltip is visual-only for a11y.

.changeset/switch-token-mapping-s2.md

@@ -0,0 +1,10 @@
+---
+'@spectrum-web-components/switch': patch
+'@spectrum-web-components/styles': patch
+---
+
+**Added**: New switch component tokens and styles were mapped to bring more fidelity for Spectrum 2 foundations theme. Switch now uses system theme tokens for track and handle border colors, handle background, and themed border width; S1 and Express handle border colors are preserved. Users can hook into `--mod-switch-border-width-themed` to adjust the switch input border; `--mod-switch-border-color-*` to modify the switch input border color; `--mod-switch-handle-border-color-*` to change the handle/thumb border color.
+
+**Fixed**: S2 foundations switch emphasized down state color was fixed to reflect the S2 switch down state design spec. The high contrast input border color for S2, and a high-contrast typo are fixed.
+
+**Fixed**: Theme bridge token additions and updates in `@spectrum-web-components/styles` (Spectrum, Express, and tokens-v2) support the switch overrides.

.changeset/tooltip-self-managed-trigger-traversal.md

@@ -0,0 +1,7 @@
+---
+'@spectrum-web-components/tooltip': patch
+'@spectrum-web-components/action-menu': patch
+'@spectrum-web-components/picker': patch
+---
+
+**Fixed**: Self-managed tooltips slotted into host components (Action Menu, Picker) no longer emit false `[TRAVERSAL_EXHAUSTED]` warnings. Added a public `triggerElement` setter on `sp-tooltip` that allows host components to explicitly wire their internal trigger element, bypassing the ancestor-based composed-tree traversal that fails when the intended trigger is a sibling of the tooltip slot rather than an ancestor.

.changeset/yummy-crabs-kick.md

@@ -0,0 +1,28 @@
+---
+'@spectrum-web-components/switch': minor
+'@spectrum-web-components/styles': minor
+---
+
+- **Fixed**: Improved `<sp-switch>` contrast in S1 and Express to meet WCAG SC 1.4.11 Non-text Contrast (3:1 minimum). The unselected track border was added in S1 and Express, matching the S2 pattern of matching the handle background color to the track border color per interaction state.
+
+- **Fixed**: Corrected `<sp-switch>` handle border colors for selected states in S1 and Express. Handle border now resolves to `--spectrum-gray-75` against the filled/selected track background.
+
+- **Fixed**: Improved `<sp-switch>` Forced Colors (Windows High Contrast) mode. Replaced `box-shadow` track borders with proper `border` declarations, expanded `--highcontrast-switch-border-color` to full state-specific tokens (default, hover, focus, down, disabled), and corrected handle border colors to use system colors (`ButtonFace` for selected, `GrayText` for disabled).
+
+- **Changed**: Renamed `--spectrum-switch-border-width-themed` to `--spectrum-switch-border-width` on `<sp-switch>`. The border width is now a consistent 2px in all themes. **The `--mod-switch-border-width-themed` variable remains unaffected.**
+
+- **Changed**: Renamed `--highcontrast-switch-border-color` to `--highcontrast-switch-border-color-default` on `<sp-switch>`, and expanded it to full per-state tokens (`hover`, `focus`, `down`, `disabled`). Previously a single token controlled the track border color in all forced-colors states.
+
+**If you were overriding `--highcontrast-switch-border-color` in Windows High Contrast styles, update your usage to the appropriate state-specific token.**
+
+```css
+/* Before */
+sp-switch {
+  --highcontrast-switch-border-color: Highlight;
+}
+
+/* After */
+sp-switch {
+  --highcontrast-switch-border-color-default: Highlight;
+}
+```

.circleci/config.yml

@@ -22,7 +22,7 @@ parameters:
   # 3. Commit this change to the PR branch where the changes exist.
   current_golden_images_hash:
     type: string
-    default: 043fc5e7810746403bc78170939ed3d7b2aa8fbb
+    default: bc3f05831171b8f420d00ee792b726e3b12da715
 
   wireit_cache_name:
     type: string

.cursor/README.md

@@ -192,7 +192,7 @@ Skills are used on-demand. When a task matches a skill’s purpose, the agent re
 - **purpose**: Run the CONTRIBUTOR-DOCS nav script to update breadcrumbs and TOCs, and handle link verification
 - **How to invoke**: Say “update contributor docs nav”, “regenerate TOC”, “fix broken links in CONTRIBUTOR-DOCS”, or “run the nav script”. Also invoked when you add, remove, rename, or move files under `CONTRIBUTOR-DOCS/` or change H1/H2/H3 headings (the contributor-doc-update rule may trigger; the skill holds the full workflow).
 - Use when: Updating contributor docs structure, regenerating navigation, or fixing reported broken links
-- Provides: Operator workflow (run script, verify, fix links), Maintainer workflow (when to update script). Full instructions in `CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/01_ai-agent-instructions.md`
+- Provides: Operator workflow (run script, verify, fix links), Maintainer workflow (when to update script). Full instructions in `.cursor/skills/contributor-docs-nav/references/ai-agent-instructions.md`
 
 #### Component migration (rendering and styling)
 
@@ -201,6 +201,12 @@ Skills are used on-demand. When a task matches a skill’s purpose, the agent re
 - Use when: On the analyze-rendering-and-styling step for one or more components; creating one markdown file per component at `CONTRIBUTOR-DOCS/03_project-planning/03_components/[component-name]/rendering-and-styling-migration-analysis.md`
 - Provides: Workflow summary (specs from CSS + SWC, three-way DOM comparison, CSS⇒SWC mapping table, summary). Full instructions in `CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_analyze-rendering-and-styling/cursor_prompt.md`
 
+#### Washing machine migration workflow
+
+- **purpose**: End-to-end 1st-gen → 2nd-gen migration sequence (phases, checklists, links to step docs and style guides)
+- **Doc**: `CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md`
+- Use when: Planning or executing a component migration in the 2nd-gen component migration workstream
+
 #### Deep understanding
 
 - **purpose**: Require a thorough deep-read of the relevant codebase before planning or implementing; write findings to a persistent markdown file (e.g. `research.md`) so the user can review and correct before any work proceeds

.cursor/rules/accessibility-migration-analysis.mdc

@@ -0,0 +1,137 @@
+---
+description: Structure and conventions for CONTRIBUTOR-DOCS accessibility migration analysis markdown (per-component a11y migration specs).
+globs: CONTRIBUTOR-DOCS/**/accessibility-migration-analysis.md
+alwaysApply: false
+---
+
+# Accessibility migration analysis documents
+
+Use this when **creating or updating** `accessibility-migration-analysis.md` under `CONTRIBUTOR-DOCS/03_project-planning/03_components/<component>/`.
+
+These docs describe how a **2nd-gen** `swc-*` component should behave for **accessibility**, aligned with **WCAG 2.2 Level AA**, and tie to the component’s **rendering-and-styling** migration doc.
+
+## Reference examples (consistency)
+
+Use these existing docs as **examples** when matching structure, headings, tables, and phrasing:
+
+- `CONTRIBUTOR-DOCS/03_project-planning/03_components/badge/accessibility-migration-analysis.md`
+- `CONTRIBUTOR-DOCS/03_project-planning/03_components/divider/accessibility-migration-analysis.md`
+- `CONTRIBUTOR-DOCS/03_project-planning/03_components/progress-circle/accessibility-migration-analysis.md`
+- `CONTRIBUTOR-DOCS/03_project-planning/03_components/status-light/accessibility-migration-analysis.md`
+
+## File location and discovery
+
+- **Path:** `CONTRIBUTOR-DOCS/03_project-planning/03_components/<component-name>/accessibility-migration-analysis.md`
+- **Pairing:** Link to `./rendering-and-styling-migration-analysis.md` from **Overview → Also read**.
+- **Nav:** After adding a file or changing `##` / `###` headings, run `node update-nav.js` from `CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs` (see **contributor-doc-update** rule). Register the doc in `03_components/README.md` when introducing a new component folder.
+
+## Required section order
+
+Use this **H2** order. **Do not** skip sections that apply; omit only what truly does not apply (and say so briefly if it helps readers).
+
+1. `## Overview`
+2. `## ARIA and WCAG context`
+3. `## Recommendations: \`<swc-component-name>\``
+4. `## Testing` with `### Automated tests`
+5. `## Summary checklist`
+6. `## References`
+
+Under **`## Recommendations`**, use these **`###` subsections** in order:
+
+1. `### ARIA roles, states, and properties`
+2. `### Shadow DOM and cross-root ARIA Issues`
+3. `### Accessibility tree expectations`
+4. **Optional (when product guidance needs it):** e.g. `### Assistive technology, live regions`—place **after** accessibility tree expectations and **before** keyboard and focus. For **motion** (WCAG 2.2.2, reduced motion, Spectrum tokens), add rows to **Guidelines that apply** and the **Recommendations** table instead of a separate `### Motion` section—see **`progress-circle/accessibility-migration-analysis.md`**.
+5. `### Keyboard and focus`
+
+Separate major sections with a horizontal rule (`---`) where existing docs use it (after Overview, after ARIA and WCAG context, after Recommendations block before Testing).
+
+## Overview
+
+- Start with a short paragraph: what the doc covers, **`swc-*` name**, and **WCAG 2.2 Level AA** as the target.
+- Use **`###` subheadings** for structured bits—**do not** use bold-only labels like `**Also read:**` as section titles.
+
+**Typical subheadings** (include what fits the component):
+
+| Subheading | Use when |
+|------------|----------|
+| `### Also read` | Always—point at the component’s `rendering-and-styling-migration-analysis.md` (and optional related a11y docs). |
+| `### What it is` or `### What a <noun> is` | Always—one clear definition. |
+| `### When to use something else` | When authors often confuse this with another component—link to other migration or a11y docs with relative paths. |
+| `### What it is not` | When a common mistaken identity exists (e.g. progress ring vs in-field spinner). |
+| `### Related` | Optional—related components (e.g. progress bar vs progress circle). |
+
+Body text under each `###` is normal paragraphs and/or bullets.
+
+## ARIA and WCAG context
+
+- `### Pattern in the APG` — bullets: how APG (or lack of a named pattern) relates to this widget; link to APG patterns when relevant.
+- `### Guidelines that apply` — a **table** with columns **`Idea`** and **`Plain meaning`** (WCAG / WAI-ARIA links in the first column as needed).
+- Use the heading **`### Guidelines that apply`** (not “Guidelines that still apply”) for consistency across components.
+- Optional closing paragraph: `**Bottom line:** …` before `---`.
+
+## Recommendations: ARIA roles, states, and properties
+
+Use a **table** (`Topic | What to do` or `Topic | What to do`).
+
+**Single semantic role policy** (always address):
+
+- **Prescribed host role** (e.g. `separator`, `progressbar`): State that the role is **prescribed** and **fixed**, **must not** be author-overridable in implementation or docs, and that **`swc-*` maps to one semantic role only**. If another role is needed, authors must use **different markup or a different component**—not a role override on this element.
+- **No default host role** (e.g. badge, status light): State that the component should still represent **one** clear semantic thing; **do not** set a conflicting host `role` (e.g. `button`, `progressbar`) to fake another widget—use the appropriate **button / link / tag / other** component instead.
+
+Then add rows for **name**, **states**, **properties**, **visual-only props**, **docs expectations**, etc., **verified against the real implementation**—do not document ARIA the code does not set.
+
+## Shadow DOM and cross-root ARIA Issues
+
+- **Heading text must be exactly:** `### Shadow DOM and cross-root ARIA Issues` (word **Issues** capitalized).
+- **If** the component has **no** cross-root ARIA concerns (no reliance on **ID references** that must resolve across shadow boundaries, e.g. `aria-labelledby` / `aria-describedby` pointing at shadow-only IDs) **and** it is **not** a **form-associated** control (or otherwise dependent on cross-root labeling in ways that need a written plan), the **entire body** of the subsection should be a single word: **`None`** (no extra sentences).
+- **Otherwise** describe the concrete issues and expectations (e.g. `ElementInternals`, `aria-*` delegation, proposed ID strategies).
+
+## Live regions and announcements (progress, loading, status)
+
+When the component or its docs touch **live regions** or **frequent** status updates:
+
+- Call out **over-announcing** as a risk: docs should **warn** authors not to flood screen reader users.
+- **Never** recommend **`aria-live="assertive"`** for loading or routine progress (interrupts and overwhelms).
+- Treat **`aria-live="polite"`** as **rare**: polite regions still **queue** speech, and **several** components or regions updating together becomes **noisy** (bursts, backlog). Prefer **native role semantics** (e.g. **`progressbar`**) and **one** primary message for related loaders when possible.
+
+See **`progress-circle/accessibility-migration-analysis.md`** for a full example.
+
+## Keyboard and focus
+
+- **If the component is not focusable** in its default, supported use (no Tab stop, not a keyboard widget): the subsection must contain **only** this sentence (no extra bullets or tables):
+
+  `**Not focusable.** Keyboard navigation should skip this component and move to the next focusable element.`
+
+- **If the component is focusable or has a keyboard pattern:** replace with accurate, component-specific guidance (Tab order, keys, roving tabindex, focus trap, etc.).
+
+## Accessibility tree expectations
+
+- Use short subsections or bold lead-ins for variants (e.g. with text, icon-only, determinate vs indeterminate).
+- Describe what assistive technologies should **see**—aligned with implementation.
+
+## Testing
+
+### Automated tests
+
+- Table: **Kind of test** | **What to check** (unit, aXe/Storybook, Playwright ARIA snapshots, contrast, etc.—match what the repo actually uses for that component).
+
+## Summary checklist
+
+- Markdown task list (`- [ ]`) of concrete, verifiable items (stories, docs, tree, focus, tooling).
+
+## References
+
+- Include **WAI-ARIA**, **WCAG 2.2**, **APG “Read me first”** (or equivalent), and the component **rendering-and-styling migration** link at minimum. Add APG pattern links when used in the doc.
+
+## Writing style
+
+- Follow **text-formatting** workspace rules: sentence case for headings (proper nouns such as **ARIA**, **WCAG**, **APG** stay as usual).
+- Prefer plain, scannable wording; avoid duplicating the rendering doc—**link** to it instead.
+- **Verify** behavior and ARIA in **2nd-gen source** before stating what the component exposes.
+
+## Related rules and skills
+
+- **contributor-doc-update.mdc** — when to run `update-nav.js` after heading or structure changes.
+- **component-migration-analysis** skill — for `rendering-and-styling-migration-analysis.md`, not this file.
+- **stories-documentation.mdc** / **stories-format.mdc** — Storybook docs, separate from this contributor planning doc.

.cursor/rules/branch-naming.mdc

@@ -1,5 +1,5 @@
 ---
-description:
+description: Suggests the preferred branch naming format for Spectrum Web Components contributions — lowercase, dash-separated, with a conventional commit type and optional issue number.
 globs:
 alwaysApply: true
 ---

.cursor/rules/contributor-doc-update.mdc

@@ -21,10 +21,10 @@ alwaysApply: false
 
 ## What to do
 
-1. **Run the nav script** from the contributor-docs-nav skill scripts folder (from project root):
+1. **Run the nav script** from the contributor docs script folder (from project root):
    ```bash
-   cd .cursor/skills/contributor-docs-nav/scripts
-   node update-nav.js ../../../../CONTRIBUTOR-DOCS
+   cd CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs
+   node update-nav.js
    ```
 2. **Confirm** the script completes without errors.
 3. **Fix any link verification errors** reported by the script (fix straightforward cases; consult the user for ambiguous ones).