Skip to content

Commit be3bb9d

Browse files
cdransfcdransf
committed
chore(migration-guides): add ai skill and contributor docs for migrations
1 parent 69f51a1 commit be3bb9d

4 files changed

Lines changed: 382 additions & 0 deletions

File tree

‎.ai/rules/migration-guide.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
# Component migration guide standards
2+
3+
Use this rule when creating or updating a `migration.md` file for a 2nd-gen component.
4+
5+
## When to apply
6+
7+
Apply when the user requests any of the following:
8+
9+
- Create a migration guide for a component
10+
- Update or review an existing migration guide
11+
- Standardize migration guide format across components
12+
13+
## File location
14+
15+
Each migration guide lives alongside the component it documents:
16+
17+
```
18+
2nd-gen/packages/swc/components/[component-name]/migration.md
19+
```
20+
21+
## Required document structure
22+
23+
Every migration guide must include all of the following sections in this order:
24+
25+
```md
26+
# [Component] migration guide: `sp-[component]` → `swc-[component]`
27+
28+
[Intro paragraph]
29+
30+
---
31+
32+
## Installation
33+
34+
## Quick reference
35+
36+
## Breaking changes
37+
38+
### Tag name
39+
40+
### [One subsection per breaking change]
41+
42+
## New in 2nd-gen (omit if none)
43+
44+
### [One subsection per new feature]
45+
46+
## Accessibility
47+
```
48+
49+
Use `---` horizontal rules between all top-level sections.
50+
51+
## Title and intro format
52+
53+
```md
54+
# Badge migration guide: `sp-badge` → `swc-badge`
55+
56+
This guide covers everything you need to move from the 1st-gen `sp-badge` component
57+
(`@spectrum-web-components/badge`) to the 2nd-gen `swc-badge` component
58+
(`@adobe/spectrum-wc/badge`).
59+
```
60+
61+
- Title uses backtick-wrapped tag names, arrow separator
62+
- Intro names both packages explicitly
63+
64+
## Installation section
65+
66+
Always include the yarn remove/add commands, then the import update. Add the monolithic
67+
package note when the component ships via `@adobe/spectrum-wc`:
68+
69+
````md
70+
## Installation
71+
72+
Remove the 1st-gen package and add the 2nd-gen equivalent:
73+
74+
```bash
75+
# Remove
76+
yarn remove @spectrum-web-components/[component]
77+
78+
# Add
79+
yarn add @adobe/spectrum-wc
80+
```
81+
82+
Update your imports:
83+
84+
```ts
85+
// Before
86+
import '@spectrum-web-components/[component]/sp-[component].js';
87+
88+
// After
89+
import '@adobe/spectrum-wc/[component]';
90+
```
91+
92+
> **Note:** `@adobe/spectrum-wc` is a monolithic package — installing it makes all
93+
> components available. Importing via a subpath (e.g. `@adobe/spectrum-wc/[component]`)
94+
> routes to that component's dedicated bundle, so only that module is loaded rather
95+
> than the entire package.
96+
````
97+
98+
## Quick reference table
99+
100+
A concise change summary at the top. Always include tag name, package, and CSS custom
101+
properties rows. Add a row for every attribute, slot, or behavior that changed.
102+
103+
Link anchor text in the "After" column to the relevant breaking change section when the
104+
change needs explanation.
105+
106+
```md
107+
## Quick reference
108+
109+
| What changed | Before (1st-gen) | After (2nd-gen) |
110+
| --------------------- | -------------------------------------- | ---------------------------------------------------------- |
111+
| Tag name | `sp-[component]` | `swc-[component]` |
112+
| Package | `@spectrum-web-components/[component]` | `@adobe/spectrum-wc` |
113+
| `variant` attribute | Description of old behavior | Description of new behavior — see [Section title](#anchor) |
114+
| CSS custom properties | `--mod-[component]-*` | `--swc-[component]-*` |
115+
```
116+
117+
Use **Removed**, **New**, or **Unchanged** as shorthand in the After column where appropriate.
118+
119+
## Breaking changes section
120+
121+
One `###` subsection per breaking change. Tag name always comes first.
122+
123+
### Tag name subsection (always required)
124+
125+
````md
126+
### Tag name
127+
128+
Find and replace all instances of `sp-[component]` with `swc-[component]` in your
129+
templates and HTML.
130+
131+
```html
132+
<!-- Before -->
133+
<sp-[component]>...</sp-[component]>
134+
135+
<!-- After -->
136+
<swc-[component]>...</swc-[component]>
137+
```
138+
````
139+
140+
### Other breaking change subsections
141+
142+
Each subsection follows this structure:
143+
144+
1. One-sentence description of what changed and why (reference the Spectrum 2 spec when relevant)
145+
2. Before/after code block
146+
3. Migration guidance (what to do, what to remove)
147+
4. Optional blockquote for important notes or caveats
148+
149+
````md
150+
### `[attribute]` renamed to `[new-attribute]`
151+
152+
The `[attribute]` attribute has been renamed to `[new-attribute]` because [reason].
153+
154+
```html
155+
<!-- Before -->
156+
<sp-[component] [attribute]="value"></sp-[component]>
157+
158+
<!-- After -->
159+
<swc-[component] [new-attribute]="value"></swc-[component]>
160+
```
161+
````
162+
163+
````md
164+
### `[attribute]` removed
165+
166+
The `[attribute]` attribute is not part of the Spectrum 2 design specification and has
167+
been removed.
168+
169+
**After:** [Describe the recommended approach to replace the removed behavior.]
170+
171+
```html
172+
<!-- Before -->
173+
<sp-[component] [attribute]>...</sp-[component]>
174+
175+
<!-- After: [brief description of replacement] -->
176+
<swc-[component]>...</swc-[component]>
177+
```
178+
````
179+
180+
### CSS custom properties subsection
181+
182+
Always include a full mapping table followed by a before/after code block:
183+
184+
````md
185+
### CSS custom properties
186+
187+
All `--mod-[component]-*` custom properties have been removed. Replace them with the
188+
`--swc-[component]-*` equivalents in your stylesheets:
189+
190+
| Removed (1st-gen) | Replacement (2nd-gen) |
191+
| ------------------------------ | ------------------------------ |
192+
| `--mod-[component]-[property]` | `--swc-[component]-[property]` |
193+
194+
```css
195+
/* Before */
196+
sp-[component] {
197+
--mod-[component]-[property]: value;
198+
}
199+
200+
/* After */
201+
swc-[component] {
202+
--swc-[component]-[property]: value;
203+
}
204+
```
205+
````
206+
207+
Add a blockquote for non-obvious override behavior (e.g., attribute-based vs class-based
208+
selector scoping for per-variant overrides).
209+
210+
## New in 2nd-gen section
211+
212+
One `###` subsection per new feature. Omit the section entirely if there are no new
213+
features — do not include it with empty content.
214+
215+
````md
216+
## New in 2nd-gen
217+
218+
### `[attribute]` attribute
219+
220+
A new `[attribute]` boolean attribute [description of what it does and when to use it].
221+
222+
```html
223+
<swc-[component] [attribute]>...</swc-[component]>
224+
```
225+
````
226+
227+
## Accessibility section
228+
229+
A bullet list — no subsections. Cover:
230+
231+
- Whether the component has an implicit ARIA role
232+
- Labeling requirements (what provides the accessible name)
233+
- Color contrast or "color alone" considerations (WCAG 1.4.1) if the component uses color to convey meaning
234+
- Any ARIA attributes that should or should not be added by consumers
235+
- Keyboard behavior if the component is interactive
236+
- Notes specific to removed or changed features that affect AT users
237+
238+
```md
239+
## Accessibility
240+
241+
- [One bullet per a11y consideration, specific to this component]
242+
```
243+
244+
Do not add `role`, `aria-label`, or `aria-live` suggestions that aren't accurate for the component.
245+
246+
## Code example rules
247+
248+
- HTML before/after: use `<!-- Before -->` and `<!-- After -->` comments
249+
- CSS before/after: use `/* Before */` and `/* After */` comments
250+
- TypeScript/JS before/after: use `// Before` and `// After` comments
251+
- Always show complete, working snippets — no abbreviated or placeholder markup
252+
- Use meaningful content in examples (e.g. `Approved`, `Published`) — not `Label` or `Content`
253+
- All examples must be accessible (labels, alt text, etc.)
254+
255+
## Accuracy requirements
256+
257+
Before writing or updating a migration guide, verify claims against source:
258+
259+
1. **Check 1st-gen component** (`1st-gen/packages/[component]/src/`) for actual removed/renamed attributes
260+
2. **Check 2nd-gen component** (`2nd-gen/packages/swc/components/[component]/`) for current API
261+
3. **Check 1st-gen CEM** (`1st-gen/packages/[component]/custom-elements.json`) for complete property list
262+
4. **Check CSS files** for actual custom property names in both generations
263+
264+
Do not claim attributes, properties, or CSS variables that don't exist in the source.
265+
266+
## Checklist
267+
268+
Before completing a migration guide, verify:
269+
270+
- [ ] Starts with `# [Component] migration guide: \`sp-[component]\` → \`swc-[component]\``
271+
- [ ] Intro paragraph names both packages
272+
- [ ] Installation section includes remove, add, and import update
273+
- [ ] Quick reference table covers all changed attributes, slots, and CSS properties
274+
- [ ] Quick reference links to relevant breaking change sections
275+
- [ ] Tag name is the first breaking change
276+
- [ ] Every breaking change has a before/after code block
277+
- [ ] CSS custom properties section includes full mapping table
278+
- [ ] `## New in 2nd-gen` present only if new features exist
279+
- [ ] Accessibility section is component-specific (not generic boilerplate)
280+
- [ ] All examples use meaningful content and are accessible
281+
- [ ] `---` horizontal rules between all top-level sections
282+
- [ ] All claims verified against component source

‎CONTRIBUTOR-DOCS/01_contributor-guides/13_writing-migration-guides.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
<!-- Generated breadcrumbs - DO NOT EDIT -->
2+
3+
[CONTRIBUTOR-DOCS](../README.md) / [Contributor guides](README.md) / Writing migration guides
4+
5+
<!-- Document title (editable) -->
6+
7+
# Writing migration guides
8+
9+
<!-- Generated TOC - DO NOT EDIT -->
10+
11+
<details open>
12+
<summary><strong>In this doc</strong></summary>
13+
14+
- [About this guide](#about-this-guide)
15+
- [When to write a migration guide](#when-to-write-a-migration-guide)
16+
- [File location](#file-location)
17+
- [Document structure](#document-structure)
18+
- [Using AI to generate migration guides](#using-ai-to-generate-migration-guides)
19+
- [Checklist](#checklist)
20+
- [Examples](#examples)
21+
22+
</details>
23+
24+
<!-- Document content (editable) -->
25+
26+
## About this guide
27+
28+
This guide explains when and how to write a consumer-facing migration guide for a 2nd-gen component. Migration guides help consumers move from the 1st-gen `sp-*` components to 2nd-gen `swc-*` components with confidence.
29+
30+
## When to write a migration guide
31+
32+
Write a migration guide when a 2nd-gen component is approaching production readiness and consumers will need to migrate from the equivalent 1st-gen component. A migration guide is required before a component is considered fully production-ready.
33+
34+
You do not need to wait until the component is feature-complete — guides can be updated as the API stabilizes.
35+
36+
## File location
37+
38+
Each migration guide lives alongside the component it documents:
39+
40+
```
41+
2nd-gen/packages/swc/components/[component-name]/migration.md
42+
```
43+
44+
## Document structure
45+
46+
Every migration guide follows a consistent structure. The full format specification — including required sections, code example conventions, table formats, and accuracy requirements — is defined in the AI rule at:
47+
48+
```
49+
.ai/rules/migration-guide.md
50+
```
51+
52+
At a high level, every guide includes:
53+
54+
1. **Title and intro** — component names, both packages
55+
2. **Installation** — remove 1st-gen, add 2nd-gen, update imports
56+
3. **Quick reference** — table of all changes at a glance
57+
4. **Breaking changes** — one subsection per breaking change with before/after examples
58+
5. **New in 2nd-gen** — new attributes, slots, or behaviors (omit if none)
59+
6. **Accessibility** — component-specific a11y notes
60+
61+
Use `---` horizontal rules between all top-level sections. See the examples below for reference.
62+
63+
## Using AI to generate migration guides
64+
65+
An AI agent (Claude Code, Cursor) will automatically follow the format in `.ai/rules/migration-guide.md` when asked to generate a migration guide. A prompt like the following works well:
66+
67+
```
68+
Write a migration guide for swc-[component] following the migration guide rule.
69+
Verify all claims against the component source before writing.
70+
```
71+
72+
The agent will:
73+
74+
- Read the 1st-gen and 2nd-gen component source to identify real breaking changes
75+
- Generate before/after examples for each change
76+
- Build the quick reference table
77+
- Write component-specific accessibility notes
78+
79+
**Always review AI-generated guides against the source.** Verify that attribute names, CSS custom property names, and behavioral descriptions are accurate before merging.
80+
81+
## Checklist
82+
83+
- [ ] File is at `2nd-gen/packages/swc/components/[component]/migration.md`
84+
- [ ] All required sections are present (Installation, Quick reference, Breaking changes, Accessibility)
85+
- [ ] Every breaking change has a before/after code block
86+
- [ ] Quick reference table links to relevant breaking change sections
87+
- [ ] CSS custom properties section includes a full mapping table
88+
- [ ] `## New in 2nd-gen` is present only if new features exist
89+
- [ ] All claims verified against `1st-gen/packages/[component]/` and `2nd-gen/packages/swc/components/[component]/`
90+
- [ ] All code examples are accessible and use meaningful content
91+
92+
## Examples
93+
94+
The following migration guides are good references:
95+
96+
- `2nd-gen/packages/swc/components/avatar/migration.md` — attribute renames, removed variant, CSS custom properties
97+
- `2nd-gen/packages/swc/components/badge/migration.md` — new attributes, expanded variant list, per-variant CSS override notes
98+
- `2nd-gen/packages/swc/components/status-light/migration.md` — removed attribute, removed variant, new color variants

‎CONTRIBUTOR-DOCS/01_contributor-guides/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
- [Maintaining StackBlitz examples for Spectrum Web Components](10_using-stackblitz.md)
2424
- [2nd gen testing](11_2ndgen_testing.md)
2525
- [Tools vs packages: where code lives](12_tools-vs-packages.md)
26+
- [Writing migration guides](13_writing-migration-guides.md)
2627

2728
</details>
2829

‎CONTRIBUTOR-DOCS/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
- [Maintaining StackBlitz examples for Spectrum Web Components](01_contributor-guides/10_using-stackblitz.md)
3030
- [2nd gen testing](01_contributor-guides/11_2ndgen_testing.md)
3131
- [Tools vs packages: where code lives](01_contributor-guides/12_tools-vs-packages.md)
32+
- [Writing migration guides](01_contributor-guides/13_writing-migration-guides.md)
3233
- [Style guide](02_style-guide/README.md)
3334
- [2nd-Gen CSS](02_style-guide/01_css/README.md)
3435
- [2nd-gen TypeScript](02_style-guide/02_typescript/README.md)

0 commit comments

Comments
 (0)