chore(thumbnail): api + a11y migration implementation

[cdransf]

Description

Implements Phase 3 (API) and Phase 4 (accessibility) of the Thumbnail 1st-gen → 2nd-gen migration, on top of the Phase 2 file-structure scaffold (#6704).

• ThumbnailBase (core): numeric size getter/setter with warnIf validation (12-value scale, default
  500), mirroring AvatarBase; a fit geontain', default 'contain') replacing1st-gen's coverboolean, matching Asset'sAssetFitnaming;decorativereflected property witharia-hiddensync.background, layer,d selectedare **not** implemented —they're dropped as documentedswc-thumbnail` attributes per the migration plan's decision log (C6, C7, C8), not deferred to a later phase.
• Thumbnail.types.ts (core, new file): THUMBNAIL_VALID_SIZES/THUMBNAIL_DEFAULT_SIZE/ThumbnailSize, THUMBNAIL_VALID_FITS/THUMBNAIL_DEFAULT_FIT/ThumbnailFit.
• Thumbnail (SWC): render() now emits a single fixed structure — <div class="swc-Thumbnail swc-OpacityCheckerboard"><slot></slot></di variant markup. Style changes forsize/fitare driven entirely by:host([size="..."])/:host([fit="..."]) attribute selectors, not template branching. Alt-fallback (alt=""whendecorative) and the missing-altDEBUG warning are implemented here rather than in core, since they need aslotchangelistener on the renderedthat core has norender()` to provide (see decision log Q5
• Updated the component migration plan's checklists and Architecture section to match what's implemented, and added decision log entry Q5 documenting the core/SWC split for the alt-fallback logic.

Motivation and context

SWC-2199 (full S2 visual fidelity / CSS migration) can't proceed without real render() markup and reflected properties for its stylelint-passing CSS to attach to. This PR closes that gap for SWC-2198's API and accessibility phases.

Related issue(s)

• Part of SWC-2198 (Phase 3/API and Phase tructure already in chore(thumbnail): add 2nd-gen file structure and stub component #6704)
• Epic: SWC-2195

Screenshots (if appropriate)

N/A — no CSS changes. thumbnail.css remains the Phase 2 :host { display: block; } stub; visual styling lands in SWC-2199.

Author's checklist

• I have read the
  CONTRIBUTING and**PULL_REQUESTS** documents.
• I have reviewed the Accessibility Practices for this feature, see: Aria Practices
• I have added automated tests to cover my changes. (Testing is Phase 6, tracked separately as SWC-2200.)
• I have included a well-written changeset if my change needs to be published. (Changesets for 2nd-gen migrations land on the final review PR once styling/testing/docs ship, matching the Card 2nd-gen migration precedent — not this intermediate phase.)
• I have included updated documentation if my change required it. (Migration plan checklist, Architecture section, and decision log updated.)

Reviewer's checklist

• Includes a Github Issue with approprumber without a link
• Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
• Automated tests cover all use cases for writing
• Validated on all supported browsers
• All VRTs are approved before the author can update Golden Hash

Manual review test cases

• Numeric size validation

  1. In Storybook, go to Thumbnail → Playground
  2. Set the size attribute to an invalid value (e.g. 999) via devtools
  3. Expect size to fall back to 500 and a dev-mode console warnIf warning naming the valid sizes

• Fit validation

  1. In Storybook, go to Thumbnail → Playground
  2. Set the fit attribute to an invalidvia devtools
  3. Expect fit to fall back to contain and a dev-mode console warnIf warning naming the valid values

• Render structure

  1. Go to Thumbnail → Playground in Storybook
  2. Inspect the shadow DOM
  3. Expect a single <div class="swc-Thumbnail swc-OpacityCheckerboard"> wrapping <slot> — no background/layer-specific markup, since those properties are dropped

• Decorative + alt fallback

  1. Slot an <img> with no alt inside >`
  2. Expect the host to get aria-hidden="true" and the image to get alt=""

• Missing-alt DEBUG warning

  1. Slot an <img> with no alt inside orative`)
  2. Expect a dev-mode console warning directing the author to add alt or set decorative

• Build and lint

  1. Run yarn build in 2nd-gen/packageses/swc
  2. Run lint on the changed files
  3. Expect both to pass with no errors

Device review

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

Accessibility testing checklist

• Keyboard
  Not applicable — swc-thumbnail has no focusable parts in any state (default or decorative).

  1. Go to Thumbnail → Playground in Storybook
  2. Press Tab repeatedly throu
  3. Expect focus to skip over <swc-thumbnail> entirely; confirm no regressions in surrounding Storybook examples

• Screen reader

  1. Go to Thumbnail → Playground in Storybook, enable VoiceOver/NVDA/JAWS
  2. Use browse/scan mode (not focus mode)
  3. Expect the slotted <img alt="Preview"> to announce as an image named "Preview"; the host itself contributes no role or name
  4. Toggle decorative on via the Controls panel
  5. Expect the thumbnail (and its image) to be skipped entirely in the accessibility tree

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2d8fece

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.

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

• Storybook (Gen2, dev mode)
• Storybook (Gen2, prod mode)
• Documentation Site (Gen1)
• Storybook (Gen1)

🔍 Gen1 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-6714

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.

[5t3ph]