feat(storybook): testing grid WIP

[aramos-adobe]

Description

Adds a Spectrum CSS–style Storybook testing grid for 2nd-gen SWC, with Button as the reference implementation. The grid is used for local VRT preview and Chromatic captures, separate from docs-friendly single-instance stories.

Storybook infrastructure

• testing-grid.ts — Lit helpers ported from Spectrum CSS utilities.js: Container, States, ArgGrid, Sizes, Variants, renderContent, isChromatic().
• testing-preview.ts decorator + Testing preview toolbar global (beaker icon) — maps to parameters.showTestingGrid, matching Spectrum CSS behavior.
• main.ts — Play-function tests stay under **/test/*.test.ts; VRT case lists live in stories/*.test.ts (imported by *.stories.ts, not indexed as separate CSF files).
• Docs in .storybook/helpers/README.md for the stories/*.template.ts + stories/*.test.ts pattern.

Button reference implementation

• button.template.ts — Pure Lit template for grid cells (avoids @wc-toolkit/storybook-helpers template(), which calls useArgs() per cell and triggers React “Rendered more hooks…” errors in large grids).
• button.test.ts — VRT case list (testData, interaction stateData) imported by stories; not a standalone Storybook entry.
• button.stories.ts — Testing grid story wired to ButtonGroups.
• Grid layout — Grouped by variant (Primary → Secondary → Accent → Negative); within each variant, columns for Default / Disabled / Hovered / Focused / Active / Pending, then fill-style × content (label, icon+label, icon-only). Static white/black sections only show primary and secondary (static-color API limit).
• VRT-only component hooks (Storybook/Chromatic, not public API):
  • vrt-state="hover" | "focus" | "active" — forces pseudo-state visuals via .is-hover, .is-focus-visible, .is-active classes (mirrors Spectrum CSS).
  • vrt-pending-active — skips the 1s pending delay for snapshot capture.
• global-button.css — Updated with the same forced-state selectors for global button styling.

Other

• Restored response-status.stories.ts (accidentally removed on branch).
• Minor color-loupe story fix (static button import vs loader).
• Minor a11y-helpers change (customElements.whenDefined).

---

Motivation and context

Spectrum CSS uses a testing grid (Variants, ArgGrid, toolbar toggle) for comprehensive Chromatic VRT. 2nd-gen SWC had hand-rolled option stories (Sizes, Variants, etc.) but no shared grid or Chromatic-oriented layout. This PR establishes the shared helper layer and proves the pattern on Button.

---

How to test

Local Storybook

cd 2nd-gen/packages/swc
yarn storybook

1. Open Button → Testing grid (dev-only story).
2. In the toolbar, open the beaker menu → Show testing preview.
3. Confirm the full matrix appears (data-testing-preview wrapper with bordered sections).
4. Toggle back to Default mode — single preview in data-html-preview (docs-style).
5. Spot-check:
   • Primary / Secondary / Accent / Negative sections, each with state columns.
   • Static white / Static black — only Primary + Secondary.
   • Sizing row at the bottom.
   • Hovered / Focused / Active rows show forced visuals (not real pointer/focus).

Chromatic / PR preview

• 2nd-gen Storybook preview
• Label run_vrt is on the PR for 2nd-gen Chromatic when ready.

Regression spot-checks

• Button docs stories (Playground, Sizes, Variants, etc.) — unchanged behavior.
• Color loupe → Parent driven visibility — still renders trigger button.
• No production API change intended beyond VRT-only attributes on swc-button.

---

Screenshots

Add Testing grid + Testing preview on/off screenshots before review.

---

Open questions for the team

1. vrt-state / vrt-pending-active on swc-button — Acceptable as dev-only reflected attributes, or should forced states live entirely in Storybook CSS (no component API)?
2. Default story for Chromatic — Should Testing grid become the Chromatic default for Button (like Spectrum CSS Default = ButtonGroups), or stay a separate dev story while Playground remains docs default?
3. Rollout order — Which 2nd-gen components should adopt grids next? (Badge, Status light, and other variant-heavy components are likely candidates.)
4. Changeset scope — Patch @adobe/spectrum-wc for Storybook helpers only, or also document the Button VRT attributes in contributor docs?
5. CONTRIBUTOR-DOCS — Unrelated deletions were reverted on this branch before review.

---

Known gaps / follow-ups

Gap	Notes
Single reference component	Only Button has *.test.ts + grid; pattern not yet applied elsewhere.
No automated grid tests	Grid is visual/Chromatic-only; no storybook test-runner coverage for matrix structure.
Accent / Negative + outline	Grid still renders outline column for all variants; component warns and falls back — filter fill-style per variant?
Pending row timing	vrt-pending-active is a test hook; real 1s delay not exercised in grid.
Global vs shadow styles	Forced-state classes on internal .swc-Button; global-button.css duplicated selectors — keep in sync via codegen (already the case).
Unrelated diff noise	a11y-helpers / color-loupe tweaks could still be split into a separate PR if reviewers prefer.
No changeset yet	changeset-bot flagged missing changeset — add before merge if we publish Storybook/helper changes.

---

Author's checklist

• I have read the CONTRIBUTING and PULL_REQUESTS documents.
• I have reviewed Accessibility Practices for this feature (N/A for Storybook infra; Button VRT attrs are display-only).
• I have added automated tests to cover my changes.
• I have included a well-written changeset if my change needs to be published.
• I have included updated documentation if my change required it (helpers README added; contributor guide TBD).

---

Reviewer's checklist

• Focus review on .storybook/helpers/testing-grid.ts, testing-preview.ts, and button.test.ts / button.template.ts.
• Validate Testing grid in PR Storybook preview with Testing preview enabled.
• Approve 2nd-gen Chromatic run when run_vrt label is applied.

Manual review test cases

• Testing grid — Button

  1. Open PR 2nd-gen Storybook → Button → Testing grid
  2. Enable toolbar Testing preview → Show testing preview
  3. Expect variant-grouped matrix with state columns and Sizing section; static sections show Primary/Secondary only.

• Testing preview toggle

  1. Same story, toggle Default mode
  2. Expect single button preview (no matrix).

Device review

• Desktop (primary target for Storybook review)
• Mobile / iPad (optional — grid is desktop-oriented VRT)

Accessibility testing checklist

N/A for Storybook infrastructure. If reviewing Button vrt-* attributes: they only affect visual presentation in Storybook and do not change runtime a11y behavior for consumers.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2139f56

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]

📚 Branch Preview Links

• Documentation Site (first-gen)
• Storybook (first-gen)
• Storybook (second-gen)

🔍 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:

• Spectrum | Light | Medium | LTR
• Spectrum | Dark | Large | RTL
• Express | Light | Medium | LTR
• Express | Dark | Large | RTL
• Spectrum-two | Light | Medium | LTR
• Spectrum-two | Dark | Large | RTL
• High Contrast Mode | Medium | LTR

Deployed to Azure Blob Storage: pr-6317

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.