feat: add 1.0.0 migration guide

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

@@ -0,0 +1,189 @@
+---
+layout: guide.njk
+title: 'Migration Guide: Spectrum Web Components (v1.0.0)'
+displayName: 2024/10/01 (v1.0.0)
+slug: migration-guide
+---
+
+## Migration: 2024/10/01 (v1.0.0)
+
+With the release of Spectrum Web Components version 1.0.0, we removed previously deprecated components and features.
+Starting with this version, Spectrum Web Components adheres to [semantic versioning (semver)](https://semver.org/), ensuring that any future breaking changes will be introduced only in major version updates. These changes will be communicated in advance, allowing developers to prepare and avoid disruption to existing applications. Patch releases, as part of this versioning approach, will be non-breaking and 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 `staticColor` attribute while keeping the same values. See the example below:
+
+```ts
+// Before
+<sp-action-button variant="black"></sp-action-button>
+
+// After
+<sp-action-button  staticColor="black"></sp-action-button>
+```
+
+### 5. Badge (`sp-badge`)
+
+The following deprecated fixed 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 `staticColor="black"` or `staticColor="white"` instead.
+-   `overBackground`: Use `staticColor="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 staticColor="black"></sp-button>
+```
+
+#### `overBackground`
+
+```ts
+// Before (overBackground)
+<sp-button variant="overBackground"></sp-button>
+
+// After (overBackground)
+<sp-button staticColor="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 `staticColor` attribute, using the same values. See the example below:
+
+```ts
+// Before
+<sp-coach-indicator variant="black"></sp-coach-indicator>
+
+// After
+<sp-coach-indicator staticColor="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 for `sp-progress-circle` has been removed.
+
+**Action Required**: Replace the `overBackground` property with the `staticColor="white"` attribute. See the example below:
+
+```ts
+// Before
+<sp-progress-circle overBackground></sp-progress-circle>
+
+// After
+<sp-progress-circle staticColor="white"></sp-progress-circle>
+```
+
+Make sure to update all instances of `sp-progress-circle` where `overBackground` 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.
+
+## 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 for support.