codeName will be a hard one to crack.

If we don't include any platform mention in the format, then codeName works on the surface.

Going back to the DTCG discussion on multi-file vs multi-value tokens which eventually resolved in favour of multi-file when a certain design software company released modes, a codeName with named attributes per platform would align with a vision of a shared build across platforms, whereas the dominant one-build-per-platform paradigm would result in one-listing-per-platform, therefore no need to name codeName or "docValue/webSafeValue".

Because one-build-per-platform is so ubiquitous, I don't think we should argue in favour of a single listing for multiple builds. That'd be impossible in SD's architecture and would force joint versioning-releases across platforms.

The only issue is if we have stacks that do produce multiple syntaxes for one platform. E.g. if I generate Tailwind classes and CSS variables. This is a legitimate use case.

Though if multiple code names are needed for one build for one platform, we can be more relaxed about the meaning of the keys in some tools / use cases. They could be used as hints to tools rather than exact identifiers that tools must match.

Say I have the following file A:

{
  "bg primary": {
    "$value": "#00241b",
    "$type": "color",
    "$extensions": {
      "org.???.listing": {
        "codeName": {
          "css": "--bg-primary",
          "tailwind": "bg-primary"
        }
      }
    }
  }
}

The Figma MCP could share both syntaxes and let the LLM decide. A token doc tool could print everything and use the keys as labels for each name. Search indexes would index every potential variable. Token diff tools would diff each code name individually.

The only annoyance would be tools designed for a specific platform, looking for a specific key. E.g. a code completion tool for a specific CSS framework that would look for the framework's name, but this is not a documented use case (they often have their theme config as part of the SD/Terrazzo output anyway) and such tools' consumers would be free to pick the codeName the tool expects.

For tools that want to display a single name (e.g. a mobile token doc), we could either argue that an order of priority exists based on the order printed, or support an optional DEFAULT/default key, or support an optional string syntax.

So, I agree with your syntax proposal but for a different semantic :) I'm curious though how you feel that Terrazzo users would handle multi-platform? I know at FTV we'd still want to produce individual listings (if anything, because we commit our token listings to git and that makes for smaller files and fewer Git conflicts when single platforms evolve).

If we did have to support multi-platform, then tools like Figma MCP would struggle to identify relevant platforms to use within a listing as (@GLips please correct me if I'm wrong, I've never built MCPs) they don't know the syntax the code will be written in ultimately by the LLM.

@GLips @drwpow @jorenbroekema I'd love to have one more round of feedback from each of you on how to handle multiple applicable codeNames, and how tools could handle this situation.

On my end, with the tools I know how to make:

Documentation platforms

Multiple codeNames would mean multiple lines to display in the token tables. Having a "preferred" codeName could help provide a more compact/synthetic view of the documentation.

Search engines

Every codeName would result in additional search index entries being created.

Token diff & derivative tools

Every codeName would result in relevant diff entries if different. Thus so in PR assistants, etc.

Codegen plugins / codemods / linters

Those tools would need to be configured to use a specific codeName syntax in specific contexts. They would need to be aware of the keys in the codeName dictionary and to be told which to use (or which to use when).

In a Figma codegen context, from a DS team perspective, this is an opportunity rather than a problem. If tools like Figma or Penpot were listing-aware in the future and wanted to provide a generic codegen feature, though (Figma certainly does), they'd need to request specific keys or be given a default/preferred codeName to use.

Yeah so to give a practical example, at Figma we had design tokens in CSS, design tokens in JS, and design tokens in C++. Each token was “truth” because it came from a designer dedicated to a project, and was consistent within its own mini-system. As we combined them into one central design system, we would have conflicts trying to make them one design system.

Perhaps one solution is naming—simply prefix tokens based on where they came from. But then we’d have to maintain a mapping back to their original names which didn’t have the prefix.

We also could just do the entire mega-mapping somehow where we come up with new names from the old conflicting “mini design systems” into the new one. But perfect is the enemy of done, so to reduce gigantic projects that blocked design system consolidation we just put all the tokens together, but it’s not always clear what the original value was created for, but identifying its original “source” provides all the info we need to understand its context and intent. So I suggested this metadata just as a way to track these things.

I know in a perfect world this problem doesn’t exist, and maybe this could just be in $extensions for our usecase and that’d be fine. But in case anyone else is ever in the process of identifying some sort of crude “history” of where a token came from it is helpful

If I were to abstract away the specifics of how you got there, would you say that you'd find value in tracking the source tokensets that a built token came from?

A generic way to track tokenset soulrces could also address the mode/platform metadata needs discussed in #1479 (reply in thread).

But then again, if e.g. a doc tool wanted to allowing filtering based on this information, it would want to know how to qualify it. E.g. I'd want a "Mode" Select to pick the color modes to display, and a "Source DS" select in your Figma-specific case. So we'd likely want an agnostic "source" metadata entry in the format to accept a dictionary?

I see value in distinguishing modes and platforms, as with modes I'd typically want MCP/codegen tools to ignore them, and doc tools to provide a select. Whereas with platforms I'd want a single platform picked (the one I'm currently on) by MCP/codegen, and I'd want separate pages/routes in the doc tool.

Problem statement

Yes, and mostly a format that maps built token data to source data with content that tool makers can rely on being present.

Format

Agreed. I've given some thought to compressed formats too but at the end of the day, it's better to let end users add compression themselves if they want to. Not compressing allows for lighter Git diffs when committing listings to a Git repo.
(@drwpow FYI)
Worth noting that sorting the tokens would also help with minimising Git diff impacts (at the expense of an extra step). We could skip sorting if we can assert that both SD and TZ output tokens in a deterministic fashion based on the order of content in input tokensets. I'd need your inputs on that. (@drwpow FYI)

Data Structure

Absolutely aligned here. Thanks for pointing out the existing conversion utility!

From that point onward, it's just about extracting meta data from the $extensions property and translating/moving it to the proposed properties (codeName, designName) for each token item?

Here I'm interpreting this as: "strip $extensions" and produce flat objects in a flat array" e.g.

[{
  "$key": "{colors.red.500}",
  "$path": ["colors", "red", "500"],
  "$type": "color",
  "$codeName": "var(--colors-red-500)",
  "$designName":" "mode/colors-red-500"
  ...
}]

Not exactly what I had in mind because I'd love for individual objects to remain fully DTCG-compliant. This is simply to offer tool makers more opportunities to use existing token manipulation libraries without worrying about type incompatibilities.

I may have misinterpreted what you meant though!

Style Dictionary format would look something like: ...

A few edits to show how I envision extensibility/customisation:

• Include versioning in the format right away
• Provide preset transforms for code/designNames (maybe include in transformGroups, up to you really)
• Let end users write custom transforms for advanced use cases

import StyleDictionary from 'style-dictionary';

const sd = new StyleDictionary({
  source: ['tokens/**/*.json'],
  platforms: {
    'token-listing': {
      transformGroup: 'web',
      transforms: [
        'name/kebab',
        'token-listing/codeName/css-variables',
        'token-listing/designName/penpot',
        'token-listing/<supported property>/<preset transform>',
      ],
      files: [{
        destination: 'usual-output.css',
        format: 'css/variables'
      }, {
        destination: 'output.json',
        format: 'json/token-listing-v1'
      }],
    }
  }
});

The TZ counterpart would look like:

  TokenListingPlugin({
    // ... totally forgot the TZ syntax and slept too little to look it up :grimacing:
    codeName: 'tailwind-class',
    designName: 'figma',
    someOtherProp: (token) => { return 'custom-output' },
  })

Parent meta

I like the idea of having a parent object with meta info e.g. version of the listing-format, this is something that's missing in DTCG (no JSON schema, no semver versioning) and it really hurts 😓

I hear you. Let's keep that in mind and have a { meta: { version: 1 }, data: [] } root structure. One meta field that comes to mind immediately is authoringTool which could tool makers with debugging in case there are regressions/differences between SD/TZ.

@Sidnioulz I think we mostly mean and talk about the same.

We'll get there eventually 😆

When I speak about having the same token names E2E, I mean that it should be favourable to have the same token name independent of possible casings or naming conventions. Technical namespaces, prefixes and all possible adjustments are still fine, as long as it is possible to identify with a certain schema/convention/rule the same token name. Therefore text-title-1-bold and CustomPackageName.CustomTypographyTokenNamespace.Title1Bold might be an extreme example, but would still fit what I understand with same token name E2E. So my point really has been, that people should not be technically encouraged in coming up with completely different names for the same token.

Thanks for clarifying. I am not suggesting either that people have legitimate reasons to re-interpret the names of tokens across teams/platforms, so that generally speaking a token would be named foo.bar on a platform and squeaky.squeak on another.

However, I am saying:

1. Exact names on each platform matter to many design token tools (codemods, codegen plugins, linters, diff tools, doc for copy&paste, etc.)
2. Producing those exact names as centrally as possible limits the surface maintenance of code and the risks of having two casing libraries produce different outcomes (this does happen!)

And as a bonus, I do feel that sometimes, not less often (and not a concern of Web-centric platforms):

3. For a given token taxonomy, you can legitimately have different naming patterns applied due to platform limitations; iOS provides native Color objects but is notoriously inflexible with typography, so teams may be able to pass color tokens as colorsets and may have to create their own data structure to hold typography tokens, resulting in two different code patterns for accessing either token

I see the benefits of also having the implementations, for these different name formats in one place, but I still doubt, that this system is flexible enough to provide fast future adoption in systems that might need a different naming convention, which so far is not supported.

Could you elaborate on that please?

If I interpret this as a worry that I want to make multiple platforms (e.g. Web + Android + iOS) use the same token listing file, that's not my goal. My goal would always be to produce one listing per code platform. This is based on my experience that teams with multiple platforms

• can have multiple token sets
• often have different token usage guidelines
• often have distinct token reference documentation for each platform
• must necessarily have distinct search indexes to handle the exact name / value patterns found in each platform
• must necessarily have distinct migration/linting/codegen tools as these depend on the technologies used in each platform

A listing file would always be tied to a specific code platform. If you were to build Web + Android in the same SD run, I'd first recommend doing two SD runs (just like the SD repo examples show) because that avoids coupling around transforms.

Listing files also are always just a transport/storage format. They known attributes in a way that's predictable for tools. Design system teams can add a listing to their tokens NPM package, and eventually tools that understand the listing format will go fetch that listing. The exact values of known attributes does not matter to this RFC, only their identity and semantics matter. Teams would retain full control over how the codeName, etc., are computed, and helpers can be provided to help new teams get started with sane defaults (e.g. Figma's naming convention, var(--foo-bar) for CSS codenames, etc.).

...by centrally providing sane defaults and presets and let anyone customise these attributes/extensions as needed. But for me the focus lies more in the default/neutral naming formats, rather than the implementations, that convert the token names in the end. Don't get me wrong, it's good to have and provide them centrally, but they are pretty trivial in the end IMO.

This is exactly why I'm bringing this proposal here. As Style Dictionary already provides transform groups with decisions on how names and values must be rendered, they're in a privileged position to provide matching sane defaults for codenames. For instance, if they name CSS variables --${kebab(name)}, they can codeName CSS variables var(${transformedName}).

Acknowledging and agreeing on your points 1. - 3., thanks for clarifying with those additional details.
Let me pick up a few points:

I see the benefits of also having the implementations, for these different name formats in one place, but I still doubt, that this system is flexible enough to provide fast future adoption in systems that might need a different naming convention, which so far is not supported.

Could you elaborate on that please?

My take here is, that the implementations for the token names should be easily extendible with own ones. No need for PRs being merged in order to get custom token name formats outputted...actually boils down to sane defaults and easy overrides. You pretty much said the same here:

Teams would retain full control over how the codeName, etc., are computed, and helpers can be provided to help new teams get started with sane defaults (e.g. Figma's naming convention, var(--foo-bar) for CSS codenames, etc.).

If I interpret this as a worry that I want to make multiple platforms (e.g. Web + Android + iOS) use the same token listing file, that's not my goal. My goal would always be to produce one listing per code platform. This is based on my experience that teams with multiple platforms
- can have multiple token sets
- often have different token usage guidelines
- often have distinct token reference documentation for each platform
- must necessarily have distinct search indexes to handle the exact name / value patterns found in each platform
- must necessarily have distinct migration/linting/codegen tools as these depend on the technologies used in each platform

If different platforms don't use the same token listing file, where do we establish a Single Source of Truth (SSOT) for token names in a neutral or universal format? Aren't the properties you've proposed supposed to be under the $extension property within the files of a SSOT token set? I might be misunderstanding, but having a Design Token Community Group (DTCG) token structure in the listing files, with the $extension property populated with necessary token name data for each platform, doesn't seem like a token name SSOT to me. Or is the idea more about a specification that provides formatted token names per platform (via token listings) derived from the design token SSOT? In that case, referring to a token name SSOT might be misleading, in my opinion. Could you provide a simple example with just one token and an example listing file for each platform to clarify this?

A listing file would always be tied to a specific code platform. If you were to build Web + Android in the same SD run, I'd first recommend doing two SD runs (just like the SD repo examples show) because that avoids coupling around transforms.

I've had positive experiences using or overriding specific transforms and applying simple filtering for particular platforms, executing a single Style Dictionary run with sd.buildAllPlatforms() for one theming permutation (multi-dimensional theming context). Whether it makes sense to have separate token sets might depend on Style Dictionary's features or the extent of token differences across platforms.

Token listings would also contain essential token properties defined in the DTCG:

name
path
value
type
deprecated
description

In our token documentation, we've considered marking design tokens also as new, alongside having the possibility to mark some as deprecated.

If different platforms don't use the same token listing file, where do we establish a Single Source of Truth (SSOT) for token names in a neutral or universal format?

I'm curious what value you expect out of a name SSOT. Is there an intrinsic value to a SSOT for names, or is it that you want to ensure you have a unique identifier for tokens wherever they're referenced? Regarding the former:

• Having a SSOT for token names is not the goal of a Style Dictionary build: SD or Terrazzo produce files usable in codebases, so their names have to reflect the codebase's constraints and architecture; the SSOT is only necessary in the source material of the build (as per the DTCG format)
• Design tools also do not acknowledge the DTCG spec entirely: famously, Figma has its own naming syntax, and as far as I know only PenPot correctly handles DTCG names
• The exact syntax (the SSOT) also doesn't matter in practice in collaborative activities; nobody goes through pronouncing the name of a token with its exact syntax, and so tokens all have an "organic" name that gets used to distinguish them, and disambiguation is done ad-hoc and when relevant by practitioners

If what you're looking for is UUIDs, know that the listing format will maintain both a token $name property (or maybe a synthetic $key matching the identity used to resolve token refs?) and a $path property, compliant with the DTCG. That need is addressed. The whole point of this RFC is to also have the actual names used in other information systems, because they matter for the needs of DT tool makers.

Aren't the properties you've proposed supposed to be under the $extension property within the files of a SSOT token set? I might be misunderstanding, but having a Design Token Community Group (DTCG) token structure in the listing files, with the $extension property populated with necessary token name data for each platform, doesn't seem like a token name SSOT to me.

Handling platform names in the source tokens file would be near-impossible. It would be hell to maintain (rename a token? rename it three-four times in the $extensions). It would lead to inconsistencies as token authoring tools would be unaware of the extensions (edit a token in TS, suddenly the names in $extensions aren't aligned). And it would completely short-circuit the role of token translation tools, which translate tokens. And of course this would mean, as you point out, that token names would no longer have a single source of truth.

Another way to look at the RFC is to ask the token translation tools to provide a log of what they've translated.

Or is the idea more about a specification that provides formatted token names per platform (via token listings) derived from the design token SSOT?

Yes, that's the goal. To map the manifestations of design tokens in different contexts so they can be reasoned about by people like GLips or myself, without having to re-invent processes and file formats and all of that for every org/team out there.

In that case, referring to a token name SSOT might be misleading, in my opinion.

I am not sure what you mean by this. I don't think I discussed SSOTs in the RFC and I don't aim to establish a new type of SSOT or to have people using the listing format define a SSOT. Ultimately, all tokens within a SD or Terrazzo build must be uniquely identifiable, or an algorithm must be in place to resolve ID conflicts, and that's a concern of the DTCG and token translation tools. My goal is to provide crucial information in a predictable format, and nothing more than that. I specifically don't want the listing format to dictate how the information should be computed so that it doesn't become a hindrance to others. It's only concerned with formatting and transporting data created elsewhere with total freedom.

Could you provide a simple example with just one token and an example listing file for each platform to clarify this?

Sure! Based on what's been discussed so far:

// Source tokens
{
  "font-weight": {
    "regular": {
      "$value": "normal",
      "$type": "fontWeight",
      "$deprecated": false
    },
    "emphasis": {
      "$value": "black",
      "$type": "fontWeight",
      "$deprecated": false
    }
  },
  "color": {
    "bg-neutral": {
      "$value": "#91939D",
      "$type": "color",
      "$deprecated": false
    },
    "bg-not-so-neutral": {
      "$value": "#FFC300",
      "$type": "color",
      "$deprecated": true
    }
  }
}

// Listing format file
{
  "meta": {
    "version": 1,
    "modes": ["light"]
  },
  "data": [

    {
      "$key": "font-weight-regular",
      "$path": ["font-weight", "regular"],
      "$value": "normal",
      "$type": "fontWeight",
      "$description": "Normal font weight",
      "$deprecated": false,
      "$extensions": {
        "token-listing": {
          "codeName": {
            "css": "var(--font-weight-regular)",
            "tailwind": "whatever-tailwind-does-nowadays"
          },
          "designName": "fontWeight/regular",
          "originalValue": "normal",
          "previewValue": "500"
        }
      }
    },
    {
      "$key": "font-weight-emphasis",
      "$path": ["font-weight", "emphasis"],
      "$value": "black",
      "$type": "fontWeight",
      "$description": "Emphasis font weight",
      "$deprecated": false,
      "$extensions": {
        "token-listing": {
          "codeName": {
            "css": "var(--font-weight-emphasis)",
            "tailwind": "whatever-tailwind-does-nowadays"
          },
          "designName": "fontWeight/emphasis",
          "originalValue": "black",
          "previewValue": "900"
        }
      }
    },
    {
      "$key": "color-bg-neutral",
      "$path": ["color", "bg-neutral"],
      "$value": "hsv(230, 8%, 62%)",
      "$type": "color",
      "$deprecated": false,
      "$extensions": {
        "token-listing": {
          "codeName": {
            "css": "var(--color-bg-neutral)",
            "tailwind": "whatever-tailwind-does-nowadays"
          },
          "designName": "color/bgNeutral",
          "subtype": "background",
          "originalValue": "#91939D",
          "previewValue": "#91939D"
        }
      }
    },
    {
      "$key": "color-bg-not-so-neutral",
      "$path": ["color", "bg-not-so-neutral"],
      "$value": "hsv(46, 100%, 100%)",
      "$type": "color",
      "$deprecated": false,
      "$extensions": {
        "token-listing": {
          "codeName": {
            "css": "var(--color-bg-not-so-neutral)",
            "tailwind": "whatever-tailwind-does-nowadays"
          },
          "designName": "color/bgNotSoNeutral",
          "subtype": "background",
          "originalValue": "#FFC300",
          "previewValue": "#FFC300"
        }
      }
    }
  ]
}

(quick reminder, most of these props still need discussion, but originalValue provides info on token refs, previewValue/webSafeValue/docValue would provide a Web-compatible value to be displayed in doc, subtype would provide preview hints for doc)

I've had positive experiences using or overriding specific transforms and applying simple filtering for particular platforms, executing a single Style Dictionary run with sd.buildAllPlatforms() for one theming permutation (multi-dimensional theming context). Whether it makes sense to have separate token sets might depend on Style Dictionary's features or the extent of token differences across platforms.

The listing would be a format, so you'd get one per platform/mode in such a context.

In our token documentation, we've considered marking design tokens also as new, alongside having the possibility to mark some as deprecated.

"Deprecated" is part of the DTCG standard draft, hence in the inclusion. A token diff tool built on top of token listings could provide you with that extra piece of information though.

Finally being able to pick up the discussion again. First of all thanks for these clarifying details. That really helped to solve some confusion or misconceptions on my side. A few misc comments:

Token IDs/Keys

Design tools also do not acknowledge the DTCG spec entirely: famously, Figma has its own naming syntax, and as far as I know only PenPot correctly handles DTCG names

If what you're looking for is UUIDs, know that the listing format will maintain both a token $name property (or maybe a synthetic $key matching the identity used to resolve token refs?) and a $path property, compliant with the DTCG. That need is addressed. The whole point of this RFC is to also have the actual names used in other information systems, because they matter for the needs of DT tool makers.

With Figma relying on actual IDs for their Figma Variables, that do not have anything to do with the design token name, they currently run into massive limitations when it comes to multi-brand theming of components. Consider a component library in Figma and the requirement of a subbrand to assign different stylings to the same component. Currently you would either override the original stylings of the main brand, for everyone, or you are losing the linkage, because the subbrand is copying the component library. The Figma Variable id reference mapping in the $themes.json visualizes this limitation and bottleneck, as well. On the other hand just relying on the design token name, like PenPot is doing it, actually comes with a lot of freedom, when it comes to overriding or extending in multi-brand approaches. I think this should be kept in the back of everyones head, when it comes to an UUID discussion for design tokens. An UUID does not hurt per se, but could introduce hardwired and hard to change dependencies, if used in the wrong place.

Token Listing Structure

{
  "$key": "font-weight-regular",
  "$path": ["font-weight", "regular"],
  "$value": "normal",
  "$type": "fontWeight",
  "$description": "Normal font weight",
  "$deprecated": false,
  "$extensions": {
    "token-listing": {
      "codeName": {
        "css": "var(--font-weight-regular)",
        "tailwind": "whatever-tailwind-does-nowadays"
      },
      "designName": "fontWeight/regular",
      "originalValue": "normal",
      "previewValue": "500"
    }
  }
}

Seeing the structure really helped me a lot and I believe this could work. At least it goes in the right direction. I also acknowledge that it tries to be as close to the DTCG spec as possible.

Brainstorming on some details of the code example

• I kind of struggle with the property designName a little bit. I feel that there potentially could be more then one design tool, that works with the same design tokens!? So we either should put all the different output token name formats in one object (ouputNames), or if we want to keep the separation between code and design, then designNames should be an object, the same way codeName is. In the example below, I have just exemplarily put it all together under outputNames.
• Besides property naming details, I think one missing, but quite crucial information is, having not only the originalValue, but the whole reference hierarchy chain, maybe in the form of an AST (if this does not bloat up the token listing JSON output file completely!?). If something like that would be possible, we could theoretically document the dependencies and references between design tokens, even for algorithmic/dynamic design tokens, which rely on calculations or maybe also relevant for composite tokens that end up i.e. as shorthand values in CSS!?

{
  "$extensions": {
    "token-listing": {
      "outputNames": {
        "css": "var(--font-weight-regular)",
        "tailwind": "whatever-tailwind-does-nowadays",
        "figma": "fontWeight/regular"
      },
      "originalValue": "{core.font-weight.standard} + {core.font-weight.increment}",
      "previewValue": "500",
      "referenceHierarchy": [                             // pretty much some AST data in the end
        {
          "key": "core.font-weight.standard",
          "sourceMap": {                                  // OPTIONAL: An object providing deep source-of-truth information. Enables "go to definition" functionality in documentation tools.
            "filePath": "token-ssot/typography.json",     // The relative path to the source file.
            "line": "123",                                // The line number where the token is defined.
            "column": "26"                                // The column number where the token definition begins.
          }
        },
        {
          "key": "core.font-weight.increment",
          "sourceMap": {                                  
            "filePath": "token-ssot/typography.json",     
            "line": "164",                             
            "column": "26"                            
          }
        }
      ]
    }
  }
}

Considerations for Style-Dictionary

The listing would be a format, so you'd get one per platform/mode in such a context.

Style-Dictionary's separate builds for each platform does not easily support the generation of an over all token listing file. But leveraging on the rather unknown public method formatAllPlatforms() instead of the buildAllPlatforms(), I could theoretically imagine to generate an over all token listing file for all platform builds, before SD is actually generating any output files, similar to how I understand Terrazzo is doing it internally. This would need some kind of post processing step, but it would finally make also things like token deduping/design token diffs possible, the base to efficiently generating responsive breakpoint token files for example, or to just mark certain tokens as new. That way the architectural difference between Terrazzo and Style-Dictionary could align pretty neatly!? But just having a token listing file per platform, would also be a way we could start with IMO!?

Token IDs/Keys

With Figma relying on actual IDs for their Figma Variables, that do not have anything to do with the design token name, they currently run into massive limitations when it comes to multi-brand theming of components. Consider a component library in Figma and the requirement of a subbrand to assign different stylings to the same component. Currently you would either override the original stylings of the main brand, for everyone, or you are losing the linkage, because the subbrand is copying the component library. The Figma Variable id reference mapping in the $themes.json visualizes this limitation and bottleneck, as well. On the other hand just relying on the design token name, like PenPot is doing it, actually comes with a lot of freedom, when it comes to overriding or extending in multi-brand approaches. I think this should be kept in the back of everyones head, when it comes to an UUID discussion for design tokens. An UUID does not hurt per se, but could introduce hardwired and hard to change dependencies, if used in the wrong place.

Ideally I want to look at the problem of identifying tokens from the perspective of SD and TZ.

Token renaming and UUIDs

Do you envision a way for token listings to be aware of refactors/renamings in a source tokenset? We've been thinking about maintaining data structures for token renamings (so codemod engines could pick them up) but we haven't found a way to produce a renaming-aware token diff with just our listing format.

This is the only use case I have in favour of UUIDs. A renamed token could persist its identity if it had a UUID instead of an id computed from its path or name.

Modes as additional identifying info

When we're given a token build to do, we don't know exactly how they'll be combined and consumed in a code platform. We also don't know what theme or mode or collection or superset they're part of, because none of that is standardised in DTCG or formally represented in transformer tools. To the best of my knowledge, only SD has a concept of platforms, and platforms are (bear with me, haven't used SD 4/5 yet, I could be wrong here) only names.

So ultimately, the job of mapping a bunch of DTCG files to different modes, and glueing together a bunch of SD build outputs into a style system with theming capabilities, is still entirely in the hands of the end users.

With my current client, we've ended up setting up a token build service that consumes SD 3 with tokens, and uses formats and actions, and then a separate build service that runs its own file manipulations without tokens, but with our own formalism to describe modes and how they're translated into code. We need this formalism to automate mode handling in code, but we don't need it in other tools. Search engines, token diffs, changelog generators, doc platforms only need the list of modes and the list of tokens in each mode and can ignore questions of mapping modes to platform settings, priority of application, inheritance, etc.

A lot of what I don't know how to represent in my proposed format is that mode formalism. I find it is safe to assume, in the current tool landscape, that two token builds or two DTCG files can have a token with the same path/key/name, and design/code environments will be able to use either interchangeably with their own understanding of modes built in their own product. Figma does that will collections. We do it in CSS with selectors and custom properties. CSS-in-JS frameworks are picking it up with their own APIs, etc. So for now, I'm happy to ignore that topic and to name tokens with just path/key information. I want to believe it's enough for most tool makers.

Considerations for Style-Dictionary

Skipping to this first as I think the topics are linked.

Style-Dictionary's separate builds for each platform does not easily support the generation of an over all token listing file. But leveraging on the rather unknown public method formatAllPlatforms() instead of the buildAllPlatforms(), I could theoretically imagine to generate an over all token listing file for all platform builds, before SD is actually generating any output files, similar to how I understand Terrazzo is doing it internally. This would need some kind of post processing step, but it would finally make also things like token deduping/design token diffs possible, the base to efficiently generating responsive breakpoint token files for example, or to just mark certain tokens as new. That way the architectural difference between Terrazzo and Style-Dictionary could align pretty neatly!? But just having a token listing file per platform, would also be a way we could start with IMO!?

I had no clue this existed! RE: should we build a listing for all platforms or one listing per platform, I have a clear preference. I believe SD platforms implement either actual code platforms or modes/themes.

When it comes to modes/themes, like I said above, I think many tools can provide value without knowing about how they interplay. Simply showing what happens for a list of tokens for a specific mode already supports many workflows. I don't want to get ahead of the CG on defining mode formalisms because I have no clue what's good enough for everyone out there. I can only share my own formalisms for my own use cases.

When it comes to different platforms (e.g. Android app, iOS app, B2C web app, internal dashboard web app), I believe token listings must not be conflated. I find it unlikely that the same developers need to consult the value of a token on Compose and SwiftUI and CSS on the same day as part of the same work unit. Usually, each platform will be handled by a different team. Even teams that work on multiple codebases aren't likely to work on the same exact UI feature across all codebases in parallel. Even when it comes to designers, it's unlikely they'd want to consume context about a built token across all platforms at the same time as they'd want to check dev tokens in relation to a collaboration with a dev, and the dev would be working on one specific codebase/platform.

So, I think producing one listing per SD platform is probably optimal for more use cases than one listing for all platforms. That's why I had a format in mind.

Token Listing Structure

• I kind of struggle with the property designName a little bit. I feel that there potentially could be more then one design tool, that works with the same design tokens!? So we either should put all the different output token name formats in one object (ouputNames), or if we want to keep the separation between code and design, then designNames should be an object, the same way codeName is. In the example below, I have just exemplarily put it all together under outputNames.

Great point. We could merge the code/design names into a single category indeed. Maybe platformNames? I wouldn't want to tie it to outputs, as in Figma's case, those names are more of an input for people who don't rely on Tokens Studio. And I'm sure someone will come up with some other type of name they'd like to store in there eventually.

Would it be worth categorising the types of platforms included, maybe in the meta section? E.g.

{
  "__meta": {
    "platforms": {
      "css": {
        "type": "code",
      },
      "figma": {
        "type": "design",
      },
      "tailwind": {
        "type": "code",
      }
    }
  }
}

I'm curious if MCPs could ever make the mistake of confusing Figma names for names to use in codegen, or if doc tools would benefit from knowing which name(s) are the design name(s) vs the code names?

• Besides property naming details, I think one missing, but quite crucial information is, having not only the originalValue, but the whole reference hierarchy chain, maybe in the form of an AST (if this does not bloat up the token listing JSON output file completely!?). If something like that would be possible, we could theoretically document the dependencies and references between design tokens, even for algorithmic/dynamic design tokens, which rely on calculations or maybe also relevant for composite tokens that end up i.e. as shorthand values in CSS!?

Right. This could be an opportunity to build source maps between source tokens and built ones. It could be relevant if metadata can be added to point to where the source is stored. A doc website or token diff UI could then have a HTML link to the source token in GitHub/TS/Penpot.

Of course, I would rather these references weren't transitive due to weight considerations. An obvious space optimisation would be to hold sourcemap info in the meta section, and to only print reference keys in individual token objects. Possibly, a SD/TZ helper library could help other tool makers extract references from value/originalValue fields without adding weight to the files.

Do you have particular use cases in mind for sourcemap data?

Thanks for sharing those mode select UIs! One aspect I don't know yet how to handle is how to carry information about applicable modes in the listing format.

I'm thinking the information might need to be provided in the format meta, e.g. if using string list:

{
  "meta": {
    "version": 1,
    "modes": [
      "sm",
      "light"
    ]
  },
  "data": [/* TOKENS GO HERE */]
}

If using named collections:

{
  "meta": {
    "version": 1,
    "modes": [
      "breakpoint": "desktop",
      "color": "hi-contrast-light"
    ]
  },
  "data": [/* TOKENS GO HERE */]
}

This assumes we stay on course with the de-facto industry standard of separating source tokensets based on modes, and of, likely, producing one build per mode. I don't know how the listing format could accomodate teams that want to build multiple modes in a single build pipeline, apart from producing multiple listing files.

This is very relevant to documentation tools. Especially, if multiple modes are provided in a listing, there needs to be a consensus on how to interpret theme (should all or only some modes match for a doc tool to show the listed tokens?).

@jorenbroekema @drwpow I'd love to have your thoughts on that too.

One could also consider storing platform information in the meta (e.g. is this the PandaCSS build? The SCSS build? The Tailwind build? A multi-tech build for the product?).

As a counterpart, one could argue this information can be provided in the filenames of the token listings being created, and extracted later. This is what I've been doing so far. But FOSS/generic tools could not display platform/mode info reliably if it's not in the meta.

@Sidnioulz Here's an exhaustive list of everything we support preview wise. We also enable top level categorization via tabs, along with the ability to search and filter the tables for easy access using a search bar (not pictured):

Note: The motion preview is animated. The font previews will also preview the font family along with their respective sizes, etc. Size previews are scaled down.