Migration – Reablocks

Migrating from 7.x to 8.x

In 8.x, we've removed the dependency of text colors to panel or surface elements. As text colors are not necessarily always tied to panel and surface elements, moving these colors into a generic text block allows for a more flexible design system.

{
  // Previously, the structure for panel and surface
  panel: {
    // Panel backgrounds, such as cards, tables, popovers, dialogs, dropdown menus, etc.
    DEFAULT: colorPalette['black-pearl'],
    content: colorPalette['athens-gray'],
    'secondary-content': colorPalette.gray[600],
    accent: colorPalette['charade']
  },
  surface: {
    // Form component backgrounds, such as text fields, checkboxes, select, etc.
    DEFAULT: colorPalette['charade'],
    content: colorPalette['athens-gray'],
    accent: colorPalette.blue[500],
    disabled: colors.gray[800]
  }
 
  // New structure with added text block
  panel: {
    // Panel backgrounds, such as cards, tables, popovers, dialogs, dropdown menus, etc.
    DEFAULT: colorPalette['black-pearl'],
    accent: colorPalette['charade']
  },
  surface: {
    // Form component backgrounds, such as text fields, checkboxes, select, etc.
    DEFAULT: colorPalette['charade'],
    accent: colorPalette.blue[500],
  },
  text: {
    primary: colorPalette['athens-gray'],
    secondary: colorPalette.gray[600]
  }
}

Move and consolidate content tokens

We set a primary and secondary text color which can be used throughout the app. In addition, we've consolidated to 2 main text colors, but our system allows for more colors to be added such as tertiary if needed.

For example, if panel.content and surface.content colors were different, a third color will need to be added under text and theme files of components that are being used will need to be updated.

We realize that adding a text block will mean Tailwind references will end up with duplicate text prefixes such as text-text-primary but we feel that this is necessary for our designs to clearly differentiate colors being used for text and colors being used for ui elements.

{
  panel: {
    // Panel backgrounds, such as cards, tables, popovers, dialogs, dropdown menus, etc.
    DEFAULT: colorPalette['black-pearl'],
-   content: colorPalette['athens-gray'],
-   'secondary-content': colorPalette.gray[600],
    accent: colorPalette['charade']
  },
  surface: {
    // Form component backgrounds, such as text fields, checkboxes, select, etc.
    DEFAULT: colorPalette['charade'],
-   content: colorPalette['athens-gray'],
    accent: colorPalette.blue[500],
    disabled: colors.gray[800]
  },
+ text: {
+   primary: colorPalette['athens-gray'],
+   secondary: colorPalette.gray[600],
+ }
}

Update theme files of components being used

This is ONLY necessary if panel.content and surface.content tokens are different.

Add a new token to the text block (ie, tertiary) with the color that surface.content was.

{
  text: {
    primary: colorPalette['athens-gray'],
    secondary: colorPalette.gray[600],
+   tertiary: colorPalette['waterloo']
  }
}

Update component theme files which previously referenced surface.content from *-surface-content to *-text-secondary:

PagerTheme: base
RedactTheme: base
SortTheme: base
ArrowTheme: base
AvatarGroupTheme: base
BadgeTheme:
- colors.primary
- colors.secondary
- colors.error
ButtonTheme:
- base
- colors.default.text
- colors.primary.filled
- colors.secondary.filled
- colors.success.filled
- colors.warning.filled
- colors.error.filled
DotsLoaderTheme: dot
CheckboxTheme: base
InputTheme:
- base
- adornment.base
RangeTheme: tooltip
SelectMenuTheme: groupItem.title
TooltipTheme: base
ListItemTheme:
- base
- header
StackTheme: base
TreeTheme:
- arrow
- node.base
- node.button.icon

Remove surface.disabled

We have removed the surface.disabled color as it was not being used in any of our component theme files - only in a story block which has been updated. If there is a reference to this color, leaving the color in place will continue to work. Otherwise, we recommend removing this color token from the theme.

{
  surface: {
    ...,
-   disabled: colorPalette.gray[800]
  }
}

Migrating from 6.x to 7.x

In 7.x, we've introduced new supporting palettes for things like: panel, surface and backgrounds. This allows us to define a more consistent and flexible color system for our components.

{
  panel: {
    // Panel backgrounds, such as cards, tables, popovers, dialogs, dropdown menus, etc.
    DEFAULT: colorPalette['black-pearl'],
    content: colorPalette['athens-gray'],
    'secondary-content': colorPalette.gray[600],
    accent: colorPalette['charade']
  },
  surface: {
    // Form component backgrounds, such as text fields, checkboxes, select, etc.
    DEFAULT: colorPalette['charade'],
    content: colorPalette['athens-gray'],
    accent: colorPalette.blue[500],
    disabled: colors.gray[800]
  }
}

We've also introduced a new color system that allows us to define a more consistent and flexible color system for our components. The color palettes for Dark and Light themes are now defined using tw-colors plugin as a result DarkTheme & LightTheme was merged in theme.

Update import to use theme from reablocks instead of `darkTheme` and `lightTheme`

- import { darkTheme, lightTheme } from 'reablocks';
+ import { theme as defaultTheme } from 'reablocks';
 
const theme = extendTheme(defaultTheme, themeOverrides);
 
<ThemeProvider theme={theme}></ThemeProvider>

In case when you want to use several themes in your project, you should install tw-colors plugin and define your custom themes.

npm i -D tw-colors

Example of palettes defined in tailwind.config.js:

import plugin from 'tailwindcss/plugin';
import { createThemes } from 'tw-colors';
 
const colorPalette = {
  // Define your color palette here
};
 
const config: Config = {
  darkMode: 'selector',
  plugins: [
    createThemes({
      light: {
        primary: {
          DEFAULT: colorPalette.blue[500],
          active: colorPalette.blue[500],
          hover: colorPalette.blue[400],
          inactive: colorPalette.gray[500]
        }
        // etc...
      },
      dark: {
        primary: {
          DEFAULT: colorPalette.blue[500],
          active: colorPalette.blue[500],
          hover: colorPalette.blue[600],
          inactive: colorPalette.blue[200]
        }
        // etc...
      }
    })
  ]
};

Update color tokens

// Previously tokens structure
colors: {
  primary: colors.blue,
  secondary: colors.gray,
  success: colors.green,
  error: colors.red,
  warning: colors.orange,
  info: colors.sky,
}
// New tokens structure
colors: {
  primary: {
    DEFAULT: colorPalette.blue[500],
    active: colorPalette.blue[500],
    hover: colorPalette.blue[400],
    inactive: colorPalette.gray[500]
  },
  secondary: {
    DEFAULT: colorPalette.gray[300],
    active: colorPalette.gray[300],
    hover: colorPalette.gray[200],
    inactive: colorPalette.gray[800]
  },
  success: {
    DEFAULT: colorPalette.green[500],
    active: colorPalette.green[500],
    hover: colorPalette.green[400]
  },
  error: {
    DEFAULT: colorPalette.red[500],
    active: colorPalette.red[400],
    hover: colorPalette.red[600]
  },
  warning: {
    DEFAULT: colorPalette.orange[500],
    active: colorPalette.orange[500],
    hover: colorPalette.orange[400]
  },
  info: {
    DEFAULT: colorPalette.blue[500],
    active: colorPalette.blue[500],
    hover: colorPalette.blue[400]
  }
}

Migrating from 5.x to 6.x

We're excited to announce that version 6.x of our Storybook library introduces a groundbreaking approach to theming with Tailwind CSS. This upgrade allows you to leverage the full capabilities of Tailwind CSS, offering a more flexible and powerful way to style your components. As part of this transition, we're moving away from the previous CSS variables method to embrace a more dynamic and efficient workflow.

Getting Started with the Migration

To ensure a seamless transition to version 6.x, please follow the steps outlined below.

Install Tailwind CSS

Begin by installing Tailwind CSS in your project: Refer to the Tailwind CSS Getting Started guide for installation instructions.

Integrate Tailwind CSS Variables

Next, incorporate Tailwind CSS Variables into your project as a development dependency:

1. Install the Tailwind CSS Variables package:

  npm install -D @mertasan/tailwindcss-variables

2. Configure the plugin in your `tailwind.config.js`:

Instead of using require, import the plugin directly to ensure compatibility with Storybook ThemeBlocks.

import tailwindcssVariables from '@mertasan/tailwindcss-variables';
// ...
module.exports = {
// ...
  plugins: [
    tailwindcssVariables
  ]
}

Migrate Legacy Theme Variables

Adapt your existing theme variables for compatibility with the new system:

1. Rename your old theme file to `legacyTheme.ts`.

2. Import legacyTheme in `tailwind.config.js` and define the theme variables:

 
import defaultTheme from 'tailwindcss/defaultTheme';
import tailwindcssVariables from '@mertasan/tailwindcss-variables';
import { legacyTheme } from './src/Theme/legacyTheme.ts';
 
/** @type {import('tailwindcss').Config} */
export default {
  content: [
    './src/**/*.{js,jsx,ts,tsx,css}',
    './node_modules/reablocks/**/*.{js,tsx,cjs}'
  ],
  theme: {
    extend: {
      colors: legacyTheme.colors,
      spacing: legacyTheme.spacings,
      fontSize: legacyTheme.typography.sizes,
      fontFamily: {
        'mono': ['"Monaco, monospace"', ...defaultTheme.fontFamily.sans]
      },
      fontWeight: legacyTheme.typography.weights,
    },
    variables: {
      DEFAULT: {
        ...legacyTheme.colors,
        spacing: legacyTheme.spacings,
        'font-size': legacyTheme.typography.sizes,
        'font-weight': legacyTheme.typography.weights,
        'shadow': legacyTheme.shadows,
        'gradient': legacyTheme.gradients,
        border: legacyTheme.borders,
        // Legacy theme components variables
        ...Object.values(legacyTheme.components).reduce((acc, obj) => ({ ...acc, ...obj }), {}),
      }
    }
  },
  plugins: [
    tailwindcssVariables
  ]
}

Note: Prefer to use plugin without require, because it's will not work in Storybook ThemeBlocks.

Wrong:

{
  plugins: [
    require('@mertasan/tailwindcss-variables')
  ]
}

Right:

import tailwindcssVariables from '@mertasan/tailwindcss-variables';
 
{
  plugins: [
    tailwindcssVariables
  ]
}

3. Access Tailwind tokens in your code through a `config.ts file`:

import resolveConfig from 'tailwindcss/resolveConfig';
import tailwindConfig from '../path_to_config/tailwind.config.js';
 
const { theme: TWConfig } = resolveConfig(tailwindConfig);
 
export default TWConfig;

Note: If you're using Reablocks Storybook blocks, ensure they are updated to utilize the new theming approach:

import TWConfig from './config';
 
- export const Colors = () => <ColorBlocks />;
+ export const Colors = () => <ColorBlocks colors={TWConfig.colors} />;

Establish a New Theme

Define and integrate your new theme, optionally extending it with legacy variables:

1. Create a `theme.ts` file and outline your new theme structure:

Note: Here is used legacyThemeVars to extend the new theme with the old theme variables, also available darkTheme and lightTheme themes (these themes doesn't support legacy css variable).

import { extendTheme, legacyThemeVars, PartialReablocksTheme } from 'reablocks';
 
const theme: PartialReablocksTheme = {
  // Override the default theme here, Example:
}
 
export const projectNameTheme = extendTheme(legacyThemeVars, theme);

2. Update theme in your `ThemeProvider`:

import { projectNameTheme } from './path_to_theme/theme.ts';
 
- <ThemeProvider theme={oldTheme}>
+ <ThemeProvider theme={projectNameTheme}>

Update Components to the New Theming Approach

Finally, adapt your components to utilize the new theme, leveraging Tailwind and the extended theme variables:

import { extendTheme, legacyThemeVars, PartialReablocksTheme } from 'reablocks';
 
const theme: PartialReablocksTheme = {
  input: {
    base: `${legacyThemeVars.components.input.base} text-white`, // use concatenation to extend the default legacyThemeVars theme
    input: `placeholder:font-normal` // full override of the default legacyThemeVars theme styles for input
  }
}
 
export const projectNameTheme = extendTheme(legacyThemeVars, theme);

Seamless Transition & Support

This guide aims to make your migration to 6.x as straightforward as possible. By following these steps, you'll be able to take full advantage of the new theming capabilities offered by Tailwind CSS within our Storybook library. If you encounter any issues or have questions, please don't hesitate to reach out to our Good Code (opens in a new tab) team for support.

Storybook Getting Started