Evaluate existing tokens integration and outline an approach to support theming

[aaronccasanova]

Tasks

Beta Give feedback

1. Document the existing Polaris tokens integration in Polaris and Web
2. Outline an incremental approach to add theming support

[aaronccasanova]

Existing Polaris tokens integration

Polaris tokens serve as the source of truth for design tokens used in Polaris, Web, ~5 peer dependent 1P apps/libraries, and 3P apps. The tokens are organized into token groups, which are JavaScript objects containing tokens related to specific conceptual categories such as color, font, and spacing. During the build process, these token groups are combined to generate various assets, including:

• ESM and CJS tokens
  • Simplified token-group objects with key/value pairs only
  • Complete token-group objects with full metadata
• JSON tokens
  • Complete token-group objects with full metadata
• SCSS stylesheets
  • Media queries stylesheet with Sass variables for each breakpoint media condition
  • Root stylesheet with all token-groups converted to custom properties
• CSS stylesheet
  • Root stylesheet with all token groups converted to custom properties

The Polaris library imports the Polaris tokens root SCSS stylesheet in the AppProvider, which assigns all custom properties to the :root selector. Web includes the AppProvider in a collection of high level components, which includes our tokens stylesheet in the built application. This allows a single set of custom properties assigned to :root to be shared between components in Polaris, Web, and the ~5 peer dependent libraries in the Admin (without runtime CSS in JS).

[aaronccasanova]

Closed by #10290 and #10103