Gemini Migration

When migrating from the "Gemini" design system to "Mercury," you'll be transitioning your project's styles, components, and design principles to align with the new system. This process involves updating your codebase to replace Gemini-specific components and styles with their Mercury equivalents, ensuring consistency with Mercury's guidelines. The migration guide will provide you with step-by-step instructions to help make this transition as smooth as possible.

1. gxg-accordion

When transitioning from a gxg-accordion:

  1. Replace the gxg-accordion tag with a ch-accordion-render tag.
  2. Remove all the attributes and values.
  3. Add the accordion-filled or accordion-outlined class in order to apply the Mercury styles.
  4. Remove all the gxg-accordion-item items, since the ch-accordion-render uses a model instead.
  5. Assign a model like the one provided in the following example (objectsAccordionModel)
  6. Read Mercury documentation to see how to apply some common cases
  7. Refer to the Chameleon documentation for the complete specifications.

Note:
The following Mercury example uses a spacing utility class .spacing-body, that applies padding all around the accordion item content. To use the .spacing-body you will need to include the propper bundle: utils/spacing.

BEFORE

AFTER

2. gxg-button: Text only

When transitioning from a gxg-button that is "only text":

  1. Replace the gxg-button tag with a button tag.
  2. Remove all the attributes and values.
  3. Add any of the mercury classes that apply for "text only" button types

BEFORE

AFTER

3. gxg-button: Text with icon

When transitioning from a gxg-button that is "text with icon":

  1. Replace the gxg-button tag with a button tag.
  2. Remove all the attributes and values.
  3. Add the button-icon-and-text class.
  4. Insert a ch-image inside the button and follow the documentation for using an icon

BEFORE

AFTER

4. gxg-columns

When transitioning from a gxg-columns:

  1. Replace the gxg-columns tag with a .layout + .layout--cols-* tags, where * is any of the available combinations.
  2. Remove all the attributes and values.
  3. Replace all the gxg-column tags with div.layout__panel tags. Each column content goes inside this tags.
  4. Refer to the Mercury documentation for complete details.

BEFORE

AFTER

5. gxg-combo-box

When transitioning from a gxg-combo-box:

  1. Replace the gxg-select tag with a ch-combo-box-render tag.
  2. Remove all the attributes and values.
  3. Add the combo-box class in order to apply the Mercury styles.
  4. Remove all the gxg-combo-box-item items, since the ch-combo-box-render uses a model instead.
  5. Assign a model like the one provided in the following example (favoriteCarsModel)
  6. Read Mercury documentation to see how to apply some common cases
  7. Refer to the Chameleon documentation for the complete specifications.

BEFORE

AFTER

6. gxg-form-checkbox

When transitioning from a gxg-form-checkbox:

  1. Replace the gxg-form-checkbox tag with a ch-checkbox tag.
  2. Remove all the attributes and values.
  3. Add the checkbox class.
  4. Specify the control properties following the documentation

BEFORE

AFTER

7. gxg-form-radio-group

When transitioning from a gxg-form-radio-group:

  1. Replace the gxg-form-radio-group tag with a ch-radio-group-render tag.
  2. Remove all the attributes and values.
  3. Add the radio-group class.
  4. Specify the control properties following the documentation

BEFORE

AFTER

8. gxg-form-text

When transitioning from a gxg-form-text:

  1. Replace the gxg-form-text tag with a ch-edit tag.
  2. Remove all the attributes and values.
  3. Add the input class.
  4. Specify the control properties following the documentation

BEFORE

AFTER

9. gxg-form-textarea

When transitioning from a gxg-form-textarea:

  1. Replace the gxg-form-textarea tag with a ch-edit tag.
  2. Remove all the attributes and values.
  3. Add the input class.
  4. Specify the control properties following the documentation

BEFORE

AFTER

10. gxg-grid

When transitioning from a gxg-grid:

  1. Replace the gxg-grid tag with a ch-tabular-grid tag.
  2. Remove all the attributes and values.
  3. Add the tabular-grid class.
  4. Specify the control properties following the documentation

BEFORE

AFTER

11. gxg-icon

When transitioning from a gxg-icon:

  1. Replace the gxg-icon tag with a ch-image tag.
  2. Remove all the attributes and values.
  3. Add the icon-sm or icon-md class.
  4. Specify the control properties following the documentation

BEFORE

AFTER

12. gxg-label

When transitioning from a gxg-label:

  1. Replace the gxg-label tag with a label tag.
  2. Remove all the attributes and values.
  3. Add the label class.

BEFORE

AFTER

13. gxg-list-box

When transitioning from a gxg-list-box:

  1. Replace the gxg-list-box tag with a ch-action-list-render tag.
  2. Remove all the attributes and values.
  3. Add the list-box class.

BEFORE

AFTER

14. gxg-modal

When transitioning from a gxg-modal: If you want to open a dialog similar to others in the IDE, it's best to use the IDE services to do so. You can find documentation and examples in the plugins repository.

BEFORE

AFTER

15. gxg-pills

When transitioning from a gxg-pills:

  1. Replace the gxg-pills tag with a ch-combo-box-render tag.
  2. Remove all the attributes and values.
  3. Add the pill class.

BEFORE

AFTER

16. gxg-select

When transitioning from a gxg-select:

  1. Replace the gxg-select tag with a ch-combo-box-render tag.
  2. Remove all the attributes and values.
  3. Add the combo-box class in order to apply the Mercury styles.
  4. Remove all the gxg-option items, since the ch-combo-box-render uses a model instead.
  5. Assign a model like the one provided in the following example (carsComboBoxModel)
  6. Read Mercury documentation to see how to apply some common cases
  7. Refer to the Chameleon documentation for the complete specifications.

BEFORE

AFTER

17. gxg-stack

When transitioning from a gxg-stack:


Gemini's gxg-stack was used to evenly space components or elements with a consistent gap. The gap size was defined as a property, selected from a predefined set of spacing tokens.


While this solution provided some visual consistency, the spacing value chosen by the user was free, causing the same type of elements to have different gap values in different sections.


In Mercury, the gap between elements is determined by the design system and depends on the type of context. At the time of writting, the only existing vertical gap is generated for controls, by the .field-group class, within which form fields (.field) are placed.


Read Mercury documentation to see how to apply some common cases

BEFORE

AFTER

18. gxg-suggest

When transitioning from a gxg-list-box:

  1. Replace the gxg-list-box tag with a ch-action-list-render tag.
  2. Remove all the attributes and values.
  3. Add the list-box class.
  4. Specify the ch-combo-box-render items following the model property
  5. Set the suggest property to true to turn the suggest feature on.
  6. Subscribe to the filterChange event listener, and use the event.detail to filter the items accordingly, by defining the filter value.
  7. Specify the options by following the suggestOptions property

BEFORE

AFTER

19. gxg-tabs

When transitioning from a gxg-tabs:

  1. Replace the gxg-tabs tag with a ch-tab-render tag.
  2. Remove all the attributes and values.
  3. Add the tab class.
  4. Specify the control properties following the documentation

BEFORE

AFTER

20. gxg-text

When transitioning from a gxg-text:

  1. Replace the gxg-text tag with a p tag.
  2. Remove the type attribute/value
  3. Add the body class.

BEFORE

AFTER

21. gxg-title

When transitioning from a gxg-title:

  1. Replace the gxg-title tag with a h* tag.
  2. Remove the type attribute/value
  3. Add the heading-* class.

BEFORE

AFTER

22. gxg-tree-view

When transitioning from a gxg-tree-view:

  1. Replace the gxg-tree-view tag with a ch-tree-view-render tag.
  2. Remove all the attributes and values.
  3. Add the tree-view class.

BEFORE

AFTER