fix(illustrated-message): migrate CSS to S2 tokens by miwha-adobe · Pull Request #6181 · adobe/spectrum-web-components

miwha-adobe · 2026-04-15T20:05:34Z

Description

Migrates illustrated-message CSS from placeholder stubs to full S2 token-based styles. Replaces all @todo SWC-1838 comments with implemented rules covering layout, illustration sizing, heading and description typography, size variants (s, m, l), horizontal orientation, CJK language support, slotted SVG fill handling, and forced-colors support. Also fixes illustration scaling in Storybook stories and consolidates the duplicate cloud SVG path into a shared cloudSvg helper.

Motivation and context

The component CSS was scaffolded with empty @todo stubs pending the S2 token migration. This PR fulfills that migration, aligning the component visually with the S2 Figma designs using tokens from the CSS repo's S2 branch.

Related issue(s)

SWC-1836, SWC-1838

Screenshots (if appropriate)

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.
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

Verify all size variants render correctly
1. Go to the illustrated-message Storybook story
2. Toggle size between s, m, and l
3. Confirm illustration scales (96px for s/m, 160px for l) and typography adjusts accordingly
Verify horizontal orientation
1. Go to the illustrated-message Storybook story
2. Set orientation="horizontal"
3. Confirm illustration and content are side-by-side, content text is start-aligned
Verify forced colors
1. Enable Windows High Contrast mode (or emulate via DevTools)
2. View the illustrated-message component
3. Confirm the illustration renders in CanvasText color and is visible

Device review

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

Accessibility testing checklist

Keyboard (required — document steps below)
1. Go to the illustrated-message Storybook story
2. Tab through the page to the component
3. Confirm the component itself receives no focus (it is non-interactive); focus passes through to any interactive content in the description slot without trapping
Screen reader (required — document steps below)
1. Open the illustrated-message Storybook story with VoiceOver or NVDA
2. Navigate to the component
3. Confirm the decorative illustration is skipped (aria-hidden="true"), and the heading and description are announced in order with correct roles

…nd add heading slot validation

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

…ck a11y tests

…stration scaling

…tor change

github-actions · 2026-04-15T20:11: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-6181

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

Great start here! We might hold until my PR addressing the docs styles merges so we can better validate any slotted typography conflicts.

5t3ph · 2026-04-16T16:53:03Z

@@ -51,31 +152,38 @@
 ::slotted(h5:not([class])),
 ::slotted(h6:not([class])) {


Let's try out the new typography protection technique I shared in Slack! You will need to add a wrapper around the heading slot that holds these styles as part of the update.

Added! Wondering if I implemented that right though haha.

changeset-bot · 2026-04-17T21:30:58Z

⚠️ No Changeset found

Latest commit: 6debf3b

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

…-message-fidelity

…hange event

Resolves conflicts from merging the shared s2 base branch: - 1st-gen: kept getter/setter deprecation warnings per property (heading + description) - 2nd-gen base: kept handleHeadingSlotChange (slotchange-based validation) - 2nd-gen component: kept inline @slotchange binding in render - 2nd-gen CSS: kept full @layer typography + revert-layer implementation - 2nd-gen tests: kept slotchange-based test structure Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

5t3ph

Looking good! Just a couple adjustments.

5t3ph

Nice work!

* 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>

@default

* docs: illustrated message a11y migration docs (#6116) * docs(illustrated-message): add migration plan for SWC-1834 (#6124) * 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 (#6150) * 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) - new size and orientation API (#6155) * 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> * feat(illustrated-message): slot-based heading API + gen1 deprecation (#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> * fix(illustrated-message): migrate CSS to S2 tokens (#6181) * 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> * chore(illustrated-message): conform to code style guides, storybook and 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 * docs(illustrated-message): add 1st-gen to 2nd-gen migration guide (#6192) * 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 * docs(illustrated-message): add 1st-gen to 2nd-gen migration guide * docs(illustrated-message): add consumer migration guide and @cssprop JSDoc tags * docs(illustrated-message): remove stale todo comment from consumer migration guide * docs(illustrated-message): mark all migration phases as complete in the status table * style(illustrated-message): fix prettier formatting in IllustratedMessage.ts * chore(illustrated-message): add changeset for S2 migration * docs(illustrated-message): add @default annotation to size property --------- Co-authored-by: Nikki Massaro <5090492+nikkimk@users.noreply.github.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

miwha-adobe and others added 6 commits April 15, 2026 13:12

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

8455af8

fix(illustrated-message): enable verbose mode for deprecation tests a…

c630b9e

…nd add heading slot validation

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

c825b08

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

fix(illustrated-message): register custom element in stories to unblo…

b1b6d48

…ck a11y tests

fix(illustrated-message): migrate CSS to S2 tokens and fix story illu…

4c07dd4

…stration scaling

fix(illustrated-message): dry up cloud SVG and revert doc-story selec…

64fbb03

…tor change

miwha-adobe requested a review from a team as a code owner April 15, 2026 20:05

miwha-adobe assigned 5t3ph Apr 15, 2026

5t3ph reviewed Apr 16, 2026

View reviewed changes

Base automatically changed from swc-1835-illustrated-message-api-slot-refactor to s2/illustrated-message April 17, 2026 19:07

fix(illustrated-message): address CSS PR feedback

e4643fd

miwha-adobe and others added 5 commits April 17, 2026 15:31

Merge branch 's2/illustrated-message' into miwha/swc-1836-illustrated…

8840e30

…-message-fidelity

refactor(illustrated-message): scope heading slot validation to slotc…

74e5836

…hange event

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

ed72be5

fix(illustrated-message): minor copy tweaks

0c3b177

5t3ph reviewed Apr 20, 2026

View reviewed changes

Comment thread 2nd-gen/packages/swc/components/illustrated-message/illustrated-message.css Outdated

Comment thread 2nd-gen/packages/swc/components/illustrated-message/illustrated-message.css Outdated

rubencarvalho reviewed Apr 20, 2026

View reviewed changes

Comment thread 2nd-gen/packages/core/components/illustrated-message/IllustratedMessage.base.ts Outdated

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

6debf3b

caseyisonit added 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. Status:Ready for re-review PR has had its feedback addressed and is once again ready for review. labels Apr 20, 2026

5t3ph approved these changes Apr 20, 2026

View reviewed changes

miwha-adobe merged commit a1d702c into s2/illustrated-message Apr 20, 2026
30 checks passed

miwha-adobe deleted the miwha/swc-1836-illustrated-message-fidelity branch April 20, 2026 18:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(illustrated-message): migrate CSS to S2 tokens#6181

fix(illustrated-message): migrate CSS to S2 tokens#6181
miwha-adobe merged 13 commits into
s2/illustrated-messagefrom
miwha/swc-1836-illustrated-message-fidelity

miwha-adobe commented Apr 15, 2026

Uh oh!

github-actions Bot commented Apr 15, 2026 •

edited

Loading

Uh oh!

5t3ph left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

5t3ph Apr 16, 2026

Uh oh!

miwha-adobe Apr 17, 2026

Uh oh!

Uh oh!

Uh oh!

changeset-bot Bot commented Apr 17, 2026 •

edited

Loading

Uh oh!

5t3ph left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

5t3ph left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

		@@ -51,31 +152,38 @@
		::slotted(h5:not([class])),
		::slotted(h6:not([class])) {

Conversation

miwha-adobe commented Apr 15, 2026

Description

Motivation and context

Related issue(s)

Screenshots (if appropriate)

Author's checklist

Reviewer's checklist

Manual review test cases

Device review

Accessibility testing checklist

Uh oh!

github-actions Bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

Uh oh!

5t3ph left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

5t3ph Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

miwha-adobe Apr 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

changeset-bot Bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

5t3ph left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

5t3ph left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions Bot commented Apr 15, 2026 •

edited

Loading

changeset-bot Bot commented Apr 17, 2026 •

edited

Loading