feat: add 1.0.0 migration guide

projects/documentation/content/migrations/2024-10-31 (1.0.0).md

@@ -0,0 +1,207 @@
+---
+layout: guide.njk
+title: 'Migration Guide: Spectrum Web Components (v1.0.0)'
+displayName: 2024/10/31 (v1.0.0)
+slug: migration-guide
+---
+
+## Migration: 2024/10/31 (v1.0.0)
+
+With the release of Spectrum Web Components v1.0.0, we've removed previously deprecated components and features.
+
+Starting with this version, Spectrum Web Components will adhere to [semantic versioning (semver)](https://semver.org/), which ensures that any future breaking changes are introduced only in major version bumps. These changes will be communicated in advance so that developers can prepare for the updates. As part of this versioning approach, patch releases will be non-breaking and will focus on fixes and minor improvements.
+
+If you're upgrading from an earlier version, please review the following changes carefully to ensure your project remains compatible.
+
+## Removed Components and Features
+
+### 1. Banner (`sp-banner`)
+
+The `sp-banner` component has been removed.
+
+**Action Required**: If you are using `sp-banner`, remove it from your application and replace it with the [alert banner](/components/alert-banner/) component to show pressing and high-signal messages, such as system alerts.
+
+### 2. Quick actions (`sp-quick-actions`)
+
+The `sp-quick-actions` component has been removed.
+
+**Action Required**: If you are using `sp-quick-actions`, remove it from your application and replace it with the [action bar](/components/alert-banner/) component to allow users to perform actions on either a single or multiple items at the same time.
+
+### 3. Split button (`sp-split-button`)
+
+The `sp-split-button` component has been removed.
+
+**Action Required**: If you are using `sp-split-button`, remove it from your application and replace it with the [button group](/components/button-group/) component to to show any additional actions related to the most critical action.
+
+### 4. Action button (`sp-action-button`)
+
+The `variant` attribute for `sp-action-button` has been removed.
+
+**Action Required**: If your application uses the `variant` attribute, replace it with the `static-color` attribute while keeping the same values. See the example below:
+
+```ts
+// Before
+<sp-action-button variant="black"></sp-action-button>
+
+// After
+<sp-action-button  static-color="black"></sp-action-button>
+```
+
+### 5. Badge (`sp-badge`)
+
+The values for the `position` attribute on `sp-badge` have been removed: `top`, `bottom`, `left`, `right`.
+
+**Action Required**: Replace these fixed values with their logical equivalents:
+
+-   `top` → `block-start`
+-   `bottom` → `block-end`
+-   `left` → `inline-start`
+-   `right` → `inline-end`
+
+### 6. Button (`sp-button`)
+
+Several deprecated values for the `variant` attribute on `sp-button` have been removed, including:
+
+-   `black` and `white`: Use `static-color="black"` or `static-color="white"` instead.
+-   `variant="over-background"`: Use `static-color="white"` with `treatment="outline"` instead.
+-   `cta`: Use `variant="accent"` instead.
+
+**Action Required**: Update all instances where you use the above `variant` attributes on `sp-button`. See the examples below:
+
+#### `black` and `white`
+
+```ts
+// Before (black and white)
+<sp-button variant="black"></sp-button>
+
+// After (black and white)
+<sp-button static-color="black"></sp-button>
+```
+
+#### `overBackground`/`over-background`
+
+```ts
+// Before (overBackground)
+<sp-button variant="over-background"></sp-button>
+
+// After (overBackground)
+<sp-button static-color="white" treatment="outline"></sp-button>
+```
+
+#### `cta`
+
+```ts
+// Before (cta)
+<sp-button variant="cta"></sp-button>
+
+// After (cta)
+<sp-button variant="accent"></sp-button>
+```
+
+### 7. Coach Indicator (`sp-coach-indicator`)
+
+The `variant` attribute for `sp-coach-indicator` has been removed.
+
+**Action Required**: Replace the `variant` attribute with the `static-color` attribute, using the same values. See the example below:
+
+```ts
+// Before
+<sp-coach-indicator variant="black"></sp-coach-indicator>
+
+// After
+<sp-coach-indicator static-color="black"></sp-coach-indicator>
+```
+
+Ensure that all instances of `sp-coach-indicator` in your codebase are updated accordingly.
+
+### 8. Popover (`sp-popover`)
+
+The `dialog` attribute for `sp-popover` has been removed.
+
+**Action Required**: Instead of using the `dialog` attribute, slot an `<sp-dialog>` element into the `sp-popover` component. See the example below:
+
+```ts
+// Before
+<sp-popover dialog></sp-popover>
+
+// After
+<sp-popover>
+  <sp-dialog></sp-dialog>
+</sp-popover>
+```
+
+Ensure that all instances of `sp-popover` using the `dialog` attribute are updated to this new structure.
+
+### 9. Progress Circle (`sp-progress-circle`)
+
+The `overBackground` property and respective `over-background` attribute for `sp-progress-circle` have been removed.
+
+**Action Required**: Replace the `over-background` attribute with the `static-color="white"` attribute. See the example below:
+
+```ts
+// Before
+<sp-progress-circle over-background=true></sp-progress-circle>
+
+// After
+<sp-progress-circle static-color="white"></sp-progress-circle>
+```
+
+Make sure to update all instances of `sp-progress-circle` where `overBackground`/`over-background` is used.
+
+### 10. Theme (`sp-theme`)
+
+The `theme` attribute for `sp-theme` has been removed.
+
+**Action Required**: Replace the `theme` attribute with the `system` attribute. This is a drop-in replacement. See the example below:
+
+```ts
+// Before
+<sp-theme theme="light"></sp-theme>
+
+// After
+<sp-theme system="light"></sp-theme>
+```
+
+Ensure that all instances of the `theme` attribute in your application are updated to use `system` instead.
+
+### 11. Thumbnail (`sp-thumbnail`)
+
+The following deprecated size values for `sp-thumbnail` have been removed: `xxs`, `xs`, `s`, `m`, `l`.
+
+**Action Required**: Replace these deprecated sizes with their corresponding numeric values:
+
+-   `xxs` → `100`
+-   `xs` → `300`
+-   `s` → `500`
+-   `m` → `700`
+-   `l` → `900`
+
+See the example below for the migration:
+
+```ts
+// Before
+<sp-thumbnail size="xs"></sp-thumbnail>
+
+// After
+<sp-thumbnail size="300"></sp-thumbnail>
+```
+
+Make sure to update all instances of `sp-thumbnail` using the deprecated `size` values.
+
+### 12. Dialog and Dialog Wrapper (`sp-dialog` and `sp-dialog-wrapper`)
+
+The `error` attribute for `sp-dialog` and `sp-dialog-wrapper` has been removed.
+
+**Action Required**: Use the [Alert Dialog](/components/alert-dialog/#error) component with the `variant="error"` instead. See the example below:
+
+```ts
+// Before
+<sp-dialog error></sp-dialog>
+
+// After
+<sp-alert-dialog variant="error"></sp-alert-dialog>
+```
+
+## Final Notes
+
+Please ensure your project is fully compatible with Spectrum Web Components 1.0.0 before upgrading. Test thoroughly and review any deprecated or removed functionality as outlined above. If you encounter any issues during migration, consult the documentation or reach out to the team for support.