# Migration guides

This document contains instructions on how to update to each new major version from the previous version.

If you need to update several versions at once, it is recommended to follow the steps for one version at a time until you reach the latest one.

Before you begin, make sure you have the latest feature/patch version of your current major version.

## Automated migrations

Many migrations can be automated using the `green-core-context migrate` command. This will detect and apply code changes for supported automated migrations.
Check out the [Context CLI documentation](/docs/guides-green-context-cli--docs) for more details on how to use the migration engine.

An effective way to apply the upgrade is to let your coding agent use the CLI to run migrations and handle manual steps.

For example:
```markdown
We're updating this app to green-core 3.0.

Please use the `npx green-core-context migrate` CLI tool to run the migrations, and then handle any manual steps required.

When done, please give me a breakdown of what was updated.
```
(remember to install the updated package first)

## 2.x.x to 3.x.x

This release includes several improvements, both technical updates and structural changes that make the system easier and more consistent to work with across platforms.

- **Card:** Legacy card variants have been renamed.
  - **Migration step:**
    - `variant="primary"` -> `variant="neutral-01"`
    - `variant="secondary"` -> `variant="neutral-02-outlined"`
    - `variant="tertiary"` -> `variant="neutral-02"`
  - **Applies to:** `gds-card`, `gds-card-linked`, `gds-card-pattern-01`, and corresponding React wrappers.
- **Checkbox/Radio group:** `direction` has been renamed.
  - **Migration step:**
    - Web component attribute: `direction` -> `flex-direction`
    - Angular property binding: `[direction]` -> `[flexDirection]`
    - Angular attribute binding: `[attr.direction]` -> `[attr.flex-direction]`
    - React prop: `direction` -> `flexDirection`
  - **Note:** JavaScript property assignments and `setAttribute('direction', ...)` usages should be reviewed and updated manually when targeting `gds-checkbox-group` or `gds-radio-group` instances.
- **Colors:** Several color tokens were renamed and a small set of tokens were removed.
  - **Migration step:** Replace renamed tokens according to the cheat sheet below.
  - **Note:** Deleted and legacy tokens must be reviewed manually.
- **Typography:** Typography tokens now use `[name]-[size]-[weight]` ordering instead of `[name]-[weight]-[size]`.
  - **Migration step:** Rename token usages according to the cheat sheet below, including shorthand style-expression values.
  - **Note:** Deleted tokens have suggested replacements, but should be reviewed manually.

### Color token migration cheat-sheet (2.x.x -> 3.x.x)

**Core color token renames**
- `--gds-sys-color-l1-inversed` -> `--gds-sys-color-l1-neutral-03`
- `--gds-sys-color-l3-neutral-01` -> `--gds-sys-color-l3-neutral-03`
- `--gds-sys-color-l3-neutral-03` -> `--gds-sys-color-l3-neutral-01`
- `--gds-sys-color-l3-brand-03` -> `--gds-sys-color-l3-brand-02-2`
- `--gds-sys-color-content-inversed` -> `--gds-sys-color-content-neutral-05`
- `--gds-sys-color-border-interactive` -> `--gds-sys-color-border-neutral-01`
- `--gds-sys-color-border-subtle-01` -> `--gds-sys-color-border-neutral-02`
- `--gds-sys-color-border-subtle-02` -> `--gds-sys-color-border-neutral-03`
- `--gds-sys-color-border-strong` -> `--gds-sys-color-border-neutral-04`
- `--gds-sys-color-border-inverse` -> `--gds-sys-color-border-neutral-05`

**Shorthand value renames (for color-related attributes/props)**
- `inversed` -> `neutral-05`
- `interactive` -> `neutral-01`
- `subtle-01` -> `neutral-02`
- `subtle-02` -> `neutral-03`
- `strong` -> `neutral-04`
- `inverse` -> `neutral-05`

**Deleted tokens (manual review required)**
- `--gds-sys-color-l3-neutral-04`
- `--gds-sys-color-l3-neutral-05`
- `--gds-sys-color-l3-disabled-02`
- `--gds-sys-color-l3-disabled-03`
- `--gds-sys-color-content-disabled-02`

**Legacy tokens (manual review required)**
- `--gds-sys-color-dark-red-2`
- `--gds-sys-color-blue`

### Typography token migration cheat-sheet (2.x.x -> 3.x.x)

**Renamed tokens (safe replacements)**
- `--gds-sys-text-detail-book-m` -> `--gds-sys-text-detail-m-book`
- `--gds-sys-text-detail-book-s` -> `--gds-sys-text-detail-s-book`
- `--gds-sys-text-detail-book-xs` -> `--gds-sys-text-detail-xs-book`
- `--gds-sys-text-detail-regular-m` -> `--gds-sys-text-detail-m-regular`
- `--gds-sys-text-detail-regular-s` -> `--gds-sys-text-detail-s-regular`
- `--gds-sys-text-detail-regular-xs` -> `--gds-sys-text-detail-xs-regular`
- `--gds-sys-text-body-medium-m` -> `--gds-sys-text-body-m-medium`
- `--gds-sys-text-body-medium-s` -> `--gds-sys-text-body-s-medium`
- `--gds-sys-text-body-book-m` -> `--gds-sys-text-body-m-book`
- `--gds-sys-text-body-book-s` -> `--gds-sys-text-body-s-book`
- `--gds-sys-text-body-regular-l` -> `--gds-sys-text-body-l-regular`
- `--gds-sys-text-body-regular-m` -> `--gds-sys-text-body-m-regular`
- `--gds-sys-text-body-regular-s` -> `--gds-sys-text-body-s-regular`
- `--gds-sys-text-body-italic-l` -> `--gds-sys-text-body-l-regular-italic`
- `--gds-sys-text-body-italic-m` -> `--gds-sys-text-body-m-regular-italic`
- `--gds-sys-text-body-italic-s` -> `--gds-sys-text-body-s-regular-italic`

**Deleted tokens (manual review with suggested replacement)**
- `--gds-sys-text-display-2xl` -> `--gds-sys-text-display-l`
- `--gds-sys-text-display-xl` -> `--gds-sys-text-display-l`
- `--gds-sys-text-heading-2xs` -> `--gds-sys-text-heading-xs`
- `--gds-sys-text-preamble-2xl` -> `--gds-sys-text-preamble-xl`
- `--gds-sys-text-preamble-xs` -> `--gds-sys-text-preamble-s`

The same typography renames also apply to shorthand style-expression values (for example `body-regular-m` -> `body-m-regular`).

## 1.90.2 to 2.x.x

This release contains several updates and refinements related to the design tokens and declarative layout system. A lot of work has gone into aligning things between code and design (Figma), in order to make the design and development process as seamless as possible for everyone.

Many of the breaking changes relates to how tokens are named and used, but we also took the opporutinity to remove some old deprecations and implement some much needed refactorings.

- **Badge:** Removed disabled property in favor for making it a variant.
  - **Migration step:** use `<gds-badge variant="disabled">` instead of `<gds-badge disabled>`
- **Badge:** There is no positive variant of the notification property of the badge
  - **Migration step:** No action necessary, but variant will be ignored when the notification property is set to true.
- **Button:** Button variants `brand`, `warning` and `notice` is now added. Default button variant is now `neutral` instead of `brand` that was before.
   - **Migration step:** Add `variant="brand"` to buttons that should have the senior green colour.
- **Card:** Removed `shadow` prop from `gds-card`
   - **Migration step:** Use `box-shadow` property instead of `shadow`.
- **Colors:** Overhaul of color tokens structure and naming conventions.
  - **Migration step:** Many of the color tokens used for `color`, `background`, `border-color`, and similar properties that accepts color tokens, have changed names. Refer to cheat sheet below for how to update the most commonly used colors.
- **Container:** Removed `gds-container`
  - **Migration step:** Use `gds-div` instead.
- **Dialog:** Removed overflow style by default.
  - **Migration step:** If you were relying on the overflow behavior for long content to be scrollable, you now need to add overflow styles to the slotted element instead. For example, wrap the content in a `<gds-div>` with overflow and height set.
- **Divider:** Removed levels from Divider since it's no longer relevant due to border lot being a part of the levels structure.
  - **Migration step:** If you have been using the levels prop to control the color you should now insted use the color prop to set the possible colors on the divider. See color documentation to see possible border colors.
- **Font:** `font-size` changed to `font`, and font tokens updated.
  - **Migration step:** Change all occurences of the `font-size` style expression property and replace with font. Add font-weight to token name. Example: `<gds-text font-size="body-m">` --> `<gds-text font="body-regular-m">`
  - **Note:** Because the `font` shorthand property includes the `font-family` property, components now expect the `SEB SansSerif GDS` font-family to be present, whereas before they just inherited `font-family` from higher in the document. Make sure you import the `SEB SansSerif GDS` font from the `@sebgroup/fonts` package and include the font declaration CSS from there.
- **Icon:** Removed deprecated `width` and `height` properties.
  - **Migration step:** Use the `size` property instead.
- **Spacer:** Removed `gds-spacer`
  - **Migration step:** Use `gds-div` instead, and set height using the `height` property.
- **Theme:** Default design-version of `gds-theme` is changed to `2023`
  - **Migration step:** To keep 2016 style, set the design-version attribute to "2016" explicitly.
- **Theme:** `gds-theme` now sets the `color` CSS property by default.
  - **Migration step:** If you were relying on inheriting `color` from higher in the document, you need to override this now by setting the `color` CSS property explicitly.

### Color token migration cheat-sheet for the most commonly used colors

**Background**
- primary -> neutral-01
- secondary -> neutral-02
- tertiary -> neutral-03
- positive -> positive-01
- negative -> negative-01

**Color**
- primary -> neutral-01
- secondary -> neutral-02
- tertiary -> neutral-03
- positive -> positive-01
- negative -> negative-01

**Border**-color
- primary -> subtle-01
- secondary -> strong