How do you refer to files in the DTCG format?

[c1rrus]

Our spec is officially titled "Design Tokens Format Module" and it recommends a file extension of .tokens or .tokens.json. But when you talk about these files with your colleagues and friends, what do you call them?

Names I've read / heard / used so far are:

• "Tokens files"
• "DTF files"
• "Design Tokens files"
• "DTCG files"

It would be interesting to hear what name(s) you've all been using.

I'm asking, because it would be useful if our community could align around a preferred way of referring to these files. That would be useful for:

• Tools that add support for this format
  • E.g. in their UI, they might need it for labelling things like "Export as ???? file", "Import from ???? file", etc.
  • In their documentation and marketing materials. "v99 adds support for reading & writing design tokens as ???? files", "How to import tokens from ??? files", etc.
• Referring to these files in talks, blog posts, conversations, etc. - especially if also mentioning or comparing with other design token file formats (e.g. StyleDictionary files, Theo files, etc.)

If a consensus emerges, we could document that in the spec itself (probably as a non-normative suggestion, but I think that could still be useful).

So, please share your names and let's discuss. Thanks! ❤️

[jeromefarnum]

I’m currently attempting to form some nomenclature for this at my company and what I’ve been pushing is token source files for the canonical .tokens.js files and token documents for the files that are generated by a translation tool like Style Dictionary.

[jeromefarnum]

Perhaps off topic for this thread, but additionally we’re calling the selected collection of token source files required to render a specific token document (e.g. base + mobile sizes + dark palette) a token theme and the collection of all token source files and the build config a token package.

[icona79]

I like @jeromefarnum 's idea: "source" makes a lot of sense to me.
I also think that a double version (extended and contracted) would be good.
DTS - Design Token Source
or
DTSF - Design Token Source Format (or File).
make both sense to me.

I'm not the best English labeler though.

Another though is to clearly stand that's a Standard:
SDTS - Standard Design Token Source etc..

On a side note, I like the extended view @jeromefarnum proposes with themes and packages 🙏 In that perspective the extra F (File) could make more sense.

[ChucKN0risK]

I love the idea of a "token source file" as the "source" term makes it easy to understand the file contains "raw" tokens that are transformed yet.

Among all your proposals @c1rrus I prefer "Design Tokens files".

[kevinmpowell]

I tend to refer to them as “source” files as well. “Token source file” or “design token source file” makes sense to me.

[TravisSpomer]

We call them "token JSON" or "token source files." Collectively they're the "source of truth." When we distinguish between files in this format and our original format, we use phrases like "W3C token JSON" (or, if you're trying to be funny, "DTF file") and "proprietary token JSON."

After being processed by tools, we produce "the generated code" and that goes to NPM in "token packages." So, a very different definition of "token package" than Jerome mentioned a few comments up!

[lauthieb]

I also like the idea of "Design Tokens source files", a way of acknowledging that these files are there to be a single source of truth for design decisions cut into several pieces that we call "tokens".

[CITguy]

• I refer to the *.tokens.json file as the "manifest"
  • It provides metadata about design tokens, but doesn't represent their final form after transformation.
• The manifest contents are defined using the "DTCG schema" or "DTCG format".
• I refer to the bundle of assets consumed downstream as the "tokens package".
  • This bundle includes the manifest alongside relevant assets (SVGs, fonts, and other binary file formats).

I don't use the term "source" because the manifest could be built in a variety of ways:

1. verbatim as manually-written JSON
2. compiled from manually-written source files (JSON, JSON5, YAML, TS, etc.)
3. managed from within design software (Figma, Sketch, Adobe suite, etc.), either directly or via plugins
4. generated from a database via a programmatic API
5. etc.

[tounsoo]

I like what @CITguy is proposing. Since "source file" could also mean the file that the design token's end user refers to when they consume them, I think "manifest" makes more sense.

As for the name part, one thing that I have recently experienced in my team is that the term token is too generic. This is more so in the current realm of WTF and because of the confusion we have encounter within team, we now use design token term specifically to be clear.

[TravisSpomer]

We can't call it a "manifest" because that means something entirely different. A manifest is a list of cargo. In software it means a file that either lists or describes other files and that's not what a design token file is at all.

If someday you had one token file for light theme and one token file for dark theme, you might also have a third file that just lists the other two, and that would be a manifest.

{
  "light": "light.tokens.json",
  "dark": "dark.tokens.json"
}

NPM's package.json files can be described as manifest files because they describe the whole package of files. And PWAs have a .webmanifest file that describes the application as a whole.

[tounsoo]

@TravisSpomer That makes sense too! Hmm, I'm not a fan of the source but now I'm not a fan of anything lol.

[jeromefarnum]

We call them "token JSON" or "token source files." Collectively they're the "source of truth." When we distinguish between files in this format and our original format, we use phrases like "W3C token JSON" (or, if you're trying to be funny, "DTF file") and "proprietary token JSON."

After being processed by tools, we produce "the generated code" and that goes to NPM in "token packages." So, a very different definition of "token package" than Jerome mentioned a few comments up!

@TravisSpomer actually, I don’t think your packages and our packages are all that different. Our token packages actually end up as NPM packages, and include the rendered token documents in a dist folder, token source files in a src folder, and theme and build config files at the root of the package (alongside a README and pretty thumbnail images).

This allows projects using our tokens to either import the prebuilt token documents directly, or import a subset (or all) of the token source files for use in their own token packages.

[nclsndr]

After some empirical implementations of the spec I ended up missing naming for more than files themselves.

From a library and API editor perspective, I missed names for:

• The JSON files as the core topic of this discussion 🎯

  • when they exist — in file-system environments, compared to API or DB as exposed by @CITguy
  • I opted for "tokens file(s)"

• The type declaration of the Design Tokens JSON Object that I would use for functions like:

  • validateDesignTokens(tokens: ???) — I opted for DesignTokenTree without conviction

• The documentation of an API accepting this very same Design Tokens JSON Object

  • "Where the body of the request is a ???" — I opted for Design Token Tree just to match the previous

I don't hold a strong opinion on any particular proposition made previously, but I think we must consider giving cohesive names to such close concepts.

[c1rrus]

Just catching up on all the replies here. Really interesting stuff! Thanks everyone for sharing.

I wonder if terms like "source" or "manifest" files refer to broader concepts that are not unique to the DTCG file format though.

For example, the files used with current versions of Style Dictionary could be considered "source" token files (since they contain the source design tokens that SD translates into whatever output formats you need). However, their internal structure does not follow our spec, so they're a different file format.

I suppose that doesn't necessarily rule out adopting a name along the lines of "DTS (Design Token Source)" or the other variations that @icona79 suggested. But, as @CITguy pointed out, these files are not necessarily the source of your design token data. In other setups, they might just be used to transfer design token data between tools (So, "Design Token Exchange Files" or DXF, perhaps? 😛)

I therefore wonder if it's best to avoid names that describe/assume a specific kind of use-case or workflow.

(Aside: It's definitely useful to continue the discussion on broader terminology. However, I'm keen to get more insights and ideas on how to differentiate DTCG format design token files from other kinds of token file formats that are out there.)

This comment from @TravisSpomer's also caught my attention:

When we distinguish between files in this format and our original format, we use phrases like "W3C token JSON" (or, if you're trying to be funny, "DTF file") and "proprietary token JSON."

I've noticed variations of "W3C" format being used to refer to files that follow the DTCG spec elsewhere too.

For example "Design Tokens Generator" can save out tokens in various formats and uses the label "W3C" for the DTCG ones:

Trouble is, that's misleading. While the DTCG is a W3C community group, it is not a W3C Working Group. The technical reports published by the DTCG are therefore not W3C Standards nor are they on the W3C Standards Track.

I therefore think that the DTCG needs to discourage referring to the file format as "W3C design token files" or similar.

However, the above screenshot from the Design Token Generator does nicely demonstrate the need for some kind of name: If we shouldn't use "W3C", then what should go onto that tab?

Perhaps "DTCG files" can be a candidate?

• It doesn't contain presumptions about how/where the files are used
• It avoids misrepresenting the format's status with the W3C
• There's a precedent for this style of naming. (For example, JPEG is short for "Joint Photographic Experts Group")

Thoughts? Better ideas?

Btw, whatever we land on, should we perhaps also update the suggested file extension in the spec to match? For example, if we wanted to encourage people and tools to refer to these files as "DTCG files", then .dtcg or .dtcg.json might be more appropriate than .tokens/.tokens.json.

[CITguy]

What if we were straightforward with it...

Design Tokens Schema (DTS)

• a.k.a., "tokens schema" or "schema"
• JSON schema that defines DTCG Design Tokens format (currently not available)

Design Tokens JSON (DTJ)

• a.k.a., "tokens JSON" or "JSON"
• a JSON file that follows the Design Tokens Schema (i.e., follows the DTCG specification)
• this file may be defined by various strategies:
  • verbatim as manually-written JSON
  • compiled from manually-written source files (JSON, JSON5, YAML, TS, etc.)
  • managed from within design software (Figma, Sketch, Adobe suite, etc.), either directly or via plugins
  • generated from a database via a programmatic API
  • etc.

Design Tokens package (DTP)

• a.k.a., "tokens package" or "package"
• only necessary for tools/workflows that need to package non-JSON assets alongside DTJs

[romainmenke]

Maybe best to google the three letter acronyms before adopting one. :)

---

Plain design-tokens seems fine to me.
This matches the mime type : https://tr.designtokens.org/format/#media-type-mime-type
And differentiates it from brand associated formats.

[CITguy]

Maybe best to google the three letter acronyms before adopting one. :)

Crowdsourced slang terms defined on social dictionary sites (we all know which one I'm referring to) are excluded as they do not represent the general industry as a whole. Regardless, many acronyms have overlapping definitions, depending on contextual use.

Here's a quick set of results for each acronym.

• DTS - https://www.acronymfinder.com/DTS.html
• DTJ - https://www.acronymfinder.com/DTJ.html
• DTP - https://www.acronymfinder.com/DTP.html

[romainmenke]

Crowdsourced slang terms defined on social dictionary sites (we all know which one I'm referring to) are excluded as they do not represent the general industry as a whole. Regardless, many acronyms have overlapping definitions, depending on contextual use.

My only concern is what people will get as results on search engines for any given acronym.
If the acronym becomes the primary way people refer to the format then searching for the acronym will be something people regularly do.

I don't really think it is an issue if there is overlap with an acronym from an unrelated industry.

If possible it would be good to avoid :

• slang
• brand names
• universal acronyms

"DTF files" in particular seems problematic.

[megaroeny]

I also like the idea of "Design Tokens source files", a way of acknowledging that these files are there to be a single source of truth for design decisions cut into several pieces that we call "tokens".

+1 - I'm with this one too. There might be non-technical people contributing or referring to these files, so keeping it in simple and friendly terms is ideal. I think it also avoids getting too "specific" which is prone to not being as scalable or future proof.

[jaakson]

A bit late to the party here, but I wanted to give my $0.02 in case it helps.

The distinction we draw most often is not between the output from tokens, but rather the tokens expressed in Figma (stored as Figma variables) and our source-of-truth token files, which have .tokens.yaml extensions. When referring to the yaml files and their output, we call them "tokens in code". I refer to the source-of-truth tokens at "canonical tokens", though, to really emphasize that these are the starting point from a normative point of view. I think "source" could be just as good a term, but that word is used all sorts of places in development... so I think it is handy to have a somewhat unique (and still very clear) term for the source-of-truth tokens.

[marcedwards]

Great topic! I’d like an answer for this as well. We’ve been using “Design Tokens JSON” here, but I would gladly switch to whatever becomes the official name. I think it’s important to distinguish between the organising body (“Design Tokens Community Group” or “DTCG”), the specification (“Design Tokens Format Module”?), and the actual JSON file artefacts.

I think it’s good to mention that it’s JSON, but “Design Tokens file” also seems good.