Design token phase II - Integration across components

[geospatialem]

Description

Addresses the final, or second phase, of our design token integration from #6558.

Majority of the effort will be performed in June and July, targeted for early August for additional documentation and pages for the September main release.

cc @alisonailea @jcfranco

Acceptance Criteria

1. All relevant components have been refactored to use CSS variables which match component design tokens.
   • Token Jam Session 01/12/2024
   • Design Tokens Standup
   • Tracking in Monday
2. All relevant components have E2E tests to automate testing of token application. (remaining estimate 1-week)
   • test: update themed to handle pseudoelements and special underline styling case #9450
   • Tracking in Monday
3. All relevant components have one Chromatic test or demo page to visually confirm token application. (remaining estimate 1 day)
   • Themed Chromatic/Demo Test Helper #9644
4. All relevant components pass final QA (remaining estimate 5 days)
   • Design confirmation design-tokens are in alignment between Figma and Web platforms.
     • Design tokens: Refactor for alignment across the design system #9524 (remaining estimate < 1 day)
     • @alisonailea, @ashetland, and @SkyeSeitz to do final review of component tokens names to confirm pattern alignment. (remaining estimate 1 day)
   • Engineering confirmation that tokens work does not cause breaking changes in Calcite-Components (remaining estimate > 1 day)
     • Requires Themed Chromatic/Demo Test Helper #9644
     • @DitwanP and @geospatialem to do manual check of all themed demos on a local instance in all major browsers to confirm tokens are applied correctly to the component.
   • Docs confirmation (remaining estimate > 1 day)
     • Each token as a CSS Custom Property/CSS Variable is listed in the relevant Calcite Component .scss file as a JSDocs @prop "token name": "description"
     • Each token listed in the component's JSDoc section is used in the component code.
     • Each token listed in the component's JSDoc section is listed in the e2e tests under "themed"
       • If a CSS Variable is deprecated, it should be noted in the JSDoc as @prop "token name": [Deprecated] Use "new token name" instead. "description"
     • Confirm any CSS Variables listed as deprecated are tested in E2E tests under a describe("deprecated", () => {}) section

Relevant Info

• For specific component issues, we can use the design-tokens label.
• Tracking of individual component token work was moved to Monday.

Components

• accordion-item
• accordion (Expose CSS variable to style accordion item header in active state  #4060 calcite-accordion-item content padding #4012)
• action-bar
• action-group
• action-menu
• action-pad
• action (Transparent Action hover state missing background color #8519)
• alert
• avatar (Avatar: add option to set the background color #4900 Avatar: css variable to adjust round corner #7651)
• block-section (feat(block-section): add component tokens #8795)
• block (feat(block): add component tokens #8790)
• button (feat(button, fab): add component tokens #8922)
• card (feat(card): Add component tokens #8597)
• checkbox
• chip-group (feat(card): Add component tokens #8605)
• chip (feat(chip, chip group): Add component tokens #8607)
• color-picker-hex-input
• color-picker-swatch (refactor(color-picker-swatch): add component tokens #8805)
• color-picker (calcite-color-picker: should be responsive to container sizes #8463)
• combobox-item-group
• combobox-item
• combobox
• date-picker-day
• date-picker-month-header
• date-picker-month
• date-picker
• dropdown-group
• dropdown-item
• dropdown
• fab (feat(button, fab): add component tokens #8922)
• filter (8722)
• flow-item(8723)
• flow (8602)
• graph (feat(graph): add component tokens #8787)
• handle (8780)
• icon ([Icon] Add support for a new token for the component's color and remove last remaining -ui-named css var #8549)
• inline-editable feat(inline-editable): add component tokens #8596 (feat(inline-editable): add component tokens #8788)
• input-date-picker
• input-message
• input-number
• input-text
• input-time-picker
• input
• label (feat(label): add component tokens #8796)
• link (feat(link): add component tokens #8660)
• list-item-group (8773)
• list-item (8773)
• list (8773)
• loader
• menu-item (Menu items/components do not get custom colors when slotted inside Navigation #8018)
• menu
• meter (feat(meter): Add component tokens #8606)
• modal
• navigation-logo (Navigation Logo - using wrong icon color with href #8482)
• navigation-user
• navigation
• notice (feat(notice): Add component tokens #8645)
• pagination (feat(pagination): Add component tokens #8777)
• panel (8670)
• popover (8642)
• progress (8661)
• radio-group-item (8831)
• radio-group (8831)
• rating (feat(rating): Add component tokens #8775)
• scrim (feat(scrim): Add component tokens #8662)
• segmented-control-item (8835)
• segmented-control (8835)
• select (feat(select): add component tokens #8599)
• shell-center-row (8798)
• shell-panel ([Shell Panel] add open/close animation #8011)
• shell (8794)
• slider (Same instances of calcite slider appear to have different rendered size #8049 [Slider] Expose slider fill css variable #7312)
• split-button
• stepper-item (stepper: add tokens for responsive layout #8174)
• stepper ((stepper: add tokens for responsive layout #8174, 8461)
• switch (Switch handle doesn't match size of its track #5792 feat(switch): add component tokens #8786)
• tab-nav (feat(tab-nav): add component tokens #8853)
• tab-title (feat(tab-title): add component tokens #8854)
• tab (feat(tab): add component tokens #8852)
• table (feat(table): Add component tokens #8940)
• tabs (8783)
• text-area
• tile ([Tile] Add visual scales #4759)
• time-picker (feat(time-picker): add component tokens to time picker #8898)
• tip-manager (8782)
• tip (8641)
• tooltip (8770)
• tree-item
• tree
• option-group not applicable
• option not applicable
• pick-list-group (deprecated)
• pick-list-item (deprecated)
• pick-list (deprecated)
• stack
• tile-select-group (future deprecated by tile-group)
• tile-select (future deprecated by tile-group)
• tip-group (8781 (future deprecated))
• value-list-item (deprecated)
• value-list (deprecated)
• functional
  • ExpandToggle
  • FloatingArrow - Note: tooltip and popover will need adjustments for the floating arrow.
  • Heading
  • XButton (refactor: Use component tokens within includes #8771)

Example Use Case

/**
 * CSS Custom Properties
 *
 * These properties can be overridden using the component's tag as selector.
 *
 * @prop --calcite-my-component-background-color: Specifies the background color of the component.
 * @prop --calcite-el-color-background: [Deprecated] Use `--calcite-my-component-background-color` instead. Specifies the background color of the component.
 * @prop --calcite-my-component-icon-color: Specifies the color of the icon sub-component.
 */

div {
  background-color: var(--calcite-my-component-background-color, var(--calcite-el-color-background, var(--calcite-color-brand)));
}

// calcite-icon
.icon {
    --calcite-icon-color: var(--calcite-my-component-icon-color, var(--calcite-color-brand));
}

describe("theme", () => {
    describe("default", () => {
      themed(`calcite-my-component`, {
        "--calcite-my-component-background-color": {
          shadowSelector: `div`,
          targetProp: "backgroundColor",
        },
        "--calcite-my-component-icon-color": {
          shadowSelector: `.${CSS.icon}`,
          targetProp: "--calcite-icon-color",
        },
      });
    });

    describe("deprecated", () => {
      themed(`calcite-my-component`, {
        "--calcite-el-color-background": {
          shadowSelector: `div`,
          targetProp: "backgroundColor",
        },
      });
    });
});

Priority impact

impact - p2 - want for an upcoming milestone

Esri team

Calcite (design)

[geospatialem]

A list of components we could use for exploring tokens to start estimations and next steps:

• avatar
• modal
• shell-panel
• tooltip

[geospatialem]

A related issue surfaced with the Maps SDK for JS team regarding a global font family variable, #7175. Should we consider the effort as part of the design token epic above? cc @alisonailea