Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add useTheme hook for runtime Polaris tokens access #10252

Merged
merged 35 commits into from
Aug 31, 2023

Conversation

aaronccasanova
Copy link
Member

@aaronccasanova aaronccasanova commented Aug 26, 2023

Rework of #10229.

  • To enhance clarity and avoid ambiguity, we have reintroduced the convention of prefixing all theme related objects and types with meta. While I was trying to steer us away from this convention, keeping it establishes consistency and makes it easier to differentiate between theme constructs with and without metadata.

  • Introduced a new createThemeVariant utility, which accepts a theme partial and constructs a complete theme object. This utility simplifies the process of creating theme variants and ensures that all required properties are included.

  • The AppProvider has been updated to incorporate a new ThemeContext.Provider and associated useTheme hook. This provider utilizes the createThemeVariant utility to expose the active theme to child components. This eliminates the need for several previously proposed exports and hooks, including themeVars, useThemeName, useThemeVarDecl, and useCSSDecl.

Before:

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

themeVars.color['color-bg'] // 'var(--p-color-bg)'
import {useThemeVarDecl} from '@shopify/polaris';

function App() {
  const colorBgDecl = useThemeVarDecl('--p-color-bg');

  colorBgDecl // { status: 'success', value: '#123', ... }
}

After:

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

function App() {
  const theme = useTheme()

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

aaronccasanova and others added 26 commits August 16, 2023 16:40
Co-Authored-By: Aaron Casanova <32409546+aaronccasanova@users.noreply.github.com>
Base automatically changed from polaris-tokens-artifacts-2 to multi-theme-support August 31, 2023 21:51
@aaronccasanova aaronccasanova marked this pull request as ready for review August 31, 2023 23:10
@aaronccasanova aaronccasanova merged commit 5c58ccc into multi-theme-support Aug 31, 2023
15 checks passed
@aaronccasanova aaronccasanova deleted the polaris-tokens-runtime-2 branch August 31, 2023 23:10
aaronccasanova added a commit that referenced this pull request Sep 7, 2023
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](#10103)

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**

```scss
: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](#10250)

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.

```ts
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](#10252)

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

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

function App() {
  const theme = useTheme()

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

---------

Co-authored-by: Laura Griffee <laura@mailzone.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants