v24.0.0

Headlines

• We’ve re-platformed Coral to make use of Panda CSS  in place of the previous styled-components.
• Coral now comes packaged with a light mode theme.
• Our colour token names have been updated to be more semantic and to remove reliance on qualifiers like light and dark.
• The API for responsive props is updated to fit with Panda’s API, but also to make the API easier to use and understand at a glance.
• Theming has been overhauled to allow consumers to customise almost all aspects of the theme without needing esoteric configurations or hacks.
• The way we bundle Coral and all of its packages has changed to support tree-shaking, resulting in smaller bundle sizes for all consumers.

Upgrading your project

We’ve removed styled-components from the system, and replaced it with Panda CSS. This means that the configuration for Coral has changed significantly.

pnpm update @krakentech/blueprint-utils@latest @krakentech/blueprint-onboarding@latest @krakentech/blueprint-dashboard@latest 

pnpm add @krakentech/coral-design@latest

pnpm add -D @pandacss/dev@latest

pnpm update @krakentech/coral@latest @krakentech/coral-charts@latest @krakentech/coral-formik@latest @krakentech/coral-media@latest @krakentech/coral-molecules@latest @krakentech/coral-organisms@latest @krakentech/coral-storyblok@latest @krakentech/icons@latest

# Panda CSS
styled-system

import { defineConfig } from '@pandacss/dev';
import { createCoralPreset, coralHooks, coralLayers } from '@krakentech/coral-design';
 
export default defineConfig({
    presets: [createCoralPreset({})],
    include: [
        // Add any paths that may contain project files that consume Coral components
        './components/**/*.{js,jsx,ts,tsx}',
        './pages/**/*.{js,jsx,ts,tsx}',
        // This is **mandatory** and must always be included
        './node_modules/@krakentech/coral-design/dist/panda.buildinfo.json',
    ],
    exclude: [
        // Exclude any files from static analysis, for example test files
    ],
    // The following options do not need to be changed
    preflight: false,
    outExtension: 'js',
    importMap: '@krakentech/coral-design',
    jsxFramework: 'react',
    syntax: 'object-literal',
    strictPropertyValues: true,
    hooks: coralHooks,
    layers: coralLayers,
    hash: true,
});

"./node_modules/@krakentech/blueprint-utils/dist/panda.buildinfo.json",
"./node_modules/@krakentech/blueprint-dashboard/dist/panda.buildinfo.json",

module.exports = {
    plugins: {
        '@pandacss/dev/postcss': {},
    },
};

@layer reset, base, tokens, recipes, coral_utilities;

import '../panda.css';

npx @krakentech/codemods coral-v24

API Changes

CoralThemeProvider

CoralThemeProvider is now CoralConfigProvider.

Before:

import { CoralThemeProvider } from '@krakentech/coral';
 
<CoralThemeProvider>...</CoralThemeProvider>;

After:

import { CoralConfigProvider } from '@krakentech/coral';
 
<CoralConfigProvider>...</CoralConfigProvider>;

Styling is now controlled via panda.config.ts and not through the old CoralThemeProvider. Properties such as overrides, color or spacing have been migrated, with properties such as defaultIcons or LinkComponent being retained.

To learn more about the how to override styles, color, spacing etc, see the Migrate overrides from CoralThemeProvider section below.

GlobalCss

The <GlobalCss /> component has been removed, and global CSS is now handled by our Panda Coral Preset. If you want to override the Global CSS rules, you can read about this in the Basic Configuration section of our coral-design package.

Colour Tokens

The colour tokens have been updated to be more semantic and to remove reliance on qualifiers like light and dark.

Responsive Props

The API for responsive props has been updated to match Panda’s API. The new API is more intuitive and easier to use. Retrofitting to fit our old API would have been regressive and would negate the benefits of the new API.

Before:

<Accordion theme="midLight" lg={{ theme: 'dark' }}>
    ...
</Accordion>

After:

<Accordion theme={{ base: 'secondary900', lg: 'base900' }}>...</Accordion>

Compound Components

Compound components are no longer barrelled within the parent component, and must be imported and rendered individually, this allows Coral to better optimize its bundle size. For example:

<Breadcrumbs>
    <Breadcrumbs.Link> ...

now becomes

<Breadcrumbs>
    <BreadcrumbsLink> ...

This is relevant for the following components:

Atoms

• Breadcrumbs
• Blockquote
• Card
• Dropdown
• Grid
• List
• Radio
• Review
• Stack
• Switch
• ToggleButton

Molecules

• AppBanner
• CardGroup
• PageNavigation

Organisms

• CookiePreferences
• CreatePassword
• Footer
• Header
• Login
• ResetPassword
• All Formik equivalents of the above (ToggleButton, Radio, Switch)

General Changes

dataAttributes

The previously deprecated dataAttributes prop has been removed from all components. If you were using this prop, use attributes instead.

headerHeight

Previously you’d be able to get the configured headerHeight from useCoralTheme, this is now available from useCoralConfig instead.

Before

import { headerHeight } = useCoralTheme();

After

import { headerHeight } = useCoralConfig();

Component Changes - Atoms

Accordion

• theme values have changed:

  Before	After
  dark	base900
  mid	base500
  light	secondary900

Alert

• severity and theme are now no longer responsive.
• theme values have changed:

  Before	After
  light	semantic
  dark	base900

Autocomplete

• theme values have changed:

  Before	After
  light	base100
  dark	secondary500

Button

• variant, size and color are now no longer responsive.
• color values have changed:

  Before	After
  primary	primary500
  secondary	secondary500
  tertiary	base100

Container

• maxWidth has been split into maxWidth and maxWidthPreset. You can no longer pass sm, md , etc. to the maxWidth property, as it only accepts valid values of the CSS property. If you are providing the breakpoint value, they need to be passed into maxWidthPreset instead.

  Before:

  <Container maxWidth="lg">

  After:

  <Container maxWidthPreset="lg">

• theme values have changed:

  Before	After
  dark	base900
  light	base100
  mid	base500

Card

• CardImage
  • No longer accepts a responsive src parameter
  • position has been renamed to backgroundPosition
• bodyHeight has been removed, and been replaced with height applied directly on CardBody
• theme values have changed:

  Before	After
  light	base100
  dark	base900
  mid	base500
  midLight	secondary900
  tertiaryLight	tertiary100

Checkbox

• theme values have changed:

  Before	After
  light	tertiary500
  dark	secondary500

Chip

• variant, size and color are now no longer responsive.
• color values have changed:

  Before	After
  primary	primary500
  secondary	secondary500
  tertiary	tertiary500
  error	error500
  warning	warning500
  success	success500

Dialog

• maxWidth has been renamed dialogWidth

Drawer

• position is no longer responsive

Grid

• templateAreas is now called gridTemplateAreas
• templateColumns is now called gridTemplateColumns
• templateRows is now called gridTemplateRows
• area is now called gridArea
• gap, rowGap and columnGap should be set to none and not 0 when setting the value to zero.

GridItem

• colSpan has been renamed to gridColumn. It now requires you to manually add span to the property, so what would previously have been, for example, colSpan={5} will now be gridColumn="span 5".
• rowSpan has been renamed to gridRow. It now requires you to manually add span to the property, so what would previously have been, for example, rowSpan={5} will now be gridRow="span 5".
• colStart has been renamed to gridColumnStart
• colEnd has been renamed to gridColumnEnd
• rowStart has been renamed to gridRowStart
• rowEnd has been renamed to gridRowEnd

Link

• color values have changed:

  Before	After
  dark	secondary500
  light	tertiary500

Loader

• color values have changed:

  Before	After
  primary	primary500
  secondary	secondary500
  tertiary	tertiary500
  base	base500
  text	base100

Radio

• theme values have changed:

  Before	After
  light	tertiary500
  dark	secondary500

Select

• theme values have changed:

  Before	After
  light	base100
  dark	secondary500

Skeleton

• In order to remove animation, you should set animation={undefined} rather than animation={false}.

Slider

• showLabels and valueLabelDisplay are now no longer responsive.

Stack

• direction has been renamed flexDirection. It now uses default CSS values (row, column, etc.) instead of the previous preset horizontal, vertical etc.
• gap, rowGap and columnGap should be set to none and 0 when setting the value to zero.

Switch

• behaviour is now set on the parent Switch rather than SwitchInput

TextArea

• theme values have changed:

  Before	After
  light	base100
  dark	secondary500

TextField

• theme values have changed:

  Before	After
  light	base100
  dark	secondary500

Toast

• toastId is now called containerId.

Tooltip

• theme values have changed:

  Before	After
  mid	base300
  light	base100
  dark	base900

Typography

• variant has been renamed textStyle, and is no longer responsive.
• Additional contents values for the color prop have also been added, such as contentsBase500, contentsBase900, contentsPrimary500, contentsSecondary500, etc. These are deemed safe text colours to use on top of the colour they reference in their name.
• The values for the color prop have changed to match the new colour tokens, as below

Component Changes - Molecules

ActionCard

• theme values have changed:

  Before	After
  light	base100
  dark	base900
  mid	base500
  midLight	secondary900
  tertiaryLight	tertiary100

CardGroup

• direction now accepts column | row, rather than vertical | horizontal
• The backgroundImage object is no longer responsive on CardGroupCard

ErrorPage

• PageNotFound has been removed

Footer

• The markup required to build a Footer has changed:
  • We no longer use ListItem
  • The List components renders as a nav element

PageNavigation

• PageNavigationItem and PageNavigationToggle now accept an icon prop and only accepts a string as children.

Before:

<PageNavigationItem href="#">
    <Stack alignItems="center" fullWidth>
        <IconHome size={24} />
        <Typography textStyle="button">Home</Typography>
    </Stack>
</PageNavigationItem>

After:

<PageNavigationItem href="#" icon={<IconHome size={24} />}>
    Home
</PageNavigationItem>

Component Changes - Formik

FormikTextField

• theme values have changed:

  Before	After
  light	base100
  dark	secondary500

Component Changes - Charts

Animation has been removed from coral-charts, and the animation prop has been removed from all chart components. If you were using this prop, you will need to remove it from your code, as there is no alternative implementation. This is because there was no usage of the animation property by consumers, and the implementation was not particularly effective or useful.

Tokens

useCoralTheme()

useCoralTheme() no longer exists. You will need to make use of token from @krakentech/coral-design/tokens to access values previously accessed through useCoralTheme()

Before:

import { useCoralTheme } from '@krakentech/coral';
 
const { colors, spacing } = useCoralTheme();
 
<Component someProp={spacing.md} />
<Component otherProp={colors.primary.main} />

After:

import { token } from '@krakentech/coral-design/tokens';
 
<Component someProp={token('spacing.md')} />
<Component otherProp={token('colors.background.primary.500')} />

Colour

The colour tokens, like with Typography, have also been updated in line with the Colour Tokens section above.

Animation

Animation tokens have also been updated and expanded, and are now exported as follows:

Migrate overrides from CoralThemeProvider

Note: Theming is more comprehensively explained in Basic and Advanced Configuration sections of the Design documentation.

Continuing on from above, here are some examples of how to migrate your overrides from the CoralThemeProvider to the new Panda CSS configuration.

Some migrations are fairly straightforward:

// CoralThemeProvider
overrides: {
    typography: {
        fontFamily: '"Figtree", sans-serif',
    },
}
 
// panda.config.ts
createCoralPreset({
    options: {
        tokens: {
            typography: {
                fontFamily: '"Figtree", sans-serif',
            },
        }
    }
}),

However, declarations contained within overrides.components are likely to be considerably more complex. You may be able to set a basic token, however, you may also be required to apply the styles by extending the internal recipes instead.

For example, changing the colour of the Banner component is fairly straightforward:

// CoralThemeProvider
overrides: {
    components: {
        banner: {
            root: {
                background: 'red',
            },
        },
    }
}
 
// panda.config.ts
createCoralPreset({
    options: {
        tokens: {
            components: {
                banner: {
                    secondary: {
                        background: 'red',
                    },
                },
            }
        }
    }
})

However, adding a box shadow to the Card component would require you to extend the internal recipe:

// CoralThemeProvider
overrides: {
    components: {
        card: {
            root: {
                boxShadow: '0 0 10px rgba(0, 0, 0, 0.1)',
            },
        },
    }
}
 
// panda.config.ts
createCoralPreset({
    ...
}),
theme: {
    extend: {
        recipes: {
            StyledCard: {
                base: partsList.cardParts({
                    root: {
                        boxShadow: '0 0 10px rgba(0, 0, 0, 0.1)',
                    },
                })
            }
        }
    }
}

coral-storyblok

As Panda CSS is a build-time CSS-in-JS library, any arbitrary styles that you apply in Storyblok (think custom widths or heights) cannot be applied at build time, as the compiler cannot know that these values exist.

To account for this, we have introduced a GetStoryblokStaticCss hook that will generate the necessary CSS for the Storyblok components at build time.

However, to use this hook, you will need to ensure that you are using getStaticProps in your calls to getStoryblokApi. This is because GetStoryblokStaticCss needs to be able to pre-generate the CSS for the Storyblok components at build time, and this is only possible when the content for the page is pre-generated from the Storyblok API.

Your Storyblok page component could look something like this:

const Page: FC<{ story: ISbStoryData; css: any }> = ({ story: s, css }) => {
    const story = useStoryblokState(s);
 
    if (!story) {
        return null;
    }
 
    return (
        <Container
            marginX="auto"
            paddingX="sm"
            paddingY="xl"
            maxWidthPreset="md"
            component="section"
        >
            <Head>
                <style>{css}</style>
            </Head>
            <Stack flexDirection="column" gap="lg">
                <Typography textStyle="hero2">{story.name}</Typography>
 
                {story.content.body?.map((nestedBlok: SbBlokData) => (
                    <StoryblokComponent
                        key={nestedBlok._uid}
                        blok={nestedBlok}
                    />
                ))}
            </Stack>
        </Container>
    );
};
 
export default Page;
 
export const getStaticProps = async ({ params }) => {
    const slug = params?.slug?.join('/') || 'home';
    const { data } = await getStoryblokApi().get(`cdn/stories/${slug}`);
 
    return {
        props: {
            story: data ? data.story : false,
            css: data
                ? GetStoryblokStaticCss(data.story.content.body)
                : undefined,
        },
    };
};

styled-components

Although this new Panda-powered version of Coral and older styled-components code can co-exist, we recommend that you migrate away from styled-components in your project to avoid confusion and potential conflicts. Some migration options in order of preference:

• Swap old custom styled-components for Coral components and remove the custom styled-components
• For cases where you need custom CSS – re-write those styled-components to use Panda CSS 

To help with the first option above the Coral team have been on a worldwide mission to remove styled-components from all codebases , but as you can imagine this is no small task, and is still ongoing. However, once your project has migrated away from styled-components, you will be able to do the following:

• Remove ServerStyleSheet from your _document.tsx file
• Remove styled-components package from your project

Light Mode

Coral now comes with a light colour mode baked into all components.

We’re currently working on a component that will allow users to switch between the colour modes and save that selection in local storage.

Light mode will work best when your project has migrated away from styled-components, and any other custom styles that don’t currently make use of Coral tokens. For now, please use this new Coral light mode as an incentive to migrate your custom styles to Coral components, or to Panda CSS. We will update with more soon!