Skip to content

Commit 4a5925b

Browse files
cdransfcdransf
committed
docs: add consumer migration guides for 7 S2 components
1 parent 2da6080 commit 4a5925b

7 files changed

Lines changed: 1291 additions & 0 deletions

File tree

‎2nd-gen/packages/swc/components/asset/migration.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Asset migration guide: `sp-asset` → `swc-asset`
2+
3+
This guide covers everything you need to move from the 1st-gen `sp-asset` component
4+
(`@spectrum-web-components/asset`) to the 2nd-gen `swc-asset` component
5+
(`@adobe/spectrum-wc/asset`).
6+
7+
---
8+
9+
## Installation
10+
11+
Remove the 1st-gen package and add the 2nd-gen equivalent:
12+
13+
```bash
14+
# Remove
15+
yarn remove @spectrum-web-components/asset
16+
17+
# Add
18+
yarn add @adobe/spectrum-wc
19+
```
20+
21+
Update your imports:
22+
23+
```ts
24+
// Before
25+
import '@spectrum-web-components/asset/sp-asset.js';
26+
27+
// After
28+
import '@adobe/spectrum-wc/asset';
29+
```
30+
31+
> **Note:** `@adobe/spectrum-wc` is a monolithic package — installing it makes all
32+
> components available. Importing via a subpath (e.g. `@adobe/spectrum-wc/asset`)
33+
> routes to that component's dedicated bundle, so only that module is loaded rather
34+
> than the entire package.
35+
36+
---
37+
38+
## Quick reference
39+
40+
| What changed | Before (1st-gen) | After (2nd-gen) |
41+
| --------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------- |
42+
| Tag name | `sp-asset` | `swc-asset` |
43+
| Package | `@spectrum-web-components/asset` | `@adobe/spectrum-wc` |
44+
| `variant` attribute | `'file' \| 'folder'` | `'file' \| 'folder'` — unchanged |
45+
| `label` attribute | `label="…"` | `label="…"` — unchanged |
46+
| CSS custom properties | `--mod-asset-*` | Not directly exposed — see [CSS custom properties](#css-custom-properties) |
47+
| Shadow DOM classes | `.file`, `.folder`, `.fileBackground`, etc. | `.swc-Asset-file`, `.swc-Asset-folder`, etc. — see [Shadow DOM](#shadow-dom-structure) |
48+
| Dark mode | Manual via color overrides | Automatic via `light-dark()` |
49+
50+
---
51+
52+
## Breaking changes
53+
54+
### Tag name
55+
56+
Find and replace all instances of `sp-asset` with `swc-asset` in your templates and HTML.
57+
58+
```html
59+
<!-- Before -->
60+
<sp-asset variant="file" label="Report.pdf"></sp-asset>
61+
<sp-asset variant="folder" label="Projects"></sp-asset>
62+
63+
<!-- After -->
64+
<swc-asset variant="file" label="Report.pdf"></swc-asset>
65+
<swc-asset variant="folder" label="Projects"></swc-asset>
66+
```
67+
68+
---
69+
70+
### CSS custom properties
71+
72+
The `--mod-asset-*` custom properties from 1st-gen have been removed. The 2nd-gen component
73+
uses a token-based design system and does not expose direct CSS custom properties for
74+
overriding colors or dimensions.
75+
76+
| Removed (1st-gen) | Replacement (2nd-gen) |
77+
| ------------------------------------- | -------------------------------------------------- |
78+
| `--mod-asset-folder-background-color` | No direct equivalent — color set via design tokens |
79+
| `--mod-asset-file-background-color` | No direct equivalent — color set via design tokens |
80+
| `--mod-asset-icon-outline-color` | No direct equivalent — color set via design tokens |
81+
| `--mod-asset-icon-min-width` | No direct equivalent |
82+
| `--mod-asset-icon-max-width` | No direct equivalent |
83+
| `--mod-asset-icon-margin` | No direct equivalent |
84+
85+
The 2nd-gen component derives its colors from Spectrum 2 design tokens (e.g.,
86+
`gray-200`, `gray-25`, `gray-500`). These resolve automatically based on the active
87+
theme and color scheme — no manual override is needed for standard light/dark mode
88+
support. If you need to override asset colors beyond what the theme provides, target
89+
the component's `::part()` selectors or use a wrapping element with custom CSS properties
90+
and consult the Spectrum 2 token documentation for the token names in use.
91+
92+
---
93+
94+
### Shadow DOM structure
95+
96+
The internal shadow DOM structure has changed. The 2nd-gen component wraps all content in
97+
a `.swc-Asset` container div and uses namespaced BEM-style class names on all internal
98+
SVG elements to avoid naming collisions.
99+
100+
If you were targeting internal shadow DOM classes directly — which is not a supported API
101+
and may have broken without warning even in 1st-gen — update your selectors:
102+
103+
| 1st-gen class | 2nd-gen class |
104+
| ------------------- | ----------------------------- |
105+
| `.file` | `.swc-Asset-file` |
106+
| `.fileBackground` | `.swc-Asset-fileBackground` |
107+
| `.fileOutline` | `.swc-Asset-fileOutline` |
108+
| `.folder` | `.swc-Asset-folder` |
109+
| `.folderBackground` | `.swc-Asset-folderBackground` |
110+
| `.folderOutline` | `.swc-Asset-folderOutline` |
111+
112+
> **Note:** Internal shadow DOM classes are not a public API. Prefer CSS custom properties
113+
> and design tokens for all theming. Internal class names may change without notice.
114+
115+
---
116+
117+
## New in 2nd-gen
118+
119+
### Automatic dark mode
120+
121+
The 2nd-gen component uses the CSS `light-dark()` function to automatically adapt colors
122+
to the user's or application's color scheme. Manual color overrides via `--mod-*`
123+
properties are no longer required for dark mode support.
124+
125+
---
126+
127+
## Accessibility
128+
129+
- Always provide a meaningful `label` when using `variant="file"` or `variant="folder"`.
130+
The label is applied to the SVG as an accessible name via `aria-label`.
131+
- When used without a `variant`, `swc-asset` renders a default slot. Ensure slotted
132+
content carries its own accessible name if it conveys meaning.
133+
- `swc-asset` is a non-interactive, presentational component. It does not manage focus
134+
and does not emit events.

‎2nd-gen/packages/swc/components/badge/migration.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Badge migration guide: `sp-badge` → `swc-badge`
2+
3+
This guide covers everything you need to move from the 1st-gen `sp-badge` component
4+
(`@spectrum-web-components/badge`) to the 2nd-gen `swc-badge` component
5+
(`@adobe/spectrum-wc/badge`).
6+
7+
---
8+
9+
## Installation
10+
11+
Remove the 1st-gen package and add the 2nd-gen equivalent:
12+
13+
```bash
14+
# Remove
15+
yarn remove @spectrum-web-components/badge
16+
17+
# Add
18+
yarn add @adobe/spectrum-wc
19+
```
20+
21+
Update your imports:
22+
23+
```ts
24+
// Before
25+
import '@spectrum-web-components/badge/sp-badge.js';
26+
27+
// After
28+
import '@adobe/spectrum-wc/badge';
29+
```
30+
31+
> **Note:** `@adobe/spectrum-wc` is a monolithic package — installing it makes all
32+
> components available. Importing via a subpath (e.g. `@adobe/spectrum-wc/badge`)
33+
> routes to that component's dedicated bundle, so only that module is loaded rather
34+
> than the entire package.
35+
36+
---
37+
38+
## Quick reference
39+
40+
| What changed | Before (1st-gen) | After (2nd-gen) |
41+
| --------------------- | -------------------------------------------------------- | -------------------------------------------------------------------- |
42+
| Tag name | `sp-badge` | `swc-badge` |
43+
| Package | `@spectrum-web-components/badge` | `@adobe/spectrum-wc` |
44+
| `variant` attribute | 14 color variants | 19 color variants — 5 new colors added |
45+
| `size` attribute | `s \| m \| l \| xl` | `s \| m \| l \| xl` — unchanged |
46+
| `fixed` attribute | `block-start \| block-end \| inline-start \| inline-end` | `block-start \| block-end \| inline-start \| inline-end` — unchanged |
47+
| `subtle` attribute | Not supported | New — reduces visual prominence |
48+
| `outline` attribute | Not supported | New — bordered appearance (semantic variants only) |
49+
| CSS custom properties | `--mod-badge-*` | `--swc-badge-*` |
50+
| Slots | `default` (label), `icon` | `default` (label), `icon` — unchanged |
51+
52+
---
53+
54+
## Breaking changes
55+
56+
### Tag name
57+
58+
Find and replace all instances of `sp-badge` with `swc-badge` in your templates and HTML.
59+
60+
```html
61+
<!-- Before -->
62+
<sp-badge variant="positive">Approved</sp-badge>
63+
64+
<!-- After -->
65+
<swc-badge variant="positive">Approved</swc-badge>
66+
```
67+
68+
---
69+
70+
### CSS custom properties
71+
72+
All `--mod-badge-*` custom properties have been renamed to `--swc-badge-*`. Update any
73+
overrides in your stylesheets:
74+
75+
| Removed (1st-gen) | Replacement (2nd-gen) |
76+
| ------------------------------------------- | ------------------------------ |
77+
| `--mod-badge-height` | `--swc-badge-height` |
78+
| `--mod-badge-corner-radius` | `--swc-badge-corner-radius` |
79+
| `--mod-badge-label-icon-color` | `--swc-badge-label-icon-color` |
80+
| `--mod-badge-font-size` | `--swc-badge-font-size` |
81+
| `--mod-badge-line-height` | `--swc-badge-line-height` |
82+
| `--mod-badge-workflow-icon-size` | `--swc-badge-icon-size` |
83+
| `--mod-badge-label-spacing-vertical-top` | `--swc-badge-padding-block` |
84+
| `--mod-badge-label-spacing-vertical-bottom` | `--swc-badge-padding-block` |
85+
| `--mod-badge-label-spacing-horizontal` | `--swc-badge-padding-inline` |
86+
| `--mod-badge-icon-text-spacing` | `--swc-badge-gap` |
87+
88+
```css
89+
/* Before */
90+
sp-badge {
91+
--mod-badge-height: 24px;
92+
--mod-badge-corner-radius: 4px;
93+
}
94+
95+
/* After */
96+
swc-badge {
97+
--swc-badge-height: 24px;
98+
--swc-badge-corner-radius: 4px;
99+
}
100+
```
101+
102+
---
103+
104+
## New in 2nd-gen
105+
106+
### `subtle` attribute
107+
108+
A new `subtle` boolean attribute reduces the visual prominence of the badge by using a
109+
softer background. It is available on all variants — both semantic and color.
110+
111+
```html
112+
<swc-badge variant="positive" subtle>Approved</swc-badge>
113+
<swc-badge variant="indigo" subtle>Label</swc-badge>
114+
```
115+
116+
---
117+
118+
### `outline` attribute
119+
120+
A new `outline` boolean attribute renders the badge with a bordered appearance and a
121+
semi-transparent background. It is available on semantic variants only (`accent`,
122+
`informative`, `neutral`, `positive`, `notice`, `negative`).
123+
124+
```html
125+
<swc-badge variant="positive" outline>Approved</swc-badge>
126+
```
127+
128+
---
129+
130+
### New color variants
131+
132+
Five new color variants have been added to match the Spectrum 2 specification:
133+
134+
| New variant | Example |
135+
| ----------- | -------------------------------------------------- |
136+
| `pink` | `<swc-badge variant="pink">Label</swc-badge>` |
137+
| `turquoise` | `<swc-badge variant="turquoise">Label</swc-badge>` |
138+
| `brown` | `<swc-badge variant="brown">Label</swc-badge>` |
139+
| `cinnamon` | `<swc-badge variant="cinnamon">Label</swc-badge>` |
140+
| `silver` | `<swc-badge variant="silver">Label</swc-badge>` |
141+
142+
All 14 original color variants remain available and are unchanged.
143+
144+
---
145+
146+
## Accessibility
147+
148+
- `swc-badge` is a non-interactive, presentational component. It does not emit events
149+
and is not focusable.
150+
- Ensure the badge label text is meaningful in context. Do not rely on color alone to
151+
convey status — always pair color variants with a descriptive text label.
152+
- When placing a badge alongside an icon in the `icon` slot, ensure the icon is
153+
decorative (hidden from assistive technology) if the text label already conveys
154+
the full meaning.

0 commit comments

Comments
 (0)