fix(swc): style API table typography and render markdown in descriptions

[rubencarvalho]

Description

Before:

(https://spectrum-web-components.adobe.com/?path=/docs/components-tabs--docs#api)

After:

(https://swcpreviews.z13.web.core.windows.net/pr-6524/docs/gen2-storybook-prod/?path=/docs/components-tabs--docs#api)

The Storybook ApiTable block (used on every 2nd-gen component/pattern/controller docs page) rendered its Properties/Slots/Events/CSS Custom Properties/CSS Parts tables at the docs-wide default table font size, and rendered CEM description text as raw strings, so markdown syntax (code spans, links, bold) authored in JSDoc never rendered, and none of the design system's own typography classes were applied.

This PR:

• Adds swc-Body/swc-Body--sizeM to each API table (bumping from 14px to 16px) and scopes the docs-wide generic table font-size override in preview-head.html to exclude these tables (table:not(.swc-ApiTable)).
• Adds swc-Code/swc-Code--sizeS to every <code> cell (property/attribute/slot/event/CSS name and default value).
• Adds swc-Detail/swc-Detail--sizeS to the (reflects) annotation, and swc-Body/swc-Body--sizeM to the empty/error-state fallback messages.
• Renders description fields through Storybook's Markdown block (forceInline: true) instead of interpolating the raw string, so markdown authored in CEM descriptions (code spans, links, bold) now renders.
• Configures Markdown's overrides so emitted <code> spans get swc-Code/swc-Code--sizeS, and wraps output in swc-Typography--prose so links inherit the design system's prose link colors/hover/focus states.

Motivation and context

The API reference tables are the primary technical reference on every component's docs page. They were both harder to read (undersized text, inconsistent with the rest of the docs page) and silently dropped any markdown formatting authored in component JSDoc (e.g. `code` references or links to related components), rendering it as literal asterisks/backticks instead.

Related issue(s)

• fixes docs(storybook): docs cleanup #6495 (comment)

Screenshots (if appropriate)

N/A — text/typography only change, verify visually in Storybook docs for any component (e.g. Badge, Button) under the API section.

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

• API table renders at increased size and description markdown renders

  1. Run Storybook (yarn storybook, in 2nd-gen/packages/swc) and open any migrated component's docs page (e.g. Badge)
  2. Scroll to the API section (Properties/Slots/Events/CSS Custom Properties/CSS Parts tables)
  3. Expect table text visibly larger than before (16px body / 14px code) and, for any property/slot with a JSDoc description containing `code` or a markdown link, expect it to render as an actual <code> span or <a> link rather than literal backticks/brackets

• No regression to other docs tables

  1. Open any docs page and inspect a non-API table (e.g. an argTypes Controls table or a Storybook-native table)
  2. Expect font size unchanged (still the smaller docs-wide default), since the override now only excludes .swc-ApiTable

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)

  • Not applicable: this change only affects static, non-interactive reference tables and prose text (font size, typography classes, and markdown rendering of description text). No focusable elements are added, removed, or reordered. Confirm no regressions in keyboard navigation through the surrounding docs page (Tab order into/out of the API section unchanged).

• Screen reader (required — document steps below)

  1. Open a component's docs page in Storybook and navigate to the API section with a screen reader active (e.g. VoiceOver)
  2. Read through a Properties table row where the description contains a markdown link (e.g. cross-references to another component)
  3. Expect the link to be announced as a link with its accessible name (not read as literal [text](url) markdown), and expect table structure (row/column headers, cell content) to be announced correctly and unchanged from before this change

[changeset-bot]

⚠️ No Changeset found

Latest commit: d70fcf1

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

• 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-6524

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.

[rubencarvalho]

At some point we need to take a look at this preview-head styles, this needs some love.

[5t3ph]

Just a note I looked into this previously and could not find a way to load a stylesheet separately, hence why it all lives in the HTML :( And the way Storybook applies it's own styles makes some of this trickier than necessary too, leading to the use of scope and some of the other funny looking stuff.

[pfulton]

Are we able to import a separate stylesheet, ala: https://github.com/adobe/spectrum-css/blob/37620864c60c4c142a506017e1a15348a26abb0e/.storybook/preview.js#L18 ? Importing from files kept here: https://github.com/adobe/spectrum-css/tree/main/.storybook/assets

[5t3ph]

Thanks for addressing this!

[pfulton]

Yes, thank you for doing this. It looks much better.