Add multi-theme support to Polaris

[aaronccasanova]

This PR consolidates the integration of three feature branches that collectively introduce a new base/variant theme architecture to Shopify Polaris. The merged PRs introduce multi-theme support, updated build artifacts, and a new useTheme hook for runtime Polaris tokens access. Below, you will find a brief overview of each PR, with links to the original PRs for a more detailed review.

Add multi-theme support to Polaris tokens

This PR introduces multi-theme support to @shopify/polaris-tokens by implementing a base/variant architecture. The base theme serves as the foundation for multiple variant themes, which extend the base theme and are the only themes exposed to consumers. Simplifying system changes by flattening the relationship between themes is the primary advantage of this pattern. The PR also includes implementation details like directory structure, stylesheet generation, and variant theme functionality.

Example styles.scss updates

:root {
  /* Default variant theme custom properties (light) */
}

html.Polaris-Summer-Editions-2023 {
  /* Variant theme custom properties */
  /*
     Note: The above selector is special
     cased for backward compatibility. See
     below for updated theme selector structure.
  */
}

html.p-theme-light-high-contrast {
  /* Variant theme custom properties */
  /*
     Note: Variant theme selectors
     contain a subset of custom properties
     overriding the base theme
  */
}

html.p-theme-dark {/* ... */}
html.p-theme-dark-high-contrast {/* ... */}
html.p-theme-dim {/* ... */}

Add multi-theme build artifacts to Polaris tokens

This PR is a rework of #10153, redefining how the themes are accessed from @shopify/polaris-tokens. It introduces changes on how asset builder functions are written and replaces reference to themes.light with a themeDefault alias.

import {themes} from '@shopify/polaris-tokens';

themes['Polaris-Summer-Editions-2023'].color['color-bg']

Note: Future releases can reduce the bundle size impact of including all themes on one object and enable more flexibility (for example with a createTheme util that deep merges variant theme partials). However, that is not needed at this time and can be introduced in a minor release.

Add useTheme hook for runtime Polaris tokens access

This PR is a rework of #10229, brings updates to the AppProvider by incorporating a new ThemeContext.Provider and an associated useTheme hook.

import {useTheme} from '@shopify/polaris';

function App() {
  const theme = useTheme()

  theme.color['color-bg'] // '#123'
}

[aaronccasanova]

/snapit

[github-actions]

🫰✨ Thanks @aaronccasanova! Your snapshots have been published to npm.

Test the snapshots by updating your package.json with the newly published versions:

yarn add @shopify/polaris-migrator@0.0.0-snapshot-release-20230831232228

yarn add @shopify/polaris@0.0.0-snapshot-release-20230831232228

yarn add @shopify/polaris-tokens@0.0.0-snapshot-release-20230831232228

yarn add @shopify/stylelint-polaris@0.0.0-snapshot-release-20230831232228

[aaronccasanova]

This is needed for backward compatibility with the existing metadata export and can be moved to a devDependency post v12.

[aaronccasanova]

Note: These exports will be removed in the v12 release as they will no longer be relevant in the new theming architecture.

[aaronccasanova]

/snapit

[github-actions]

🫰✨ Thanks @aaronccasanova! Your snapshots have been published to npm.

Test the snapshots by updating your package.json with the newly published versions:

yarn add @shopify/polaris-migrator@0.0.0-snapshot-release-20230905190500

yarn add @shopify/polaris@0.0.0-snapshot-release-20230905190500

yarn add @shopify/polaris-tokens@0.0.0-snapshot-release-20230905190500

yarn add @shopify/stylelint-polaris@0.0.0-snapshot-release-20230905190500