Skip to main content
Version: 3.x.x

Migrating to v4 (See API changes)

Using v4-rc.1​

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:

Only the core package is available as version 4.0.0-rc.1

npm install @desygna/desygna-core@4.0.0-rc.1

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 write type-safe components.

/**
 *
 * 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 { 
  $styled, 
  $composeAll, 
  shouldForwardProp, 
  DesygnaProvider, 
  DesygnaComposedProps
} from "@desygna/desygna-core";
import { customTheme } from "./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 on CodeSandbox

Additions​

shouldForwardProp​

$animation system utility​

DesygnaGenericProp type​

DesygnaGenericBreakpointValues type​

Deprecated​

ResponsiveProp type will be marked as deprecated​

Breaking Changes​

DesygnaTheme type scheme has changed​

styled has changed as $styled​

An example usage of v4
/**
 *
 *  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"
});

variant has changed as $variant​

compose has changed as $compose​

composeAll has changed as $composeAll​

css has changed as $css​

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​