search

Esri / calcite-design-system

A monorepo containing the packages for Esri's Calcite Design System
https://developers.arcgis.com/calcite-design-system/
Other
279 stars 76 forks source link

Design token phase II - Integration across components #7180

Open geospatialem opened 1 year ago

geospatialem commented 1 year ago

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)

    • 9450

    • Tracking in Monday
  3. [ ] All relevant components have one Chromatic test or demo page to visually confirm token application. (remaining estimate 1 day)

    • 9644

  4. [ ] All relevant components pass final QA (remaining estimate 5 days)
    • [ ] Design confirmation design-tokens are in alignment between Figma and Web platforms.

      • 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 #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

Components

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 commented 1 year ago

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

geospatialem commented 10 months ago

A related issue surfaced with the Maps SDK for JS team regarding a global font family variable, https://github.com/Esri/calcite-design-system/issues/7175. Should we consider the effort as part of the design token epic above? cc @alisonailea

alisonailea commented 9 months ago

Next steps Review tokens in components #4098 Apply font family tokens to all components #7175

geospatialem commented 5 months ago

Once completed, we should verify if #7854 is mitigated, or if follow-up is needed.