Determine CSS Custom Property Integration

Enabling this feature

Couple of options:

• Introduce capabilities behind a feature flag, possibly use-custom-properties
• Introduce capabilities with appropriate fallback, meaning:

.selector {
  color: #000000;
  color: var(--token-01, #000000);
}

Wrapping behind a feature flag would mean complicating authoring logic, potentially, but could be encapsulated by helper mixins/functions (although not ideal).

Writing this feature

The general strategy for CSS Custom properties will most likely output:

.selector {
  color: #000000;
  color: var(--token-01, #000000);
}

We want to do this so that browsers that do not support CSS Custom Properties will use the correct fallback value. However, we will probably want to author this feature in a different way. Some ideas:

// Option 1: specify token directly with no fallback, use build step
// to generate correct output
.selector {
  color: var(--token-01);
}

// Option 2: specify token and fallback, use build step to generate correct output
// drawback is that it could be error prone when authoring, may need lint rule
.selector {
  color: var(--token-01, $token-01);
}

// Option 3: use a helper function to output `var(--token-01, $token-01)`
// and a build step for correct output
.selector {
  // Name TBD
  color: some-function(token-01);
}

// Option 4: use a helper mixin to output the correct properties with no build step
.selector {
  // Name TBD
  @include some-mixin(token-01);
}

Theming support

We want to support top-level theming and zone theming. Top-level theming should be a static transform (meaning no need to set custom properties). Zone theming will need to set custom properties. While subtle, the difference would be:

// Input
$carbon--theme: (
  token-01: #ffffff,
);
@include carbon--theme($carbon--theme);

.selector {
  color: var(--token-01, $token-01);
}

// Output
.selector {
  color: #ffffff;
  color: var(--token-01, #ffffff);
}

// Input
$light-theme: (
  token-01: #ffffff,
);

// Specify light theme as default
$carbon--theme: $light-theme
@include carbon--theme($carbon--theme);

.selector {
  color: var(--token-01, $token-01);
}

// Scope dark mode to `.dark` selector
$dark-theme: (
  token-01: #ffffff,
);
.dark {
  @include carbon--theme($dark-theme);
}

// Output
.selector {
  color: #ffffff;
  color: var(--token-01, #ffffff);
}

.dark {
  --token-01: #000000;
}

[mattrosno]

I think it’d be great to for variables to remain Sass variables, and then we have a transformation based on the feature flag. E.g. tokens like:

$token-01: pink !default;
$token-02: blue !default;

Then save those in a map that is iteratable:

$tokens: (
  'token-01': $token-01,
  'token-02': $token-02
) !default;

Then in your build step, if the custom property feature flag is enabled, do the transformation:

@each $key, $value in $tokens {
  $tokens: map-merge(
    $tokens,
    (
      $key: var(--#{$prefix}--#{$key}, #{$value}),
    )
  );
}

Now, the value of $token-01 is no longer pink, it’s var(--bx--token-01, pink). The Sass:

.selector {
  background: $token-01;
}

Becomes CSS:

.selector {
  background: var(--bx--token-01, pink);
}

And after PostCSS’ed:

.selector {
  background: pink;
  background: var(--bx--token-01, pink);
}

P.S. CSS custom properties should be prefixed to prevent run-time collisions with 3rd-party styling or scenarios when there’s a need to use multiple Carbon versions on the same page.

[joshblack]

We’re going to move forward with the following and get feedback on if the sass build pipeline is needed:

.selector {
  // Tokens are namespaced with --c-
  color: var(--c-token-01, $token-01);
}

And we will polyfill our output scss directory with if folks justify it as needed

.selector {
  color: $token-01;
  color: var(--c-token-01, $token-01);
}