Are token types optional or required?

Example:

{
  colorTextPrimary: {
    value: '#000000',
    type: 'Color'
  }
}

Resolution: #63 (comment)

First of all, super excited to see the amazing team working on this project!!

I've been quietly following for a while, and was thinking of something perhaps might relate to this project.

My Question: How are teams currently taking the values of their design tokens and 'transferring' them into a computable format?

As an example: [Maybe in Sketch or similar]

Designer: "we've decided our brand is #123456, subdued text color is #222222, spacing scale is base 8 etc... Now let's get these values out of Sketch and into our color token management system...".

Currently the way we've done it is basically just manually gone through each one and copy-pasted the hex value into a JS object.

This has come up because I am currently working on a Sketch plugin that goes the other way around (eg. takes a JS object of my DS tokens and renders out layer styles with the colors / color names applied)... which works for generating / updating our core palette of our DS. BUT when I think of it, a JS object is probably not where the initial definition of a product's color styles would be defined (most probably by a designer with a visual tool).

I was considering making a "Design Token editor" app that basically is a visual tree structure (thinking out loud: one probably already exists) that lets you build up what basically is a JS object fitting the design token spec under the hood.... but it got me thinking that I'd like to know how others might envision it, or even what others have done in the past.

Considering the future, I'm sure many of these newer design tools will be integrated with whatever amazing design token spec you gang all come up with, and maybe you could one day export your color palette in Sketch directly to match the spec, but for now maybe we something like a plugin could work.

Keen to hear thoughts!

✌️🎨

Cheers
Lucas
https://twitter.com/lucasarundell

Should token names be case sensitive?

{
  colorTextPrimary: {
    value: '#000000'
  },
  ColorTextprimary: {
    value: '#000000'
  }
}

Should the above be two valid token keys (case-sensitive) or a duplicate entry (case-insensitive)?

Dear group members, today we're excited to start our first call for editors 🎉

One of the DTCG’s main goals is to produce a specification.

The specification is broken into multiple modules:

• Format (the language and its grammar)
• Colors
• Spacing
• Easing
• (more to come!)

We need 2 to 3 editors per module, ideally representing various interests: design tool makers, design system creators and maintainers, users of design systems, as well as design token tool makers.

Read the full call for editors (in Google Docs) to learn more and apply to become an editor.

Looking forward to hearing from y'all!

@jina & @kaelig

Hi,

Our Design and Development teams are currently trying to implement a new Design system based on the specified document as of 2021-12-13 (with the current proposal of limiting composite types (#86) in mind). The whole standard is awesome, and we'd like to thank everyone involved for all the great work done!

Problem definition

We're currently struggling to create a correct colors.tokens.json with colors that use references parts of other colors, e.g. the RGB value or the opacity.
Our Design system consists of multiple levels of color definitions which reference to each other to provide consistency, but also long-term flexibility.

For example:

{
  "base": {
    "red": {
      "type": "color",
      "value": "#ff0000"
    },
    "green": {
      "type": "color",
      "value": "#00ff00"
    },
    "blue": {
      "type": "color",
      "value": "#0000ff"
    },
    "yellow": {
      "type": "color",
      "value": "#ffff00"
    },
    "background": {
      "type": "color",
      "value": "#ffffff"
    },
    "foreground": {
      "type": "color",
      "value": "#000000"
    }
  },
  // ...
}

Now, in order to define a component which is based on these variables, would use references to these values:

{
  // ...
  "components": {
    "alert": {
      "error": {
        "background": {
          "type": "color",
          "value": "{base.red}"
        },
        "foreground": {
          "type": "color",
          "value": "{base.foreground}"
        }
      },
      // ...
    },
  },
  // ...
}

But in our Design system, we'd like to reference the base color and modify it (e.g. add adding opacity to the value):

{
  // ...
    "alert": {
      "modify": {
        "background": {
          "opacity": {
            "value": 0.1
          }
        },
        "border": {
          "opacity": {
            "value": 0.3
          },
        }
      },
      "error": {
        "background": {
          "type": "color",
          // Invalid value
          "value": "rgba({base.red}, {components.alert.modify.background.opacity})"
        },
        "border": {
          "type": "border",
          "value": {
            // Invalid value
            "color": "rgba({base.red}, {components.alert.modify.border.opacity})",
            "width": "{border.base.m}",
            "style": "{border.base.style}"
          },
        }
      }
    }
  // ...
}

Unfortunately, this would result in an invalid tokens file: Currently only colors in the formats #RRGGBB and #RRGGBBAA are allowed at a value field when it has been defined as type color.

A potential workaround would be to use the calculated #RGBA value and add the reference to the extensions field.

For us, keeping the references in a standardised way which will be supported throughout code and design is important. A custom composite type would cover this use case as well, but this part will not be part of the specification MVP.

Concerns

We're concerned that not covering this use-case early would cause fragmentation in the ecosystem over time. If there's no common style for modifying the alpha value (or maybe even hue, saturation or lightness as example), there might be plugins and converters requiring different formats, which make it hard to create an easy-to-write file that works everywhere.

Example: Fictional workflow with Figma, Style Dictionary and Storybook

(Just to clarify, this workflow is fictional - all formats and decisions listed here are just exemplary)

The designers are creating their designs with Figma tokens, which might in a future version for example use their own extension com.figma.tokens:

{
  "background": {
    "type": "color",
    "value": "{color.base.red}",
    "extensions": {
      "com.figma.tokens": {
        // Note the opacity written as percentage (10% = "10") in this example
        "opacity": 10
      }
    }
  }
}

Another tool might use it's own extension or format to store the modification. For example, the documentation of style-dictionary's transitive transforms lists the following format in the examples (to provide compability with chroma-js):

{
  "background": {
    "type": "color",
    "value": "{color.base.red}",
    "modify": [{
      "type": "alpha",
      "amount": 0.1
    }]
  }
}

Generating the documentation from the tokens file in a tool like Storybook might get hard at this point, because there could be multiple sources of truth for opacities. If there was for example a generic <DesignTokens> renderer, how could it know how to correctly display the defined color?

As a workaround, it would always be possible to write converters between these tools, formats, and extensions. Having the format for these standardised would greatly benefit interoperability for users.

Benefits of referenced opacity values in tokens files

Our main motivation for referencing colors or modifications is to retain the references in CSS variables. We'd like to use the design tokens to create CSS variables directly from the token files, for example with this result:

/* base.css */
:root {
  --color-base-red: #f00;
  --color-base-green: #0f0;
  --color-base-blue: #00f;
  --color-base-yellow: #ff0;
  --color-base-background: #fff;
  --color-base-foreground: #000;

  /* Additional RGB values could be added by the CSS generator to support usage in rgba() */
  --color-base-red-rgb: 255, 0, 0;
  /* ... */

  --color-alert-background-opacity: 0.1;
  --color-alert-border-opacity: 0.3;
  --color-alert-error-background:
    rgba(var(--color-base-red-rgb), var(--color-alert-background-opacity));
  --color-alert-error-border:
    var(--border-base-m) var(--border-base-style) rgba(var(--color-base-red-rgb), var(--color-alert-border-opacity));
}

/* components/alert.css */
.alert-component--error {
  background: var(--color-alert-error-background);
  border: var(--color-alert-error-border);
}

We would benefit from using CSS variables instead of using the direct values once we enable other themes (e.g. a "dark" or "high contrast" version). It wouldn't be required to re-generate the whole file, but just to replace the some of the base variables in e.g. another dark.tokens.json file:

{
  "base": {
    "red": {
      "type": "color",
      "value": "#200000"
    },
    "green": {
      "type": "color",
      "value": "#002000"
    }
    // ...
  },
  "components": {
    "alert": {
      "modify": {
        "background": {
          "opacity": {
            "value": 0.2
          }
        },
        "border": {
          "opacity": {
            "value": 0.4
          }
        }
      }
    }
  }
}

Since the references in the second file would still be intact, it could generate a second file for (prefers-color-scheme: dark), which could only overwrite the new values and still work:

/* dark.css */
:root {
  --color-base-red: #200000;
  --color-base-green: #002000;

  --color-alert-background-opacity: 0.2;
  --color-alert-border-opacity: 0.4;
}

Proposal: Additional pre-defined composite type

We would like to propose adding basic color modifications to the MVP. This could help avoiding the need for parsing different color syntaxes (#79) and prepare for a future implementation of computed token values (#81).

We have no preferred syntax for this, but assume that an additional pre-defined composite type for "modified colors" would fit in best with the current state of the specification. This could also enable other composite types to use color or computed-color as values.

One potential format could be for example:

{
  "background": {
    "type": "modified-color",
    "value": {
      "color": "{color.base.red}",
      "modify": {
        "opacity": 0.1,
      }
    }
  }
}

This might eventually also enable further modifications to the color, like e.g.:

• Hue
• Saturation
• Lightness
• Red
• Green
• Blue
• Tint
• Shade

Are there any reserved words that should not be used in token names?

Examples: 'default', 'int'

{
  default: {
    value: '#000000'
  },
  int: {
    value: 50
  }
}

Will these (and others) cause problems when converted to various languages and platforms?

Resolution: #61 (comment)

Hi folks! There is one thing we’d love for you to participate in to get your perspective (if you have the time this week):

As a designer, using the design tool of your choice, what would your ideal workflow be to define/deliver tokens? What do you wish your tool had in place to do this? What would make your life easier?

Think about color and type as the main use cases.

The deliverable is open to what works for you and how much time you can give — doesn’t have to be a formal slide presentation (unless you want it to be). Can just be wireframe(s), or even just draw on a napkin and take a photo. Whatever you want to do to share your ideas.

Please share here in the comments by end of day Thursday so the Format team can review and discuss in the next Friday format meeting.

The color type is currently very specific, allowing only 8-bit per channel RGB(A) values.

I see two problems with this approach:

1. Perfectly understandable and valid color definitions like hsla(300, 100%, 50%, 0.5) are not allowed.
2. It is not future proof. We might eventually go past the sRGB color space when HDR displays become the new normal. In the future there could be color definitions with 16 bits per channel. Those could definitely make sense for gradients or in combination with filter effects.

Allowing all values that CSS understands would make it easier to build the file by hand but it would be more work for the design tools since they need a parser for the color values.

HDR for the web is already being considered and a limit to 8 bits per channel might be a problem in the future.

Visual Studio Code supports a top-level $schema property which provides their JSON Language Server with automatic completions, hovers, etc. While it is not part of the JSON Schema specification, it is a feature that I see being used with increasing frequency. See schemastore.org for examples of tools which have public schemas.

IMO calling this property out in the specification would be wise, even just as something that tools should accept but ignore. I've definitely encountered tools that have trouble validating or parsing a JSON file when $schema is used and it can be a pain.

It is useful to have more semantic information about a token and how it is to be used, especially when displaying previews of tokens or limiting which tokens are available to use.

However, some of the current token types are missing this semantic information. A good example of this is the dimension type. It is being used for fontSize, letterSpacing, borderRadius, width, padding, margin, etc.

Without knowing how a token is intended to be used, we are unable to display the correct token preview or limit where it is available. e.g. all dimension tokens would show up in a picker for a borderRadius property.

I can see a few options for adding this information to a token:

1. Add more semantic types — I can only think of a few which would cover most needs. These could be added as aliases. e.g. fontSize type as an alias for dimension.
2. Add an additional optional property on tokens specifically for this. e.g. semanticType or usedFor, but this feels overly complex
3. Add the semantic type in the token extensions. This is what we are doing at the moment, but removes some of the interoperability between different tools.

Is this something that has been considered? What is the suggested approach to handle this from a tooling perspective?

As all platforms are just about to support their own versions of dark mode, theming is becoming an important part of an efficient design workflow.

Let's talk about how design tokens should handle theming.

Here's a rough draft that essentially mimics how the CSS cascade works:

// Defaults
[
  { name: 'tokenA', value: 'foo' },
  { name: 'tokenB', value: 'bar' },
]

// Overrides for dark mode, loaded subsequently
[
  { name: 'tokenA', value: 'baz' },
]

// Should resolve to:
[
  { name: 'tokenA', value: 'baz' },
  { name: 'tokenB', value: 'bar' },
]

In a design tool, a designer could load and toggle any number of override files in order to get to the target platform (such as: Defaults < Android < Dark mode).

Hi everyone,

Summary

1. We found editors for most modules: format, colors, animation, spacing (we need more folks, please reach out if you're interested), and a few people also joined the team for support and to work on the education track (website, documentation, etc.)
2. We had a kick-off meeting (slide deck) on June 25th.
3. Research groups gathered resources (see below):
   1. The state of design tokens
   2. Syntax and language
   3. Stakeholder mapping
   4. Future of tokens
4. Our current priority: write drafts for the specification, so we can involve design tool makers in the discussion

Next steps

1. Align on the "why", principles, and scope
2. First editors’ draft for the format module
3. Drafts for other modules
4. Second editors’s draft for the format module
5. Review by implementers (makers of popular design tools)
6. Rince and repeat and see the technical recommendation mature

The team is also working on collecting the findings of these research groups, and will publish some of them on the website (work in progress).

Editors

Jina and I reviewed more than 25 applications for editorship, met ~20 out of them, and we now have a team of dedicated editors, as well as some folks who'll be working on the website, community, and educational aspects. The questions we asked them were around experience, availability, and what they expected to get out of this experience.

The practitioners working on the Design Tokens W3C Community Group’s core team are:

• Adam Sedwick
• Donna Vitan (editor)
• James Nash (editor)
• Adekunle Oduye (editor)
• Ayesha Mazumdar (editor)
• Caleb Williams
• Danny Banks (editor)
• Garth Braithwaite
• Johan Stromqvist (editor)
• Kathleen McMahon (editor)
• Kevin Powell (editor)
• Louis Chenais (editor)
• Matt Felten (editor)
• Nathan Curtis
• Val Head (editor)
• Zack Brown (editor)

Kick-off meeting

On Thursday, June 25, 2020, @jina and myself led a kick-off meeting (slide deck) with the core team of the Design Tokens W3C Community Group.

We gave the team some historical context, and then provided prompts to the team who was instructed to work in 4 separate research groups.

Research groups

Jina and I assigned people into 4 research groups, with these instructions:

Each group (unrelated with the modules) will research specific topics over the next 2 weeks and will have 15 minutes to present their findings during our next meeting.
Go as deep as you want, the research will help make better spec decisions, will be published, and could lead to blog posts later on (edited by the folks who will work on the education track).

We gave each group prompts to help them focus their research in a direction we were expecting, with some nuance:

These prompts are suggested to help you find inspiration. They can be rephrased or skipped if you find areas that would require more attention. Go as deep as you’d like into these topics. Make sure to mention your sources and recognize authors/articles you’re quoting.

The state of design tokens

Danny, Kathleen, Louis, Nathan.

• What are examples of teams currently using tokens, and what trends seem to emerge (tools, languages…)?
• Related: is design or development the starting point, as in: what do teams consider as their source(s) of truth?
• How do design tools and plugins implement tokens today?
• What community traction do design token tools have (DSM, Style Dictionary, Theo, Diez, theme-ui, Lona…)?
• How is accessibility considered by teams using tokens?

Syntax and language

Donna, James, Kevin, Zack

• What are the pros and cons of creating a new format/syntax?
• What are the pros and cons of relying on an existing format/syntax?
• What are relevant examples of specifications that created a new format/syntax?
• What are relevant examples of specifications that relied upon or augmented an existing format/syntax?

Stakeholder mapping

Ayesha, Garth, Matt

• Who at each implementer company should we proactively talk to and put in the loop? (Adobe, Figma, Framer, Sketch…)
• Consider product managers and decision makers, as well as influencers/advocates within these companies.

Future of tokens

Adam, Caleb, Val

• What design token tools are coming up?
• What doors will interoperability open in making the design and development process better?
• Optional: How could no-code tools such as Webflow, Shopify, Squarespace… make use of design tokens (webhooks, APIs, …)?
• Optional: Beyond digital product design: Google Docs themes, experiential marketing, IoT lighting…
• Optional: What might we see in the far future? (GUIs, AI/ML-driven generative design, design linting, accessibility linting…)

Currently we don’t publish contact details for companies / individuals in the README. Is this intentional because we assume all communications will happen on GitHub?

And if it isn’t, do we think it would be a Good Thing™ to have public contact details there?

I've been building Token CSS, a CSS tool based on the current draft spec.

I really like the groups can define a type which will be applied to all child tokens. I was curious if extensions could also be applied to groups? I'm hoping to use extensions to define a scale (semantic-type or used-for values) on a per-group basis.

I'm not sure there's anything blocking this usage in the current specification but clarity would be nice! I don't think the spec needs to weigh in on how inheritance/cascading of extensions could work—that seems like an implementation detail left up to each tool.

Edit: I had not seen that #89 moves group-level properties under the metadata name, but I'm a huge fan of that move! I guess my question then becomes "Is extensions allowed inside of group.metadata?"

So far, design tokens are the best way to soften the communication between design and development. For the first time, as designers, we are not dependent on tools to hand-off our work. We are developing an agnostic language that empowers everyone to build and manage design components collaboratively. That's great.

But, as facilitators in the communication across design and development, we still miss some major definitions that are beyond the design tokens per se. Some of those definitions have a consensus in isolated teams, but not in a broader overview.

Being in a team responsible for ensuring design consistency across hundreds of applications, I can easily give a few examples:

Variation
What exactly is a component variation? If it is when a component changes, can we consider a hover effect as a variation? Are different themes in the same component a variation? Are variations just an additional component look?

Behavior
What exactly is a component behavior? Is it how behaves in an application or how it reacts to different interactions?

Theming
Is theming a definition for components or for the context where they are? If theming is for components, can I use them in different themes on the same screen? What sounds better: a blue button or a button inserted in a blue themed application?

We all know the answers - some of us probably have sound arguments on it - but we don't need to answer it now.

Since our goal is to harmonize the discussion, the real question is: why not have a glossary to support conversations and empower the beginners?

We are from different cultures, contexts, and areas. A glossary is a simple way to avoid misunderstandings and help all of us to communicate in the same way - especially in the long term, separating context from definitions. It can be a support for discussions, which is precisely the purpose of this group.

Hi, I'm curious as to the differences between this WG and the goals of UDT (whom is referenced as inspiration)?

The reason I ask is if two parties are moving in slightly different directions it could begin n+1 design token specs.

Whatever the outcome - a universal standard of design token which is software/platform agnostic is absolutely what we should be moving towards.

Should our spec add an optional $private property, along similar lines to the one proposed for StyleDictionary by @silversonicaxel? It would instruct tools not to display or export a token by default (though tools may provide an option for users to override that and still see / export private tokens if they wish). Its value is a boolean. true makes the token private, false makes it (explicitly) public. If there is no $private property, the token is public.

As per the thread on the StyleDictionary issue, I think this could be convenient way for teams to exclude (or flag) tokens that they don't consider part of their public API from code, design tools, styelguides, etc.

For example, the following DTCG token file:

{
  "red": {
    "$type": "color",
    "$value": "#ff0000"
  },
  "green": {
    "$type": "color",
    "$value": "#00ff00",
    "$private": true
  },
  "blue": {
    "$type": "color",
    "$value": "#0000ff",
    "$private": false
  }
}

...might cause a SASS export tool to output code like this:

$red: #ff0000;
$blue: #0000ff;

(Note how the "green" token is omitted because it is private)

Furthermore, if a token is an alias to a private token, then the dereferenced value must be output. E.g.:

{
  "red": {
    "$type": "color",
    "$value": "#ff0000"
  },
  "blue": {
    "$type": "color",
    "$value": "#0000ff",
    "$private": true
  },

  "danger-color": {
    "$value": "{red}"
  },
  "link-color": {
    "$value": "{blue}"
  }
}

...might be exported to SASS like so:

$red: #ff0000;
$danger-color: $red;
$link-color: #0000ff;

(Note how $link-color has the dereferenced value, because the "blue" token is private)

Finally, I'd suggest that this property should be inheritable from groups, just like $type is. This would make it easier to make all tokens within a group private. For example:

{
  "color": {
    "$type": "color",
    "$private": true,

    "black": {
      "$value": "#000000"
    },
    "white": {
      "$value": "#ffffff"
    }
  }
}

is equivalent to:

{
  "color": {
    "$type": "color",

    "black": {
      "$value": "#000000",
      "$private": true
    },
    "white": {
      "$value": "#ffffff",
      "$private": true
    }
  }
}

What do you think?

have you seen this? https://udt.design what do you think about?

This may be a bit much for the MVP spec, but should the spec allow for computed values?

Much of tokens is around defining a system, and much of a system is about relative choices. It'd be nice to define the relative nature of those choices when defining the values. This could apply to colors via things like "tint" and in numbers via basic arithmetic.

It looks like this concept is already underway in the dimension's suggestion to use rem. Isn't that really setting the value relative to an arbitrary master unit that only has value in the Web?

Hello,

I was wondering if an optional "tags" property containing an array of strings could be added to the tokens?
This way we would be able to filter or group certain tokens using these tags in our tools ie. Figma Tokens, instead of adding metadata to our naming. It allows more flexibility for future updates and changes.

{
  "color": {
    "brand": {
      "primary": {
        "400": {
          "value": "#7cf88b",
          "type": "color",
          "tags": ["brand", "global", "…"]
        }
      }
    }
  }
}

What do you think?

Ward

(the content below was also sent as an email to everyone who showed interest in the design tokens community group, and cross-posted on the W3C community page)

Hi,

You're receiving this message because you've shown an interest in the Design Tokens W3C Community Group.
Its goal is to provide standards upon which products and design tools can rely for sharing stylistic pieces of a design system at scale.

To make substantive contributions to specifications, you must either join the Design Tokens W3C Community Group or make a non-member patent licensing commitment.

[Action required 1]
Join the community group (it's free, and doesn't require a W3C membership).
Instructions: https://www.w3.org/community/design-tokens/2019/07/31/call-for-participation-in-design-tokens-community-group/

[Action required 2]
Watch the repository to be notified of all conversations:

1. Go to https://github.com/design-tokens/community-group
2. In the top right-hand corner (on large screens), click "Watch"
3. Select the "Watching" option

As per the group’s charter, contributions happen in GitHub and can be made in the form of pull requests, issues, or comments:

Community Group participants agree to make all contributions in the GitHub repo the group is using for the particular document. This may be in the form of a pull request (preferred), by raising an issue, or by adding a comment to an existing issue.

All documents in the repository are licensed by contributors under the W3C Document License.

For more information, read the full charter.

Please also read the code of conduct. It will be enforced with a zero-tolerance policy to ensure the community group is an open and welcoming environment.

Next steps (choosing a chair and specification editors, workshops, meet-and-greet) will be communicated soon on the GitHub repository.

If you have any questions about this process and the community group, please ask it publicly in the dedicated GitHub issue or get in touch with me directly: [email protected].

Thank you!

Kaelig Deloumeau-Prigent

Is the gradient composite type fit for purpose? Does it need to also specify the type of gradient (.e.g linear, radial, concial, etc.)?

Please share your feedback, thoughts and ideas in this issue.

Comment: #52 (review)

A naive approach like the one below may be appropriate for the first stage of the specification, but this may be more complicated than it seems due to platform/OS/browser restrictions.

Please share feedback, ideas and concerns in the issue below so we can assess the best course of action.

Font name

Represents a font name or an array of font names (ordered from most to least preferred). The type property must be set to the string “font”. The value must either be a string value containing a single font name or an array of strings, each being a single font name. For example:

{
  "Primary font": {
    "value": "Comic Sans MS",
    "type": "font"
  },
  "Body font": {
    "value": ["Helvetica", "Arial"],
    "type": "font"
  }
}

The current design tokens spec is in JSON, and that’s great! Forgive me if this has been talked about already, but I’d like to propose YAML as an alternate format for design tokens specification.

One precedent for this is the OpenAPI specification, arguably the most popular way to document APIs. It is great prior art on a time-tested specification format, and one of the things that’s led to its adoption (I think) is the ability to use either schema.json or schema.yaml formats. Adopters of OpenAPI can choose JSON or YAML—whichever they prefer—because perhaps one fits better with their tooling and in the end both produce identical results.

There has already been a comparison of JSON vs YAML discussed in #1. But that was asking JSON OR YAML, and I’d like to ask if JSON AND YAML makes sense (with JSON remaining the default/preferred format as already decided). Borrowing some points from that comment, and expanding on it, here would be some of the advantages:

• Code generation with YAML is just as easy as JSON (in some circles YAML is preferred)
• YAML tooling is just as ubiquitous and readily-available as JSON tooling (often many libraries handle both)
• YAML is friendlier to read and write with fewer extraneous characters
• YAML allows comments (JSON doesn’t)
• (opinion) More teams will adopt the design tokens spec if they can choose whichever format better fits their current tooling

Lastly, to the point about “JSON being better for APIs,” I would disagree, also citing OpenAPI returning YAML as a good example. Whitespace weight becomes negligible when gzipped which any good API response will do. Further, few—if any—systems should rely on design tokens at runtime (building your tokens into code ahead-of-time will always be more reliable and more performant), so API response time shouldn’t be a deciding factor in format; the user writing experience should (and in my opinion, writing YAML is very user-friendly).

Again, forgive me if there was a discussion I missed, but I wanted to get peoples’ thoughts on this question I’ve had. Thanks so much to the people organizing this project together, and I’m already excited by the current direction and amount of thought that’s been put into it!

It might be very platform specific, but i guess, that VDS (Value Definition Syntax) form CSS fits very well for description the type of the tokens.

For example, if you want to define a color-token, you can write:

  "Majestic magenta": {
    "value": "#ff00ff",
    "type": "<color>"
  },

Or, if you want to define a bezier function, you can use a <cubic-bezier-easing-function> from css-specification.

And that way would work well for the css at-rule @property for define a custom properties (and type os custom properties).

CSS is created for description of interface appearance, like a design tokens too. I guess, that it will be convenient)

P.S. sorry for my not perfect english)

If so, which composites should be included initially?

• border
• transition
• shadow
• gradient
• text style
• color pair

Other questions

• Would composites allow for better integration with design tools?
• How would user-defined composites be rendered within design tools?

Resolution: #54 (comment)

JSON supports string, number, array and object as data types. Which of these do we want to support for token values.

String:

{
  colorTextPrimary: {
    value: '#000000'
  }
}

Number:

{
  durationDefault: {
    value: 10
  }
}

Array:

{
  breakpoints: {
    value: ['320', '640', 1080]
  }
}  

Object:

{
  textHeadingLevel1: {
    value: {
      fontSize: 32
      fontWeight: 700
      lineHeight: 1.5
    }
  }
}

I suspect we'll need to support all four data types.

currently reaching out to various design software vendors to get a representative from each one on the community group.

I'm opening this issue to look into the status of reaching out to @InVisionApp. I'm happy to help with this, whether it involves connecting to the appropriate folks or lending a hand where needed in the initiative 🙌🏽 Love that y'all are coming together to create a tech-agnostic architecture for scaling design 💛

fwiw, I'm leaning on experience from other open source projects (@nodejs), education initiatives (@nodeschool), and foundations (@openjs-foundation).

Is the border composite type fit for purpose? Does it need more sub-values to account for features like outset, border images, multiple borders, etc. that some platforms an design tools have?

Please share your feedback, thoughts and ideas in this issue.

Character restrictions in token names

Should the specification restrict the name property to a specific Unicode range or make certain characters invalid at the start/middle/end of a name (such as white space, line breaks…)? If so, what characters and why? Should emoji be allowed in token names?

Examples:

{
  '      space-at-the-beginning': {
    value: 50\
  },
  {
    'color⚽️': {
      value: '#445566'
  }
}

Resolution: #60 (comment)

Is the stroke style composite type fit for purpose? Does it need more sub-values (e.g. equivalents to SVG's stroke-linejoin, stroke-miterlimit and stroke-dashoffset attributes)?

Please share your feedback, thoughts and ideas in this issue.

{
  "token name": {
    "value": "token value"
  }
}

The structure in the example above is a JSON object, an unordered set of name/value pairs.

• Objects can't contain members with duplicate keys
• Ordering of object members may not be preserved (as per RFC 7159), meaning token retrieval may or may not result in the same ordering as the input

Please raise concerns if these limitations create problems for implementers.

In conversations about groups and tokens sharing a name (#97), I had a few ideas about group format.

The current spec has us write the tokens in a group as properties of that group. This affords a high level of flexibility in writing and reading tokens, but results in a lot of extra work on the parsing side¹. And that's a totally fine tradeoff to make, but I thought it might be worth exploring ways to get some more concrete definition/formatting in place to help parsers, without losing human read/write-friendliness.

So, an example group according to the current spec (not using prefixes currently being discussed in #61):

{
  "colors": {
    "red": {
      "value" : "#ff0000"
    }, {
    "green": {
      "value": "#00ff00"
    }
  }
}

My suggestion (but by no means the only possibility) is that groups, like tokens, should have a "value" property.

{
  "colors": {
    "value": {
      "red": {
        "value" : "#ff0000"
      }, {
      "green": {
        "value": "#00ff00"
      }
    }
  }
}

I don't write a parser/translator (hopefully the folks who do can weigh in), but I imagine that being able to expect every object to have a "value" property, regardless of it being a group or token, allows for some performance gains (and code maintenance gains).

Additionally, having all the group's tokens in a value property make it faster/easier to access them.

Finally, and this is just a personal aesthetic preference, but it makes me happy to have a very concise and consistent grammar associated with the spec; every object has a "value" property!

What do y'all think?

Several issues have raised the need for adding token properties at group and file levels. I'm creating this issue to consolidate discussions about this topic.

For example Types:

{
  "colorTextPrimary": {
    "value": "#000000",
    "type": "Color"  // Tedious
  },
  "colorTextSecondary": {
    "value": "#333333",
    "type": "Color" // Tedious
  },
  ...
}


///  VS  ///
{
  "color": {
    "type": "Color", // Define once for the grouping
    "textPrimary": {
      "value": "#000000",
    },
    "textSecondary": {
      "value": "#333333",
    },
  ...
  }
}

Or descriptions for documentation about an entire group:

{
  "colorText": {
    "type": "Color",
    "description": "Our palette of colors for text only.",
    "primary": {
      "value": "#000000",
      "description": "Use as the default text color",
    },
    "secondary": {
      "value": "#333333",
      "description": "Use for text that is not as important."
    },
  ...
  }
}

Is the shadow composite type fit for purpose? Does it need to support multiple shadows, as some tools and platforms do?

Please share your feedback, thoughts and ideas in this issue.

See comments:

#62 (comment)

#62 (comment)

#62 (comment)

Resolution: #84 (comment)

To ensure discussions in the DTCG lead to open-source / open-standards, and intellectual property can’t be derived out of it, I am looking into affiliating the DTWG to an existing standards body or foundation that will be able to issue a license, as well as provide some structure / legitimacy to this working group.

The W3C came up as a good place to create a community group, so I’ll be investigating this first.

I’m also in touch with experts who’ve been working on open standards for the past few decades, see if they have other suggestions.

I’ll be updating this post with the latest news over the next few weeks.

Please let me know in the comments below if you’re aware of foundations/consortiums that could host the DTCG.

See @kaelig's notes on #64

Is the typography composite type fit for purpose? Should the lineHeight sub-value use a number value, dimension or a new line-height type?

Please share your feedback, thoughts and ideas in this issue.

Adhere to and credit RFC 2119 Key words for use in RFCs to Indicate Requirement Levels [KEYWORDS] (e.g., "MUST", "MUST NOT", "REQUIRED").

When these keywords are used in the RFC sense, make them UPPERCASE.

The author may explain why if these keywords are not used in the RFC sense.

Where they are not required for interoperation or to limit behavior which has potential for causing harm these keywords must not be used to try to impose a particular method on implementors where the method is not required for interoperability.

Source: https://www.w3.org/Guide/manual-of-style/#RFC

Example of fix needed

For example, in the Description section:

The description property must MUST be a plain JSON string, for example:

Exceptions

This doesn't impact notes and issues (as they are informative, not normative).

For example, this usage of "should" is acceptable 👍🏻

• camelCase consistency on all spec properties, values and sub-value names. Example: "cubic-bezier" should be "cubicBezier"
• Add clarification on group property inheritance ($type is inherited, $description is not)
• Round of review from all editors prior to publishing
• Update all format properties with a $ prefix. For example type becomes $type

Are token descriptions optional or required?

{
  colorTextPrimary: {
    value: '#000000',
    description: 'The text color most commonly used in the design system.'
  }
}

Resolution: #62 (comment)

let's favor strong element over all caps for emphasis.

Originally posted by @jina in #52 (comment)

The current draft of the spec allows colors to be specified as #112233 or #112233aa. That would mean that it's impossible to specify a color using the system colors used in high contrast modes. But, it's essential that a CSS file or XAML resources file (or whatever) produced by processing the token file be able to reference those colors, so a user who needs the background of their apps and web pages to be navy blue for readability can achieve that.

I propose that the 15 values defined in the system colors section of CSS Color Module Level 4 be added: "ActiveText", "ButtonBorder", and so on.

Tools could leave those values as-is when exporting to CSS, map them to the equivalent platform-specific value for other platforms (for example, "Highlight" in CSS is "SystemColorHighlightColor" in WinUI), or interpret them as aliases to hard-coded values (say, #00ffff) in a UI design tool such as Figma where mapping them to a system color might not make sense.

Without this, organizations that support high contrast accessibility modes would have to use hard-coded colors for those items along with additional data in the extensions node, and then have tools that know what to do with that extension data.

Is the transition composite type fit for purpose? Are these transitions parameters by themselves useful considering that they don't let you specify what aspect of a UI is being transitioned and what the start and end states are?

Please share your feedback, thoughts and ideas in this issue.

Hey,

I think it would be very important for the standardisation process to define what we within the community group would define as a design token. This has influence on the specs for the format #1 and possibly other specs as well.

It will potentially also influence how tools would export and implement design tokens. I for example, am thinking about this because I am work working on a figma plugin for design tokens.

It may seem clear at first, but I tripped about the following aspects and there are probably more.

Single value entities

We can probably agree that any single value design property can be a design token.
Examples: (using css as an easy to show example)

--color-primary: #40FFBA;
--color-spacer: 16px;
--typescale-xxs: .5rem;

Multi-Value entities

There are properties like shadows or gradients that have more than one value.
The question is if the combined property is a design token or if only the indivisible aspects are design tokens:

Examples combined:

--gradient-success: linear-gradient(90deg, rgba(32,223,26,1) 0%, rgba(95,240,12,1) 54%, rgba(221,255,0,1) 100%);

Examples separated:

--gradient-success-angle: 90deg;
--gradient-success-stop-1-color: rgba(32,223,26,1);
--gradient-success-stop-1-position: 0%;
--gradient-success-stop-2-color: rgba(95,240,12,1);
--gradient-success-stop-2-position: 54%;
--gradient-success-stop-3-color: rgba(221,255,0,1);
--gradient-success-stop-3-position: 100%;

When working as a designer one would normally see the entire gradient or the shadow / elevation as a key aspect. E.g. for this card I used elevation-small. I don't know if this may be different for developers.

Multi-property entities (e.g. styles)

When working for example with text-styles there are different properties like font-size and font-family that make up a style. I would assume only the individual properties to be design tokens and the combination to be styles. Is this something we can agree on?

Examples design tokens

--font-family-sans: Roboto;
--font-size-large: 54px;
--font-style-italic: italic;
--line-height-small: 120%;

Examples style (?)

--display-headline-font-family: var(--font-family-sans);
--display-headline-font-size: var(--font-size-large);
--display-headline-line-height: var(--line-height-small);

A question that's come up various discussions and for which the current spec draft doesn't really have an answer is this: How can you have design tokens that share the same name as a group?

For example, imagine you wanted to author a token file that could be exported to SASS like this:

$color-accent: #dd0000;
$color-accent-light: #ff2222;
$color-accent-dark: #aa0000;

...and you wanted to use groups to organise your token file. You could create a color group, with an accent group inside it and put your light and dark tokens in there. But then, where does the token that gets exported as $color-accent go?

{
  "color": {
    "accent": {
      "light": {
        "type": "color",
        "value": "#ff2222"
      },
      "dark": {
        "type": "color",
        "value": "#aa0000"
      }

      // Does the token go here, inside the "accent" group? If so, what is it called?
    }

    // Or does the "accent" token go here, but then how do we prevent the
    // name clash with the "accent" group?
  }
}

This issue came up at the last format editors' meeting and we feel like this is something our format should support in some way. Also, debating this issue may generate some ideas or highlight considerations that could be useful for the "reserved words" discussion over in issue #61.

We'd love to hear your thoughts and ideas on this!

Principles

• For core properties (name, value, description…), a design token file must be both human-editable and human-readable
• The format is simple, extensible, and as unopinionated as possible
• Vendors (design system tools, design tools…) can store information for their own usage, both globally and for each token
• The format translates well to existing design tools, in order to facilitate adoption

v1 priorities

1. Agreement and adoption by several design tools
2. Define core use-cases

Inspiration

• https://github.com/system-ui/theme-specification
• https://github.com/salesforce-ux/theo/blob/d9637c3f90636900e6cb990f31173c0f84d41e3a/README.md#spec
• https://github.com/airbnb/Lona/blob/7dd7986357a4aa4d24ba38cf944c1a992ea1d04d/docs/file-formats/colors.md
• https://amzn.github.io/style-dictionary/#/properties
• https://github.com/universal-design-tokens/udt/blob/master/packages/spec/schemas/dev/udt-schema.json

Proposal

At the moment, this proposal doesn't advocate for a particular file format (JSON, TypeScript…), it merely discusses what the shape of it should look like.

interface TokenList {
  // Where tokens are stored (in an array)
  tokens: Token[];
  // is this useful? should it be optional or not?
  version?: string;

  // Optional metadata
  data?: Data;

  // What other global properties are needed? (type, category, group…)
}

interface Token {
  name: string;
  value: any;
  description?: string;
  data?: Data;
  // What other properties are needed? (type, category, group…)
}

interface Data {
  // Vendor-prefixed data
  // for example: `data: { vendor: { "@sketch": {} } }`
  vendor?: object;

  // Any number of additional properties can live here,
  // for example, for storing additional information related to the token
}

Example

{
  tokens: [
    {
      name: 'Foo',
      value: 'Bar'
    },
    {
      name: 'I am a token',
      value: 'This is a value',
      description: 'A nice description.',
      data: {
        myOwnFlag: true,
        oneMoreThing: 'yay'
        vendor: {
          '@sketch': {
            // ...
          },
          '@figma': {
            // ...
          }
        }
      }
    }
  ],
  data: {
    vendor: {
      '@sketch': {
        // ...
      },
      '@figma': {
        // ...
      }
    }
  }
}

Hey ya'lls - working on some of the interop capabilities in Figma right now. Was wondering if there was an example json file as well as potentially an example css file that the json file would compile down to? Would help us resolve some of the q's we have with the format.