Colour Tokens Spec

[matthewmorek]

Background

Colour tokens help improve the developer experience of Kotlin and SwiftUI engineers by providing a standardised and efficient way to implement colour consistently 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 values for using in developing mobile applications.

Proposal

Sharing a unified colour/theme 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 colour tokens format.

Specification

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

{
  "semantic": {
    "border": {
      "invertible": {
        "container": "#FFFF8b8f",
        "seperator": "#FF1fFFe8",
        "containerError": "#FFFFff50",
        "containerSelected": "#FFFF7089"
      }
    },
    "background": {
      "accent": {
        "invertible": {
          "info": "#FFFF4b70",
          "alert": "#FFFFe82c",
          "brandPrimary": "#FFFF8c75",
          "success": "#FFFF178b",
          "warning": "#FFFFb863",
          "disabled": "#FFFF3335",
          "brandSecondary": "#FFFFffff",
          "infoSubtle": "#FFFF0a12",
          "alertSubtle": "#FFFF2c06",
          "brandPrimarySubtle": "#FFFF1813",
          "successSubtle": "#FFFF0418",
          "warningSubtle": "#FFFF2011",
          "brandSecondarySubtle": "#FFFF1f22"
        }
      },
      "neutral": {
        "invertible": {
          "low": "#FFFF1213",
          "high": "#FFFF1f22"
        }
      },
      "feature": {
        "fixed": {
          "fuelGas": "#FFFF4067",
          "climateHot": "#FFFFf936",
          "climateMid": "#FFFF7462",
          "climateCool": "#FFFF5e7d",
          "fuelElectric": "#FFFF0894",
          "functionBlack": "#FFFF0000",
          "functionBlackSubtle": "#FFFF2e30"
        }
      }
    },
    "foreground": {
      "accent": {
        "invertible": {
          "info": "#FFFF7089",
          "alert": "#FFFFff50",
          "success": "#FFFF20a4",
          "warning": "#FFFFd776",
          "disabled": "#FFFFa9ad"
        }
      },
      "neutral": {
        "invertible": {
          "primary": "#FFFFffff",
          "secondary": "#FFFFa9ad",
          "tertiary": "#FFFF8b8f"
        }
      },
      "neutralInverse": {
        "fixed": {
          "primary": "#FFFFffff",
          "secondary": "#FFFFa9ad",
          "tertiary": "#FFFF8b8f"
        },
        "invertible": {
          "primary": "#FFFF0102",
          "secondary": "#FFFF1f22",
          "tertiary": "#FFFF3335"
        }
      }
    },
    "overlay": {
      "scrim": {
        "fixed": {
          "semiOpaque": "#FFf5FF00",
          "translucent": "#FF8fFF00",
          "semiTransparent": "#FF3dFF00"
        }
      },
      "state": {
        "fixed": {
          "darken": {
            "dragged": "#FF29FF00",
            "enabled": "#FF00FF00",
            "focused": "#FF1fFF00",
            "hovered": "#FF14FF00",
            "pressed": "#FF1fFF00",
            "resting": "#FF14FF00"
          },
          "lighten": {
            "dragged": "#FF29FFff",
            "enabled": "#FF00FFff",
            "focused": "#FF1fFFff",
            "hovered": "#FF14FFff",
            "pressed": "#FF1fFFff",
            "resting": "#FF14FFff"
          }
        },
        "invertible": {
          "darken": {
            "dragged": "#FF29FFff",
            "enabled": "#FF00FFff",
            "focused": "#FF1fFFff",
            "hovered": "#FF14FFff",
            "pressed": "#FF1fFFff",
            "resting": "#FF14FFff"
          },
          "lighten": {
            "dragged": "#FF29FF02",
            "enabled": "#FF00FF02",
            "focused": "#FF1fFF02",
            "hovered": "#FF14FF02",
            "pressed": "#FF1fFF02",
            "resting": "#FF14FF02"
          }
        }
      }
    }
  }
}

Semantic colour tokens are split by brand and by theme, ensure there's always two JSON files for each brand: dark and light.

Each file will have exactly the same structure, just the values may be different, depending on the intention.

Note

Each value uses a HEX8 colour format with alpha channel as the first number: #{alpha}{colour}, which can translate to #FF00FF02.