Example json files?

[jjcm]

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.

[splitinfinities]

Hey there! I'm also experimenting in this on Stencil. @c1rrus helped point me to https://github.com/design-tokens/community-group/tree/example-token-files/examples, which has helped my prototyping effort.

[roblevintennis]

Looking at the examples and seeing the "flat" vs. "nested" approaches, I think I understand the motivation for using JSON.

However, I do wonder why I can't start or centralize my tokens as CSS custom properties since that's a very natural CSS web page authoring place to start; and ultimately what will need to be placed on the page (unless I am using a preprocessing approach)? You could I think use naming conventions and tooling to make it interoperable.

Sorry to piggyback but seemed relevant to the examples being discussed. Lmk if I should move this otherwise.

[c1rrus]

@roblevintennis If you're only working with CSS, then it's absolutely fine to just use CSS custom properties. Not everyone needs to use the format we're proposing here.

Design tokens the methodology is one thing. The design tokens file format we're specifying is a different thing. It's a way of serialising design token data into a file, but it's not the only way to do that.

However, when you're trying to define tokens in a platform-agnostic way because you need to target multiple platforms (e.g. web, Android and iOS), then a format like what we're proposing is likely to be a better fit. Similarly, if you need your design tokens to flow in and out of UI design tools like Figma.

While these things are possible today, each tool has its own, proprietary file format and/or API so it can be a bit of a chore to integrate them with each other. Our hope is that if all those tools support our format someday, it will no longer be a chore to make wire them up in fun and interesting ways.

[c1rrus]

@jjcm Making more example files is on my to-do list. So far there's only the ones that @splitinfinities already pointed to. I should stress though that the spec itself is still a work in progress and things may change. I'll try to update the example files to match if needed, so that they're valid compared whatever the current spec draft is.

[roblevintennis]

Hi @c1rrus — I totally get the benefits and would love my code-driven variables to be able to simply be imported into a Figma or Sketch by an onboarded designer and I can't imagine the design tokens working group participants aren't far from making this a reality as it's such a no brainer.

As such, I elected to do this for my UI component library; while the tokens aren't adding anything to the project yet, I do think the interoperability will be helpful as it grows. Since asking this a couple weeks back I was able to refactor AgnosticUI's CSS custom properties to be derived from design tokens

    "transform": "style-dictionary build --config ",
    "build:colors": "yarn transform ./tokens/colors/config.colors.json",
    "build:focus": "yarn transform ./tokens/focus/config.focus.json",
    "build:motion": "yarn transform ./tokens/motion/config.motion.json",
    "build:sizes": "yarn transform ./tokens/sizes/config.sizes.json",
    "build:type": "yarn transform ./tokens/typography/config.typography.json",
    "build:tokens": "yarn build:colors && yarn build:focus && yarn build:motion && yarn build:sizes && yarn build:type"

Once I read a page or two from the style dictionary docs it was pretty easy to generate the css custom properties. My defs are a bit flatter or denormalized then many of the examples but it was easy to accommodate that by simply using configurations per token type like:

{
  "source": ["tokens/colors/**/*.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "public/css-src/",
      "prefix": "agnostic",
      "files": [{
        "format": "css/variables",
        "destination": "colors.css",
        "options": {
          "outputReferences": true
        }
      }]
    }
  }
}

@c1rrus I know this is nothing surprising to you but maybe it's of interest to others seeking an example and to show how easy it is and/or for you as you document various examples and need to think of the various use cases ;-)

[drwpow]

I’ve converted a few open source design systems into an examples folder on a design tokens parser / builder I’m currently working on. So far there’s GitHub Primer, IBM Carbon, Salesforce Lightning, and a few others.

They probably aren’t complete, and may have accidentally deviated from the spec in some areas. But I’ll be working on these to update them as the spec changes.

[edzillion]

Will the examples here (https://github.com/design-tokens/community-group/tree/example-token-files/examples) be updated to meet the new draft spec? It would be useful to be able to test against them. It seems those are out of date, e.g. the following type: typedef is a 'user defined composite token' and I think that is being dropped in the next draft release?

 "my-types": {
    "text-style": {
      "type": "typedef",
      "value": {
        "size": {
          "type": "dimension",
          "required": true
        },
        "color": {
          "type": "color",
          "required": true
        },
        "font": {
          "type": "font",
          "required": true
        },
        "weight": {
          "type": "font-weight",
          "required": true
        },
        "line-height": {
          "type": "number",
          "required": true
        }
      }
    }
  },

(also, I don't see a timeline anywhere, what's the ETA of the next draft? It does seem to be soon)