Docs
πŸš€ ⏐ Getting Started
Migration

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.