Specification / recommendation for custom types

[lukasoppermann]

Currently the specs only cover a fairly small amount of possible token types. This makes total sense considering how the specification process works.

However from a user and tool developer perspective I very often run into situations where I have to move beyond what is specified.

One typical case is when tokens for types that are not defined are needed.

I think it would be valuable for this case to define how one should create custom types.

The main issue I see is how to create a custom $type property name?

Additionally it would be interesting when it is recommended to use composite types, vs. e.g. an array for multiple numeric values.

[TravisSpomer]

It's my understanding that the recommendation for custom types would be that you use one of the existing types as the $type and then add additional identification necessary as an $extension.

{
  "MyBlendingModeToken": {
    "$type": "string",
    "$value": "subtract",
    "$extensions": {
      "com.example.extendedtype": "blendingMode"
    }
  }
}

That's how you would do it now—there are other issues open that propose various ways of formalizing custom types so that tools that have never heard of com.example.extendedtype would still know its allowed values and format.

[PavelLaptev]

@lukasoppermann is there a problem, just to add your own type? I mean DTCG standardizes types but not restrict them. I actually have the same issue with my Figma plugin — I have a few custom types like grid and blur. Because we don't have a standard for them yet, I just wrote my own.

/**
 * Grid token propoasal
 */

interface GridTokenI extends GenericTokenI {
  $type: "grid";
  $value: {
    columnCount?: number;
    columnGap?: DimensionStringType;
    columnWidth?: DimensionStringType;
    columnMargin?: DimensionStringType;
    rowCount?: number;
    rowGap?: DimensionStringType;
    rowHeight?: DimensionStringType;
    rowMargin?: DimensionStringType;
  };
}

/**
 * Blur token propoasal
 */

interface BlurTokenI extends GenericTokenI {
  $type: "blur";
  $value: {
    role: "layer" | "background";
    blur: DimensionStringType;
  };
}

[lukasoppermann]

@PavelLaptev this is what I currently do. I just add custom- before the type, so custom-grid.

I just figured it would be great if there was a way that was defined so that it would never clash with spec types that get added. Similar to how web components need to be two words with a dash to make sure future html components don't conflict with web components.

@TravisSpomer I didn't know about that, I use extensions for some other metadata but this of course makes sense in a way.

Just a bit cumbersome and how would I use it for objects? There is no object type, is there?

[PavelLaptev]

@lukasoppermann understand, but until there is no grid type in the specs, you don't need to worry about overlapping. When it appears, you can update your type.