Skip to main content
Version: 4.x.x (latest)

Migrating from v3

Using v4​

First, you need to install peer dependencies:

npm install @emotion/react@^11.10.0 @emotion/styled@^11.10.0 styled-system@^5.1.5 @styled-system/should-forward-prop@^5.1.5

Install the package through npm or yarn:

npm install @desygna/desygna-core@^4.0.0
// or
// npm install @desygna/desygna@^4.0.0

Improvements​

Type-safety on theme variables​

You can define your theme as a type definition, which will allow you to create components that are fully type-safe using your custom theme tokens. With this approach, you only need to include a few files to achieve this functionality.

By having a theme.ts file that defines your custom theme and a desygna.d.ts file that provides type definitions for the Desygna library, you can get typings in your code editor (such as VS Code). This means that your editor will provide autocomplete suggestions and type-checking for your custom theme properties, making it easier and faster to create type-safe components.

INFORMATION

Codesandbox example previews are not working for Desygna version 4.
We are still investigating but you can use "Open in Sandbox" button.

/**
 * To get typings in your code editor,
 * you need to have a theme.ts file for your custom theme and a desygna.d.ts file
 * for type definitions of the Desygna library.
 *
 * These files allow your editor to provide autocomplete suggestions and type-checking
 * for your custom theme properties, making it easier to write type-safe components.
 *
 */
import React from "react";
import { 
  $styled, 
  $composeAll, 
  shouldForwardProp, 
  DesygnaProvider, 
  DesygnaComposedProps
} from "@desygna/desygna-core";
import { customTheme } from "./src/theme";

export type CustomBoxProps = {
  id?: string;
  role?: string;
  className?: string;
  tabIndex?: number;
} & DesygnaComposedProps;

export const CustomBox = $styled("div", {
  shouldForwardProp
})<CustomBoxProps>(
  {
    boxSizing: "border-box",
    minWidth: 0,
    transition: "all 0.2s ease"
  }, 
  $composeAll
);

/**
 *
 *   Now use the component in your app,
 *   get type-checking and autocomplete for prop values like this:
 *
 *  "text" | "background" |
 *  "primary.100" | "primary.200" | "primary.300" |
 *  "accent.100" | "accent.200" | "accent.300" |
 *  "neutral.100" | "neutral.200" | "neutral.300" |
 *  "success.100" | "success.200" | "success.300" |
 *  "warning.100" | "warning.200" | "warning.300" |
 *  "error.100" | "error.200" | "error.300" |
 *  "info.100" | "info.200" | "info.300" | ...
 */

export default function App() {
  return (
    <DesygnaProvider theme={customTheme}>
      <CustomBox display="flex" flexDirection="column" gap="12px">
        <CustomBox
          c="primary.300"
          bg="primary.100"
          borderColor="primary.200"
          borderWidth="1px"
          borderStyle="solid"
          w="full"
          h="full"
          padding="4px"
        >
          This is a custom box
        </CustomBox>

        <CustomBox
          c="accent.300"
          bg="accent.100"
          borderColor="accent.200"
          borderWidth="1px"
          borderStyle="solid"
          w="full"
          h="full"
          padding="4px"
        >
          This is a custom box
        </CustomBox>

        <CustomBox
          c="success.300"
          bg="success.100"
          borderColor="success.200"
          borderWidth="1px"
          borderStyle="solid"
          w="full"
          h="full"
          padding="4px"
        >
          This is a custom box
        </CustomBox>

        <CustomBox
          c="warning.300"
          bg="warning.100"
          borderColor="warning.200"
          borderWidth="1px"
          borderStyle="solid"
          w="full"
          h="full"
          padding="4px"
        >
          This is a custom box
        </CustomBox>

        <CustomBox
          c="error.300"
          bg="error.100"
          borderColor="error.200"
          borderWidth="1px"
          borderStyle="solid"
          w="full"
          h="full"
          padding="4px"
        >
          This is a custom box
        </CustomBox>
        <CustomBox
          c="info.300"
          bg="info.100"
          borderColor="info.200"
          borderWidth="1px"
          borderStyle="solid"
          w="full"
          h="full"
          padding="4px"
        >
          This is a custom box
        </CustomBox>
        
        <CustomBox
          c={{
            _: "neutral.300",
            sm: "info.300",
            md: "success.300",
            lg: "error.300",
            xl: "warning.300",
          }}
          bg={{
            _: "neutral.100",
            sm: "info.100",
            md: "success.100",
            lg: "error.100",
            xl: "warning.100",
          }}
          w="full"
          h="full"
          mt="36px"
          padding="12px"
          textAlign="center"
        >
          This is a responsive box. <br /> <br />
          &larr; You can resize the panels to see changes by dragging from center of the code editor and the preview. 
          <br /> <br />
          Alternatively, you can click the button in the bottom right corner to see the sandbox.
        </CustomBox>
      </CustomBox>
    </DesygnaProvider>
  );
}


Open in sandbox

Additions​

  • shouldForwardProp

  • $animation system utility

  • DesygnaGenericProp type

  • DesygnaGenericBreakpointValues type

Deprecated​

  • ResponsiveProp type has deprecated

Breaking Changes​

  • DesygnaTheme type scheme has changed

  • styled has changed as $styled

Styled API Changes
/**
 *
 *  Changes:
 *    styled        $styled
 *
 *  Additions:
 *    shouldForwardProp
 *
 *  You can use `shouldForwardProp` for prop forwarding
 *
 */
import { $styled, shouldForwardProp } from "@desygna/desygna-core";

export type BoxProps = {
  id?: string;
  role?: string;
  className?: string;
  tabIndex?: number;
};

export const Box = $styled("div", {
  shouldForwardProp
})<BoxProps>({
  boxSizing: "border-box",
  minWidth: 0,
  transition: "all 0.2s ease"
});

  • css has changed as $css

  • variant has changed as $variant

  • compose has changed as $compose

  • composeAll has changed as $composeAll

     // Usage:
     $composeAll()

  • background has changed as $background

  • border has changed as $border

  • color has changed as $color

  • cursor has changed as $cursor

  • flexbox has changed as $flexbox

  • grid has changed as $grid

  • layout has changed as $layout

  • position has changed as $position

  • shadow has changed as $shadow

  • space has changed as $space

  • typography has changed as $typography