[rubencarvalho]

Description

Four fixes from a structural audit of gen2/, plus two gen2 docs links.

1. @adobe/spectrum-wc no longer bundles workflow icons. The swc library build aliased @adobe/spectrum-wc-icons to its source but didn't mark it external, so dist/icons/src/ shipped a second copy of swc-icon-alert-triangle (used by <swc-text-field>) and the chevron icons (used by <swc-prompt-field>). The build now treats the icons package like core: it's external, and it's a runtime dependency (2.0.0-beta.6, same linked version as core).
2. DEBUG: false set before load is kept. The dev mode setup in core/element/spectrum-element.ts overwrote window.__swc.DEBUG with true. It now keeps a value the page set before the first component loaded, and it skips the "in dev mode" notice when DEBUG is off. The setup moved into an @internal installDevMode() function, which the same NODE_ENV check calls, so a test can run it like a first load.
3. Dev mode warnings link to the right docs page. The linear progress mixin, the pending mixin, and the button base hard-coded one component's page for several elements; they now use componentDocsHref(this.localName). Action group, prompt field, drop zone, status light, the dev mode notice, and the duplicate element warning linked to pages that return 404 or don't exist; they now link to existing pages on spectrum-web-components.adobe.com. The debug validation style guide taught the 404 URL format, so it's updated, and the dev mode guide now explains the duplicate element warning that links to it.
4. Storybook docs pages build the source link and the getting started snippets from the stories file, not the sidebar title. The folder comes from parameters.fileName, the tag from meta.component, and the core entry (controllers or mixins) from where the stories file lives. Pages that don't document a single element show no snippet. The 12 packagePath overrides in the AI Toolkit stories aren't needed anymore.
5. Docs links. The Gen1 agent skill's website now points to spectrum-web-components.adobe.com, like the other two skills published there, and the Build with AI page links to the gen2 llms.txt (it said there wasn't one yet). Links that describe Gen1 itself still point to the Gen1 site, because that content isn't on the gen2 site: the Gen1 Storybook ref in .storybook/main.ts (spectrum-web-components.adobe.com/storybook/ returns 404), the Gen1 column of the docs site row in "Gen1 vs Gen2", and the "Gen1 documentation site" link on the Build with AI page.

Validation

• yarn type-check:gen2: passed, 0 errors.
• ESLint and Prettier on the changed files: clean.
• npx cem analyze --config cem.config.js && npx vitest --run --project storybook on the 12 affected test files in gen2/packages/swc (spectrum-element, dev-validation, progress-bar, meter, action-button, button, close-button, infield-button, action-group, dropzone, status-light, prompt-field): 12 files and 167 tests passed.
• Putting each bug back makes the 4 new or changed assertions fail (Install Dev Mode Test, Enum Warning Docs Link Test, and the action button pending and icon-only warning tests).
• npx vite build in gen2/packages/swc and gen2/packages/icons: swc/dist has no icons/ folder anymore, and it imports @adobe/spectrum-wc-icons/swc-icon-alert-triangle.js, ChevronLeft.js, and ChevronRight.js, which the icons build provides through its ./*.js export.
• Every hard-coded docs URL in gen2 source, checked against https://spectrum-web-components.adobe.com/index.json: only the unused alert-banner base class still links to a missing page (there's no gen2 alert banner).
• A script that runs the new sourceLocation() helper over all 60 stories files: every source folder exists, every registration import and type import resolves, and every controller and mixin export is in its published barrel.
• 7 docs pages rendered in a local Storybook (Drop zone, UI icons, Badge, Prompt field, Workflow icons, Focus group navigation controller, Labelling mixin): source links and snippets are correct.

Cross-model review

• Reviewers: gpt-6.1-sol and gemini-4-argon, as adversarial "merge challenge" reviewers.
• Verdicts: both MERGE. No blocker or major findings.
• Fixed: Gemini's minor finding. OverviewStory read fileName from csfFile.meta and GettingStarted from preparedMeta. Both read preparedMeta now. (Storybook sets fileName on both today, so this was consistency, not a bug.)
• Not changed, Gemini nits:
  • installDevMode() resets issuedWarnings and logs the notice again if it runs twice. It's @internal, not re-exported from the element barrel, and runs once at module load; only the test calls it again.
  • The Workflow icons page would show no getting started snippet if it ever used <DocsHeader />. It doesn't today, and its MDX has its own import examples.
• Both reviewers agreed that the three links describing Gen1 should keep pointing to the Gen1 site.

Motivation and context

• A page that loaded <swc-text-field> and @adobe/spectrum-wc-icons/swc-icon-alert-triangle.js threw NotSupportedError, because the element was defined twice.
• The documented way to turn dev mode off didn't work.
• Warnings sent people to another component's docs or to 404 pages. For example, every <swc-progress-bar> warning linked to the meter docs.
• Docs pages showed imports that fail, such as import '@adobe/spectrum-wc/components/drop-zone/swc-drop-zone.js' and import { FocusGroupNavigationController } from '@adobe/spectrum-wc-core/controllers/focus-group-navigation-controller.js', and "View source on GitHub" opened folders that don't exist on controller, mixin, and pattern pages.

Related issue(s)

• fixes SWC-2740
• Related: fix(progress-circle): derive ring radius from stroke thickness #6911 (SWC-2739, progress circle radius) and fix(core): let PlacementController clear its own inline styles #6912 (SWC-2738, placement controller style cleanup for popover, menu, and tooltip) fix other findings from the same audit of gen2/.

Screenshots (if appropriate)

Not applicable: no visual change to components. Docs snippets, before and after:

Page	Before	After
Drop zone	import '@adobe/spectrum-wc/components/drop-zone/swc-drop-zone.js';	import '@adobe/spectrum-wc/components/dropzone/swc-dropzone.js';
UI icons	import type { UiIcons } …	import type { UiIcon } from '@adobe/spectrum-wc/components/ui-icons';
Focus group navigation controller	import { FocusGroupNavigationController } from '@adobe/spectrum-wc-core/controllers/focus-group-navigation-controller.js';	import { FocusgroupNavigationController } from '@adobe/spectrum-wc-core/controllers';
Labelling mixin	import { LabellingMixin } from '@adobe/spectrum-wc-core/controllers/labelling-mixin.js';	import { LabellingMixin } from '@adobe/spectrum-wc-core/mixins';

---

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

• swc doesn't bundle icon elements

  1. Run yarn build in gen2/packages/swc
  2. Check that dist/icons/ doesn't exist
  3. Expect dist/components/text-field/TextField.js to import @adobe/spectrum-wc-icons/swc-icon-alert-triangle.js

• DEBUG: false set before load turns dev mode off

  1. In a page, set window.__swc = { DEBUG: false }; before importing @adobe/spectrum-wc/components/badge/swc-badge.js
  2. Add <swc-badge variant="banana">Badge</swc-badge>
  3. Expect no "Spectrum Web Components is in dev mode" notice and no variant warning in the console

• Warnings link to the element's own docs

  1. Go to Components > Progress bar > Playground in the local Storybook and open the console
  2. Set label-position to an unsupported value in the console, for example document.querySelector('swc-progress-bar').labelPosition = 'nope'
  3. Expect the warning to link to ?path=/docs/components-progress-bar--docs, not the meter docs

• Docs pages show working imports and source links

  1. Go to Components > Drop zone docs; expect import '@adobe/spectrum-wc/components/dropzone/swc-dropzone.js';, and "View source on GitHub" opens gen2/packages/swc/components/dropzone
  2. Go to Patterns > AI Toolkit > Prompt field docs; expect the source link to open gen2/packages/swc/patterns/ai-toolkit/prompt-field
  3. In the local Storybook, go to Core > Controllers > Focus group navigation controller docs; expect import { FocusgroupNavigationController } from '@adobe/spectrum-wc-core/controllers'; and a source link to gen2/packages/core/controllers/focusgroup-navigation-controller

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 to Components > Text field > Invalid (?path=/story/components-text-field--invalid)
  2. Press Tab into the field
  3. Expect the same focus order as before and the alert icon still shown; no component's keyboard behavior changed in this PR

• 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 to Components > Text field > Invalid with VoiceOver on
  2. Move focus into the field
  3. Expect the label, invalid state, and error text announced as before, with the alert icon not announced; no roles, names, or states changed in this PR

[changeset-bot]

⚠️ No Changeset found

Latest commit: 240afa3

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.

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

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! ✨