Spacing JSON tokens

[matthewmorek]

Background

Spacing tokens help improve the developer experience of Kotlin and SwiftUI engineers by providing a standardised and efficient way to implement consistent UI spacing in their applications.

Objective

Our goal is to create a universal JSON structure that could be converted from Figma (Tokens Studio) format into a final structure digestible by iOS and Android platforms at build time to generate required measure values and units for apps.

Proposal

Sharing a unified spacing definition across different platforms (Kotlin/Android, SwiftUI/iOS, and Figma for design) can be highly efficient, reduce the probability of mistakes, and ensure a visually consistent user interface. We're looking for comments on the following proposal for a measure tokens format.

JSON Tokens

Based on the information gathered about using spacing/measures in Kotlin and SwiftUI, here’s a suggested sample JSON structure for use with both languages:

{
  "spacing": {
    "none": 0,
    "xxSmall": 2,
    "xSmall": 4,
    "small": 6,
    "xxMedium": 8,
    "xMedium": 12,
    "medium": 16,
    "large": 20,
    "xLarge": 24,
    "xxLarge": 32,
    "xxxLarge": 40,
    "huge": 48,
    "xHuge": 56,
    "xxHuge": 64,
    "xxxHuge": 72,
    "gigantic": 80,
    "xGigantic": 96
  }
}

Specification

The above code can be boiled down to the following structure using JSON Schema. Values are considered as point values, as these seem to be most universally translatable between different mediums.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "spacing": {
      "type": "object",
      "properties": {
        "none": { "type": "integer" },
        "xxSmall": { "type": "integer" },
        "xSmall": { "type": "integer" },
        "small": { "type": "integer" },
        "xxMedium": { "type": "integer" },
        "xMedium": { "type": "integer" },
        "medium": { "type": "integer" },
        "large": { "type": "integer" },
        "xLarge": { "type": "integer" },
        "xxLarge": { "type": "integer" },
        "xxxLarge": { "type": "integer" },
        "huge": { "type": "integer" },
        "xHuge": { "type": "integer" },
        "xxHuge": { "type": "integer" },
        "xxxHuge": { "type": "integer" },
        "gigantic": { "type": "integer" },
        "xGigantic": { "type": "integer" }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Concerns

• Kotlin and SwiftUI typography APIs differ. Will this specification satisfy the requirements of both platforms?
• What about using the proposed naming convention with Figma?
• Parsing & Usage of JSON: both Kotlin and SwiftUI can parse JSON, but there might be differences in how they handle JSON parsing, particularly for edge cases.
• Even though we’re using raw numbers here, which represent points, those points may have different meaning depending on the environment used (Kotlin vs SiwftUI vs Figma).
• Leaving number interpretation (spacing values) up to developers might lead to inconsistencies if not clearly documented. It is very sensitive to scale, and what works in design does not always translate perfectly in code.
• How do we handle potential JSON parsing errors?