Migration to Fuegokit React v3

Fuegokit React v3 Migration Guide

The Design Systems team is thrilled to announce the release of Fuegokit React v3. 🎉

This guide describes how you can easily migrate and get the latest changes, either manually, or using our codemods, and it describes changes made in the library itself.

What's changing

Fuegokit React v3:

• ships with a default theme built with Fuegokit design tokens
• introduces new components
• migrates several components to deprecated status
• deprecates system props

Why you should upgrade

Fuegokit React v3 ships with a default theme built with design tokens.

Why you should upgrade to v3:

• Fuegokit's design tokens provide a more stable and predictable API.
• Appfire's designers use design tokens, and Fuegokit's design tokens integrates designer tools like Figma with the actual code shipped into Fuegokit design tokens. Designers and developers at Appfire now share a single source of truth.
• You will always be able to opt in to the most up-to-date design decisions in your app after upgrading to v3.
• Tokens make features like accessibility color modes, more responsive design, and other types of user customization possible.
• Changes can be made once and propagate across the system
• Tokens are at the core of how Appfire is implementing its visual design foundations. This delivers visual consistency and other improvements to every Appfire product that adopts Fuegokit.

Fuegokit React v3 also ships with many new "batteries-included" and fully-styled React components you can use as 1:1 drop-in replacements in the product environment, as well as ecosystem-agnostic and accessible React components authored according to WAI-ARIA authoring principles.

Try it today

You can preview the latest changes in your app by installing @fuegokit/react@0.0.0-20230613172515.

The release candidate is available for preview and feedback -- we don't recommend using it in production until you've had a chance to try the release candidate in a testing environment.

Codemods

Running codemods will bulk apply all of the necessary changes to Fuegokit React components installed in your project in one command.

You can run the codemods by installing the Fuegokit codemod CLI utility:

npm install @fuegokit/codemod

Then run the V3 codemods in your project:

npx @fuegokit/codemod v3.0.0/fuegokit-v2-to-v3 ./path/to/your/file

This will make all of the necessary changes in your project at once.

Additionally, you can run codemods individually. See the Codemods docs for details.

Breaking changes

The most significant changes have to do with adopting Fuegokit's design tokens stable taxonomy.

That means that some CSS-in-JS token names are getting updates in the default theme. In CSS-in-JS, surface.default becomes elevation.surface.default.[default]. CSS variables are not changing.

Additionally, there are additional scale values now included in the default theme scales for fontSizes, fontWeights, and radii.

Adopting the stable taxonomy introduced with Fuegokit design tokens means more stability, greater multi-ecosystem theming support, and less maintenance.

How to update manually

The default theme that ships with Fuegokit React is now shipped directly via Fuegokit's design tokens.

When you install Fuegokit React v3, you will need to update a few of the design token values that originally shipped with Fuegokit React v2.

If you are not using codemods, you can use find-replace and exchange the new value for the previous value in your app, for example:

-  <MyStyledComponent>My text</MyStyledComponent>;
-
- const MyStyledComponent = styled(Text)`
-   font-size: ${themeGet('fontSize: 2')};
- `
-
+ <MyStyledComponent>My text</MyStyledComponent>;
+
+ const MyStyledComponent = styled(Text)`

Each of the following contain values that are changing in the default Fuegokit React theme. The guide below provides details about how to update each.

Summary of values that contain token names that are being updated to the stable taxonomy in V3:

• Font sizes
• Font weights
• Border radius
• Box shadow
• Color (surface)
• Color (background)

Updating font-size token names

Fuegokit React now ships with a default theme built with tokens.

The new font-size scale adds several additional steps on the font-size scale for greater utility.

You should update your use of this set of tokens as follows:

with themeGet

If you're using a token with the themeGet function, you can find-replace or use regex to make the following substitutions.

Example

-  <Text sx={{fontSize: 2}}>My text</Text>;
-
- const StyledText = styled(Text)`
-   font-size: ${themeGet('fontSize: 2')};
- `
-
+ <StyledText>My text</StyledText>;
+
+ const StyledText = styled(Text)`

with the sx prop

If you're using a token with the sx prop, you can find-replace or use regex to make the following substitutions.

• fontSize: 2 --> fontSize: 3
• fontSize: 3 --> fontSize: 4
• fontSize: 4 --> fontSize: 5
• fontSize: 5 --> fontSize: 6
• fontSize: 6 --> fontSize: 7
• fontSize: 7 --> fontSize: 11
• fontSize: 8 --> fontSize: 12
• fontSize: 9 --> fontSize: 13

Example

-  <Text sx={{fontSize: 2}}>My text</Text>;
+ <Text sx={{fontSize: 3}}>My app</Text>;

with system props

System props are deprecated. Migrate to the sx prop or create a styled component using the themeGet function.

If you're using a token with the system props, you can find-replace or use regex to make the following substitutions.

• fontSize={2} --> fontSize={3}
• fontSize={3} --> fontSize={4}
• fontSize={4} --> fontSize={5}
• fontSize={5} --> fontSize={6}
• fontSize={6} --> fontSize={7}
• fontSize={7} --> fontSize={11}
• fontSize={8} --> fontSize={12}
• fontSize={9} --> fontSize={13}

Example

-  <Text fontSize={2}>My text</Text>;
+ <Text fontSize={3}>My text</Text>;

Updating font-weight token names

Fuegokit React now ships with a default theme built with tokens.

The new font-weights scale adds additional font-weights for greater flexibility and cross-ecosystem translation.

You should update your use of this set of tokens as follows:

with themeGet

If you're using a token with the themeGet function, you can find-replace or use regex to make the following substitutions.

• fontWeights.semibold --> fontWeights.medium
• fontWeights.bold --> fontWeights.semibold

Example

-  <Text sx={{fontSize: 2}}>My text</Text>;
-
- const StyledText = styled(Text)`
-   font-size: ${themeGet('fontSizes.2')};
- `
-
+ <StyledText>My text</StyledText>;
+
+ const StyledText = styled(Text)`

with the sx prop

If you're using a token with the sx prop, you can find-replace or use regex to make the following substitutions.

• fontWeight: 'semibold' --> fontWeight: 'medium'
• fontWeight: 'bold' --> fontWeight: 'semibold'

-  <Text sx={{fontWeight: 'bold'}}>My text</Text>;
+ <Text sx={{fontWeight: 'semibold'}}>My text</Text>;

with system props

System props are deprecated. Migrate to the sx prop or create a styled component using the themeGet function.

If you're using a token with the system props, you can find-replace or use regex to make the following substitutions.

• fontWeight="semibold" --> fontWeight="medium"
• fontWeight={'semibold'} --> fontWeight="medium"
• fontWeight="bold" --> fontWeight="semibold"

Example

-  <Text fontWeight={'semibold'}>My text</Text>;
-
+ <Text fontWeight={'medium'}>My text</Text>;
+

Updating border-radius token names

Fuegokit React now ships with a default theme built with tokens.

The new border radius scale adds an additional step for greater flexibility and cross-ecosystem translation.

You should update your use of this set of tokens as follows:

with themeGet

If you're using a token with the themeGet function, you can find-replace or use regex to make the following substitutions.

• radii.4 --> radii.5

Example

-  <Box >My box</Box>;
-
- const StyledBox = styled(Box)`
-   border-radius: ${themeGet('radii.4')};
- `
-
+ <StyledBox>My box</StyledBox>;
+
+ const StyledBox = styled(Box)`

with the sx prop

If you're using a token with the sx prop, you can find-replace or use regex to make the following substitutions.

• borderRadius: 4 --> borderRadius: 5

Example

-  <Text sx={{borderRadius: 4}}>My text</Text>;
+ <Text sx={{borderRadius: 5}}>My app</Text>;

with system props

System props are deprecated. Migrate to the sx prop or create a styled component using the themeGet function.

If you're using a token with system props, you can find-replace or use regex to make the following substitutions.

• borderRadius={4} --> borderRadius={5}

Example

-  <Box borderRadius={4}>My text</Box>;
+ <Box borderRadius={5}>My text</Box>;

Updating box-shadow token names

Fuegokit React now ships with a default theme built with tokens.

The new shadow tokens add a modifer to overflow.

You should update your use of this set of tokens as follows:

with themeGet

If you're using a token with the themeGet function, you can find-replace or use regex to make the following substitutions.

• shadows.shadow.raised --> shadows.elevation.shadow.raised
• shadows.shadow.overlay --> shadows.elevation.shadow.overlay
• shadows.shadow.overflow --> shadows.elevation.shadow.overflow.default

Example

-  <StyledBox>My box</StyledBox>;
-
- const StyledBox = styled(Box)`
-   box-shadow: ${themeGet('shadows.shadow.overlay')};
- `
-
+ <StyledBox>My box</StyledBox>;
+
+ const StyledBox = styled(Box)`

with the sx prop

If you're using a token with the sx prop, you can find-replace or use regex to make the following substitutions.

• boxShadow: shadow.raised --> boxShadow: elevation.shadow.raised
• boxShadow: shadow.overlay --> boxShadow: elevation.shadow.overlay
• boxShadow: shadow.overflow --> boxShadow: elevation.shadow.overflow.default

Example

-  <Box sx={{boxShadow: 'shadow.overlay'}}>My box>/Box>;
+ <Box sx={{boxShadow: 'elevation.shadow.overlay'}}>My box>/Box>;

with system props

System props are deprecated. Migrate to the sx prop or create a styled component using the themeGet function.

• boxShadow={shadow.raised} --> boxShadow={elevation.shadow.raised}
• boxShadow={shadow.overlay} --> boxShadow={elevation.shadow.overlay}
• boxShadow={shadow.overflow} --> boxShadow={elevation.shadow.overflow.default}

Example

-  <Box boxShadow={'shadow.overflow'}>My box</Box>;
-
+ <Box boxShadow={'elevation.shadow.overflow.default'}>My box</Box>;
+

Updating color token names

Fuegokit React now ships with a default theme built with tokens.

You can easily and safely make all of the required updates at once with the Fuegokit V3 codemods.

You can also manually substitute the updated token names using the values below.

Depending on how you use Fuegokit React and its default theme tokens, you might search for different patterns:

• with the themeGet function: ${themeGet('colors.<token>')}
• with the sx prop: sx={{color: '<token>'}}
• with system props:backgroundColor={'<token>'}

with themeGet

If you're using a token with the themeGet function, you can find-replace or use regex to make the following substitutions.

Example

- <StyledBox>My box</StyledBox>;
-
- const StyledBox = styled(Box)`
-   background-color: ${themeGet('colors.background.neutral.default')};
- `
-
+ <StyledBox>My text</StyledBox>;
+
+ const StyledBox = styled(Box)`

with the sx prop

If you're using a token with the sx prop, you can find-replace or use regex to make the following substitutions.

Example

- <Box sx={{backgroundColor: 'background.neutral.default'}}>My box</Box>;
-
+ <Box sx={{backgroundColor: 'background.neutral.default.[default]'}}>My box</Box>;
+

Updated color token names

Only color tokens in the elevation.surface and background token groups have had additional modifiers added.

The tables below contains the token names that have changed. Additionally, we've included the tokens that have not changed for reference below.

Unchanged color token names

Most color tokens in the default Fuegokit React theme are unchanged. They are listed here for reference.

New components

Unless marked otherwise, all new components are considered Experimental. They graduate to Alpha once used in a production application for one month, after which they graduate to Beta status.

• Avatar
• Code
• Collapse
• Combobox
• Dropdown
• GlobalHeader
• GlobalHeaderMenu
• Popover
• ProductSurvey
• ActionsFilter
• Autocomplete
• RuleItem
• IconWithTooltip
• ScrollableList
• Select
• Switch

Batteries-included components

Additionally, Fuegokit React v3 will begin shipping a selection of ecosystem-specific, "batteries-included" React components that you can use as drop-in replacements in different product ecosystems.

These offer a familiar API and the props that you're used to, but offer some extended capabilities that are unique to Appfire products. They include:

• AtlasBadge
• AtlasButton
• AtlasCheckbox
• AtlasLozenge
• AtlasRadio
• AtlasTextfield
• AtlasTooltip

To replace these using codemods, you can run this command:

npx @fuegokit/codemod v3.0.0/transforms/atlaskit-components/transform-atlaskit-to-fuegokit-v3 ./path/to/your/file

For additional details on how to use these Codemods, see this page on the v3 Codemods.

Deprecated components

Components that have been marked as deprecated will

1. Move into a deprecated bundle
2. Receive limited ongoing support as the Design Systems team shifts focus to graduated versions and new component work
3. Be marked as end-of-life 6 months after the date of deprecation
4. Be removed entirely from Fuegokit React after the end-of-life date has passed

Summary of deprecated components

• AdminFeaturesCard
• AdminFeaturesCardGrid
• AdvancedFeaturesCardGrid
• ButtonCard
• CoreFeaturesCard
• CoreFeaturesCardGrid
• ListCard
• MicroHeader
• SectionHeader
• MktgButton

System props are deprecated

System props are deprecated in all components except the Box and Text utility components.

You can install the Fuegokit React ESLint plugin to lint your React projects for system props and migration help.

npm install @fuegokit/eslint-plugin-fuegokit-react