[RFC] Format specification

[kaelig]

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': {
        // ...
      }
    }
  }
}

[kaelig]

Our mileage varies across projects / companies / tools, so I would like to hear thoughts and feedback on where this draft format works / doesn't work, with use cases showing where it breaks 🧐

⚠️ Please provide use cases and examples in your posts (where appropriate)

[danoc]

One interesting scenario that's come up in Thumbprint is that some of our tokens have different values depending on the platform.

For example, our spacing system on web versus native is:

Token	Web	iOS/Android
space1	4	4
space2	8	8
space3	16	16
space4	24	24
space5	32	32
space6	64	48
space7	128
space8	256

(Notice that space6 has a different value and space7 and space8 are web only.)

Here's what our JSON file for this looks like: https://github.com/thumbtack/thumbprint/blob/73bedcf83fb01f3c8617aee30b6a14e4e9143c0c/packages/thumbprint-tokens/src/tokens/space.json

Not sure if this should be supported, but it's something to consider. 🤷‍♂

[kaelig]

Thank you @danoc – do you know if any design tool supports this kind of theming/ platform-specific variants so far?

[dbanksdesign]

I think this is a great start! We might want to focus on the token interface to start, so we don't "boil the ocean".

@danoc brings up an interesting issue, where is the platform-specific information, and do we even include it in the core token interface? Theo and Style Dictionary keep that out of the tokens themselves by using transforms. Same with names, they could be different per platform as well. Maybe if this is a universal/interchange format each token could have any platform data it wants to provide. For example, in @danoc's example, the space8 token would only have 'web' platform data...

interface Token {
  name: string;
  value: any;
  description?: string;
  platforms: Platform[];
  data?: Data;
}

interface Platform {
  platform: string;  
  name: string;
  value: any;
}

[mathieudutour]

instead of platforms, I think a more generic term could be variant or theme. A variant could be a platform but it could also be a dark theme for colors, etc.. The value of a token could then be an object keyed with the variant names (if the value should change between variants ofc)

[kaelig]

Those are definitely super valid use cases!

Theo achieves this with the concept of platform-specific and theming "overrides", or one could also do this by importing a different set of token aliases, specific to the platform or theme.

---

We might want to focus on the token interface to start, so we don't "boil the ocean".

I've added another principle to the draft above:

"The format translates well to existing design tools, in order to facilitate adoption".

This means we need to ask ourselves:

• How much would design tools need to adapt to be able to work with this data?
• Is there a way the schema could be extensible accommodate for theming and platform-specific concepts (via the data field, or other), without having them baked into the spec?

[mathieudutour]

A easy way to adopt the format without caring about the variants at first would be to specify which one is the default one and the existing design tool just has to care about that one

[zackbrown]

I know this conversation focuses on the "shape of the data" rather than the implementation, but FWIW our take on platform-specific overrides in Diez is to use TypeScript decorators on top of property declarations. variant is a solid way to think of this too, @mathieudutour!

@override({
  ios: 32,
  android: 16,
  web: 32,
}) spacingTop = 16

Is it worth elevating "cross-platform" as one of the guiding principles? Seems like a pretty big fork in the road. IMHO any spec with a claim to a Design Token Standard should treat platform-specifications(/overrides/variants) as first-class, but can do so without "hard-coding" specific platforms.

[mathieudutour]

@zackbrown I was also thinking about having a default value and some overrides for variants but with @dabbott we found that it might be safer to specify a value for all the variants so that when you add a new variant, your tool can warn you about the places where you need to look at (eg. the tokens not specifying the value for the new variant)

Is it worth elevating "cross-platform" as one of the guiding principles? Seems like a pretty big fork in the road. IMHO any spec with a claim to a Design Token Standard should treat platform-specifications(/overrides/variants) as first-class, but can do so without "hard-coding" specific platforms.

I think it's necessary too. But I'd say "platform independent" instead "cross-platform".

[zackbrown]

@mathieudutour to help me understand:

we found that it might be safer to specify a value for all the variants

could you sketch out (or point to) an example/pseudocode?

[mathieudutour]

{
  variants: [
    { name: "web" },
    { name: "ios"  }
  ],
  tokens: [
    { name: "token1", value: { web: 1, ios: 2 } },
    { name: "token2", value: 3 }
  ]
}

Let's say you want to add a new variant android. Then whatever tool you are using to manage your tokens could warn you that token1 needs to be looked at because it's missing the android variant. That way your are sure that you won't have any surprise about tokens implicitly using values that they shouldn't

[ventrebleu]

Definitely need some kind of category/grouping system, alias could be useful too. Something like:

{
    name: 'I am a token',
    value: 'This is a value',
    description: 'A nice description.',
    category: {
        'Color': {
            'value': 'Primary'
        }
    },
    alias: {
        'value': 'Also known as',
        'value': 'Peter Parker'
    }
    data: {
    myOwnFlag: true,
    oneMoreThing: 'yay'
    vendor: {
        '@sketch': {
        // ...
        },
        '@figma': {
        // ...
        }
    }
    }
}

[kaelig]

cc @nikolasklein you worked on the styles panel in Figma – do you have thoughts on data structure for grouping/categories?

[mathieudutour]

IMO a group is just a token which has an array of tokens as value. To reference another token, you can then use an array where each item is the name of the token you need to go through:

{
  tokens: [
    { name: "token1", value: 1 },
    { name: "group", value: [
        { name: "nestedToken", value: 2 },
        { name: "nestedToken2", value: 3 }
    ]},
    { name: "refToken", value: ["group", "nestedToken2"] }
  ]
}

[danoc]

Thank you @danoc – do you know if any design tool supports this kind of theming/ platform-specific variants so far?

I do not! We rolled our own a while back: https://github.com/thumbtack/thumbprint/tree/master/packages/thumbprint-tokens

[zackbrown]

@mathieudutour gotcha, I totally agree with this principle (re: variants; few messages above).

Implementation-wise (speaking from the perspective of having already implemented this!) Diez leans on the TypeScript compiler [and a subsequent static-analysis pass for our transpiler] as the tool providing a warning, e.g. that you tried to use a platform dart that wasn't defined.

It would be quite easy to warn also that e.g. "Your overrides are sparse! You might be forgetting Android definitions" without having to contort the data format. In other words, the data is either there or it isn't; IMO it should not be the purview of the data format to make it "extra easy" to perform static analysis, e.g. by duplication; the data format should instead strive to be minimal + ergonomic.

Automated tooling can read that data and determine "sparse overrides" or "missing variants" almost regardless of the shape of the data. So keep it human-centered! [I doubt we disagree on this point!]

[mathieudutour]

I kind of do disagree actually haha. While I do think it should be kept human-readable, I don't think we needs to go out of our way to make it human-writable. I'm sure it will be pretty easy to build tools to edit tokens once we agree on a common format. And so I'm not too worried about introducing duplication as long as it's still readable.

I'd even argue that specifying all the variants is more readable than a default value + overrides.

So my point was to make sure that nothing weird can happen with the data format and that there is only way way to write one thing. So a token should either be a constant or depends on the variant. Otherwise you have multiple way to write a constant: default value + all the overrides with that value, default value + 1 override with that value, etc.

[danoc]

I'd even argue that specifying all the variants is more readable than a default value + overrides.

Agreed. In my earlier example, which would be the default for space6? The web or native value?

[zackbrown]

@mathieudutour

I don't think we needs to go out of our way to make it human-writable.

appears to be at odds with Principle 1 outlined by @kaelig :

For core properties (name, value, description…), a design token file must be both human-editable and human-readable

Granted, the joy of determining a standard is that of wrangling a variety of viewpoints & needs. And compromising! Maybe @kaelig and I are in the minority here in desiring hand- read/writebility?

Design tokens are a promising key to achieving that fabled "single source of truth" for a design language — maybe even, ultimately, to entire applications. To me, hand-editability is important because any "single source of truth" must be accessible to a maximum number of stakeholders [incl. developers and low-code designers.]

You can always build tooling on top of hand-editable code [see any IDE ever], but supporting hand-editability of machine-generated or 'machine-first' code is a very different beast. To me this all circles back to prioritizing ergonomics & minimalism in the data format.

[mathieudutour]

Of course it needs to be human-writable, and if it is readable, it will be writable. But introducing confusion (and multiple ways to write the same thing is def confusing) for the sake of convenience when writing the file by hand isn't something we should lean to IMO.

[jxnblk]

Hi! :wave: Co-author of the System UI Theme Specification here. Thanks for bringing everyone together in one place!

Based on the Twitter conversations, I originally thought that this sounded very similar to the efforts we're working on in the Theme Specification, but after seeing the examples in the initial comment, I suspect that there might be slightly different goals.

If I'm wrong, I'm happy to combine efforts into a single place, but either way I'd love to make sure the two efforts can work together and build on top of one another – or perhaps the two specs can live under the same roof.

For background on where we're coming from, some of our high-level goals, which I've written about here are:

• Create a common naming convention that other OSS libraries can adopt to ensure greater interoperability
• Be as unopinionated as possible, striving for the lowest-common denominator (most naming conventions are derived directly from CSS)
• Be as flexible and extensible as possible
• Use an object that is JSON-serializable and works as production-ready shippable code

Part of the reason the word theme is used here is that this should allow components to be written in a themeable way so that, for example, the same datepicker component can be installed and used at GitHub or Artsy, but match their own brand's "theme".

As far as adoption goes, the spec is built into a few OSS libraries, and there is some interest from the following projects:

• Styled System, which is used internally by Artsy, Priceline, GitHub, and others.
• Modulz also seems likely to be adopting part of the spec – cc @peduarte
• Theme UI is planned to be used in official Gatsby themes and Docz
• Tailwind CSS expressed interest – cc @adamwathan
• Several people have reached out to Material UI, but they are limited by their release schedule
• Smooth UI & xstyled cc @neoziro
• DesignQL cc @johno

In my opinion, adoption among the open source community is really key to adoption in proprietary tools. That is, you have to provide something so good that it would be silly not to use, but businesses will rarely have interoperability as a primary goal.

As far as the goals set out above, here are my thoughts.

For core properties (name, value, description…), a design token file must be both human-editable and human-readable

Agreed. This is sort of a definition of code, i.e. human-and-machine-readable language. If human's can edit design tokens, then I would say that you're describing something more akin to machine learning.

The format is simple, extensible, and as unopinionated as possible

This is also one of our principles, and I think it's key for any standard to achieve adoption, which is a very difficult thing to pull off.

Vendors (design system tools, design tools…) can store information for their own usage, both globally and for each token

This sounds equivalent to what I mean when I say it should be flexible and extensible. By creating a solid foundation, others should be able to build anything they need on top of that foundation.

The format translates well to existing design tools, in order to facilitate adoption

Any schema can be converted to another shape. I might be reading this the wrong way, but I would argue that accepting translation leads to fragmentation. We already have transformers for parsing data from the Figma API, or converting a theme-spec compliant object to other libraries like Tailwind CSS, but this creates friction and doesn't lead to the level of interoperability that I would like to see tools adopt.

So far, this sounds like we're fairly closely aligned with goals, even if they are slightly different. However, the code examples make me suspect that the aim here is more for a documentation format and less about a schema. If that's the case, the Theme Specification and this one could both be adopted and not be mutually-exclusive.

Given this example:

interface Token {
  name: string;
  value: any;
  description?: string;
  data?: Data;
}

The Theme Specification intentionally omits this level of schema definition and does not include documentation or metadata since that would not be desirable in production code and isn't required for interoperability. Things like code comments and type definitions are removed during compilation and more human readable documentation is generally stored in formats like markdown or MDX. That said, you could absolutely use the schema above to store a Theme-Spec-compliant theme object that is used in an application.

I'll try to chime in again with more thoughts later, but we have an initial discussion around the Theme Specification in this issue if anyone in this thread would like to join the discussion.

I hope this is helpful, and hopefully there's a way that both efforts can work together and we can stop reinventing the wheel as often. :v:

[dabbott]

👋🏻 Lona here! (@mathieudutour is also Lona). I'm excited to see this get off the ground!

A couple more meta thoughts:

• I'd like to see a separate discussion around the principles. I want to make sure we have a clear agreement on the problem(s) before getting too deep in possible solutions. For example, principle #3 (vendor's storing their own info) doesn't seem important to me, but maybe with more discussion I would understand it better.
• If this group is self-organized and we all tag our friends it's possible we'll end up with a very un-diverse group... which IMO will lead to a solution that doesn't work for a lot of people/tools/systems. It might be worth thinking about who should/shouldn't be involved and to what degree.

Sorry I haven't contributed much so far, I have some other priorities this week and next, but hope to hop in more soon

[colmtuite]

👋🏻Modulz co-founder here.

Thanks for kicking this off, I'm very interested in seeing this discussion evolve.

We're a few months away from first-class theme/tokens support in Modulz. We've adopted Theme Specification for Radix (our own design system) and we're working towards adopting it for Modulz theming in general.

I'm very keen to see a standard for many aspects of design systems. I'm up for investing time and other resources into it, if people think that might be helpful.

[c1rrus]

Hi all. I'm the person behind Universal Design Tokens, which I started with essentially the same goal in mind: Defining a single file format for (source) design token data. So glad to see that others are tackling this too! Thanks @kaelig for kicking off this thread!

Reading through the thread so far, I have a few comments / thoughts:

• There were a couple of comments about groups of tokens. I too feel this is something the format ought to support. I'm quite fond of Style Dictionary in that respect, since it lets you nest groups as much or as little as you like (although it does recommend their "Category / Type / Item" structure). I realise that having multiple token files (possibly arranged in folders) is another way of achieving this. But, in the spirit of being "unopinonated", I'd suggest we should strive to allow some structure within the files themselves.
• The comments about different values for a certain OS are interesting. I wonder, if you go beyond just UIs, whether a similar mechanism could be useful when using design tokens in other media. Consider print - perhaps a color token could provide an explicit Pantone color in addition to an RGB value which would override the result of an automated conversion that tools would otherwise perform.
  • That being said, I also agree that this perhaps not a priority for version 1. As others have said, let's not boil the ocean. This is something people could use the data field for initially. If the working group spots patterns - i.e. lots of teams and/or products trying to solve the same thing - then it can be incorporated into a future spec revision as a dedicated property of the token objects. (Akin to how the WHATWG try to "pave the cowpaths" in the HTML5 spec by analysing real-world usage patterns)

I also have some additional suggestions:

• Spec versioning. All going well, whatever spec we come up with won't be the final chapter in design tokens, so it feels inevitable that there will be future revisions. Versioning the spec therefore becomes important to help keep track of changes and communicate them to the wider community. I propose we adopt the SemVer convention for versioning the spec as it's already broadly used, various tools and libraries have support for it and I think it lends itself well to a spec like this. Similar to an API, we will have fixes, new additions and, perhaps some day, breaking changes.
• Version identifier in file. Related to the above, I think it's a good idea for token files to identify which version of the spec they conform to. The Lona colors spec appears to have something like this in the form of $version and my own UDT format intends to do the same via a $schema property.
  • Consider a tool that is able to understand version 1.2.3 of this spec. Then, later, we introduce a v2.0.0 spec that has breaking changes. So, a 2.0.0 file is no longer guaranteed to work in that tool. Having a version identifier would let the tool determine this incompatibility automatically and warn the user.
  • Similarly, another tool might have support for both 1.x and 2.x file formats, but may need to parse them differently, so having the version in the file lets them do that. It's just like DOCTYPEs in HTML and how browsers switch between "quirks mode" and "standards mode", depending on what DOCTYPE a page has.
• Token types. Looking at tools like Theo and Style Dictionary, they need to have some notion of what type a token's value is in order to correctly convert or transform that value. Theo does this by having type properties on the values themselves. StyleDictionary instead leans on the "Category / Type / Item" structure to determine the type of a token (and if you choose to not follow that structure, then the onus is on your own config to correctly assign types to your tokens).
  • I prefer something akin to Theo's approach for this. Having a type attribute directly on a token is more explicit and, perhaps, more human-readable too.

[c1rrus]

I also wonder whether there should be an additional v1 priority:

• Create a conformance test suite to enable tool vendors to verify their tools output design token data correctly

That might be a validator, some kind of coded test suite or a combination of those. But I feel it's worth having something like that as soon as possible.

I believe the main motivation for an effort like this is for better interoperability. I want to one day be able to save out colors from PhotoShop, put them into ColorBox to to generate tints and shades, and then run them through a contrast checker to find accessible pairings and then save the results into my design system's source code without ever needing to convert between file formats.

So, the more tools we can provide to let developers ensure their software parses or writes our universal format correctly, the less risk of bugs and incompatibilities creeping in and - ultimately - fragmenting the eco-system and reducing the benefits.

[maraisr]

Hello 👋🏻 Marais here! Human behind Overdrive. Just here dropping my two cents:

• This file is going to get massive, especially if you have a 1-9 colour scale, per colour. So to battle that, would be good build fragments like a colours.json, sizes.json - and combine them together with a CLI or something?
• For things like elevations, that visually look different when applied to a background. Ie a white'ish background, drop shadows look more prevalent - whereas applied to a deep red, you'd darken everything more so it "looks more there". So would that mean a new token "red-elevation-1", or could we give tokens context? So we can have things like $COLOUR_RED_900__ELEVATION_1 - or is this more or less what @ventrebleu was talking about, with aliases?

  {
  tokens: [
      {
          name: 'elevation-1',
          value: '0 1px 10px 0 rgba(0, 0, 0, 0.03)',
          '@context': [
              {
                  'colour-red-900': '0 1px 10px 0 rgba(0, 0, 0, 0.09)',
              },
          ],
      },
      {
          name: 'colour-red-900',
          value: '#780502',
      },
  ];
  }

• Would also be nice to also allow micro-tokens, like component specific tokens. Like within a checkbox component you might want to token the size of the checkbox's tick-box. But not necessarily have that token hoisted to the design system. Just thinking of scenarios where you want input's heights the same height as buttons. So the decision of "do we make a token for button heights" that our "inputs use", or a "token for our inputs height" that our "buttons use" - "or 2 tokens with a comment for future me to keep in sync".
• Bit of a trivial one. There's a name and a value in each token item, then a vendor override. Is this to say "our primary product is web" so the value's are for web targets, with overrides for Figma and say Sketch. Or should we merely just have name, and the value would be in the @scss vendor, or the @web .css vendor?

Thanks for all the efforts though guys!

[Kilian]

There's a tension here between us naturally wanting an all-encompassing spec but also not wanting to 'boil the ocean'. I would suggest we start very small and pave the cowpaths before coming up with new things. The cowpaths here being: existing implementations in design tools, and examples used in more than 1 (or any other n) publicly available design system.

Paving cowpaths

If we zoom in on colors and the way they're used now:

• Sketch: Colors are unnamed and ordered
• Adobe XD: Colors are named and ordered
• Figma: Colors are unnamed and unordered(?)
• Many design systems: Colors are named, ordered and grouped/shown in a range

There's a discrepancy between how people want (others) to use colors, namely they want certain colors to be used only for backgrounds, and they want people to choose between named colors blue-400 and blue-500, and what design tools offer, which is mostly 'a list of colors'.

Keeping things small

Variants, platform-dependent tokens and meta data are all important but what is the least this format should do to be useful? For example, these can be solved by having different token files for different variants. Vendors could choose how to interpret tokens without that having to be in the spec (if we put that in a spec and they ignore it in favor of their own translation of the true value, then what good is the spec?)

What do we want a token to be?

If we keep most of these things out, then focussing on what an actual token should encompass has us ask questions like:

• Is a token a single value, or can it also be a range, or multiple values? (like in system-ui),
• Following from that, are all tokens named?
• Should we enumerate the data type? (string, int, color, json)
• What about usage type (like for colors: "text" vs "background")
• What happens with related token values? (Like a color range: each color is an individual token, but they live in a range. Additionally, A "heading" token might be comprised of a color, a font-family, a font-size, a font-weight, a font-variant, a line-height and letter-spacing. I like UDT's id references here, but how would that look for combinatory tokens)
• Most systems out there have a relatively similar grouping: colors, typography, spacing, border radius, shadow/elevation. Does it make sense to bring this along, or should tokens be ungrouped and solely depend on data type or usage type? This would be unopinionated but could also hamper adoption.

Still, some of these questions already make things bigger rather than smaller (the nature of exploration).

[mkeftz]

Hello, 👋 Co-founder of Interplay here.
Thank you for starting this @kaelig 🙏

After reviewing the spec and comments above, here are some thoughts...

1. Overlap with System UI Theme Specification Firstly I think it should be agreed on if/how this lives with System UI Theme Specification. It is a great spec and as @jxnblk mentions above, has some very similar goals to this. At Interplay we already support System UI structure for tokens. However, from a design tool perspective, it is intentionally missing some of the extra metadata around tokens we need. This looks like it will fill that gap. Possibly aligning the specs so design-tokens can compile to System UI?

2. Theming/Platform specific values This is a tricky one. I feel having multiple variant values in a token would get overly complex, especially when you consider a matrix of values. e.g. what's a token value for mobile and dark mode? As suggested previously this will bloat the file size and make the file less human readable/writable.

Another option would be to leave this above the spec for now. i.e. The spec only deals with the values for a specific theme/platform. You can have complete token-sets (with the exact same structure) for each theme/platform/whatever. Obviously, in implementation, they could inherit from a base set. @kaelig - is this like the theming "overrides" in Theo?

3. Token Structure One of the biggest challenges from the design tool perspective is the structure/categorization of the tokens. We need to be able to import tokens from code and understand what they can be used for and how they should be grouped. I like Style Dictionaries "Category/Type/Item" structure but think it could be too opinionated for the spec. Possibly specific meta-data fields on the tokens could work? e.g. "type" and "category"?

4. Cross-referencing Not mentioned yet, but I think the ability to cross-reference tokens is important. This allows for "option" and "decision" tokens. Style Dictionary does an awesome job of this.

Other than that, I love the idea of having a spec, and happy to help however we can.

[kaelig]

A lot of the (super interesting ❤️) comments mention theming. After talking with @dbanksdesign earlier today, we think it'd make sense for theming to get its own task force. I'd like to start the conversation by laying out the basics of what a simple, low level theming spec could look like and ask y'all to comment on this topic over here: https://github.com/design-tokens/working-group/issues/2

[bomberstudios]

Ale from Sketch here, quick comment to say ‘hi’ and let everyone know that:

• we’re definitely keeping an eye on this project, and I’ll be happy to be your point of contact for all things Sketch, and…
• interoperability is high on our list of priorities. I don’t think it makes sense for any tool to try to own the world, and playing well with others is key. Every team has different needs, and trying to be everything for everyone is a recipe for disaster 😅

[nikolasklein]

Hey there, Niko from Figma here. :) Wanted to drop in, too, and say that this is really exciting and that the discussions here have been super interesting to watch evolve! Very much looking forward to seeing where this is going!

Thanks for looping me in, @kaelig!

[camacho]

👋 Hi, Patrick from Framer here!

We are excited to see this effort get off the ground. We believe in the vision of sharing design properties seamlessly across tools and platforms and look forward to seeing this effort advance.

Please feel free to reach out to me for all things Framer related 😄

[ehudhal]

👋Hi everyone, Ehud from InVision here. Very excited for this initiative. Looking forward to working with you all to support sharing design properties across platforms. Thanks for bringing us together @kaelig !

[peduarte]

Hello 👋 Pedro from Modulz here. As Colm mentioned above, we've adopted some parts of System UI's Theme Spec for our Design System, Radix

Since Modulz is a tool built and optimised for Design Systems we'll also be using Theme Specs within the product itself, so I'm extremely happy to see this initiative of forming a theme standard.

[berkcebi]

Hey, hey! Berk here from Zeplin.

It's wonderful to see all tools represented here. Super excited to be a part of this effort and looking forward to contributing and seeing it evolve over time! 🎡

[zol]

Hey everyone 👋Zoltan from Chroma here.

I'm excited to help out on the spec however I can. I'm especially interested in better ways to connect Storybook to design tools.

[kaelig]

Thank you @zol, I was just about to reach out to the Storybook team following the introduction of the new Component Story Format in v5.2! Welcome :)

[zol]

Thanks @kaelig, glad you saw it. I didn't want to mention it here as it's sort of tangential to design tokens but we're committed to increasing interop between tools in our space!

[jthoms1]

Hello! Josh here from Stencil DS / Ionic.

Just found this thread about the specification as we are working on some tooling around tokens. This spec is pretty exciting to us and we would love to help out if possible.

[gregberge]

Hello! Greg from xstyled.

Very good initiative! We are already following the specification started by @jxnblk: https://system-ui.com/theme/. I want to stick as possible as standard, so I am in.

[mirisuzanne]

Hey all 👋 – I work on Sass, Accoutrement, and Herman. Glad to see this happening! Thanks for the invite @kaelig.

I tend towards the keep-it-simple suggestions above - with a concern for writing-by-hand. In my experience design systems have to be co-maintained by designers and developers (including CSS developers) across a range of contexts. While it's great (and necessary) to build tooling around the format – I would find it much less useful if it requires tooling to write/maintain easily.

And I'll follow that up by adding some complexity. 😬 I think alias references are necessary, but only a half solution. Design systems should be able to store meaningful relationships that include adjustment of values: e.g. space2 = space1 * 2. If I can't capture real relationships, it doesn't feel like a system - it's just a list of keys and values. I realize that becomes much more complex when you start thinking about color-spaces, and the meaning of a term like "lighten" – but something to consider…

(Or it's possible that both of my concerns should be addressed on a syntax-sugar layer above the spec?)

[c1rrus]

While I agree that it would make sense for adjustments to become part of the spec - as @mirisuzanne rightly says, that can help make the relationships and intents that underpin the system more explicit - I suggest that we tackle them a bit further down the line. As it stands we don't even have a basic spec for file format, permitted types of values, etc. I suggest that those are prerequisites for more advanced functionality like adjustment functions. (On a related note - maybe we need to start a backlog somewhere so that all these awesome suggestions don't get forgotten!)

It's also conceivable that tools (assuming they all begin supporting the format we define) could provide a work-around until the format "natively" supports adjustments. I'll outline a couple of examples to show what I mean:

Modular scale of text sizes A design tool like, say, Sketch might one day be able to import all font size tokens from a file using our new format. In the absence of math operators, the file would therefore need to contain the pre-calculated values. However, from the perspective of a design system team that authors and maintains the "single source of truth" design token files, they may prefer to only be storing the inputs need to generate the font sizes - i.e. a base font size and a multiplier (and perhaps min and max points on the scale).

In this scenario the design system team could maintain a "source" token file that only contains those values. But, they could use a build process to generate a "dsitribution" token file which is then made available to consumers of that design system. Imagine if, for instance https://www.modularscale.com/ (or better yet, some kind of CLI utility with equivalent functionality) could load a token file, generate a scale and save out the values to a new token file. That could work.

Color palettes In a similar vein, if tools that manipulate colors (e.g. https://www.colorbox.io/) gain support for our standardised format, they could be fed with some "source" token values and then save out (possibly to a new file, if desired) calculated "distribution" token values for other tools to then consume - or further manipulate.

So, with a setup like that you could potentially maintain a minimal set of source colors and adjustment parameters and then lean on tools to generate all the tints and shades needed for the full palette.

---

It's exactly this kind of interoperability that I hope we can unlock by defining a standardised file format for design tokens. I love the idea that one day I'll be able to mix and match all kinds of tools to create, maintain and also use design tokens. :-)

[c1rrus]

Now that we have a sizable group of representatives from various companies and projects, it's perhaps time for us to become more active.

I'll start my summarising my reading of this thread so far (and please do correct me if you disagree or if I miss out anything!) and then suggest a few areas I think we need to focus on.

Summary of thread so far

• Everyone here is an agreement that a standardised file format for design tokens is a good idea
• I think there's a consensus (or at least, no disagreement) that:
  • We should start small and "not boil the ocean"
  • The format should be human readable
  • Support for categories / groups of tokens is desirable
    • But, the file format should not prescribe a particular organisation of design tokens
  • Support for aliases (aka references) is desirable (i.e. one token can reference the value of another)
  • Tokens should have (optional) descriptions
  • Tokens should be allowed to contain other, optional meta-data as well
  • Tokens should have explicit data types
• Theming and notions of inheritance or overrides have spawned a separate discussion thread. I suggest that this is a higher-level concern that would build on a low-level file format, rather than be an integral feature of that file format. What do you think?
• Other features that have been proposed and/or discussed - but arguably don't need to be part of the initial version of the spec - are:
  • Allowing multiple values for the same token (e.g. for variations between platforms).
  • Allowing proprietary vendor data per token (so tools can save any auxiliary info they need along with the design token)
  • Saving the spec version that a file conforms to (so that, if there are breaking changes between future versions of the format spec, tools can easily determine whether or not they can reliably parse a given design token file)
  • The format should be able to express relationships between tokens (perhaps via adjustment functions and math operations). E.g. tokenA = 2 * tokenB

Suggested next steps I think we need to agree some ways of working.

For instance, all discussions so far are in Github issues (and to a lesser extent PR comments). A Gitter channel was set up but has barely been used. Also a W3C Community Group is being setup, which will provide us with things like a mailing list.

I think long threads like the comments on this issue are not great for technical discussions about specific features because, as they grow ever longer, it becomes harder to track different threads. We could start creating lots of issues for specific topics (e.g. one for file format, one for data types, one for categories, etc.), but I fear that will then make it harder to keep track of the bigger picture of how everything hangs together.

What I therefore propose is that we do a PR that adds an initial skeleton file format spec as a markdown file. It could use the TypeScript pseudo code from this issue as a starting point, or it could be more of a narrative akin to what I started doing for UDT (which is very much work-in-progress and will hopefully be superseded by whatever we cook up here). I don't think it matters to much since whatever we start with will evolve quite substantially over time. Then we successively add or edit it via PRs.

Those PRs should aim to focus on a single issue (e.g. adding a chapter about X, amending the definition of Y, fixing a typo, etc.). Each goes through a peer review and, if accepted and merged, becomes part of the emerging spec.

At some point, once it's mature enough, we can version and release a snapshot of that spec. The same process continues though in order to produce future iterations of the spec.

This of course raises the question of who are the maintainers that can merge a PR? So far I think it's only @kaelig, but I suggest we have a few more to avoid bottlenecks when folks are busy with other things or on vacation. (A related question is whether or not the same set of people should become "chairs" of the W3C community group)

Besides very specific discussions via PRs, I think there is value in having a place for broader discussions. So far it's kind of been this comment thread, but I don't think it should remain that way. We may eventually have many Github issues, so how would a newcomer know that the comments in one particular issue are for general chit-chat. That doesn't feel very intuitive to me.

I propose we choose one place where these general discussions happen (so that people don't have to keep tabs on multiple sources). It could be Gitter or the mailing list we'll get from the W3C community group. My preference would be the latter since it feels more official and also has a publicly accessible archive.

I'm sure there's more stuff to figure out - but I'm putting these suggestions forward to get the ball rolling. :-)

[ChucKN0risK]

Hi, Louis co-founder of Specify here 👋

I'm the author of Design Tokens For Dummies.

We are excited to see this conversation coming up. We believe in the vision of sharing design properties seamlessly across tools and platforms and look forward to seeing this project advance.

We're thrilled to see all tools represented here and we're excited to be a part of this effort.

[dominikwilkowski]

Hi everyone,

I've been following this repo for a while now. Very keen to help and see where it goes. Some thoughts from my side:

• Even though we may not want to boil the ocean it's good to talk about what the horizon looks like to make sure we don't paint our-self into a corner. Then go back to the small scope and deliver the most basic first step.
• I'd be very keen on a schema driven token system. This may or may not fall into the scope of this group but a schema driven data-structure would give us type-safety, documentation out of the box and make it possible to import only those types we need and not build a monolith. I take inspiration from GraphQL here.
• Grouping tokens is something we found very valuable as opposed to atomic tokens. Things like type packs that group font styling (font weight, line height, family etc) into semantic groups helps communicate the design intent and build a common language.

Something that would help this would be a self-referencing system where I can declare an atomic token (lineheight: 1.2 or rounded-corners: 6px) and can reuse this in the same file or system:

{
  color: {
    brand: '#000',
    action: '#999'
  },
  space: {
    'line-height': [ 1.2, 1.4, 2 ],
  },
  type: {
    'page-headline': {
      family: 'SF',
      weight: 900,
      size: '2.5rem',
      line-height: space[ line-height ][ 2 ]
    },
    'section-headline1': {
      family: 'SF',
      weight: 700,
      size: '2rem',
      line-height: space[ line-height ][ 1 ]
    },
    'section-headline2': {
      family: 'SF',
      weight: 700,
      size: '1.5rem',
      line-height: space[ line-height ][ 1 ]
    },
    'body': {
      family: 'SF',
      weight: 300,
      size: '1rem',
      line-height: space[ line-height ][ 0 ]
    }
  }
}

No matter where these things fall, I'm keen to help.

Cheers from Australia

[tobestobs]

Hi all 👋this is Tobias, I'm part of the Material Design team at Google.

It's super exciting to see so much interest in an open Design Token format. We're thinking about how Design Systems can be described using Tokens and made portable across tools and platforms.

I know that there is the intent to keep things manageable to begin with. However we are thinking about Tokens not just for basic stylistic attributes like color and type (subsystems in the world view of Material Design) but also for component level values (like the background color of a button that would reference a token carrying a color value).

It would be very exciting to be able to load a Token file into a compatible design tool that would then be able to render the components described in in the Tokens.

[NateBaldwinDesign]

👋 Hey there folks. I'm a designer for Adobe's Spectrum and have been maintaining our token system for the past few years. I'm also the creator of Leonardo, which is a tool for generating colors based on desired contrast ratios.

So much of this thread is spot on. I have a few thoughts to add.

1. Cross-referencing tokens is necessary, but may not need to be part of this scope
2. Contextual changes to token values are also necessary, but may be out of this scope depending on how it's handled. I see 'contextual changes' as akin to "themes", which can encompass color changes, size value changes, and combinations of font, color, and size changes for any given context. (ie "color theme" changes color, "scale" changes sizes, "locale" changes font/size/colors)

Something that seems suggested but not fully articulated is the notion that tokens may act as configurations for outputting values. @c1rrus mention of type scales is a good example. One may see the output of each font size as the tokens, however the core set of tokens that define those values are computed from the base font size & multiplier.

base-font-size: 14px;
type-scale-multiplier: 1.125;

// outputs:
font-size-100: 14px;
font-size-200: 16px;
font-size-300: 18px;
...

It's worth noting that constraints are still required in this use case, in order to ensure consistent naming of the output tokens (font-size-100) as well as how large/small they go. For example, you would not likely wish to output a 5px font size, even though it conforms to the base font + multiplier.

What appears to be the topic in question would be w/r/t whether the output tokens are stored in the token library, how naming is handled (generated?), etc. I believe cross-references and calculations will help resolve this. As @mirisuzanne said

"If I can't capture real relationships, it doesn't feel like a system "

So this could be:

base-font-size: 14px;
type-scale-multiplier: 1.125;

// outputs:
font-size-100: base-font-size;
font-size-200: base-font-size * type-scale-multiplier;
font-size-300: base-font-size * (type-scale-multiplier * 2);
...

Note: the above examples are only illustrating concept of input/output tokens, not an opinion on the structure.

[NateBaldwinDesign]

I also believe that types is an important aspect of the spec, and wonder if formats differ per type? The example I have in mind is regarding color. The requirements for alternative values for color is different from the notion of alternative values based on platform or context.

For instance, a brand may likely wish to follow a system like Pantone (or of their own invention), where optimal color values are manually selected for each colorspace, knowing that a direct conversion will not result in an optically correct output. Best example is CMYK to RGB, however with the fact that web uses sRGB and many device screens support P3, this becomes more relevant.

colors: {
  'Red': [
      // each tint/shade is an object in this array
     {
        name: 'red-100',
        contrast: 3,
        values: {
            srgb: 'rgb(a,b,c)',
            p3rgb: 'rgb(a,b,c)',
            cmyk: ...
            lab: ...
       },
       ...
   ],
   'Blue': [ ... ],
   'Gray': [ ... ],
}

I wonder how to handle grouping, which can be seen at a few levels. First level being a set of tints and shades each with necessary data, second being a set of the color sets (all tints and shades for every color in the palette)

[NateBaldwinDesign]

What I therefore propose is that we do a PR that adds an initial skeleton file format spec as a markdown file.

@c1rrus 's recommendation here sounds appropriate here -- has this begun already? I'd be curious to see where this is at

[mathieudutour]

the core set of tokens that define those values are computed from the base font size & multiplier

That's interesting. In the more generic sense: shall we allow tokens' value to be the result of a function taking other tokens as arguments, eg. tokenC = fn(tokenA, tokenB) (here the multiply function but we could also think about a saturate function for colors, etc.)? If so, do we need to define a set of functions in the spec? Do we need to be able to define functions with the format?

a brand may likely wish to follow a system like Pantone (or of their own invention), where optimal color values are manually selected for each colorspace

Isn't the colorspace just a variant (as discussed more on #2)? Do we need to be arbitrary about the kind of variants we allow for each "types"?