Burton SmithHow are teams organizing their #DesignTokens based on the W3C @designtokens spec? Are they in single file, split up by theme, category, tier, etc.?
Will Browar 👨🏻💻@stuffbreaker @designtokens I’m still trying to learn my way through this, but so far I have layers like a fundamental base that doesn’t get rendered, but gets used by other files.
Then a semantic layer for global things, like font families, border styles, transition/animation properties. If I were on a big project I feel like it would make sense to break this up by type.
Then I have component specific tokens, which set defaults and sort of reserve the token name.
Then if there are themes needed, I have those broken out, but mostly so I can change the selectors on the individual files.
All of this gets broken out into their own CSS files, then I am currently using a build system to import the files as needed into CSS files, or importing them in to web components as adopted stylesheets.. I don’t know for sure how I’d set that up if I weren’t using a build system, though.
Folder structure is something like this:
automated (place where everything is generated)
tokens
base
global
components
theme
style.css (imports from `automated` directory in order, then gets flattened down in the build step)
@wbrowar @designtokens are the foundation, semantic, and component layers all in their own files or are they groups within a single file?
@stuffbreaker @designtokens because they get combined later, I’m okay with multiple source files, but it depends I guess on what you prefer. I typically have at least one directory and at least one file per layer (one for foundation, one for semantic, etc…). Then if you’re dealing with a lot of tokens, you could break thing out into more files in that directory, like fontFamily, color, dimensions, etc…
The theming stuff I’ve done is usually one file per theme and those typically stay on the same level as the other semantic file.
@wbrowar @designtokens what are you combining them later in / what tools are using these files? I am looking at these from a tooling perspective and I think a lot of modes and resolvers can be problematic from an UX and DX perspective.
@stuffbreaker @designtokens I’m traveling without a laptop, so here’s sort of the high-level description of what my team and I do:
For context, so far we’ve used this setup on projects that use NPM and compile with Vite or Webpack. So I’ve been using the Style Dictionary (https://styledictionary.com) package to compile my design tokens into CSS files.
The way I have it set up is that I have a custom Node script that is run from a few NPM scripts. The Node script’s job is to do the following:
1. Compile the base + semantic layer together, filtering out the `base` tokens by filtering the file path. This gets run for each file in the semantic directory and outputs one CSS file for each token JSON file.
2. Then if there’s a theme involved I have it do the same thing on those files. Since you can change the selector for each compiled file, I usually use a class or data attribute in my HTML and I match that up here.
From there I have all of these CSS files output into a directory called something like `src/assets/automated`. This directory is gitignored and each file is flagged with a comment about it being machine-generated to warn around manually editing it.
I could have the Node script do the work to combine these files together in a specific order, but instead, I found it more intuitive to set up my main CSS file to use `@import` rules and then PostCSS (in Webpack) or LightningCSS (in Vite) flattens that out at compile time so it’s not actually doing an actual import client side. (The only thing I haven’t taken the time to figure out is how to combine selectors to remove multiple `:root {}` selectors in the final output)
So since this Style Dictionary compile is done via this Node script before running `npm run dev` or a CI build, it means from my project’s perspective it just sees the CSS files like regular CSS assets. So this means token autocomplete is there in my editor. I can also open up the CSS files in case I want to reference token values.
@stuffbreaker All of this has been working fine so far, but I don’t know how well this would scale on a much larger project, yet.
Also, while Style Dictionary does support a lot of the design tokens spec, I don’t think it supports compiling everything yet. I think things that are broken out more in the spec, like box shadow (?), dont work yet. In those cases I have it set as a generic string value in my token JSON files and I use a `$description` that includes something to mark it as something to come back to.
@wbrowar I have seen limitations across tooling for those kinds of things as well. Figma is particularly problematic for translating the spec into variables and Effects.
@stuffbreaker I’ve been going into to it so far under the impression that the spec is still in progress and that it might still be a bit before things are updated to follow it all.
In looking at it now, I just realized a stable version of the spec was released late last year.
It’ll be really nice when tools, like Figma and maybe IDEs catch onto it and make it easier to work with.