@primer/primitives 7.16.0 → 7.17.0-rc.1685583f

package/src/transformers/dimensionToRem.ts

@@ -0,0 +1,56 @@
+import {isDimension} from '../filters'
+import type StyleDictionary from 'style-dictionary'
+import type {Platform} from 'style-dictionary'
+
+/**
+ * @description base font size from options or 16
+ * @param options
+ * @returns number
+ */
+const getBasePxFontSize = (options?: Platform): number => (options && options.basePxFontSize) || 16
+
+/**
+ * @description checks if token value has a specific unit
+ * @param value token value
+ * @param unit unit string like px or value
+ * @returns boolean
+ */
+const hasUnit = (value: string | number, unit: string): boolean => {
+  if (typeof value === 'number') {
+    return false
+  }
+
+  return value.indexOf(unit) > -1
+}
+
+/**
+ * @description converts dimension tokens value to `rem`, ignores `em` as they are relative to the font size of the parent element
+ * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher matches all tokens of $type `dimension`
+ * @transformer returns a `rem` string
+ */
+export const dimensionToRem: StyleDictionary.Transform = {
+  type: `value`,
+  transitive: true,
+  matcher: isDimension,
+  transformer: (token: StyleDictionary.TransformedToken, options?: Platform) => {
+    const baseFont = getBasePxFontSize(options)
+    const floatVal = parseFloat(token.value)
+
+    if (isNaN(floatVal)) {
+      throw new Error(
+        `Invalid dimension token: '${token.name}: ${token.value}' is not valid and cannot be transform to 'rem' \n`,
+      )
+    }
+
+    if (floatVal === 0) {
+      return '0'
+    }
+
+    if (hasUnit(token.value, 'rem') || hasUnit(token.value, 'em')) {
+      return token.value
+    }
+
+    return `${floatVal / baseFont}rem`
+  },
+}

package/src/transformers/dimensionToRemPxArray.ts

@@ -0,0 +1,60 @@
+import {isDimension} from '../filters'
+import type StyleDictionary from 'style-dictionary'
+import type {Platform} from 'style-dictionary'
+
+type SizePx = '0' | `${number}px`
+type SizeRem = '0' | `${number}rem`
+type SizeEm = '0' | `${number}em`
+
+/**
+ * @description base font size from options or 16
+ * @param options
+ * @returns number
+ */
+const getBasePxFontSize = (options?: Platform): number => (options && options.basePxFontSize) || 16
+
+/**
+ * @description checks if token value has a specific unit
+ * @param value token value
+ * @param unit unit string like px or value
+ * @returns boolean
+ */
+const hasUnit = (value: string | number, unit: string): boolean => {
+  if (typeof value === 'number') {
+    return false
+  }
+
+  return value.indexOf(unit) > -1
+}
+
+/**
+ * @description converts dimension tokens value to `rem`, ignores `em` as they are relative to the font size of the parent element
+ * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher matches all tokens of $type `dimension`
+ * @transformer returns an array with the `rem` and `pixel` string
+ */
+export const dimensionToRemPxArray: StyleDictionary.Transform = {
+  type: `value`,
+  transitive: true,
+  matcher: isDimension,
+  transformer: (token: StyleDictionary.TransformedToken, options?: Platform): [SizeRem | SizeEm, SizePx] => {
+    const baseFont = getBasePxFontSize(options)
+    const floatVal = parseFloat(token.value)
+
+    if (isNaN(floatVal)) {
+      throw new Error(
+        `Invalid dimension token: '${token.name}: ${token.value}' is not valid and cannot be transform to 'rem' \n`,
+      )
+    }
+
+    if (floatVal === 0) {
+      return ['0', '0']
+    }
+
+    if (hasUnit(token.value, 'rem') || hasUnit(token.value, 'em')) {
+      return [token.value, `${floatVal * baseFont}px`]
+    }
+
+    return [`${floatVal / baseFont}rem`, `${floatVal}px`]
+  },
+}

package/src/transformers/durationToCss.ts

@@ -0,0 +1,29 @@
+import type StyleDictionary from 'style-dictionary'
+import {isDuration} from '../filters/isDuration'
+
+/**
+ * @description converts duration tokens string value to number with `ms` unit
+ * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher matches all tokens of $type `duration`
+ * @transformer returns a css duration
+ */
+export const durationToCss: StyleDictionary.Transform = {
+  type: `value`,
+  transitive: true,
+  matcher: isDuration,
+  transformer: (token: StyleDictionary.TransformedToken, _options?: StyleDictionary.Platform) => {
+    // throw an error if token value is not a string or does not end with `ms`
+    if (typeof token.value !== `string` || !token.value.endsWith(`ms`)) {
+      throw new Error(`duration token value must be a string with an "ms" unit`)
+    }
+    // get value
+    let value = parseInt(token.value.replace('ms', ''))
+    let unit = `ms`
+    if (value >= 1000) {
+      value = value / 1000
+      unit = `s`
+    }
+    // return value
+    return `${value}${unit}`
+  },
+}

package/src/transformers/figmaAttributes.ts

@@ -0,0 +1,55 @@
+import type StyleDictionary from 'style-dictionary'
+
+type FigmaVariableScope =
+  | 'ALL_SCOPES'
+  | 'TEXT_CONTENT'
+  | 'CORNER_RADIUS'
+  | 'WIDTH_HEIGHT'
+  | 'GAP'
+  | 'ALL_FILLS'
+  | 'FRAME_FILL'
+  | 'SHAPE_FILL'
+  | 'TEXT_FILL'
+  | 'STROKE_COLOR'
+
+const figmaScopes: Record<string, FigmaVariableScope[]> = {
+  all: ['ALL_SCOPES'],
+  radius: ['CORNER_RADIUS'],
+  size: ['WIDTH_HEIGHT'],
+  gap: ['GAP'],
+  bgColor: ['FRAME_FILL', 'SHAPE_FILL'],
+  fgColor: ['TEXT_FILL', 'SHAPE_FILL'],
+  borderColor: ['STROKE_COLOR'],
+}
+
+const getScopes = (scopes: string[] | string | undefined): FigmaVariableScope[] => {
+  if (typeof scopes === 'string') scopes = [scopes]
+  if (Array.isArray(scopes))
+    return scopes
+      .map(scope => {
+        if (scope in figmaScopes) return figmaScopes[scope]
+        throw new Error(`Invalid scope: ${scope}`)
+      })
+      .flat() as FigmaVariableScope[]
+
+  return ['ALL_SCOPES']
+}
+/**
+ * @description retrieves figma attributes from token and adds them to attributes
+ * @type attribute transformer — [StyleDictionary.AttributeTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher matches all tokens
+ * @transformer returns ab object of figma attributes
+ */
+export const figmaAttributes: StyleDictionary.Transform = {
+  type: `attribute`,
+  transformer: (token: StyleDictionary.TransformedToken, platform: StyleDictionary.Platform = {}) => {
+    const {mode, collection, scopes, group, codeSyntax} = token.$extensions?.['org.primer.figma'] || {}
+    return {
+      mode: platform.options?.mode || mode || 'default',
+      collection,
+      group: group || collection,
+      scopes: getScopes(scopes),
+      codeSyntax,
+    }
+  },
+}

package/src/transformers/fontFamilyToCss.ts

@@ -0,0 +1,38 @@
+import type StyleDictionary from 'style-dictionary'
+import {isFontFamily} from '../filters'
+import {getTokenValue} from './utilities/getTokenValue'
+
+const hasSpaceInName = (string: string) => /\s/g.test(string)
+/**
+ * takes a value and returns it if its a string or concats strings in an array quoting strings with spaces
+ * @param value
+ * @returns string
+ */
+export const parseFontFamily = (value: unknown): string => {
+  if (typeof value === 'string') {
+    return value
+  }
+  if (Array.isArray(value)) {
+    return value
+      .map((string: string) => {
+        if (typeof string !== 'string') {
+          throw new Error(`Invalid value in array ${string}, must be a string`)
+        }
+        return hasSpaceInName(string) ? `'${string}'` : string
+      })
+      .join(', ')
+  }
+  throw new Error(`Invalid value ${value}, should be a string or array of strings`)
+}
+/**
+ * @description converts fontFamily tokens value to string
+ * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher matches all tokens of $type `fontFamily`
+ * @transformer returns a number
+ */
+export const fontFamilyToCss: StyleDictionary.Transform = {
+  type: `value`,
+  transitive: true,
+  matcher: isFontFamily,
+  transformer: (token: StyleDictionary.TransformedToken): string => parseFontFamily(getTokenValue(token)),
+}

package/src/transformers/fontWeightToNumber.ts

@@ -0,0 +1,53 @@
+import type StyleDictionary from 'style-dictionary'
+import {isFontWeight} from '../filters'
+import {getTokenValue} from './utilities/getTokenValue'
+
+const fontWeightMatrix: Record<string, string[]> = {
+  '100': ['thin', 'hairline'],
+  '200': ['extra-light', 'ultra-light'],
+  '300': ['light'],
+  '400': ['normal', 'regular', 'book'],
+  '500': ['medium'],
+  '600': ['semi-bold', 'demi-bold'],
+  '700': ['bold'],
+  '800': ['extra-bold', 'ultra-bold'],
+  '900': ['black', 'heavy'],
+  '950': ['extra-black', 'ultra-black'],
+}
+
+export const parseFontWeight = (value: unknown): number => {
+  // throw on anything but string and number
+  if (typeof value !== 'string' && typeof value !== 'number') {
+    throw new Error(`Invalid value ${value}, should be a number or fontWeight string`)
+  }
+  // valid string
+  if (typeof value === 'string') {
+    const key = Object.keys(fontWeightMatrix).find((k: string) => fontWeightMatrix[k].includes(value as string))
+    if (key !== undefined) {
+      return parseInt(key)
+    }
+  }
+  // if number as string
+  if (typeof value === 'string' && typeof parseInt(value) === 'number' && !isNaN(parseInt(value))) {
+    value = parseInt(value)
+  }
+  // return if valid numver
+  if (typeof value === 'number' && value > 0 && value <= 1000) {
+    return value
+  }
+  // invalid value
+  throw new Error(`Invalid value ${value}, should be a number or fontWeight string`)
+}
+
+/**
+ * @description converts fontWeight tokens value to numeric value
+ * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher matches all tokens of $type `fontWeight`
+ * @transformer returns a number
+ */
+export const fontWeightToNumber: StyleDictionary.Transform = {
+  type: `value`,
+  transitive: true,
+  matcher: isFontWeight,
+  transformer: (token: StyleDictionary.TransformedToken): number => parseFontWeight(getTokenValue(token)),
+}

package/src/transformers/index.ts

@@ -0,0 +1,21 @@
+export {borderToCss} from './borderToCss'
+export {colorToHex} from './colorToHex'
+export {colorToHexAlpha} from './colorToHexAlpha'
+export {colorToHexMix} from './colorToHexMix'
+export {colorToRgbAlpha} from './colorToRgbAlpha'
+export {colorToRgbaFloat} from './colorToRgbaFloat'
+export {dimensionToRem} from './dimensionToRem'
+export {dimensionToRemPxArray} from './dimensionToRemPxArray'
+export {dimensionToPixelUnitless} from './dimensionToPixelUnitless'
+export {durationToCss} from './durationToCss'
+export {figmaAttributes} from './figmaAttributes'
+export {fontFamilyToCss} from './fontFamilyToCss'
+export {fontWeightToNumber} from './fontWeightToNumber'
+export {jsonDeprecated} from './jsonDeprecated'
+export {namePathToCamelCase} from './namePathToCamelCase'
+export {namePathToDotNotation} from './namePathToDotNotation'
+export {namePathToFigma} from './namePathToFigma'
+export {namePathToKebabCase} from './namePathToKebabCase'
+export {namePathToSlashNotation} from './namePathToSlashNotation'
+export {shadowToCss} from './shadowToCss'
+export {typographyToCss} from './typographyToCss'

package/src/transformers/jsonDeprecated.ts

@@ -0,0 +1,15 @@
+import {isDeprecated} from '../filters'
+import type StyleDictionary from 'style-dictionary'
+/**
+ * @description replaces tokens value with content of tokens `deprecated` property
+ * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher matches all tokens with a `deprecated` property
+ * @transformer returns `string` specified in `token.deprecated` or `null`
+ */
+export const jsonDeprecated: StyleDictionary.Transform = {
+  type: `value`,
+  transitive: true,
+  matcher: isDeprecated,
+  transformer: (token: StyleDictionary.TransformedToken) =>
+    typeof token.deprecated === 'string' ? token.deprecated.replace(/[{}]/g, '') : null,
+}

package/src/transformers/namePathToCamelCase.ts

@@ -0,0 +1,14 @@
+import type StyleDictionary from 'style-dictionary'
+import {toCamelCase} from '../utilities'
+
+/**
+ * @description converts the [TransformedToken's](https://github.com/amzn/style-dictionary/blob/main/types/TransformedToken.d.ts) `.path` array to a camelCase string, preserves casing of parts
+ * @type name transformer — [StyleDictionary.NameTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher omitted to match all tokens
+ * @transformer returns `string` camelCase
+ */
+export const namePathToCamelCase: StyleDictionary.Transform = {
+  type: `name`,
+  transformer: (token: StyleDictionary.TransformedToken, options?: StyleDictionary.Platform): string =>
+    toCamelCase([options?.prefix || '', ...token.path]),
+}

package/src/transformers/namePathToDotNotation.ts

@@ -0,0 +1,34 @@
+import {upperCaseFirstCharacter} from '../utilities'
+import type StyleDictionary from 'style-dictionary'
+
+/**
+ * camelCase
+ * @scope custom camelCase implementation should only be used within `name path to dot notation` transformer
+ * @description replaces space ` `, dash `-`, underscore `_` and plus `+` by camelCasing e.g. `camel-case` -> `camelCase`
+ * @param string
+ * @returns string
+ */
+const camelCase = (string: string): string => {
+  return string
+    .split(/[\s-_+]+/g)
+    .map((stringPart: string, index: number) => (index === 0 ? stringPart : upperCaseFirstCharacter(stringPart)))
+    .join('')
+}
+/**
+ * @description converts the [TransformedToken's](https://github.com/amzn/style-dictionary/blob/main/types/TransformedToken.d.ts) `.path` array to a dot.notation string
+ * @type name transformer — [StyleDictionary.NameTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher omitted to match all tokens
+ * @transformer returns `string` in dot.notation
+ */
+export const namePathToDotNotation: StyleDictionary.Transform = {
+  type: `name`,
+  transformer: (token: StyleDictionary.TransformedToken, options?: StyleDictionary.Platform): string => {
+    return (
+      [options?.prefix, ...token.path]
+        // remove undefined if exists
+        .filter((part: unknown): part is string => typeof part === 'string' && part !== '@')
+        .map((part: string) => camelCase(part))
+        .join('.')
+    )
+  },
+}

package/src/transformers/namePathToFigma.ts

@@ -0,0 +1,28 @@
+import type StyleDictionary from 'style-dictionary'
+
+export const transformNamePathToFigma = (
+  token: StyleDictionary.TransformedToken,
+  options?: StyleDictionary.Platform,
+): string => {
+  let pathArray = token.path.filter((part: unknown): part is string => part !== '@')
+  if (['fgColor', 'borderColor', 'bgColor'].includes(pathArray[0]) && pathArray.length === 3) {
+    pathArray = [pathArray[0], `${pathArray[1]}-${pathArray[2]}`]
+  }
+  return (
+    [options?.prefix, ...pathArray]
+      // remove undefined if exists
+      .filter((part: unknown): part is string => typeof part === 'string' && part !== '@')
+      .join('/')
+  )
+}
+
+/**
+ * @description converts the [TransformedToken's](https://github.com/amzn/style-dictionary/blob/main/types/TransformedToken.d.ts) `.path` array to a specific figma name
+ * @type name transformer — [StyleDictionary.NameTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher omitted to match all tokens
+ * @transformer returns `string`
+ */
+export const namePathToFigma: StyleDictionary.Transform = {
+  type: `name`,
+  transformer: transformNamePathToFigma,
+}

package/src/transformers/namePathToKebabCase.ts

@@ -0,0 +1,19 @@
+import type StyleDictionary from 'style-dictionary'
+
+/**
+ * @description converts the [TransformedToken's](https://github.com/amzn/style-dictionary/blob/main/types/TransformedToken.d.ts) `.path` array to a kebab-case string, preserves casing of parts
+ * @type name transformer — [StyleDictionary.NameTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher omitted to match all tokens
+ * @transformer returns `string` kebab-case
+ */
+export const namePathToKebabCase: StyleDictionary.Transform = {
+  type: `name`,
+  transformer: (token: StyleDictionary.TransformedToken, options?: StyleDictionary.Platform): string => {
+    return (
+      [options?.prefix, ...token.path]
+        // remove undefined if exists
+        .filter((part: unknown): part is string => typeof part === 'string' && part !== '@')
+        .join('-')
+    )
+  },
+}

package/src/transformers/namePathToSlashNotation.ts

@@ -0,0 +1,19 @@
+import type StyleDictionary from 'style-dictionary'
+
+/**
+ * @description converts the [TransformedToken's](https://github.com/amzn/style-dictionary/blob/main/types/TransformedToken.d.ts) `.path` array to a slash/notation string
+ * @type name transformer — [StyleDictionary.NameTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher omitted to match all tokens
+ * @transformer returns `string` on slash/notation
+ */
+export const namePathToSlashNotation: StyleDictionary.Transform = {
+  type: `name`,
+  transformer: (token: StyleDictionary.TransformedToken, options?: StyleDictionary.Platform): string => {
+    return (
+      [options?.prefix, ...token.path]
+        // remove undefined if exists
+        .filter((part: unknown): part is string => typeof part === 'string' && part !== '@')
+        .join('/')
+    )
+  },
+}

package/src/transformers/shadowToCss.ts

@@ -0,0 +1,37 @@
+import {toHex} from 'color2k'
+import {isShadow} from '../filters'
+import {alpha} from './utilities/alpha'
+import {checkRequiredTokenProperties} from './utilities/checkRequiredTokenProperties'
+import type {ShadowTokenValue} from '../types/ShadowTokenValue'
+import type StyleDictionary from 'style-dictionary'
+import {getTokenValue} from './utilities/getTokenValue'
+
+/**
+ * @description converts w3c shadow tokens in css shadow string
+ * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher matches all tokens of $type `shadow`
+ * @transformer returns css shadow `string`
+ */
+export const shadowToCss: StyleDictionary.Transform = {
+  type: `value`,
+  transitive: true,
+  matcher: isShadow,
+  transformer: (token: StyleDictionary.TransformedToken) => {
+    // extract value
+    const {value}: {value: ShadowTokenValue | ShadowTokenValue[]} = token
+    // turn value into array
+    const shadowValues = !Array.isArray(value) ? [value] : value
+
+    return shadowValues
+      .map((shadow: ShadowTokenValue) => {
+        // if value === string it was probably already transformed
+        if (typeof shadow === 'string') return shadow
+        checkRequiredTokenProperties(shadow, ['color', 'offsetX', 'offsetY', 'blur', 'spread'])
+        /*css box shadow:  inset? | offset-x | offset-y | blur-radius | spread-radius | color */
+        return `${shadow.inset === true ? 'inset ' : ''}${shadow.offsetX} ${shadow.offsetY} ${shadow.blur} ${
+          shadow.spread
+        } ${toHex(alpha(getTokenValue({...token, ...{value: shadow}}, 'color'), shadow.alpha || 1, token))}`
+      })
+      .join(', ')
+  },
+}

package/src/transformers/typographyToCss.ts

@@ -0,0 +1,31 @@
+import type StyleDictionary from 'style-dictionary'
+import {isTypography} from '../filters'
+import type {TypographyTokenValue} from '../types/TypographyTokenValue'
+import {checkRequiredTokenProperties} from './utilities/checkRequiredTokenProperties'
+import {parseFontFamily} from './fontFamilyToCss'
+import {parseFontWeight} from './fontWeightToNumber'
+import {getTokenValue} from './utilities/getTokenValue'
+
+/**
+ * @description converts typograhy token value to css font shorthand
+ * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher matches all tokens of $type `typography`
+ * @transformer returns a css font string
+ */
+export const typographyToCss: StyleDictionary.Transform = {
+  type: `value`,
+  transitive: true,
+  matcher: isTypography,
+  transformer: (token: StyleDictionary.TransformedToken) => {
+    // extract value
+    const value: TypographyTokenValue = getTokenValue(token)
+    // validate token properties
+    checkRequiredTokenProperties(value, ['fontWeight', 'fontSize', 'fontFamily'])
+    // format output
+    return `${value.fontStyle || ''} ${parseFontWeight(getTokenValue(token, 'fontWeight'))} ${value.fontSize}${
+      value.lineHeight ? `/${value.lineHeight}` : ''
+    } ${parseFontFamily(getTokenValue(token, 'fontFamily'))}`
+      .trim()
+      .replace(/\s\s+/g, ' ')
+  },
+}

package/src/transformers/utilities/alpha.ts

@@ -0,0 +1,23 @@
+import {rgba, parseToRgba} from 'color2k'
+import type {TransformedToken} from 'style-dictionary'
+/**
+ * alpha
+ * @description takes a colors string like hex or rgba and returns an rgba color with the specified alpha value
+ * @param color color string like a `#334455` or `rgb(255,200,100)`
+ * @param desiredAlpha number
+ * @returns rgba value
+ */
+export const alpha = (color: string, desiredAlpha: number, token?: TransformedToken): string => {
+  const [r, g, b, a] = parseToRgba(color)
+
+  if (a < 1 && desiredAlpha < 1) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `🚨 You are setting an alpha value of "${desiredAlpha}" for a color with an alpha value (${color}). The previous alpha value will be disregarded as if the color would have been 100% opaque.${
+        token !== undefined ? `\n ↳ Token: "${token.name}" in file: "${token.filePath}"` : ''
+      }`,
+    )
+  }
+
+  return rgba(r, g, b, desiredAlpha)
+}

package/src/transformers/utilities/checkRequiredTokenProperties.ts

@@ -0,0 +1,16 @@
+/**
+ * checks if all required properties exist on token
+ * @param object - tokenValue
+ * @param array - property names
+ * @returns void or throws error
+ */
+export const checkRequiredTokenProperties = (
+  tokenValue: Record<string, unknown>,
+  requiredProperties: readonly string[],
+) => {
+  for (const prop of requiredProperties) {
+    if (prop in tokenValue === false) {
+      throw new Error(`Missing property: ${prop} on token with value ${JSON.stringify(tokenValue)}`)
+    }
+  }
+}

package/src/transformers/utilities/getTokenValue.ts

@@ -0,0 +1,18 @@
+import type StyleDictionary from 'style-dictionary'
+import {invalidTokenValueError, invalidTokenValuePropertyError} from './invalidTokenError'
+
+export const getTokenValue = (token: StyleDictionary.TransformedToken, property?: string) => {
+  if (token.value === undefined) {
+    throw new invalidTokenValueError(token)
+  }
+  // for composite token if subproperty is needed
+  if (typeof property === 'string' && token.value[property] === undefined) {
+    throw new invalidTokenValuePropertyError(token, property)
+  }
+
+  if (typeof property === 'string') {
+    return token.value[property]
+  }
+
+  return token.value
+}

package/src/transformers/utilities/hexToRgbaFloat.ts

@@ -0,0 +1,31 @@
+import type {RgbaFloat} from './isRgbaFloat'
+
+export const hexToRgbaFloat = (hex: string, alpha?: number): RgbaFloat => {
+  // retrieve spots from hex value (hex 3, hex 4, hex 6 or hex 8)
+  let result
+  if (hex.length > 5) {
+    result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})?$/i.exec(hex)
+  } else {
+    result = /^#?([a-f\d]{1})([a-f\d]{1})([a-f\d]{1})([a-f\d]{1})?$/i.exec(hex)
+  }
+
+  if (result === null) {
+    throw new Error('Invalid hex value in "hexToRgbaFloat". Please provide a valid hex3, hex4, hex6 or hex8 value.')
+  }
+  // doule characters if hex 3 or hex 4
+  if (hex.length < 6) {
+    result[1] = `${result[1]}${result[1]}` // double the character
+    result[2] = `${result[2]}${result[2]}` // double the character
+    result[3] = `${result[3]}${result[3]}` // double the character
+    if (result[4]) {
+      result[4] = `${result[4]}${result[4]}` // double the character
+    }
+  }
+  // return parsed rgba float object using alpha value from token, from hex code or defaults to 1
+  return {
+    r: parseInt(result[1], 16) / 255,
+    g: parseInt(result[2], 16) / 255,
+    b: parseInt(result[3], 16) / 255,
+    a: alpha !== undefined ? alpha : result[4] ? parseInt(result[4], 16) / 255 : 1,
+  }
+}

package/src/transformers/utilities/invalidTokenError.ts

@@ -0,0 +1,34 @@
+import type {TransformedToken} from 'style-dictionary'
+import {namePathToDotNotation} from '../namePathToDotNotation'
+
+const composeValueErrorMessage = (token: TransformedToken) => {
+  // eslint-disable-next-line i18n-text/no-en
+  return `Invalid token "${namePathToDotNotation.transformer(token, {})}" in file "${
+    token.filePath
+  }". Transformed value: "${JSON.stringify(token.value)}". ${
+    token.original.value ? `Original value: "${JSON.stringify(token.original.value)}" ` : ''
+  }This may be due to referencing a token that does not exists.`
+}
+
+const composeValuePropertyErrorMessage = (token: TransformedToken, property: string) => {
+  // eslint-disable-next-line i18n-text/no-en
+  return `Invalid property "${property}" of token "${namePathToDotNotation.transformer(token, {})}" in file "${
+    token.filePath
+  }". Transformed property value: "${token.value[property]}". ${
+    token.original.value ? `Original value: "${token.original.value[property]}" ` : ''
+  }This may be due to referencing a token that does not exists.`
+}
+
+export class invalidTokenValueError extends Error {
+  constructor(token: TransformedToken) {
+    super(composeValueErrorMessage(token))
+    Error.captureStackTrace(this, invalidTokenValueError)
+  }
+}
+
+export class invalidTokenValuePropertyError extends Error {
+  constructor(token: TransformedToken, property: string) {
+    super(composeValuePropertyErrorMessage(token, property))
+    Error.captureStackTrace(this, invalidTokenValuePropertyError)
+  }
+}