Establish a pattern for accessing theme values at runtime in JSX

[aaronccasanova]

No description provided.

[aaronccasanova]

Discussed offline with @samrose3

Notes

Considering a future where Polaris tokens supports multiple themes (e.g. light, light-hight-contrast, etc.), runtime access in JSX (for example within a useTheme() hook) has the potential to increase bundle sizes since each variant theme is a complete theme object. We tentatively brainstormed a couple strategies:

• Introduce a useThemeVars hook that doesn't need to be theme aware. The hook would simply return a themeVars object that references fully qualified CSS vars:
  • Example: themeVars.color['color-bg'] === 'var(--p-color-bg)'
  • Pros: No impact on bundle size as there is only one themeVars object in memory regardless of how many themes we support
  • Cons: There are valid cases where developers need the underlying values
  • Note: Alternatively, themeVars could be a named export from Polaris tokens e.g.
    import {themeVars} from '@shopify/polaris-tokens'
• Introduce dedicated theme aware hooks for accessing select token values
  • Reasoning: There are existing and valid imports of motion token values in Polaris and Web for setting animation timeouts (e.g. when used with libraries like react-transition-group that expect numbers in milliseconds)
  • Example: const motionDuration = useMotionDuration() where motionDuration['motion-duration-200'] === '200ms'
  • Pros: Minimized impact on bundle size as useMotionDuration would only hold a subset of tokens for each theme in memory
  • Cons: Discoverability could be challenging and require education how and when to use the utility

[aaronccasanova]

Introduce a useThemeVars hook that doesn't need to be theme aware[...]

Here is the initial exploration of this approach.

Overview:

• The themeVars object is constructed and exposed from @shopify/polaris-tokens
• Since most consumers don't include @shopify/polaris-tokens directly themeVars are exposed from @shopify/polaris
• The themeVars object is accessible from a useThemeVars context initialized in the AppProvider

Note: The React hook isn't really necessary. Alternatively, we can simply re-export @shopify/polaris-tokens themeVars from @shopify/polaris. This also has a subtle advantage over the React hook in that access isn't constrained to function components.

Example themeVars access from @shopify/polaris-tokens

Example themeVars access from useThemeVars

Example alternative/re-export approach

// polaris-react/src/index.ts
export {themeVars} from '@shopify/polaris-tokens';

// src/my-app/index.tsx
import {themeVars} from '@shopify/polaris';

[aaronccasanova]

Closed by #10290 and #10252