Color Module - First Draft

[adekunleoduye]

Overview

This is the first draft of the Design Tokens Color Module.

[netlify]

✅ Deploy Preview for dtcg-tr ready!

Name	Link
🔨 Latest commit	c58ca34
🔍 Latest deploy log	https://app.netlify.com/sites/dtcg-tr/deploys/66c78acd82949c00080b6713
😎 Deploy Preview	https://deploy-preview-147--dtcg-tr.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[adekunleoduye]

Update examples

[cgatian]

Suggested change

	<li>No fully supported (only safari)</li>
	<li>Not fully supported (only safari)</li>

[cgatian]

Just a nitpick. It would be nice if the Con sections mentioning the lack of browser support were consistent.

Something like

"Limited Browser Support (Safari)"

Consistent verbiage and browsers with support are listed.

[kaelig]

I think we may need to move this section directly into the technical-reports/color/index.html file like we do with the format:

community-group/technical-reports/format/index.html

Lines 89 to 100 in d7fb899

	<section id="introduction">
	<h1>Introduction</h1>
	<p>
	<em>This section is non normative</em>
	</p>
	<p>
	Design tokens are a methodology for expressing design decisions in a
	platform-agnostic way so that they can be shared across different
	disciplines, tools, and technologies. They help establish a common
	vocabulary across organisations.
	</p>

And we can probably remove the Color module title.

[kaelig]

Not supported in all browsers (IE 11)

Source?

[kaelig]

Limited browser support (Safari only)

Now supported in Chrome, Edge, Safari, and Firefox behind a flag.

https://caniuse.com/mdn-css_types_color_oklch

[kaelig]

Is there another way to write this without the cx utility function?

[kevinmpowell]

@adekunleoduye @ayeshakmaz is there any reason for single declarations we can't do:

...
"$value": "#111111"
...

?
The additional object with a single key of "$hex" seems unnecessary.

[kaelig]

My understanding was that this notation was still supported?

[c1rrus]

That's my understanding too. So, both of the syntaxes below are permitted and are exactly equivalent:

{
  "my-color-token": {
    "$type": "color",
    "$value": "#111111"
  }
}

and

{
  "my-color-token": {
    "$type": "color",
    "$value": {
      "$hex": "#111111"
    }
  }
}

However, for this example, it might be better to use the first style since it'll be more familiar to folks used to the current spec draft (which only permits that syntax at the moment) and is more terse.

[drwpow]

Suggestion: $hex, $colorSpace, $name etc should probably drop the $ prefix, right? For all other tokens, $value objects contain normal non-prefixed keys. Which feels more expected because outside the token, $value is a special reserved word that marks any object as a token. But inside the $value, a strict schema is enforced where arbitrary properties are no longer allowed (so no benefit to prefixing keys).

Apologies if there’s a discussion I missed or if this suggestion isn’t helpful.

[c1rrus]

I was just about to make the same point! :-)

(FWIW, alternatively we could go down the route of making all spec-related properties have a $ prefix for consistency. But then we'd need to make some significant changes to the current format draft in order to update all the composite types. Personally, I'd prefer to stick with the current approach though)

[c1rrus]

Sorry it's taken me so long to review this. Great work putting all of this together!

However, I think there's still work to be done to better align this with the format spec.

[c1rrus]

The overview.md is missing in this PR. Is this an old link that needs to be removed, or does this file just need to be added to git?

[c1rrus]

Dunno if this is something that's (going to be?) covered in the missing overview.md file (see my other review comment), but I think it would be helpful to provide a bit more context about this document's purpose here.

My reading is that the "Token naming" chapter is providing non-normative guidance and advice for how to name & organise colour tokens. However, the later sections are detailed specs for how colour tokens should be represented in DTCG files - so I presume they are intended to be normative. Furthermore, those specs conflict with the current format draft (e.g. the format doc currently states that the $value of a color token MUST be a string with a hex value. My understanding is that we want the info in this doc to supersede that though)

I therefore suggest we distinguish between the spec stuff and the guidance stuff more clearly. A few ways we might do this:

• Move the color type and gradient chapters into the format spec, replacing/updating the corresponding chapters there as needed. Then the color report would only contain guidance and the intro could make that clear.
• OR, remove the existing color and gradient type chapters from the format spec and replace them with links to this doc. Then this doc becomes the definitive spec for those types - and also complements that with some helpful guidance. In that case, I'd argue that this doc's primary purpose would become being the spec for color tokens in the DTCG format. So maybe we ought to then move the token naming chapter to the end - perhaps even as an appendix (bear in mind that format spec is intentionally agnostic about how folks name and organise their tokens, so putting advice about that at the start of a "spec" document might feel a little odd to readers).

Personally, I have a slight preference for the first option, since it keeps all the spec stuff in one place. But, I'd be OK with the other approach too.

Either way, this will also set a nice precedent for the animation module and any others we may have in the future to follow.

[c1rrus]

Given that we're broadening the ways color values can be expressed in the DTCG format, this should probably be worded more generically:

Suggested change

	Base tokens are the lowest level tokens and typically consist of a name and [hexadecimal](https://www.w3.org/TR/css-color-4/#hex-notation) value pair.
	Base tokens are the lowest level tokens and typically consist of a name and color value pair.

[phun-ky]

If the naming convention for color tokens are in the same format as the others (most likely?), why don't we reference a global naming convention here?

[c1rrus]

That's my understanding too. So, both of the syntaxes below are permitted and are exactly equivalent:

{
  "my-color-token": {
    "$type": "color",
    "$value": "#111111"
  }
}

and

{
  "my-color-token": {
    "$type": "color",
    "$value": {
      "$hex": "#111111"
    }
  }
}

However, for this example, it might be better to use the first style since it'll be more familiar to folks used to the current spec draft (which only permits that syntax at the moment) and is more terse.

[c1rrus]

This is not permitted by the format (as it stands). There's no $darkValue format property defined for tokens and extraneous properties not defined in the spec are not allowed.

Right now, there isn't really a means of doing the "single file method" in a DTCG file. We need to reach some conclusion on #210 to have a means of doing that. (and once we do, we can always revisit this section and add a valid DTCG example then)

For now though, I think it would be best to remove this example completely for the time being. I wouldn't want folks to see this and mistakenly think $darkMode in DTCG files is something they can use.

We could still describe a "single file approach" in general terms and cite things like @dbanksdesign "Dark Mode with Style Dictionary" article or Figma's variables as examples of tools that can use this approach though

[c1rrus]

Perhaps make the list of permitted color spaces more explicit? Maybe something like...

- `name` (required): one of the following keys, identifying the color space that this color is in. Note: Other keys are not permitted to avoid clashes with future spec iterations that might add support for additional color spaces.
    - `rgb`: _Some blurb about the RGB color space_
    - `srgb`: _Some blurb about the sRGB color space_
    - `hsl`: _Some blurb about the HSL color space_
    - `lch`: _Some blurb about the LCH color space_

[c1rrus]

Would something like colorSpace or space be a better property name than name? That would be more explicit about its purpose.

Also, given that this is within a design token, might some folks confuse this with the name of the token?

[phun-ky]

I agree, since colorSpace is optional, it can have a more distinct nomenclature instead of name

[drwpow]

Sorry; this PR needs to be updated to reflect the current proposal. In an upcoming update you’ll see colorSpace is required, and MUST be a value matching a defined colorspace in CSS Color Module 4. We’ve kept it colorSpace from @c1rrus’ proposal for clarity.

[c1rrus]

Question: Do we need to specify what ranges those component values can have? For example, are they always in the range of [0 ... 1] and, if so, how should tools interpret values that fall outside that range - do they clamp them down to that range (similar to what we do for the position values in the format's gradient type), or should they be treated as errors and the whole color value (or even token?) is ignored?

Or, if the permitted range of values might vary depending on the color space, then we ought to list that out somewhere.

[phun-ky]

Just curious, Is it not clear enough from 0 - 1? My only concern is that designers (that I have worked with) says 70% transparency, but in CSS that is equal to 0.3 or 30%. Should that be commented on?

[drwpow]

Oh yes this definitely needs clarification! Because no, values won’t always be between 0-1 if we follow CSS Color Module 4. There are 2 reasons:

1. Degrees. As in the case of HSL, the range is 0°–360°. This could probably be normalized to 1 but I think most would agree that fails the goal of this spec being human writable since that’s nonstandard
2. Device-independent colorspaces. In the case of colorspaces like LAB/LCH and OKLAB/OKLCH, they describe many colors that are outside the range of any device existing today, and so there’s no “maximum.”

For the latter, CSS Color Module 4 still does define allowable ranges which are still far beyond what most devices can support; I believe they just put reasonable caps on values that decades of hardware improvements still wouldn’t catch up to (without overreaching and normalizing, which “sets it in stone;” this, conversely, can be expanded if ever needed). Here are some of the values:

• Lab: L [0 … 100], a [-125 … 125], b [-125 … 125]
• Lch: L [0 … 100], c [0 … 150], h [0 … 360]
• Oklab: L [0 … 1], a [-0.4 … 0.4], b [-0.4 … 0.4]
• Oklch: L [0 … 1], c [0 … 0.4], h [0 … 360]
• XYZ: 🤔 for some reason this is normalized [0 … 1] but not sure why

The general approach of “match CSS Color Module 4 as much as possible” has been discussed in meetings but I think it would be good to explicate this as much as possible. As far as I know, the color proposal wouldn’t deviate from Color Module 4 in any way. cc @resource11

[drwpow]

Also alpha in all cases is always normalized [0 … 1], and is optional (default 1 if omitted).

[phun-ky]

@drwpow yeah, if no color space is omitted, and no other color function is used, opacity/alpha channel (rgba) should always default to normalized 0-1

[c1rrus]

To align with the current spec draft and, as far as I know, how hex color values are interpreted in CSS and most design tools, should we say here that the sRGB color space is always implied for these fallback hex values?

[drwpow]

Agreed. Hex values have started to be used for Display P3 in design tools, but the intent is limited to sRGB.

[Shrinks99]

Suggested change

For the color value, the required fallback format to represent color through design tokens is a hex or hex8 value. A hex triplet is a 6-digit, 24 bit, hexadecimal number that represents Red, Green, and Blue values as `#RRGGBB`. An eight-character hex will include the alpha value in the last 2 characters. If no alpha value is specified, it is assumed the color if fully opaque.

For the color value, the required fallback format to represent color through design tokens is a hex or hex8 value. A hex triplet is a 6-character, 24 bit, hexadecimal number that represents Red, Green, and Blue values as `#RRGGBB`. An eight-character hex encoded value will include the alpha value in the last 2 characters. If no alpha value is specified, it is assumed the color if fully opaque. The sRGB colorspace MUST be used when interpreting fallback hex values.

[c1rrus]

Might it be worth using the string value syntax for this token, to show that that is something people can still do?

Suggested change

	"$value": {
	"$hex": "#00000080"
	}
	"$value": "#00000080"

Or adding a 3rd token that uses that syntax?

[c1rrus]

I suggest splitting this out into a separate PR for now.

As it stands, this has got quite a few deviations from how the gradient type is currently defined in the format:

• The format does not use $ prefixes for the value's inner properties and, as per the comments from @drwpow and myself on the updated color type, I think we should stick with that. (or, if we didn't, we'd need to change all the other composite types to be consistent)
• The format does not include a style property, though several folks have suggested something along those lines in Gradient type feedback #101. I think that's probably a worthwhile addition, but there are other interesting proprosals in that thread too, which I think we ought to consider holistically.
• The format does not have an alpha property on the stops and, given that the color values can have an alpha channel, it feels kinda redundant. Besides, what would be the expected behaviour if both have been specified but have conflicting values?

I presume the intent of this section is really just to show that the new, expanded color value syntax defined in the previous chapter can be used anywhere else that color values are permitted.

The value of a gradient stop is one case of that, but there are others too:

• the color sub-value of a shadow
• the color sub-value of a border

So, perhaps this section could be reworked into something that just states that the new object-style color values can be used throughout the spec and include an example of each of those things?