Migration guide for @uploadcare/blocks v0.44.0

BREAKING CHANGES

  • All theme variables of the previous version are deprecated and won't affect the look anymore.
  • The default button that opens the uploader dialog (SimpleBtn) component now uses independent variables.
  • By default, the theme now uses OKLCH color space. You can still override it using other color spaces, but we recommend converting your colors to OKLCH.

How to migrate

Dark and light mode

CSS variable --darkmode won't affect color scheme anymore. Now, the theme is determined by user preference by default. To force a color scheme, apply uc-light or uc-dark class to the component.

  1. If you are using light mode only, apply uc-light class to the component.
  2. If you are using dark mode only, apply uc-dark class to the component.
  3. If you apply user system preference, you don't have to do anything. You can safely delete any code that uses --darkmode variable.

Case 1 - you're not using --darkmode variable

The light mode was previously the default theme. If you want to keep it, apply the uc-light class to the component.

<lr-file-uploader-regular>
  ctx-name="my-uploader" class="uc-light"
</lr-file-uploader-regular>

Case 2 - you are using --darkmode variable to constantly apply dark mode

If you want to keep dark mode, apply the uc-dark class to the component.

<lr-file-uploader-regular>
  ctx-name="my-uploader" class="uc-dark"
</lr-file-uploader-regular>

Case 3 - you are using --darkmode variable to apply dark mode only when the user prefers it

For example, you are using this code:

@media (prefers-color-scheme: dark) {
  .my-uploader {
    --darkmode: 1;
  }
}
@media (prefers-color-scheme: light) {
  .my-uploader {
    --darkmode: 0;
  }
}

Now, you can safely delete it. The mode is determined by user preference by default.

Accent colors

Case 1 - you're not using --*-accent variables

In this case, you don't have to do anything. The default accent color is used.

Case 2 - you're using --*-accent variables

For example, you have this code:

.my-colors {
  --h-accent: 144;
  --s-accent: 67%;
  --l-accent: 57%;
}

First, you need to convert your accent color from HSL to OKLCH. We recommend using https://oklch.com/ for conversion.

Then, depending on your use of light or dark mode, change the following variables. Write values only:

.my-colors {
  --uc-primary-oklch-light: 79.2% 0.176 153;
  --uc-primary-oklch-dark: 79.2% 0.176 153;
}

Note: to maintain the contrast, don’t change first numbers that stand for lightness.

Other colors and variables

Case 1 - you're not using CSS variables other than --*-accent

In this case, you don't have to do anything. The default values will be used.

Case 2 - you're using CSS variables other than --*-accent

The new styling system does not directly replace most of the values. Yet, using this guide can yield very close results.

  1. Convert your colors from HSL to OKLCH. We recommend using https://oklch.com/ for conversion.
  2. Assign OKLCH colors to correspondent variables using this table. If you use only light or only dark mode, override the variable with the respective suffix: -light or -dark.
BeforeAfter
--*-foreground--uc-foreground-light
--uc-foreground-dark
--*-background--uc-background-light
--uc-background-dark
--*-accent--uc-primary-oklch-light
--uc-primary-oklch-dark

Note: don’t use full color syntax for these two variables, apply only numbers, e.g. 59% 0.22 264
--*-confirmNo replacement.
--*-errorColors of error text:
--uc-destructive-foreground-light
--uc-destructive-foreground-dark

Transparent background of errors:
--uc-destructive-light
--uc-destructive-dark
--opacity-*No replacement.
--ui-size--uc-button-size
--uc-preview-size
--gap-*--uc-padding
--gap-tableNo replacement.
--bordersNo replacement.
--border-radius-element--uc-radius
--border-radius-frameNo replacement. Now it's calculated as 1.75x of --uc-radius.
--border-radius-thumbNo replacement.
--transition-duration--uc-transition now contains time and easing function, e.g. 0.2s ease
--shadowsNo replacement.
--*-shadowNo replacement.
--modal-normal-w--uc-dialog-width
--modal-max-w--uc-dialog-max-width
--modal-max-h--uc-dialog-max-height

Derivative values

Case 1 - you're not using derivative values described below

In this case, you don't have to do anything. The default values will be used.

Case 2 - you're using derivative values described below

  1. Convert your colors from HSL to OKLCH. We recommend using https://oklch.com/ for conversion.
  2. Assign OKLCH colors to correspondent variables using this table. If you use only light or only dark mode, override the variable with the respective suffix: -light or -dark.
BeforeAfter
--clr-background*--uc-background-light
--uc-background-dark
--clr-accent*--uc-primary-oklch-light
--uc-primary-oklch-dark

Note: don’t use full color syntax for these two variables, apply only numbers, e.g. 59% 0.22 264
--clr-confirmNo replacement.
--clr-errorColors of error text:
--uc-destructive-foreground-light
--uc-destructive-foreground-dark

Transparent background of errors:
--uc-destructive-light
--uc-destructive-dark
--clr-txt*For normal text color:
--uc-foreground-light
--uc-foreground-dark

For lighter text color:
--uc-muted-foreground-light
--uc-muted-foreground-dark
--clr-shade-lv*No replacement.
--border-*--uc-border
--clr-curtainNo replacement.
--clr-btn-bgr-primary*--uc-primary-light
--uc-primary-dark
--uc-primary-hover-light
--uc-primary-hover-dark

Note: by default these colors derive from --uc-primary-oklch-light and --uc-primary-oklch-dark
--clr-btn-txt-primary--uc-primary-foreground-light
--uc-primary-foreground-dark
--shadow-btn-primaryNo replacement.
--clr-btn-bgr-secondary--uc-secondary-light
--uc-secondary-dark
--uc-secondary-hover-light
--uc-secondary-hover-dark
--clr-btn-txt-secondary--uc-secondary-foreground-light
--uc-secondary-foreground-dark
--shadow-btn-secondaryNo replacement.
--clr-btn-bgr-disabledNo replacement.
--clr-btn-txt-disabledNo replacement.
--shadow-btn-disabledNo replacement.

See Styling article for more info.