Bezier React v2 Release & Migration Guide

[sungik-choi]

What's Changed?

In bezier-react v2, we have addressed issues within the style system and improved the usability of components! 🎉

Removal of styled-components

• From bezier-react v2 onwards, styled-components are no longer a peer dependency.
• The theme implementation based on styled-components' ThemeProvider (React context) has been switched to CSS variables. While Semantic color CSS variables were already provided, v2 expands this to include all design tokens, such as font size, box shadow, etc.

Component Improvements

• A new layout component, Box, is introduced for easily implementing layouts without separate style files.
• More consistent interfaces are provided across the library.
• The performance of some components has been improved. Dynamic styles previously handled through styled-components and React state are now managed with CSS.
• Styles overridden via the className property now always take precedence, leveraging CSS Cascade layers.

Elevated Minimum Browser Support Version

• Due to the adoption of modern CSS features such as :where(), :is(), :has(), and CSS cascade layers, the minimum supported browser version has been elevated.

// https://developers.channel.io/reference/web-browser-support-kr
Chrome: latest
- Safari: >= 14
+ Safari: >= 15.6
Edge: latest

• For detailed support range, please refer to browserslist.

Separation of the Design Token Library

• The Foundation (design tokens) within bezier-react has been spun off into a separate library, bezier-tokens. There is no change for users.
• (Planned) Similar to bezier-icons, integrating Figma with this library to establish a single source of truth for the Channel team's (web/mobile) design tokens is the goal.

How to Migrate?

Getting Started

Refer to the bezier-react releases to install the latest version of bezier-react.

yarn add @channel.io/bezier-react
# For monorepos
yarn up @channel.io/bezier-react

🤖 Icons Migration can be partially automated through the bezier-codemod library. You can execute it with the following command:

npx @channel.io/bezier-codemod

AppProvider

BezierProvider has been renamed to AppProvider. Unlike before, only one instance should exist at the application's root. Moreover, as styling is now done through precompiled style sheets rather than at runtime, you must import the library's style sheet at the application's root.

Importing the Style Sheet at the Root of Your App

You can import it using a bundler like webpack or directly link the resource in your HTML.

import '@channel.io/bezier-react/styles.css'

Changing BezierProvider to AppProvider at the Root of Your App

<AppProvider 
  themeName="light" 
  // optional
  features={[SmoothCornersFeature]}
  // optional
  window={window}
>
  {children}  
</AppProvider>

Global Style

Wrapping with @layer base

To maintain the same behavior as before, global styles must be wrapped with @layer base. Since bezier-react uses CSS cascade layers internally, not wrapping them would result in global styles taking precedence.

The order of bezier-react CSS cascade layers is as follows:

@layer tokens, base, components;
/* tokens: Design tokens (CSS variables) */
/* base: Global style */
/* components: Component style */

Warning

If you were using bezier-react's createGlobalStyle, you should switch to styled-components' function with the same name. Note that styled-components v5 does not recognize the @layer keyword and removes it, so you must upgrade to v6 or above. If you wish to keep v5, avoid using createGlobalStyle and opt for static CSS instead.

Nested Theme

Using ThemeProvider instead of Nested BezierProvider

The combination of BezierProvider + Foundation to set a specific theme has been replaced with using ThemeProvider or a specific ThemeProvider (LightThemeProvider, DarkThemeProvider).

Warning

Note that all theme-related provider components, including ThemeProvider, operate by assigning the data-bezier-theme attribute to sub-elements at runtime. Therefore, sub-elements must spread props, as they internally use radix-ui's Slot (Reference).

<BezierProvider
  foundation={LightFoundation}
  themeVarsScope={Styled.Wrapper}
>
 <Styled.Wrapper>
  { ... }
  </Styled.Wrapper>
</BezierProvider>

<LightThemeProvider> {/* 혹은 DarkThemeProvider */}
 <Styled.Wrapper>
  { ... }
  </Styled.Wrapper>
</LightThemeProvider>

Removal of --inverted CSS Variables

The support for CSS variables starting with --inverted and the foundation.subTheme has been removed. Now, each theme can only access tokens specific to it. If you need to use inverted colors, please wrap the relevant area with InvertedThemeProvider.

const BlueText = styled.span`
  /* AS-IS: color: var(--inverted-bgtxt-blue-normal) */
  color: var(--bgtxt-blue-normal);
`

<InvertedThemeProvider>
  <Styled.InvertedArea>
    <Styled.BlueText>Inverted Blue</Styled.BlueText>
  </Styled.InvertedArea>
</InvertedThemeProvider>

Warning

The content areas of the Tooltip and Toast components are now set to the InvertedTheme area by default.

Migration Strategies for Specific Cases

In cases where the color should follow the light theme and the background-color should follow the dark theme, the new design system's proximity-based theming may be challenging to adapt directly. While not recommended, you can migrate by directly accessing the useThemeName and tokens object. Designs should evolve to avoid mixing theme contexts in the long term.

/* Styled component */
const MixedThemeBox = styled.div<{ themeName: ThemeName }>`
  color: var(--bg-black-dark);
  background-color: ${({ themeName }) => (
  tokens[themeName === 'light' ? 'darkTheme' : 'lightTheme'].color['txt-black-darkest']
 )};
`

/* Inside React component */
const currentThemeName = useThemeName()

<Styled.MixedThemeBox themeName={currentThemeName} />

🤖 Removal of styled, css, and related APIs (v2-import-from-bezier-to-styled-components)

The styled, css, and related APIs from styled-components are no longer provided. Please import them directly from styled-components.

import { styled, Button, css } from "@channel.io/bezier-react";

export const Wrapper = styled(Button)`
  ${css`
    background: red;
  `}
`;

import styled, { css } from "styled-components";
import { Button } from "@channel.io/bezier-react";

export const Wrapper = styled(Button)`
  ${css`
    background: red;
  `}
`;

🤖 Foundation to CSS Variable Migration (v2-foundation-to-css-variable)

The foundation object is no longer provided. Please migrate to the corresponding CSS variables. If you were directly importing LightFoundation or similar objects, switch to using the tokens object or the return value of useTokens.

import { styled } from "@channel.io/bezier-react";

const Wrapper = styled.div`
  color: ${({ foundation }) => foundation?.theme?.["txt-black-dark"]};

  ${({ foundation }) => foundation?.rounding.round12};

  ${({ foundation }) =>
    foundation?.border?.getBorder(0.5, foundation.theme["bdr-black-light"], {
      top: false,
      right: false,
      left: false,
    })};

  ${({ foundation }) => foundation?.elevation?.ev1()};

  margin-bottom: ${({ foundation }) => foundation?.spacing.s6};

  ${({ foundation }) => foundation?.transition?.getTransitionsCSS("color")};
`;

import { styled } from "@channel.io/bezier-react";

const Wrapper = styled.div`
  color: var(--txt-black-dark);

  overflow: hidden;
  border-radius: var(--radius-12);

  border-color: var(--bdr-black-light);
  border-style: none none solid none;
  border-width: 0.5px;

  background-color: var(--bg-white-low);
  box-shadow: var(--ev-1);

  margin-bottom: 16px;

  transition: color var(--transition-s);
`;

Removal of useFoundation

The useFoundation hook is no longer available. For accessing theme-related values, please use useTokens or useThemeName hooks as suitable replacements.

- const foundation = useFoundation()
+ const tokens = useTokens()
- const isDarkFoundation = foundation === DarkFoundation
+ const isDarkTheme = useThemeName() === 'dark'
- const textColor = foundation?.theme?.['txt-black-darker']
+ const textColor = tokens.semantic.color['txt-black-darker']

🤖 Removal of Interpolation (v2-interpolation-to-css-variable)

Support for mixins and constants such as Typography, ZIndex, InputWrapperStyle, Rounding, etc., has been phased out in favor of corresponding CSS variables. Please note, the Spacing object is no longer provided but might be reintroduced as a design token in future updates based on clear specifications.

Warning

As an exception, we no longer provide the Spacing object; we will add it as a design token in the future when the specification is clarified.

import {
  styled,
  Typography,
  inputWrapperStyle,
  focusedInputWrapperStyle,
  erroredInputWrapperStyle,
  ZIndex,
  Rounding,
} from "@channel.io/bezier-react";

const Wrapper = styled.div`
  ${Typography.Size11};

  ${inputWrapperStyle};

  ${({ focus }) => focus && focusedInputWrapperStyle};

  ${erroredInputWrapperStyle};

  ${inputPlaceholderStyle};

  z-index: ${ZIndex.Hide};

  ${Rounding.round12};
`;

const OVERLAY_POSITION1 = {
  zIndex: ZIndex.Modal,
};

import { styled } from "@channel.io/bezier-react";

const Wrapper = styled.div`
  /* NOTE: Do not use font-related css variables below separately, use Text component instead */
  font-size: var(--typography-size-11-font-size);
  line-height: var(--typography-size-11-line-height);

  box-shadow: var(--input-box-shadow);

  ${({ focus }) =>
    focus &&
    css`
      box-shadow: var(--input-box-shadow-focused);
    `};

  box-shadow: var(--input-box-shadow-invalid);

  &::placeholder {
    color: var(--txt-black-dark);
  }

  z-index: var(--z-index-hidden);

  overflow: hidden;
  border-radius: var(--radius-12);
`;

const OVERLAY_POSITION1 = {
  zIndex: "var(--z-index-modal)",
};

Mixins

We no longer provide mixins (interpolation of styled-components). For mixins not mentioned, please refer to the link and implement them in your application.

Removal of smoothCorners

Not supported. Please replace it with the SmoothCornersBox component.

const Box = styled.div`
  smoothCorners({
    borderRadius: 10,
    shadow: '0 5px 15px 0 rgba(0, 0, 0, 0.5)';
    shadowBlur: 15,
    backgroundColor: 'white',
    hasBackgroundImage: true,
  })
`

<Box>...</Box>

<SmoothCornersBox 
  borderRadius={10}
  shadow={{
    offsetX: 0,
    offsetY: 5,
    blurRadius: 15, 
    spreadRadius: 0,
  }}
  backgroundColor="white"
  backgroundImage="..."
>...</SmoothCornersBox>

Removal of gap

Not supported. please implement the function below in your app to use it.

function gap(spacing: number) {
  return css`
    gap: ${spacing}px;

    @supports not (gap: ${spacing}px) {
      margin-top: ${-spacing}px;
      margin-left: ${-spacing}px;

      > * {
        margin-top: ${spacing}px;
        margin-left: ${spacing}px;
      }
    }
  `;
}

Removal of touchableHover

Not supported. please implement the function below in your app to use it.

function touchableHover(
  interpolation: ReturnType<typeof css>
) {
  return css`
    @media (hover: hover) {
      &:hover {
        ${interpolation}
      }
    }

    @media (hover: none) {
      &:active {
        ${interpolation}
      }
    }
  `;
}

Components

Common: Deprecation of interpolation property

With the inability to use interpolation from styled-components, all components no longer support the interpolation and related properties (e.g., wrapperInterpolation). Please migrate to style and related properties (e.g., wrapperStyle). For override styles using selectors, you can migrate to className and related properties.

Common: Support for as Property in Certain Components Only

To prevent excessive flexibility, the support for the as property has been limited to the following components:

• Box
• Stack
• Text
• Button
• ListItem
• OutlineItem
• LegacyStack
• LegacyStackItem
• LegacyTooltip

🤖 Change in Text Component Interface (v2-text-component-interface)

The type of typo has been changed to string literals for an improved development experience.

- <Text typo={Typography.Size11} />
+ <Text typo="11" />

🤖 Transition of Stack Related Components from Legacy to Stable (v2-remove-alpha-from-alpha-components)

import {
  VStack,
  StackItem,
  AlphaStack,
  AlphaCenter,
} from "@channel.io/bezier-react";

function Foo() {
  return (
    <VStack>
      <StackItem>
        <div />
      </StackItem>
      <StackItem>
        <div />
      </StackItem>
    </VStack>
  );
}

function Bar() {
  return (
    <AlphaStack direction="horizontal">
      <div />
      <div />
    </AlphaStack>
  );
}

function Baz() {
  return (
    <AlphaCenter>
      <div />
    </AlphaCenter>
  );
}

import {
  LegacyVStack,
  LegacyStackItem,
  Stack,
  Center,
} from "@channel.io/bezier-react";

function Foo() {
  return (
    <LegacyVStack>
      <LegacyStackItem>
        <div />
      </LegacyStackItem>
      <LegacyStackItem>
        <div />
      </LegacyStackItem>
    </LegacyVStack>
  );
}

function Bar() {
  return (
    <Stack direction="horizontal">
      <div />
      <div />
    </Stack>
  );
}

function Baz() {
  return (
    <Center>
      <div />
    </Center>
  );
}

🤖 Conversion of Enum Members to String Literals (v2-enum-member-to-string-literal)

Enum members such as ***Size, ***Variant have been converted to string literals to enhance autocomplete and improve the developer experience.

import React from 'react'
import { ProgressBar, ProgressBarSize, ProgressBarVariant, AvatarSize, Avatar } from '@channel.io/bezier-react'

export default function UploadProgress({
  uploadProgressPercentage,
}: {
  uploadProgressPercentage: number
}) {
  return (
    <ProgressBar
      width='100%'
      size={ProgressBarSize.M}
      variant={ProgressBarVariant.GreenAlt}
      value={uploadProgressPercentage / 100}
    />
  )
}

export function DummyAvatar() {
  return (
  <Avatar
    avatarUrl="https://bit.ly/kent-c-dodds"
    name="Kent Dodds"
    size={AvatarSize.Size20}
    showBorder
  />)
}

import React from 'react'
import { ProgressBar, Avatar } from '@channel.io/bezier-react'

export default function UploadProgress({
  uploadProgressPercentage,
}: {
  uploadProgressPercentage: number
}) {
  return (
    <ProgressBar
      width='100%'
      size='m'
      variant='green-alt'
      value={uploadProgressPercentage / 100}
    />
  )
}

export function DummyAvatar() {
  return (
  <Avatar
    avatarUrl="https://bit.ly/kent-c-dodds"
    name="Kent Dodds"
    size='20'
    showBorder
  />)
}

Changes in ListItem Interface and Size

• The properties iconStyle, iconClassName, iconInterpolation, contentStyle, contentClassName, and contentInterpolation are no longer supported. These were removed to reduce excessive flexibility within the interface.
• The leftIcon property is no longer supported. This change aligns with the consistency across other component interfaces. Please use leftContent instead.
• The name property is no longer supported. Additionally, the second parameter (name) in the onClick has been removed. If an identifier is needed, please combine functions externally to the component.
• The properties hide, nested, optionKey, and disableIconActive are no longer supported. These legacy properties have been removed. For hiding elements, please use conditional rendering.
• The sizes according to ListItemSize have changed to unify the design. Please adjust accordingly:
  • ListItemSize.S -> ListItemSize.XS
  • ListItemSize.M -> ListItemSize.S
  • ListItemSize.L -> ListItemSize.M
  • ListItemSize.XL -> ListItemSize.L
• Bug Fix: Corrected the incorrect text size for the XL (now L) size.

Changes in NavItem, NavGroup Interface

The leftIcon property is no longer supported, for consistency across other component interfaces. Please use leftContent instead.

Changes in TextField Interface

• TextFieldVariant has been removed. Please use string literals instead.
• The properties inputStyle and inputClassName are no longer supported. Please use style and className instead.

Changes in TextArea Interface

The properties wrapperStyle and wrapperClassName are no longer supported.

Changes in Name and Interface of KeyValueListItem

Renamed to KeyValueItem to align with the design system naming convention. Similarly, KeyValueMultiLineListItem has been changed to KeyValueMultiLineItem.

Changes in SectionLabel Interface and Internal Implementation

To enhance design consistency and simplify component responsibilities, the internal implementation has been changed:

• Removed the internal div wrapper. Use style and className in place of wrapperStyle and wrapperClassName.
• No longer supports the divider property. Please use the Divider component directly.
• It is no longer possible to override iconColor in leftContent, rightContent properties.
• When an onClick handler is injected, the root element is improved to become a button to support keyboard focus behavior.

Changes in OutlineItem Interface and Internal Implementation

Originally designed for implementing a tree view, however, it was observed that no place in the desk used OutlineItem's inherent functionality for this purpose. Thus, unused properties have been removed to simplify the component's responsibilities:

• The paddingLeft property is no longer supported. A default padding of 6px is now added, consistent with the design specifications.
• Style override properties starting with icon and content have been removed.
• The leftIcon property is no longer supported, for consistency across other component interfaces. Please use leftContent instead.
• The name property is no longer supported, and the second parameter(name) in onClick has also been removed. If an identifier is needed, please combine functions externally to the component.
• The properties hide, optionKey, and disableIconActive are no longer supported as they were legacy properties. Use conditional rendering for hiding elements.
• No longer supports onOpen, onClickArrow, selectedOutlineItemIndex, and onChangeOption properties.

Removal of ListMenuTitle

This component is no longer used in the design system. If there's a use case in your application, please switch to using SectionLabel.

Changes in Tag Interface and Removal of TagBadgeColorPreset

• The color property of Tag is no longer supported. Only predefined variants can be used through the variant property, to maintain consistency.
• The unnecessarily exported TagBadgeColorPreset has been removed.

Removal of TagBadgeSize & TagBadgeVariant

Removed for consistency with other components. Please use TagSize, BadgeSize, or TagVariant, BadgeVariant instead.

Removal of Default offset in Toast

This style was specific to certain applications within Channel, hence it has been removed. To achieve the same behavior as before, please add the following offset object as a default:

offset={{ left: 68, right: 0, bottom: 0 }}

Removal of TooltipProvider

Removed for performance reasons.

Types

Removal of InterpolationProps

No longer provided. Please use the return type of styled-components' css for similar purposes.

type InjectedInterpolation = ReturnType<typeof css>
interface InterpolationProps {
  interpolation?: InjectedIntepolation
}

Changes to BezierComponentProps

The interface, which included properties like as and interpolation, has been updated to extend HTMLAttributes<T extends HTMLElement>, streamlining it with standard HTML attribute extensions.

• If you wish to use the as type declaration, consider utilizing PolymorphicProps.
• The testId property has been removed. If you were using testId for queries in a testing-library environment, you should switch to using the data-testid attribute.

Renaming SemanticNames

This has been changed to SemanticColor to better reflect its purpose and usage.

Renaming FormComponentProps

These are now referred to as FormFieldProps, aligning with their role in form components more accurately.

Hooks & Utilities

Removal of useEventHandler

This hook is no longer provided. Please refer to the provided link for implementation guidance if needed in your application.

Removal of useMergeRefs

This hook is no longer provided. Please refer to the link for implementation guidance if needed in your application.

Removal of useId

This hook is no longer provided. Please refer to the link for implementation guidance if needed in your application.

Removal of getRootElement

Instead of getRootElement, you are encouraged to use the useRootElement hook. This change accommodates the addition of features like new windows, where accessing the nearest context's window is necessary.

const { window, document, rootElement } = useWindow();
// Same as useWindow().rootElement
const rootElement = useRootElement();

Other Improvements

• The Text component now supports the align property for text alignment.
• The Stack component has introduced a new justify option, between, for evenly spacing children.
• The Banner component now correctly renders content, whether it is a string or a component.
• A size property has been added to FormControl, which affects Select and TextField components, ensuring uniform height when labels are positioned on the left.
• The Radio component will now shrink to the size of the indicator if no label (children) is provided.
• Additionally, numerous minor improvements have been made, including enhancements to accessibility. Please refer to the release notes for a comprehensive overview.

Q&A

Do I need to migrate all styled-components in my application?

No, you do not need to migrate. The main objective is removing styled-components from bezier-react dependencies, which does not directly affect the styling system of your application.

How do I handle CSS for unused components?

This issue is challenging to address. Currently, only a single stylesheet is provided. In the future, we plan to explore solutions like PurgeCSS to remove unused CSS from applications.

How can I ensure type safety with the new version?

Since CSS variables do not benefit from TypeScript's typing, referencing a non-existent design token will not result in a compile-time error. For type safety, use layout components like Box, where interface properties are type-checked.

Future developments, such as a stylelint plugin, may help detect errors at the linting stage.

Won't the lack of IDE autocomplete for CSS variables be inconvenient?

We plan to develop a VSCode extension to support autocomplete functionality for CSS variables, aiming to improve the development experience.