feat(link): 2nd-gen template, stories, styling

[aramos-adobe]

Description

Implements Phases 2–5 of the Link 2nd-gen migration (washing-machine workflow): setup, public API direction, accessibility policy documentation, and S2 styling. Phase 6 (testing) and full Phase 7 (documentation) are not in scope — Storybook stories, migration guide, and Typography cross-links are included only as a visual validation scaffold and will be refined in a follow-up PR along with dedicated a11y verification and automated tests.

Link is an atypical migration: there is no swc-link custom element and no core package. Delivery is CSS + native <a href>, aligned with migration plan and PR 6304 packaging review.

2nd-gen files added or updated (2nd-gen/packages/):

Stylesheets

• swc/stylesheets/link.css — S2 link presentation migrated from spectrum-css spectrum-two (components/link/index.css); BEM modifiers (.swc-Link, --secondary, --quiet + --standalone, --staticWhite, --staticBlack, --inline); --swc-* custom properties (no --mod-*)
• swc/stylesheets/global/global-link.css — opt-in baseline for bare <a> (no cascade layer; imports link.css for modifiers)
• swc/stylesheets/typography.css — regenerated; default anchor rules for .swc-Typography--prose and .swc-Typography--links via :where(a)
• tools/swc-tokens/src/typography.js — generator appends prose/links anchor block (no @import of link.css into typography)

Documentation (scaffold — Phase 7 follow-up)

• swc/components/link/migration-guide.mdx — sp-link → native <a>, import paths, attribute→class mapping, a11y policy callouts
• swc/components/link/stories/link.stories.ts + link.template.ts — Playground + option stories for standalone / prose / link-list contexts (visual review only)
• swc/components/typography/migration-guide.mdx — links section; cross-link to Link guide
• swc/components/typography/stories/typography.stories.ts — inline link in Prose story; LinkList story (swc-Typography--links)

Packaging / Storybook

• swc/package.json — exports for link.css and global-link.css
• swc/.storybook/preview.ts — imports link.css
• swc/.storybook/preview-head.html — .link-samples layout utilities

Motivation and context

Part of the 1st-gen → 2nd-gen component migration workstream. Epic SWC-1956.

Key architectural decisions in this PR (see migration plan for full rationale):

• CSS + native <a> only — no transitional sp-link / CE; prose and link lists use Typography wrappers
• link.css holds explicit BEM modifiers; typography.css (generator) supplies default unclassed anchor appearance inside .swc-Typography--prose and .swc-Typography--links with :where(a) so modifier classes can override
• global-link.css is opt-in for app-wide bare <a> baseline — not bundled in swc.css, intentionally outside cascade layers
• Quiet requires .swc-Link--quiet.swc-Link--standalone (section-scoped pattern; not for undifferentiated body prose)
• Inline is internal/CSS-level (inherit in prose); not an author-facing variant like 1st-gen
• No disabled on navigational links — documented in migration guide (SWC-966)

Related issue(s)

• Epic SWC-1956
• Packaging direction from PR 6304 review

Out of scope (follow-up PR)

• Phase 6: Playwright / Storybook a11y specs, VRT, prose + static-color regression coverage
• Phase 7 (complete): story JSDoc polish, contributor-docs updates, full manual a11y test documentation
• Phase 8: status table, changeset (if needed on merge), peer sign-off checklist completion
• Additive: trailing icon (A3) — Design / React sync

Manual review test cases

Stylesheets

• Import @adobe/spectrum-wc/link.css and @adobe/spectrum-wc/typography.css; confirm standalone .swc-Link modifiers (default, secondary, static white/black, quiet+standalone) match S2 intent
• Inside .swc-Typography--prose, unclassed <a href> inherits body typography and shows default link color/underline/focus ring
• Inside .swc-Typography--links, three list links render with default styling (Typography Link list story and Link Link list story)
• Optional: import @adobe/spectrum-wc/global-link.css — bare <a> without classes pick up standalone link presentation

Generator / packaging

• yarn workspace @adobe/spectrum-wc stylesheet:typography regenerates typography.css with the prose/links :where(a) block; no @import of link.css in typography output
• yarn workspace @adobe/spectrum-wc build emits dist/link.css and dist/global-link.css

Storybook scaffold (visual only)

• Components → Link → Playground — controls for variant, context (standalone / prose / links), size, quiet, inline
• Option stories render without console errors; treat copy/JSDoc as draft

Migration docs

• Link migration guide accurately maps sp-link attributes to BEM classes and Typography import paths
• Typography migration guide links section does not duplicate the full Link story catalog

Accessibility testing checklist

Full keyboard and screen reader testing is deferred to the Phase 6/7 follow-up PR (native <a> behavior, focus-visible in prose, quiet usage scope). Reviewers can verify policy direction from docs/code:

• Migration guide states: real <a href> for navigation; no disabled on links; quiet scoped to section patterns; icon-only links need accessible names
• Prose/links default styles use :focus-visible outline (not deprecated double-underline-only focus from 1st-gen)
• No sp-link / shadow-DOM focus delegation — activation target is the author’s native anchor

[changeset-bot]

⚠️ No Changeset found

Latest commit: 060ffbb

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

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.

[cdransf]

Looks good! Just a few minor things. ✨

[5t3ph]

Great start here!

The comments I have on link would apply to global-link as well.

[5t3ph]

Getting close!

[5t3ph]

Looks like this removal was missed

[5t3ph]

The output is looking good! The biggest thing is the typography generator needs updated.

Also I realized this is going to main but the PR description notes that documentation and tests are not complete. Would you prefer to finish those now, or aim this at a feature branch instead?

[5t3ph]

This can be removed as it's the browser default

[5t3ph]

The typography stylesheet is correct but it looks like it was manually edited instead of the generator being updated. Please sync the updates we made to the output to how the generator is creating those rules otherwise they will change on the next tokens update.