2024-09-04 Meeting notes

Color tokens, accents

Adam Stankiewicz

The 2U/edX.org Paragon Elm Theme (@edx/elm-theme) currently depicts the levels 100-900 for the accent-a and accent-b colors.

This is a change from the current Paragon theme in that accent-a and accent-b represent singular values (the 500 level in the below screenshot).

Discussion

• If the accent-a and accent-b levels 100-900 are needed from a design perspective, the upstream Paragon tokens will need to support levels for accent-a and accent-b, instead of a single values.

  • Is this something we want to do? Otherwise, Elm Theme can only account for the accent-a-500 and accent-b-500 levels for compatibility with Paragon.

• Non breaking change from eng perspective because utility classes exist to allow using $accent-a to mean $accent-a-500

• [Kevin B] Risk of contrast failing with more choices

  • [Adam S] Already complexity we need to handle with all the other colors

Updates to build-tokens CLI command

Adam Stankiewicz

[inform] One of the changes in the following PR includes updating the build-tokens Paragon CLI command, separating --source-tokens-only from --output-references.

https://github.com/openedx/paragon/pull/3203

Without this change, the CSS variables output from a brand package will not contain references to relevant CSS variables, which limits support for runtime theming of those tokens.

Before

Brand packages did not include CSS variables in its output, instead having hard coded values (i.e., HEX codes).

After

When relevant, the output CSS variables will reference its underlying CSS variable, instead of always hardcoding the raw value.

Discussion

• Warnings

  • Using references from base paragon tokens in brand packages

    • Intentional as they will exist when brand package used with paragon

    • Could tell brand package to build everything instead

      • [Brian S] Don’t want to rethink how styles are provided to MFEs right now, might be worth revisiting this decision with frontend-base

  • a11y contrast ratio

Composite tokens in style-dictionary

Adam Stankiewicz

Why?

Simpler tokens schema in JSON for theme authors, by combining style properties under a composite token vs. implementing separate tokens.

style-dictionary v3 did not support composite tokens, IIRC; v4 now does!

Impacted token types:

• Stroke style

• Border

• Transition

• Shadow

• Gradient

• Typography

Docs:

• https://tr.designtokens.org/format/#composite-types (“Composite types”)

• https://tr.designtokens.org/format/#groups-versus-composite-tokens (“groups vs. composite tokens”)

• https://styledictionary.com/reference/config/#expand (expand)

Examples:

{
  "shadow-token": {
    "$type": "shadow",
    "$value": {
      "color": "#00000080",
      "offsetX": "0.5rem",
      "offsetY": "0.5rem",
      "blur": "1.5rem",
      "spread": "0rem"
    }
  }
}

https://tr.designtokens.org/format/#typography (“Typography”)

{
  "type styles": {
    "heading-level-1": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Roboto",
        "fontSize": "42px",
        "fontWeight": 700,
        "letterSpacing": "0.1px",
        "lineHeight": 1.2
      }
    }
  }
}

Discussion

• Related to now supporting the DTCG format, do we want to migrate any tokens (e.g., typography) to composite tokens before merging alpha → master?

  • I.e., within the scope of style-dictionary upgrade v3 → v4

  • Example migration of an existing shadow token to a composite shadow token:

    • https://github.com/openedx/paragon/pull/3213