style(conversation-ai): define WHCM, typography utils, CSS patterns

[aramos-adobe]

Description

This PR focuses on the UI and styling of the conversational AI components which include:

• WHCM
• Visual regressions
• Making sure CSS follows the 2nd gen guidelines and token rules

Motivation and context

#6170 The goal here is to continue refining the conversational AI work and have 100% parity between the design and engineering work done in the UI.

Figma

React Spectrum Prototype

Related issue(s)

• fixes [SWC-2051]
• fixes [SWX-2058]

Screenshots (if appropriate)

---

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

• Prompt field — This PR: 1px solid transparent on the field shell and toolbar buttons so dimensions stay stable under forced-colors.

  1. Open Patterns → Conversational AI → Prompt field → Playground; skim Modes and Artifact.
  2. Tab through the text area and trailing actions (attach, send, mic, overflow, etc.); confirm each focused control shows a visible focus ring in the default theme and under forced-colors.
  3. Confirm the composed field still reads as one surface (no accidental double outlines except where the design calls for emphasis).

• Upload artifact — This PR: tokenized gray thumbnail surfaces, transparent borders on card/media/dismiss, overflow: hidden on the media surface; Playground swaps the thumbnail slot when type is card vs media; Media story shows optional title/subtitle under the preview.

  1. Open Upload artifact → Playground: change type between card and media and confirm the thumbnail region matches each layout.
  2. Open Card and Media; confirm thumbnails use token grays (no ad-hoc gradient), dismiss control alignment is correct, and Media shows slotted title/subtitle beneath the preview when provided.
  3. Tab to the dismiss control; verify focus in default and forced-colors.

• Response status — No CSS in this diff; regression.

  1. Open Response status → Playground, Loading, or Reasoning.
  2. Confirm typography, disclosure behavior, and spacing still match expectations next to other conversational patterns.

• Message feedback — This PR: transparent borders on buttons; @media (forced-colors: active) sets outline-color: CanvasText on :focus-visible.

  1. Open Message feedback → Playground or Status.
  2. Activate positive/negative via pointer and keyboard; confirm selected/hover token backgrounds and that focus in HC follows system text color.
  3. Toggle selection; no layout shift from border width changes.

• Message sources — Regression.

  1. Open Message sources → Playground or Open.
  2. Expand/collapse; confirm row spacing, chevrons, and focus on triggers are unchanged.

• Conversation turn — Regression.

  1. Open Conversation turn → Playground or Overview.
  2. Confirm system vs user regions still stack and align with thread spacing.

• User message — This PR: transparent border on the bubble for sizing under forced-colors.

  1. Open User message → Playground (and Content if you rely on rich examples).
  2. Compare the bubble edge in default vs forced-colors; nested focusables should not clip.

• Suggestion item — This PR: transparent border; forced-colors outline-color: CanvasText on :focus-visible.

  1. Open Patterns → Conversational AI → Suggestion group → Suggestion item → Playground (nested story).
  2. Hover, focus, and activate; chip should stay legible in HC when focused.

• Suggestion group — Regression (contains suggestion items).

  1. Open Suggestion group → Playground or Suggestion count.
  2. Tab through chips; heading + grid alignment should match prior behavior.

• System message — Stories / demo: rich slot content uses swc-Typography--prose; system-prose-demo.css removed.

  1. Open System message → Playground, Loading, and any story with prose + lists.
  2. Confirm heading hierarchy and list rhythm look intentional (no oversized inline headline styles left in the demo) and slotted Response status still reads coherently.

• Conversation thread — This PR: vertical gap uses token("spacing-100") instead of a 16px fallback.

  1. Open Conversation thread → Playground or Full pattern.
  2. Compare spacing between stacked turns; it should follow the token scale across themes.

Device review

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

Accessibility testing checklist

Required: Complete each applicable item and document your testing steps (replace the placeholders with your component-specific instructions).

• Keyboard (required — document steps below) — What to test for: Focus order is logical; Tab reaches the component and all interactive descendants; Enter/Space activate where appropriate; arrow keys work for tabs, menus, sliders, etc.; no focus traps; Escape dismisses when applicable; focus indicator is visible.

  1. Go here
  2. Do this action
  3. Expect this result

• Screen reader (required — document steps below) — What to test for: Role and name are announced correctly; state changes (e.g. expanded, selected) are announced; labels and relationships are clear; no unnecessary or duplicate announcements.

  1. Go here
  2. Do this action
  3. Expect this result

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2ab63a5

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

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 progress on this!

A few general comments (numbered for ease of reference in replies):

1. Suggest updating the "full pattern demo" block size to 90vb vs. 100vb so it is more likely to fit in the viewable area for the sake of the story.
2. Will you update buttons to use the button component when it's available? It would be good not to have multiple extra components and a unified styling surface. I think the variants and icon support cover your needs.
3. Throughout stories, you could update the sublabel for variants within the same story to use swc-Detail swc-Detail--sizeS classes instead of inline styles.
4. Multi-artifact examples feel hidden on the Prompt Field page. Perhaps show how to populate that area there, then link over to Upload Artifact and show even more examples of multi-artifact display there? That would help us validate styles for more mutations, too.
5. For artifacts:
   a. We should make background-image more explicitly supported and document assigning it, possibly via an explicit attribute. This would support consumers injecting a derived thumbnail, as for 5.c.
   b. We need to test/show support of a slotted image, not just the styled divs, as those require different styles.
   c. Maybe a question to design or for the backlog: do we need to anticipate video upload, and capturing a frame to use as the thumbnail?
   d. We really should support a "loading" state with injecting the progress circle until it's swapped with a thumbnail.

[rise-erpelding]

A few comments!

I noticed the disclosure fixes come in as I was reviewing, those look nice!

Also, one thing that didn't touch the code here that I noticed: conversation-turn.css sets up a container query that doesn't appear to be used (container-name: swc-conversation-turn;), is it still needed?

[5t3ph]

GitHub didn't save some of my comments yesterday, so a few more things!

[rubencarvalho]

LGTM!! However I can't verify WHCM (my browserstack isn't working)

[rubencarvalho]

just curious, do we need display: none on the hidden attribute?

[aramos-adobe]

@rubencarvalho Yes we do. @5t3ph called this one out. This container renders in the DOM at zero height and full width before any artifacts is uploaded without this CSS modification.

[5t3ph]

yup! the browser rule on [hidden] is weak specificity, and so the display applied for this class prevents it actually working, so we have to strengthen it. Strictly speaking it could be attached to the attribute and not need to repeat the class since !important is... well... the important part 😅

[rise-erpelding]

A nit, we need a transparent border here too if we want to see the outline in WHCM:

[5t3ph]

yup! the browser rule on [hidden] is weak specificity, and so the display applied for this class prevents it actually working, so we have to strengthen it. Strictly speaking it could be attached to the attribute and not need to repeat the class since !important is... well... the important part 😅

[5t3ph]

Just a few last things!

[5t3ph]

I was going to suggest moving the inline styles for your thumbnails (that aren't providing style like hte gradients) to prompt-field.css but it looks like you do have some styles there that these are repeating. Try removing all inline styles that aren't instance-specific, I think your ::slotted() styles have you covered.

[5t3ph]

A couple adjustments to the typography considerations.

[rise-erpelding]

There are at least a couple of instances here of this background color being set inline, but it looks like the CSS styles it as --swc-gray-100 in upload-artifact.css, do we want to fall back to that instead of using the inline style?

[rise-erpelding]

Does the class swc-conversationalAi-systemProse do anything? I think those styles were removed, right? It might be a good idea to clean this up a little.