[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"] }
  ]
}