braid-design-system@32.0.0

The is a huge enablement release that sees the removal of legacy themes and treat our previous styling solution, as well as a migration to our new build tool Crackle.

By moving to Crackle, Braid will now be published as a pre-compiled artefact, no longer requiring TypeScript to be transpiled by consumers. This should see faster build times and clearer boundaries between Braid and consuming applications.

Outside of the removal of treat and the legacy themes, there is no impact on the public API of Braid. However, if a consuming web app is reaching into Braid internals, this will no longer work and require code changes.

For these cases, to support teams in upgrading we have provided a Compiled Braid Migration Guide based on patterns observed in code bases.

For more detail on the specific changes in this release, please read on.

Major Changes

• Drop support for React 16. (#1229)

  To support the pre-compilation of Braid, it is now a requirement that consumers are on React 17 or later.
  Originally the plan was to drop React 17 as well, however the team has been able to maintain support for a little longer — but there is a catch (see migration guide below).

  MIGRATION GUIDE:

  React 16 consumers

  As this version is no longer supported it is a requirement that consumers upgrade.
  For more information on the differences between v16 and v17, see the React blog.
  We strongly encourage teams to take this opportunity to upgrade to v18 as well.

  React 17 consumers

  The way React 17 exposes the jsx-runtime is not compatible with ESM, which means the bundler will need instructions on how to resolve the import.
  This can be done by adding a fallback module resolve rule to the webpack configuration.

  For sku consumers, this can be done as follows:

  // sku.config.ts
  {
    dangerouslySetWebpackConfig: (config) =>
      webpackMerge(config, {
        resolve: {
          fallback: {
            'react/jsx-runtime': require.resolve('react/jsx-runtime'),
          },
        },
      }),
  }

  We recommend using webpack-merge to ensure both configurations are deep merged correctly.

  Note: This rule can be removed after upgrading to React 18, which has ESM support.

  React 18 consumers

  No action required.

• Playroom imports are now formalised entrypoints rather than path imports, and as such no longer require the file path extensions to be provided. (#1229)

  EXAMPLE USAGE:

  // playroom.config.js
  module.exports = {
    frameComponent: require.resolve(
      'braid-design-system/playroom/FrameComponent',
    ),
    components: require.resolve('braid-design-system/playroom/components'),
    snippets: require.resolve('braid-design-system/playroom/snippets'),
    scope: require.resolve('braid-design-system/playroom/scope'),
  };

• Remove legacy themes: catho, occ and seekAnz (#1229)

  The seekAnz theme facilitated consumers migrating like-for-like from seek-style-guide, while the catho and occ themes intended to enable a specific use case that never eventuated.

  Removing these themes allows us to move faster with upcoming theme uplift work.

  MIGRATION GUIDE:

  Any remaining consumers of the catho, occ or seekAnz themes should migrate to the apac theme like so:

  -import seekAnz from 'braid-design-system/themes/seekAnz';
  +import apac from 'braid-design-system/themes/apac';

• Remove treat support (#1229)

  Treat has been deprecated for nearly 2 years, superseded by vanilla-extract.
  .treat.ts files can no longer be used for styling and should be converted to .css.ts (vanilla-extract) stylesheets.

• Remove experimental color-mode check script (#1229)

  The experimental script for checking which color mode to render has been formalised to an entrypoint specific to the mechanism that is being used — in this case the query parameter.
  In the future we may add other mechanisms, such as local storage for example, but for now all existing consumers should have been migrated to the query-param check.

  MIGRATION GUIDE:

  - import { __experimentalDarkMode__ } from 'braid-design-system/color-mode'
  + import { colorModeQueryParamCheck } from 'braid-design-system/color-mode/query-param'