### AI Migration Guide Generation Command

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/13_writing-migration-guides.md

Demonstrates the command-line interface for invoking the AI assistant to generate a migration guide for a specified component.

```bash
/consumer-migration-guide [component-name]
```

--------------------------------

### Clone the SWC repository

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/03_working-in-the-swc-repo.md

Use this command to get a local copy of the Spectrum Web Components repository. Ensure Git is installed.

```bash
git clone https://github.com/adobe/spectrum-web-components.git
```

--------------------------------

### Install dependencies with Yarn

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/03_working-in-the-swc-repo.md

After cloning the repository, navigate into the directory and run this command to install all necessary project dependencies using Yarn.

```bash
cd spectrum-web-components
yarn install
```

--------------------------------

### Basic FocusgroupNavigationController Setup

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/14_focus-management.md

Demonstrates the basic setup of FocusgroupNavigationController within a custom element, including how to provide items and handle active item changes.

```typescript
import { FocusgroupNavigationController } from '@spectrum-web-components/core/controllers';
import { SpectrumElement } from '@spectrum-web-components/core/element';

class SpTabs extends SpectrumElement {
  private navigation = new FocusgroupNavigationController(this, {
    getItems: () => [...this.querySelectorAll('sp-tab')] as HTMLElement[],
    direction: 'horizontal',
    wrap: true,
    // Auto-select tab on arrow key navigation
    onActiveItemChange: (tab) => {
      if (this.auto && tab) {
        this.selectTab(tab);
      }
    },
  });

  protected override firstUpdated(): void {
    super.firstUpdated();
    this.navigation.refresh();
  }

  // Expose the active item for external focus management
  get focusElement(): HTMLElement | null {
    return this.navigation.getActiveItem();
  }
}
```

--------------------------------

### Migration Guide File Location

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/13_writing-migration-guides.md

Specifies the standard directory structure for migration guides within the 2nd-gen Spectrum Web Components project.

```bash
2nd-gen/packages/swc/components/[component-name]/migration-guide.mdx
```

--------------------------------

### Changeset with Consumer Action Example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/15_changelog-strategy.md

A full changeset example demonstrating how to describe a change and include a 'Consumer action:' note when necessary. This format is used for user-visible impacts.

```markdown
---
'@adobe/spectrum-wc': minor
---

`Avatar` — Removed `href` link mode. Consumer action: wrap in a native `<a>` instead.
```

--------------------------------

### Mixin depth examples

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/13_mixin-composition.md

Examples demonstrating acceptable mixin depth versus scenarios requiring refactoring to controllers.

```ts
// Depth 2: SizedMixin → ObserveSlotText → SpectrumElement
export abstract class StatusLightBase extends SizedMixin(
  ObserveSlotText(SpectrumElement),
  { noDefaultSize: true }
) {
```

```ts
// Depth 3: SizedMixin → ObserveSlotText → ObserveSlotPresence → SpectrumElement
// @todo review — exceeds target depth of 2
export abstract class BadgeBase extends SizedMixin(
  ObserveSlotText(ObserveSlotPresence(SpectrumElement, '[slot="icon"]'), ''),
  { noDefaultSize: true }
) {
```

```ts
// ❌ Too deep — 3 mixins
FocusableMixin(ValidatableMixin(LocaleMixin(SpectrumElement)))

// ✅ Better — 2 mixins + 1 controller
export abstract class MyComponentBase extends FocusableMixin(
  ValidatableMixin(SpectrumElement)
) {
  private localeController = new LanguageResolutionController(this);
}
```

--------------------------------

### FocusgroupNavigationController Usage Example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/03_project-planning/05_strategies/focus-management-strategy-rfc.md

Provides an example of how to instantiate and use the `FocusgroupNavigationController` to manage focus within a group of elements.

```typescript
import {
    FocusgroupNavigationController,
    FocusgroupControllerOptions,
} from '@spectrum-web-components/reactive-controllers/src/FocusgroupNavigationController.js';

const options: FocusgroupControllerOptions = {
    // ...
};

const controller = new FocusgroupNavigationController(this, options);

// ...

controller.destroy();
```

--------------------------------

### Install Pre-release Version

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/06_releasing-swc.md

Install a pre-release version of a package using a specific dist-tag like 'next' or 'beta'. This is useful for testing upcoming versions before a stable production release.

```bash
yarn add @spectrum-web-components/button@next
yarn add @spectrum-web-components/button@beta
```

--------------------------------

### 1st-Gen Opacity Checkerboard Consumer Example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/03_project-planning/03_components/opacity-checkerboard/migration-plan.md

Example of how a consumer would apply the opacity checkerboard class to an element within its own shadow DOM. This demonstrates the CSS-only nature of the 1st-gen tool.

```html
<!-- consumer applies the class to an element inside its own shadow root -->
<div class="opacity-checkerboard"></div>
```

--------------------------------

### HTML Example for Badge Component

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md

Demonstrates basic usage of the swc-badge component with a simple text label.

```html
<swc-badge variant="positive">New</swc-badge>
```

--------------------------------

### TypeScript Example for Component Lifecycle Method

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md

Illustrates documenting a component's lifecycle method, such as 'updated', using a fenced code block within @example.

```typescript
/**
 * @example
 * ```typescript
 * protected override updated(changes: PropertyValues): void {
 *   // ...
 * }
 * ```
 */
```

--------------------------------

### Comprehensive Concrete Class JSDoc Example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md

Demonstrates a more detailed JSDoc for a concrete component class, including @element, @property, @example, and slot usage.

```typescript
/**
 * @element swc-badge
 *
 * @property {string} variant - The visual variant of the badge.
 * @property {boolean} subtle - Whether the badge uses subtle styling.
 *
 * @example
 * <swc-badge variant="positive">New</swc-badge>
 *
 * @example
 * <swc-badge variant="neutral" fixed="fill">
 *   <sp-icon-checkmark slot="icon"></sp-icon-checkmark>
 *   Verified
 * </swc-badge>
 */
export class Badge extends BadgeBase {
```

--------------------------------

### Install Stylelint Header Plugin

Source: https://github.com/adobe/spectrum-web-components/blob/main/linters/stylelint-header-plugin/README.md

Add the stylelint-header-plugin as a dev dependency using the workspace protocol.

```json
{
  "devDependencies": {
    "@spectrum-web-components/stylelint-header-plugin": "workspace:*"
  }
}
```

--------------------------------

### Install Snapshot Release

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/06_releasing-swc.md

Install a snapshot version of a package for testing purposes. Snapshot releases are published under the 'snapshot-test' dist-tag and do not affect the 'latest' tag.

```bash
yarn add @spectrum-web-components/button@snapshot-test
```

--------------------------------

### Automated CHANGELOG Output Example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/15_changelog-strategy.md

This is an example of the automatically generated CHANGELOG output at release time. It groups changes by type (Minor, Patch) and includes PR and commit references.

```markdown
## 2.1.0

### Minor Changes

- [#6210](https://github.com/adobe/spectrum-web-components/pull/6210) [`a1b2c3d`](https://github.com/adobe/spectrum-web-components/commit/a1b2c3d) - `Button` — Added wiggle radius to button.

### Patch Changes

- [#6285](https://github.com/adobe/spectrum-web-components/pull/6285) [`e4f5g6h`](https://github.com/adobe/spectrum-web-components/commit/e4f5g6h) - `Badge` — Fixed contrast ratio in dark theme for `notice` variant.
```

--------------------------------

### DisabledMixin Example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/03_project-planning/05_strategies/focus-management-strategy-rfc.md

Demonstrates how to use the `DisabledMixin` to manage the disabled state of a component.

```typescript
import {
    DisabledMixin,
    Constructor,
} from '@spectrum-web-components/reactive-controllers/src/DisabledMixin.js';

class MyElement extends DisabledMixin(HTMLElement as Constructor<HTMLElement>) {
    // ...
}

customElements.define('my-element', MyElement);
```

--------------------------------

### Complex HTML Example for Badge Component

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md

Shows a more complex swc-badge usage with an icon slot and a 'fill' fixed attribute.

```html
<swc-badge variant="neutral" fixed="fill">
  <sp-icon-checkmark slot="icon"></sp-icon-checkmark>
  Verified
</swc-badge>
```

--------------------------------

### Relative Link Example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/07_authoring-contributor-docs/README.md

When linking to other documentation files, use relative paths and always link to the specific file, not the folder.

```markdown
[Workstreams](../../03_project-planning/02_workstreams/README.md)
```

--------------------------------

### StatusLight Component JSDoc Example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md

Example JSDoc for the base class of a StatusLight component, including a slot declaration.

```typescript
/**
 * A status light is a great way to convey semantic meaning...
 *
 * @slot - The text label of the status light.
 */
export abstract class StatusLightBase extends SizedMixin(...)
```

--------------------------------

### Conventional Commits Examples

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/04_making-a-pull-request.md

Examples of conventional commit messages, including feature, fix, documentation, and breaking changes.

```git
feat(sp-card): add shadow styles for theme consistency
```

```git
fix(sp-action-menu): correct arrow key navigation in nested menus
```

```git
docs: clarify how to submit bug reports
```

```git
feat(sp-button)!: change API for icon placement
```

--------------------------------

### Start Storybook for development

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/03_working-in-the-swc-repo.md

Launches Storybook for both 1st-gen and 2nd-gen Spectrum Web Components, opening a browser tab for each. Use this for interactive component development and documentation.

```bash
yarn start
```

--------------------------------

### Badge Component JSDoc Example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md

Example JSDoc for the base class of a Badge component, including attribute and slot declarations.

```typescript
/**
 * A badge is a non-interactive visual indicator used to highlight
 * a status, category, or other metadata.
 *
 * @attribute {ElementSize} size - The size of the badge.
 *
 * @slot - Text label of the badge.
 * @slot icon - Optional icon that appears to the left of the label
 */
export abstract class BadgeBase extends SizedMixin(...)
```

--------------------------------

### Validation Example in update()

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/06_method-patterns.md

An example of validation logic within the `update()` method for a Badge component. It checks if the variant property is valid during debug mode.

```typescript
protected override update(changedProperties: PropertyValues): void {
  super.update(changedProperties);
  if (window.__swc?.DEBUG) {
    const constructor = this.constructor as typeof BadgeBase;
    if (!constructor.VARIANTS.includes(this.variant)) {
      window.__swc.warn(this, /* ... */);
    }
  }
}
```

--------------------------------

### Method Ordering Example in Implementation Section

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/06_method-patterns.md

Demonstrates the recommended order of public, protected, and private methods within the IMPLEMENTATION section, with an exception for private methods used exclusively by lifecycle hooks.

```typescript
protected override firstUpdated(changes: PropertyValues): void { ... }

private formatProgress(): string { ... }

protected override updated(changes: PropertyValues): void { ... }
```

--------------------------------

### Tooltip Migration Sequencing

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/03_project-planning/03_components/tooltip/migration-plan.md

Details the migration sequencing and prerequisites for the Tooltip component, emphasizing dependency-aware recommendations.

```markdown
### Migration sequencing and prerequisites

### Dependency-aware recommendation

Core tooltip (variants, CSS, `role="tooltip"`, event renames) can proceed without prerequisites. Automatic trigger integration is additive and blocked on two controller extractions from the Overlay RFC:

- **`PlacementController`** — Floating UI wrapper for viewport-aware positioning (`offset`, `flip`, `shift` middleware). Must be extracted before automatic trigger positioning ships.
- **`HoverController`** — warm-up/cooldown, focus parity, WCAG 1.4.13 pointer bridge. Must be extracted before automatic trigger open/close behavior ships.

Neither controller is available yet. The automatic trigger integration additive phase should not begin until both are ready. Track their extraction status before scheduling the additive implementation ticket.

### Related components and ordering notes

| Component | Relationship | Notes | 
| --------- | ------------ | ----- |
| `PlacementController` | Prerequisite for automatic trigger integration additive phase | Viewport-aware positioning (`offset`, `flip`, `shift`). Tip element centering is CSS-only; no arrow middleware needed. To be extracted per Overlay RFC. Not a prerequisite for the core tooltip migration. |
| `HoverController` | Prerequisite for automatic trigger integration additive phase | Hover/focus event wiring, warm-up/cooldown timing, and WCAG 1.4.13 pointer bridge. To be extracted from `@spectrum-web-components/overlay`. Not a prerequisite for the core tooltip migration. |
| `sp-overlay` | Not a prerequisite | 2nd-gen Tooltip and controllers replaces `sp-overlay` with native popover API + Floating UI directly. |
```

--------------------------------

### Direct Warning Spy Setup with `setupSwcWarningSpy`

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/04_testing/05_testing-utilities.md

Use `setupSwcWarningSpy` for lower-level access to `swcGlobals` when direct control over the warning spy is needed. Remember to manually call `restore()` in a `finally` block.

```typescript
import { setupSwcWarningSpy } from '../../../utils/test-utils.js';

const { warnCalls, restore } = setupSwcWarningSpy();
try {
  badge.variant = 'invalid' as Badge['variant'];
  await badge.updateComplete;
  expect(warnCalls.length, 'warning count for invalid variant').toBeGreaterThan(0);
} finally {
  restore();
}
```

--------------------------------

### One-time ARIA Role Setup in firstUpdated()

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/06_method-patterns.md

Perform one-time ARIA role setup in `firstUpdated()`. This method runs only once after the component's initial render.

```typescript
protected override firstUpdated(changed: PropertyValues<this>): void {
  super.firstUpdated(changed);
  this.setAttribute('role', 'separator');
}
```

--------------------------------

### 2nd-Gen Only Storybook Start Configuration

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/09_accessibility-testing.md

This specific configuration is used by `yarn test:a11y:2nd` to start only the 2nd-gen Storybook server, optimizing test runs for that generation.

```typescript
webServer: {
        command: 'cd 2nd-gen/packages/swc && SWC_STORYBOOK_MODE=ci-a11y yarn storybook',
    port: 6006,
    reuseExistingServer: !process.env.CI,
};
```

--------------------------------

### Build all packages

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/03_working-in-the-swc-repo.md

Compiles all packages within the repository. This is rarely needed explicitly during development but can be run as necessary.

```bash
yarn build
```

--------------------------------

### Minimum Concrete Class JSDoc Example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md

Provides the essential JSDoc tags required for a concrete component class, including the @element, @example, and @slot tags.

```typescript
/**
 * @element swc-divider
 *
 * @example
 * <swc-divider></swc-divider>
 *
 * @example
 * <swc-divider vertical></swc-divider>
 */
export class Divider extends DividerBase {
```

--------------------------------

### Example Component CSS Ruleset

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/01_css/01_component-css.md

Demonstrates the recommended ordering of CSS properties within a component's base class selector, following display, spacing, dimensions, color, and decoration guidelines.

```css
.swc-Badge {
  display: inline-flex;
  gap: var(--swc-badge-gap, token("text-to-visual-100"));
  align-items: center;
  min-block-size: var(--swc-badge-height, token("component-height-100"));
  padding-block: calc(/* ... */);
  padding-inline: calc(/* ... */);
  color: var(--swc-badge-label-icon-color, token("white"));
  background: var(--swc-badge-background-color, token("neutral-subdued-background-color-default"));
  border: var(--_swc-badge-border-width) solid var(--swc-badge-border-color, transparent);
  border-radius: var(--swc-badge-corner-radius, token("corner-radius-medium-size-medium"));
  cursor: default;
}
```

--------------------------------

### Correct getItems() implementation (live DOM query)

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/14_focus-management.md

Demonstrates the correct way to implement `getItems` by querying the live DOM on each call to ensure focus management is always up-to-date.

```typescript
// GOOD: getItems() queries live DOM every time
class SpTabs extends SpectrumElement {
  private navigation = new FocusgroupNavigationController(this, {
    getItems: () => [...this.querySelectorAll('sp-tab')] as HTMLElement[],
    direction: 'horizontal',
  });
}
```

--------------------------------

### Class-level JSDoc with @element, @property, and @example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md

Shows a more detailed class-level JSDoc including the @element tag, @property tags for component attributes, and an @example tag for usage.

```typescript
/**
 * @element swc-progress-circle
 *
 * @property {string} staticColor - Reflected as the `static-color` attribute. Static color variant for use on different backgrounds.
 * @property {number} progress - Progress value between 0 and 100.
 *
 * @example
 * <swc-progress-circle progress="75" label="Loading progress"></swc-progress-circle>
 */
export class ProgressCircle extends ProgressCircleBase {
```

--------------------------------

### Class-level JSDoc with @element and @example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/02_typescript/07_jsdoc-standards.md

Illustrates the basic JSDoc structure for a class, including the required @element tag for the custom element name and an @example tag for usage.

```typescript
/**
 * @element swc-badge
 *
 * @example
 * <swc-badge variant="positive">New</swc-badge>
 */
export class Badge extends BadgeBase {
```

--------------------------------

### Changeset for New Component

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/15_changelog-strategy.md

Use this format for adding a new component. Include links to the component's Storybook documentation and migration guide for consumer reference. The PR link is automatically appended.

```markdown
---
'@adobe/spectrum-wc': minor
---

`Accordion` — Added `<swc-accordion>` with Spectrum 2 tokens. See the [component docs](https://spectrum-web-components.adobe.com/?path=/docs/components-accordion--docs) and [migration guide](https://spectrum-web-components.adobe.com/?path=/docs/components-accordion-migration-guide--docs).
```

--------------------------------

### Playwright Accessibility Testing Setup

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/02_style-guide/04_testing/03_playwright-accessbility-testing.md

Imports necessary Playwright modules and helper functions for accessibility testing. Use this setup for ARIA snapshot and aXe validation tests.

```typescript
import AxeBuilder from '@axe-core/playwright';
import { expect, test } from '@playwright/test';

import { gotoStory } from '../../../utils/a11y-helpers.js';
```

--------------------------------

### Story File Structure

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/07_add-stories-for-2nd-gen-component.md

Illustrates the expected file structure for component stories, indicating that a single `.stories.ts` file is sufficient and no `.usage.mdx` file is needed.

```text
stories/
  [component].stories.ts   ← single file; no .usage.mdx needed
```

--------------------------------

### FocusgroupNavigationController Runtime Behavior Example

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/01_contributor-guides/14_focus-management.md

Illustrates the dynamic changes in tabindex and focus as a user navigates a focus group using arrow keys and tabs.

```text
Tab into group → focus lands on element with tabindex="0":
  [ A: 0 ]  [ B: -1 ]  [ C: -1 ]  [ D: -1 ]

Arrow Right → tabindex swaps, focus moves to B:
  [ A: -1 ]  [ B: 0 ]  [ C: -1 ]  [ D: -1 ]

Tab out, then Tab back in → returns to B (memory: true, the default):
  [ A: -1 ]  [ B: 0 ]  [ C: -1 ]  [ D: -1 ]
```

--------------------------------

### Workflow Overview Diagram

Source: https://github.com/adobe/spectrum-web-components/blob/main/CONTRIBUTOR-DOCS/03_project-planning/02_workstreams/02_2nd-gen-component-migration/02_step-by-step/01_washing-machine-workflow.md

Visual representation of the 8 phases involved in the 2nd-gen component migration workflow, from initial input to the final output.

```mermaid
flowchart LR
    subgraph Input
        A[Existing 1st-gen component]
    end
    subgraph Phases
        B[1. Preparation]
        C[2. Setup]
        D[3. API]
        E[4. A11y]
        F[5. Styling]
        G[6. Testing]
        H[7. Docs]
        I[8. Review]
    end
    subgraph Output
        J[2nd-gen component]
    end
    A --> B --> C --> D --> E --> F --> G --> H --> I --> J
```