Skip to content

docs: add consumer migration guides for S2 components #6169

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
cdransf wants to merge 4 commits into
base: main
Choose a base branch
from
Draft

docs: add consumer migration guides for S2 components #6169

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5d730aa
docs: add consumer migration guides for 7 S2 components
cdransf Apr 10, 2026
5c8eff6
docs: additional migration refinements
cdransf Apr 10, 2026
d4220ba
docs: migration css info refinement
cdransf Apr 10, 2026
bac4d74
docs: a11y updates for migration docs
cdransf Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
135 changes: 135 additions & 0 deletions 2nd-gen/packages/swc/components/asset/migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
# Asset migration guide: `sp-asset` → `swc-asset`

This guide covers everything you need to move from the 1st-gen `sp-asset` component
(`@spectrum-web-components/asset`) to the 2nd-gen `swc-asset` component
(`@adobe/spectrum-wc/asset`).

---

## Installation

Remove the 1st-gen package and add the 2nd-gen equivalent:

```bash
# Remove
yarn remove @spectrum-web-components/asset

# Add
yarn add @adobe/spectrum-wc
```

Update your imports:

```ts
// Before
import '@spectrum-web-components/asset/sp-asset.js';

// After
import '@adobe/spectrum-wc/asset';
```

> **Note:** `@adobe/spectrum-wc` is a monolithic package — installing it makes all
> components available. Importing via a subpath (e.g. `@adobe/spectrum-wc/asset`)
> routes to that component's dedicated bundle, so only that module is loaded rather
> than the entire package.

---

## Quick reference

| What changed | Before (1st-gen) | After (2nd-gen) |
| --------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
| Tag name | `sp-asset` | `swc-asset` |
| Package | `@spectrum-web-components/asset` | `@adobe/spectrum-wc` |
| `variant` attribute | `'file' \| 'folder'` | `'file' \| 'folder'` — unchanged |
| `label` attribute | `label="…"` | `label="…"` — unchanged |
| CSS custom properties | `--mod-asset-*` | Not directly exposed — see [CSS custom properties](#css-custom-properties) |
| Shadow DOM classes | `.file`, `.folder`, `.fileBackground`, etc. | `.swc-Asset-file`, `.swc-Asset-folder`, etc. — see [Shadow DOM](#shadow-dom-structure) |
| Dark mode | Manual via color overrides | Automatic via `light-dark()` |

---

## Breaking changes

### Tag name

Find and replace all instances of `sp-asset` with `swc-asset` in your templates and HTML.

```html
<!-- Before -->
<sp-asset variant="file" label="Report.pdf"></sp-asset>
<sp-asset variant="folder" label="Projects"></sp-asset>

<!-- After -->
<swc-asset variant="file" label="Report.pdf"></swc-asset>
<swc-asset variant="folder" label="Projects"></swc-asset>
```

---

### CSS custom properties

The `--mod-asset-*` custom properties from 1st-gen have been removed. The 2nd-gen component
uses a token-based design system and does not expose direct CSS custom properties for
overriding colors or dimensions.

| Removed (1st-gen) | Replacement (2nd-gen) |
| ------------------------------------- | -------------------------------------------------- |
| `--mod-asset-folder-background-color` | No direct equivalent — color set via design tokens |
| `--mod-asset-file-background-color` | No direct equivalent — color set via design tokens |
| `--mod-asset-icon-outline-color` | No direct equivalent — color set via design tokens |
| `--mod-asset-icon-min-width` | No direct equivalent |
| `--mod-asset-icon-max-width` | No direct equivalent |
| `--mod-asset-icon-margin` | No direct equivalent |

The 2nd-gen component derives its colors from Spectrum 2 design tokens (e.g.,
`gray-200`, `gray-25`, `gray-500`). These resolve automatically based on the active
theme and color scheme — no manual override is needed for standard light/dark mode
support. If you need to override asset colors beyond what the theme provides, use a
wrapping element with custom CSS properties and consult the Spectrum 2 token
documentation for the token names in use. `swc-asset` does not expose `::part()`
selectors.

---

### Shadow DOM structure

The internal shadow DOM structure has changed. The 2nd-gen component wraps all content in
a `.swc-Asset` container div and uses namespaced BEM-style class names on all internal
SVG elements to avoid naming collisions.

If you were targeting internal shadow DOM classes directly — which is not a supported API
and may have broken without warning even in 1st-gen — update your selectors:

| 1st-gen class | 2nd-gen class |
| ------------------- | ----------------------------- |
| `.file` | `.swc-Asset-file` |
| `.fileBackground` | `.swc-Asset-fileBackground` |
| `.fileOutline` | `.swc-Asset-fileOutline` |
| `.folder` | `.swc-Asset-folder` |
| `.folderBackground` | `.swc-Asset-folderBackground` |
| `.folderOutline` | `.swc-Asset-folderOutline` |

> **Note:** Internal shadow DOM classes are not a public API. Prefer CSS custom properties
> and design tokens for all theming. Internal class names may change without notice.

---

## New in 2nd-gen

### Automatic dark mode

The 2nd-gen component uses the CSS `light-dark()` function to automatically adapt colors
to the user's or application's color scheme. Manual color overrides via `--mod-*`
properties are no longer required for dark mode support.

---

## Accessibility

- Always provide a meaningful `label` when using `variant="file"` or `variant="folder"`.
The label is applied to the SVG as an accessible name via `aria-label`.
- When used without a `variant`, `swc-asset` renders a default slot. Ensure slotted
content carries its own accessible name if it conveys meaning.
- `swc-asset` is a non-interactive, presentational component. It does not manage focus
and does not emit events.
184 changes: 184 additions & 0 deletions 2nd-gen/packages/swc/components/badge/migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
# Badge migration guide: `sp-badge` → `swc-badge`

This guide covers everything you need to move from the 1st-gen `sp-badge` component
(`@spectrum-web-components/badge`) to the 2nd-gen `swc-badge` component
(`@adobe/spectrum-wc/badge`).

---

## Installation

Remove the 1st-gen package and add the 2nd-gen equivalent:

```bash
# Remove
yarn remove @spectrum-web-components/badge

# Add
yarn add @adobe/spectrum-wc
```

Update your imports:

```ts
// Before
import '@spectrum-web-components/badge/sp-badge.js';

// After
import '@adobe/spectrum-wc/badge';
```

> **Note:** `@adobe/spectrum-wc` is a monolithic package — installing it makes all
> components available. Importing via a subpath (e.g. `@adobe/spectrum-wc/badge`)
> routes to that component's dedicated bundle, so only that module is loaded rather
> than the entire package.

---

## Quick reference

| What changed | Before (1st-gen) | After (2nd-gen) |
| --------------------- | -------------------------------------------------------- | -------------------------------------------------------------------- |
| Tag name | `sp-badge` | `swc-badge` |
| Package | `@spectrum-web-components/badge` | `@adobe/spectrum-wc` |
| `variant` attribute | 14 color variants | 19 color variants — 5 new colors added |
| `size` attribute | `s \| m \| l \| xl` | `s \| m \| l \| xl` — unchanged |
| `fixed` attribute | `block-start \| block-end \| inline-start \| inline-end` | `block-start \| block-end \| inline-start \| inline-end` — unchanged |
| `subtle` attribute | Not supported | New — reduces visual prominence |
| `outline` attribute | Not supported | New — bordered appearance (semantic variants only) |
| CSS custom properties | `--mod-badge-*` | `--swc-badge-*` |
| Slots | `default` (label), `icon` | `default` (label), `icon` — unchanged |

---

## Breaking changes

### Tag name

Find and replace all instances of `sp-badge` with `swc-badge` in your templates and HTML.

```html
<!-- Before -->
<sp-badge variant="positive">Approved</sp-badge>

<!-- After -->
<swc-badge variant="positive">Approved</swc-badge>
```

---

### CSS custom properties

All `--mod-badge-*` custom properties have been removed. Replace them with the
`--swc-badge-*` equivalents in your stylesheets:

| Removed (1st-gen) | Replacement (2nd-gen) |
| ------------------------------------------- | ------------------------------ |
| `--mod-badge-height` | `--swc-badge-height` |
| `--mod-badge-corner-radius` | `--swc-badge-corner-radius` |
| `--mod-badge-label-icon-color` | `--swc-badge-label-icon-color` |
| `--mod-badge-font-size` | `--swc-badge-font-size` |
| `--mod-badge-line-height` | `--swc-badge-line-height` |
| `--mod-badge-workflow-icon-size` | `--swc-badge-icon-size` |
| `--mod-badge-label-spacing-vertical-top` | `--swc-badge-padding-block` |
| `--mod-badge-label-spacing-vertical-bottom` | `--swc-badge-padding-block` |
| `--mod-badge-label-spacing-horizontal` | `--swc-badge-padding-inline` |
| `--mod-badge-icon-text-spacing` | `--swc-badge-gap` |

```css
/* Before */
sp-badge {
--mod-badge-height: 24px;
--mod-badge-corner-radius: 4px;
}

/* After */
swc-badge {
--swc-badge-height: 24px;
--swc-badge-corner-radius: 4px;
}
```

> **Note on per-variant color overrides:** Semantic variants (`neutral`, `informative`,
> `positive`, `negative`, `notice`, `accent`) use attribute-based selectors internally,
> so consumer per-variant overrides work as expected:
>
> ```css
> swc-badge[variant='positive'] {
> --swc-badge-background-color: darkgreen;
> }
> ```
>
> Non-semantic color variants (`gray`, `red`, `orange`, `yellow`, `chartreuse`, `celery`,
> `green`, `seafoam`, `cyan`, `blue`, `indigo`, `purple`, `fuchsia`, `magenta`, `pink`,
> `turquoise`, `brown`, `cinnamon`, `silver`) are applied via internal class selectors.
> A consumer attribute selector targeting one of these variants will not reliably override
> its color properties — use a global (unscoped) override instead, which will affect all
> variants:
>
> ```css
> /* Works — but applies to all badge instances */
> swc-badge {
> --swc-badge-background-color: rebeccapurple;
> }
> ```

---

## New in 2nd-gen

### `subtle` attribute

A new `subtle` boolean attribute reduces the visual prominence of the badge by using a
softer background. It is available on all variants — both semantic and color.

```html
<swc-badge variant="positive" subtle>Approved</swc-badge>
<swc-badge variant="indigo" subtle>Label</swc-badge>
```

---

### `outline` attribute

A new `outline` boolean attribute renders the badge with a bordered appearance and a
semi-transparent background. It is available on semantic variants only (`accent`,
`informative`, `neutral`, `positive`, `notice`, `negative`).

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

---

### New color variants

Five new color variants have been added to match the Spectrum 2 specification:

| New variant | Example |
| ----------- | -------------------------------------------------- |
| `pink` | `<swc-badge variant="pink">Label</swc-badge>` |
| `turquoise` | `<swc-badge variant="turquoise">Label</swc-badge>` |
| `brown` | `<swc-badge variant="brown">Label</swc-badge>` |
| `cinnamon` | `<swc-badge variant="cinnamon">Label</swc-badge>` |
| `silver` | `<swc-badge variant="silver">Label</swc-badge>` |

All 14 original color variants remain available and are unchanged.

---

## Accessibility

- `swc-badge` is a non-interactive, presentational component. It does not emit events
and is not focusable.
- Ensure the badge label text is meaningful in context. Do not rely on color alone to
convey status — always pair color variants with a descriptive text label.
- When placing a badge alongside an icon in the `icon` slot, ensure the icon is
decorative (hidden from assistive technology) if the text label already conveys
the full meaning.
- For icon-only badges (no visible text), set `aria-label` directly on the `swc-badge`
element to provide an accessible name. A badge with no visible text and no
`aria-label` has no accessible name and fails WCAG 4.1.2.
- `variant` does not set any ARIA states. The meaning of a badge comes from its label
text, not from the color. Do not add `aria-invalid`, `role="status"`, or similar
attributes based on `variant` value alone.
Loading
Loading