V4 Migration Guide

General Changes
Tokenization & CSS Variables
- Z-index CSS Variable Overrides
Default styles for HTML elements / CSS reset
Legacy Theme
Component Stability Changes
Component API Changes
- V3 Beta Components Promoted to Stable in V4 API Changes
- Stable Component API Changes
Components Without API Changes

General Changes

There is a new genesys-spark package that will load the components from the web at runtime, ensuring that apps will not unnecessarily bundle component assets. This is now the recommended way to install the design system. More information here
Typescript updated to v5
registerElements() is no longer an async/promise function.
Visualizations have been moved out of genesys-spark-components into a separate package in the same genesys-spark monorepo project, genesys-spark-visualizations
PopperJS dependency removed. All instances of PopperJS have been replaced with Floating UI. We do not expect this to affect component usage.

Tokenization & CSS Variables

In the v4 release, components have gone through a redesign process to adopt the new design system styles. Part of this effort included adopting tokens for styles within the components. Using tokens will simplify design changes in the future, helping us keep aligned with the Spark design system. Since we have moved toward using tokens in the components, some of our shared classes are no longer needed. These include:

Shadows: see the shadow styles migration guide
Colors: see the color palette migration guide
Spacing: see the spacing variables migration guide

The tokens are exposed as CSS variables, which are used by the components. However, they are not yet an officially supported API. The specifics of the variables should be considered to be in a beta state. We will do our best to avoid removing/renaming CSS variables, but will do so if needed to resolve problems in the components.

Z-index CSS Variable Overrides

The default z-index values and CSS variable overrides for components have been changed and set as tokens in v4. See the z-index migration guide for more details

Default styles for HTML elements / CSS reset

As part of the alignment with the Spark design system, the default styles for HTML elements have changed. While this is not necessarily a breaking change, layouts and spacing of elements may look different after upgrading to V4. Read more about the Spark V4 typography on the Spark Design System documentation site

Legacy Theme

After the release of v4 the UX team received feedback on how the style changes from v3 to v4 were too large of a change to introduce to customers without notice. We have created a Legacy Theme for v4 that should allow teams to work past this concern and introduce the style change in a controlled manner. The legacy theme decouples the component API migration and the Flare style migration. Teams can migrate from v3 to v4 with the legacy theme first to minimize visual change and them follow up with a migration from the legacy theme to the latest Flare theme.

import { registerSparkComponents } from 'genesys-spark';

- registerSparkComponents();
+ registerSparkComponents({theme: 'legacy'});

Component Stability Changes

As part of our major version release process, we evaluate the following:

Beta components that have well established APIs may be promoted to stable
Stable components that have been replaced or are no longer supported in the design system may be moved to legacy
Legacy components from the previous version may be removed
Beta components from the previous version may be removed

More details about this process can be found in the component evolution documentation

V3 Beta Components Promoted to Stable in V4

Action: (required) remove -beta from the tag name of the component.

- <gux-example-beta>
+ <gux-example>
  ...
- </gux-example-beta>
+ </gux-example>

Component tag rename only, no API changes:

V3 tag name	V4 tag name
`gux-blank-state-beta`	`gux-blank-state`
`gux-column-manager-beta`	`gux-column-manager`
`gux-context-menu-beta`	`gux-context-menu`
`gux-copy-to-clipboard-beta`	`gux-copy-to-clipboard`
`gux-inline-alert-beta`	`gux-inline-alert`
`gux-loading-message-beta`	`gux-loading-message`
`gux-flyout-menu-beta`	`gux-flyout-menu`
`gux-pagination-beta`	`gux-pagination`
`gux-popover-beta`	`gux-popover`
`gux-popup-beta`	`gux-popup`
`gux-skip-navigation-list-beta`	`gux-skip-navigation-list`
`gux-tab-panel-beta`	`gux-tab-panel`
`gux-table-beta`	`gux-table`
`gux-table-toolbar-beta`	`gux-table-toolbar`
`gux-time-picker-beta`	`gux-time-picker`
`gux-truncate-beta`	`gux-truncate`

Component tag rename AND required API changes:

V3 tag name	V4 tag name	API Changes
`gux-badge-beta`	`gux-badge`	migration details
`gux-button-slot-beta`	`gux-button-slot`	migration details
`gux-card-beta`	`gux-card`	migration details
`gux-dropdown-multi-beta`	`gux-dropdown-multi`	migration details
`gux-tag-beta`	`gux-tag`	migration details

V3 Stable Components Archived to Legacy in V4

V3 tag name	V4 tag name	V4 stable equivalent (requires API changes)	Migration Guide
`gux-action-toast`	`gux-action-toast-legacy`	`gux-toast`	migration details
`gux-disclosure-button`	`gux-disclosure-button-legacy`	none	Contact the Design System UX Team
`gux-notification-toast`	`gux-notification-toast-legacy`	`gux-toast`	migration details
`gux-pagination`	`gux-pagination-legacy`	`gux-pagination` (`gux-pagination-beta` in v3)	migration details
`gux-simple-toast`	`gux-simple-toast-legacy`	`gux-toast`	migration details
`gux-switch`	`gux-switch-legacy`	`gux-segmented-control-beta` (or `gux-tabs`)	migration details
`gux-modal`	`gux-modal-legacy`	`gux-modal`	migration details

Action: (required) add -legacy to the tag name of the component.

- <gux-example>
+ <gux-example-legacy>
  ...
- </gux-example>
+ </gux-example-legacy>

If possible, avoid the usage of legacy components that have a migration path and do a full migration to a stable component. The basic migration of adding -legacy will have to be followed up with a full migration to a stable component before the next major version is released. If you are using a legacy component that has no documented migration path please contact the Design System UX Team. They will guide you on the best approach to take to remove your dependency on that legacy component.

V3 Beta Components Removed From V4

V3 tag name	V4 equivalent	Migration Guide
`gux-error-message-beta`	N/A	migration details

V3 Legacy Components Removed from V4

V3 tag name	V4 stable equivalent (requires API changes)	Migration Guide
`gux-accordion-legacy`	`gux-accordion`	migration details
`gux-action-button-legacy`	`gux-action-button`	migration details
`gux-action-list-legacy`	`gux-list`	migration details
`gux-button-multi-legacy`	`gux-button-multi`	migration details
`gux-command-palette-legacy`	N/A	N/A
`gux-dropdown-legacy`	`gux-dropdown`	migration details
`gux-form-field-legacy`	`gux-form-field-{type}`	migration details
`gux-list-legacy`	`gux-list`	migration details
`gux-panel-frame-legacy`	N/A	N/A
`gux-side-panel-legacy`	N/A	N/A
`gux-tabs-legacy`	`gux-tabs`, `gux-tabs-advanced`	migration details
`gux-text-label-legacy`	N/A	N/A

Component API Changes

V3 Beta Components Promoted to Stable in V4 API Changes

gux-badge

New Prop: The color property has been removed. Instead, now use the accent property. All uses of the color property can be migrated to the accent property.

color	accent
green	success
inherit	inherit
neutral	info
red	error
yellow	warning

- <gux-badge-beta color="green">Text</gux-badge-beta>
+ <gux-badge accent="success">Text</gux-badge>

- <gux-badge-beta color="inherit">Text</gux-badge-beta>
+ <gux-badge accent="inherit">Text</gux-badge>

- <gux-badge-beta color="neutral">Text</gux-badge-beta>
+ <gux-badge accent="info">Text</gux-badge>

- <gux-badge-beta color="red">Text</gux-badge-beta>
+ <gux-badge accent="error">Text</gux-badge>

- <gux-badge-beta color="yellow">Text</gux-badge-beta>
+ <gux-badge accent="warning">Text</gux-badge>

gux-button-slot

New Prop: An icon-only prop has been added. This should be used when the slotted button only contains an icon. This will allow the component to be styled correctly.

- <gux-button-slot>
+ <gux-button-slot icon-only>
    <button
      type="button"
      title="This will be read by a screen reader"
      onclick="notify(event)"
    >
      <gux-icon icon-name="fa/diamond-regular" decorative></gux-icon>
    </button>
  </gux-button-slot>

gux-calendar

Event Rename: The input event has been renamed calendarSelect

gux-card

Prop Update: The accent types for gux-card have been updated.
- The outline type has been deprecated in v4 and has been replaced by bordered as the default accent.
- The filled type has been deprecated in v4.

gux-dropdown-multi

Removed Prop: The deprecated attribute filterable has now been completely removed in favor of filter-type. The equivalent to the boolean filterable attribute is filter-type with a string value of starts-with.

- <gux-dropdown-multi-beta filterable>
+ <gux-dropdown-multi filter-type="starts-with">
    ...
  </gux-dropdown-multi>

gux-popover

New Prop: An is-open prop has been added to control showing and hiding the component. This property should now be used instead of the component's hidden global attribute. Note the different context of the new property and old attribute so hidden="true" will become is-open="false" and vice-versa.
Style Change: A min-width of 280px has been applied to the component.

gux-popover-list

New Prop: An is-open prop has been added to control showing and hiding the component. This property should now be used instead of the component's hidden global attribute. Note the different context of the new property and old attribute so hidden="true" will become is-open="false" and vice-versa.

gux-tag

Removed Prop: The color property has been removed.
New Prop: The new accent property has been added.
- All uses of the color property must be migrated to the accent property.
- The accent property accepts a number 1-10, default or inherit
- The mapping of color to accent is not 1:1, so there is no specific guidance for mapping a specific color to an accent. The inherit property can be used to provide the tag with a custom color.
- If further guidance is needed for your use case, please reach out to the Design System Team

- <gux-tag-beta color="navy">Text</gux-tag-beta>
+ <gux-tag accent="1">Text</gux-tag>

Removed Prop: The value property has been removed.
- This change also effects the guxdelete event. The event no longer contains the value in the detail field.
- You should now remove the element using the events target to get a reference to the element.
```
document.querySelector('gux-tag').addEventListener('guxdelete', event => {
  event.target.remove();
});
```

Stable Component API Changes

gux-accordion

Prop Changes: The arrow-position property has had the following changes:

The default arrow position is now end.

The before-text value has been renamed start.

- <gux-accordion><gux-accordion-section arrow-position="before-text"></gux-accordion-section></gux-accordion>
+ <gux-accordion><gux-accordion-section arrow-position="start"></gux-accordion-section></gux-accordion>

The beside-text value has been removed.

- <gux-accordion><gux-accordion-section arrow-position="beside-text"></gux-accordion-section></gux-accordion>
+ <gux-accordion><gux-accordion-section></gux-accordion-section></gux-accordion>

gux-action-button

Removed Prop: The deprecated text prop has been removed. Instead, slot in a span or div with a slot name of title.

- <gux-action-button text="Primary" accent="primary" is-open="true">
+ <gux-action-button accent="primary" is-open="true">
+   <span slot="title">Primary</span>
    <gux-list-item onclick="notify(event)">Test 1</gux-list-item>
    <gux-list-item onclick="notify(event)">Test 2</gux-list-item>
  </gux-action-button>

gux-button-multi

Removed Prop: The deprecated text prop has been removed. Instead, slot in a span or div with a slot name of title.

- <gux-button-multi text="Primary" accent="primary" is-open="true">
+ <gux-button-multi accent="primary" is-open="true">
+   <span slot="title">Primary</span>
    <gux-list-item onclick="notify(event)">Test 1</gux-list-item>
    <gux-list-item onclick="notify(event)">Test 2</gux-list-item>
  </gux-button-multi>

gux-content-search

Style Change: Internal margins have been removed. See details in the form-field-component section for more details

gux-datepicker

Style Change: Internal margins have been removed. See details in the form-field-component section for more details

gux-dropdown

Removed Prop: The deprecated property filterable has now been completely removed in favor of filter-type. The equivalent to the boolean filterable attribute is filter-type with a string value of starts-with.

- <gux-dropdown filterable>
+ <gux-dropdown filter-type="starts-with">
    ...
  </gux-dropdown>

gux-radial-progress

Removed Prop: The scale property has been removed. The displayed percentage will now always be an integer value.

- <gux-radial-progress scale="2" screenreader-text="Uploading file" value="0" max="100"></gux-radial-progress>
+ <gux-radial-progress screenreader-text="Uploading file" value="0" max="100"></gux-radial-progress>

gux-form-field (color, number, range, search, select, text-like, textarea)

Style Change: Internal margins have been removed from the form field components.

This change was implemented to accommodate layouts that already accounted for spacings between components. In v3, developers could override the component margins with four CSS custom properties:
- --gux-form-field-container-margin-top
- --gux-form-field-container-margin-bottom
- --gux-form-field-fieldset-container-margin-top
- --gux-form-field-fieldset-container-margin-bottom
These custom properties were used to override the style of the internal margins, (usually to set them to 0).

In v4, since the internal margin styles have been removed, developers who were using the custom properties to set the internal margins to 0 can remove that workaround as it is no longer needed (or supported).

In v4, developers who want the component to have a margin similar to v3 can add margin: 16px 0 16px 0 to the component in their application.

gux-form-field-checkbox

New Prop: The label-position property has now been added to gux-form-field-checkbox. The property can be used to change the position of the label.
- The positions beside and screenreader are currently available to use. The default label-position is beside.
```
+ <gux-form-field-checkbox label-position="beside">
  ...
  </gux-form-field-checkbox>
+ <gux-form-field-checkbox label-position="screenreader">
  ...
  </gux-form-field-checkbox>
```

gux-icon

New Prop: The size property has now been added to gux-icon. The property can be used to set the size on the element to one of the three Spark approved sizes {small, medium, large}. A gux-icon can still be set to an arbitrary size if that is what your application calls for.
Access to legacy icons
- No legacy icons have been removed in v4 but how they are accessed has changed.
- We have removed automatic legacy/ prefixing of icon names that only existed in the legacy icon list. You may need to add this prefix yourself in v4 and plan to migrate to an official Spark icon.
- We have removed automatic icon mapping from one icon name to another. You may need to change your icon name if you were using an icon name that was mapped to another.
- These changes simplify the icon component as now all icon names are a one-to-one mapping to an svg file.
- These changes should also make it clearer to application teams if the icons they are using are official Spark icons or not.
- The process for adding Official Spark icons has been streamlined and you should contact the UX Design System Team if you require an official replacement for a legacy icon used in your application

gux-rating

New Prop: A new increment property has been added to gux-rating. This property can be set to "default" or "half". In V3 increments were always 0.5 (half) so if needed you must add increment="half" to your rating component for it to behave in an identical manner.
```
  <gux-rating
    aria-label="feedback"
+   increment="half"
  >
  </gux-rating>
```

gux-tabs

Removed Prop: The use-flexbox prop has been removed. The tabs component now uses flexbox positioning by default.

gux-tab-panel

Shadow DOM: This component now uses the shadow DOM. We do not expect this change to require any updates in applications. If this change does cause you an issue please reach out to the CORE UI team for help.

gux-text-highlight

New Prop: A new dimmed property has been added to gux-text-highlight. This property changes the color used to highlight the text to a lighter one.
Shadow DOM: This component now uses the shadow DOM. We do not expect this change to require any updates in applications. If this change does cause you an issue please reach out to the CORE UI team for help.

gux-tooltip

New Prop: accent property.

The accents light and dark are currently available to use. The default accent is light.

+ <gux-tooltip accent="light">Tooltip</gux-tooltip>
+ <gux-tooltip accent="dark">Tooltip</gux-tooltip>

New Prop: anchor property.
- The anchor property will display an anchor on the tooltip pointing towards the target element.
```
+ <gux-tooltip anchor>Tooltip</gux-tooltip>
```

The default component behavior for gux-tooltip remains unchanged. We suggest reading the Spark Design documentation or consulting with your UX contact before using the new properties.

Components Without API Changes

The following components do not have any API changes or tag name changes and should not require any migration work

Beta:

gux-announce-beta
gux-date-beta
gux-date-time-beta
gux-month-picker-beta
gux-phone-input-beta
gux-screen-reader-beta
gux-time-zone-picker-beta
gux-time-beta

Stable:

gux-breadcrumbs
gux-button
gux-list
gux-listbox
gux-listbox-multi
gux-page-loading-spinner
gux-pagination-cursor
gux-rating
gux-radial-loading
gux-toggle

Legacy:

advanced-dropdown-legacy

This migration guide is open to anyone to edit. If you have migrated a component and think it would be helpful to others to document something you encountered please do so. We understand that at the moment because of the need to fork the repo the overhead of making a small contribution is high so feel free to raise an issue on the COMUI board instead it that is more convenient and a core team member will create the PR.

Files

readme.md

Latest commit

History