Skip to content

Illustrated Message Component Migration#6207

Draft
miwha-adobe wants to merge 12 commits intomainfrom
s2/illustrated-message
Draft

Illustrated Message Component Migration#6207
miwha-adobe wants to merge 12 commits intomainfrom
s2/illustrated-message

Conversation

@miwha-adobe
Copy link
Copy Markdown

Description

Migrates sp-illustrated-message to swc-illustrated-message for Spectrum 2. This includes the full component implementation, CSS token migration, accessibility improvements, and consumer-facing migration documentation.

Key changes:

  • New size (s | m | l) and orientation (vertical | horizontal) attributes
  • Slot-based heading API: heading and description attributes removed; consumers must use <h2><h6 slot="heading"> and <span slot="description">
  • Heading level is now consumer-controlled (1st-gen always rendered <h2>)
  • Illustration accessibility is now consumer-declared (aria-hidden or role="img" + aria-label on the slotted SVG)
  • CSS migrated from --mod-illustrated-message-* to --swc-illustrated-message-* tokens

Motivation and context

Part of the Spectrum 2 component migration workstream. The 1st-gen component had no size or layout control, always rendered a fixed <h2> with no heading level API, and did not give consumers control over illustration accessibility intent.

Related issue(s)

  • SWC-1843

Author's checklist

  • I have read the CONTRIBUTING and PULL_REQUESTS documents.
  • I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
  • 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.

Reviewer's checklist

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

Manual review test cases

  • Consumer migration guide renders in Storybook

    1. Open Storybook and navigate to Components / Illustrated message / Consumer migration guide
    2. Confirm all sections render correctly with no MDX parse errors
  • Heading level is consumer-controlled

    1. Open the swc-illustrated-message Storybook entry
    2. Slot an <h3> into the heading slot
    3. Confirm the DOM reflects <h3>, not a fixed <h2>
  • Size and orientation attributes work

    1. Open the Options stories for swc-illustrated-message
    2. Confirm size="s", size="m", size="l" render at the correct illustration sizes
    3. Confirm orientation="horizontal" switches to a row layout

Device review

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

Accessibility testing checklist

  • Keyboard — No focusable parts on the host. Confirm Tab moves through any interactive elements in the description slot in document order, with no focus traps.

    1. Open the swc-illustrated-message Storybook entry
    2. Tab through the page and confirm focus reaches any slotted links or buttons
    3. Confirm no focus trap and no unexpected focus behavior
  • Screen reader — Heading level, heading text, and description are announced correctly.

    1. Open the swc-illustrated-message Storybook entry with a screen reader active
    2. Navigate to the component and confirm the heading role and level match the slotted element
    3. Confirm the description text is announced and the illustration is silent (aria-hidden)

nikkimk and others added 11 commits April 1, 2026 09:35
* docs(illustrated-message): add migration plan for SWC-1834

* docs(illustrated-message): update migration plan with reviewer feedback for SWC-1834

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* docs(illustrated-message): add size variants s|m|l with m as default per React Spectrum

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(illustrated-message): file structure and initial API pass

* test(illustrated-message): add stories, interaction tests, and a11y spec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(illustrated-message): update a11y snapshot to match current story heading

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(illustrated-message): extract headingClass const and fix Playground illustration slot

* refactor(illustrated-message): remove heading and description attributes, rely on slots only

* refactor(illustrated-message): update stories to use template pattern and simplify API docs

* refactor(illustrated-message): update stories to use html template slot pattern with inline SVG

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(illustrated-message): file structure and initial API pass

* test(illustrated-message): add stories, interaction tests, and a11y spec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(illustrated-message): update a11y snapshot to match current story heading

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(illustrated-message): add size and orientation additive features

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(illustrated-message): re-add size and orientation additive API

* feat(illustrated-message): add size and orientation additive API and css

* fix(illustrated-message): add runtime validation and tighten const types

* test(illustrated-message): add size and orientation attribute/property tests

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
…6173)

* feat(illustrated-message): slot-based heading API + gen1 deprecation

* fix(illustrated-message): enable verbose mode for deprecation tests and add heading slot validation

* feat(illustrated-message): update status to unsupported (SWC-1944)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(illustrated-message): register custom element in stories to unblock a11y tests

* fix(illustrated-message): replace component-level deprecation with property-level warnings

* docs(contributor-docs): add deprecation warning guidance to debug-validation guide

* docs(contributor-docs): rename "Warning structure" to "Deprecation warning structure" for clarity

* fix(illustrated-message): scope heading slot validation to slotchange instead of every updated()

* test(illustrated-message): update heading slot test

* fix(illustrated-message): register slotchange listener unconditionally, guard warn inside method

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(illustrated-message): slot-based heading API + gen1 deprecation

* fix(illustrated-message): enable verbose mode for deprecation tests and add heading slot validation

* feat(illustrated-message): update status to unsupported (SWC-1944)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(illustrated-message): register custom element in stories to unblock a11y tests

* fix(illustrated-message): migrate CSS to S2 tokens and fix story illustration scaling

* fix(illustrated-message): dry up cloud SVG and revert doc-story selector change

* fix(illustrated-message): address CSS PR feedback

* refactor(illustrated-message): scope heading slot validation to slotchange event

* fix(illustrated-message): add Sizes and Orientation option stories

* fix(illustrated-message): minor copy tweaks

* fix(illustrated-message): css selector updates and jsdoc

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
…nd tests (#6191)

* style(illustrated-message): align source, stories, and tests with CONTRIBUTOR-DOCS code standards

* chore(illustrated-message): add SWC-1992 ticket reference to Stackblitz todo

* fix(illustrated-message): scope a11y spec locators to swc-illustrated-message instances
@changeset-bot
Copy link
Copy Markdown

changeset-bot Bot commented Apr 24, 2026

⚠️ No Changeset found

Latest commit: 3c6ab72

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
Copy link
Copy Markdown
Contributor

📚 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-6207

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants