Types

This is a complete reference for all token types supported by Terrazzo. This includes all of the DTCG Format, as well as Terrazzo extensions like link, boolean, string, etc.

Color

Any CSS Module 4 color as defined in DTCG 8.1.

{
  "blue": {
    "600": {
      "$type": "color",
      "$value": {
        "colorSpace": "oklch",
        "channels": [0.6, 0.216564, 269],
        "alpha": 1
      }
    }
  }
}

blue:
  600:
    $type: color
    $value: oklch(60% 0.216564 269)

See also

Color is a frequently-used base token that can be aliased within the following composite token types:

• Border
• Gradient
• Shadow

Tips & recommendations

• Culori is the preferred library for working with color. It’s great both as an accurate, complete color science library that can parse & generate any format. But is also easy-to-use for simple color operations and is fast and lightweight (even on the client).
• Prefer the OKLCH format for declaring colors (why?). It’s not only a futureproof standard; it also allows for better color manipulation than sRGB/hex and is more perceptually-even.

Dimension

A unit of distance as defined in DTCG 8.2.

{
  "space": {
    "md": {
      "$type": "dimension",
      "$value": "16px"
    },
    "lg": {
      "$type": "dimension",
      "$value": "32px"
    }
  }
}

Uses

Dimension is one of the most versatile token types, and can be used for:

• Spacing (margin, padding, gutters)
• Font size
• Line height
• Border width
• Shadow size & width
• …and more

As such, organizing dimension tokens properly (and setting good $descriptions) is important!

See also

Note that dimensions must have units. To specify a number without units, see number.

Tips & recommendations

• Prefer rems over px whenever possible. It’s not only more accessible, it’s also easier to enforce consistent grids & spacing (e.g. 13px doesn’t stand out as much as 0.8125rem).
• Prefer unitless numbers for line heights.

Font Family

A font name (and optional fallbacks) as defined in DTCG 8.3.

{
  "no-fallbacks": {
    "$type": "fontFamily",
    "$value": "Graphik Regular"
  },
  "with-fallbacks": {
    "$type": "fontFamily",
    "$value": ["Graphik Regular", "-system-ui", "Helvetica", "sans-serif"]
  }
}

Notes

• In an old version of the spec, this originally had a $type of font.

See also

• Font Family is a part of the Typography type

Tips & recommendations

• The following universal fallback font stack is recommended for your base typography tokens:

  -apple-system, BlinkMacSystemFont, Segoe UI, Noto Sans, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji, Noto Color Emoji`
  

  This falls back to system fonts (if a glyph isn’t available) and enables emojis in every OS.

Font Weight

A font weight as defined in DTCG 8.4.

{
  "font-weight-default": {
    "$type": "fontWeight",
    "$value": 350
  },
  "font-weight-thick": {
    "$type": "fontWeight",
    "$value": "extra-bold"
  }
}

Aliases

A font weight can be a number from 1 (lightest) – 999 (heaviest), but the following string keywords may also be used (and only the following words):

Notes

• Though this seems similar to a number token, the difference is the string aliases, and the fact that this can only be used for font weights (and typography tokens).

See also

• Font Weight is a part of the Typography type

Duration

A length of time as defined in DTCG 8.5.

{
  "quick": {
    "$type": "duration",
    "$value": "100ms"
  },
  "moderate": {
    "$type": "duration",
    "$value": "0.25s"
  }
}

See also

• Duration can also be used within a transition token.

Tips & recommendations

• Most UI animations should exist between 100ms – 1s (source), ideally on the faster end. Any faster and it seems glitchy or unintentional; any slower and it feels unresponsive.

Cubic Bézier

An easing curve as defined in DTCG 8.6.

{
  "linear": {
    "$type": "cubicBezier",
    "$value": [0, 0, 1, 1]
  },
  "easeOutCubic": {
    "$type": "cubicBezier",
    "$value": [0.33, 1, 0.68, 1]
  },
  "easeInCubic": {
    "$type": "cubicBezier",
    "$value": [0.32, 0, 0.67, 0]
  },
  "easeInOutCubic": {
    "$type": "cubicBezier",
    "$value": [0.65, 0, 0.35, 1]
  }
}

See also

• A Cubic Bézier can be used within a transition token.

Tips & recommendations

• For a list of common easing functions, refer to easings.net.
• For most UI animations, prefer ease-out curves, though in some instances linear or ease-in curves help (guide).

Number

A number as defined in DTCG 8.7.

{
  "line-height-large": {
    "$type": "number",
    "$value": 100
  }
}

Usage

A number token theoretically has many creative uses. But in practice. It can’t be used for a font weight, and has no units like a dimension requires.

However, it can be used for lineHeight within a typography token (as a shorthand for em dimension), as well as stops within a gradient token.

See also

• Gradient
• Typography

Link

Terrazzo extension. A link to a resource such as an image. Not a supported token type outside of Cobalt.

{
  "iconAlert": {
    "$type": "link",
    "$value": "/assets/icons/alert.svg"
  }
}

Usage

Assets such as icons, images, and logos are a critical part of any design system. The behavior of how assets are handled depends on the plugin used. For example, the CSS plugin can optionally embed small files directly into CSS for performance.

There’s also the image optimization plugin (coming soon) that can optimize image and icon assets.

Refer to each plugin’s documentation to learn what special features are available for Link token types.

Boolean

Terrazzo extension. TODO

String (extension)

Terrazzo extension. TODO

Stroke Style

A type of stroke as defined in DTCG 9.2.

{
  "focus-ring-style": {
    "$type": "strokeStyle",
    "$value": "dashed"
  },
  "alert-border-style": {
    "$type": "strokeStyle",
    "$value": {
      "dashArray": ["0.5rem", "0.25rem"],
      "lineCap": "round"
    }
  }
}

Value types

A Stroke Style token’s $value must be either of 2 possible types: string or object

String

A string value as defined in 9.2.1 must be one of the following keywords that correspond to the equivalent CSS line styles:

• solid
• dashed
• dotted
• double
• groove
• ridge
• outset
• inset

Object

An object value as defined in 9.2.2 is an object that must have the following 2 properties:

Notes

• Stroke Style is the only composite token type that can also be used in another composite type (Border)

See also

• Border

Border

A composite type combining a color, dimension, and stroke style, as defined in DTCG 9.3.

{
  "heavy": {
    "$type": "border",
    "$value": {
      "color": "#36363600",
      "width": "3px",
      "style": "solid"
    }
  }
}

Transition

A composite type combining duration and cubicBezier types to form a CSS transition, as defined in DTCG 9.4.

{
  "easeOutQuick": {
    "$type": "transition",
    "$value": {
      "duration": "150ms",
      "delay": "0ms",
      "timingFunction": [0.33, 1, 0.68, 1]
    }
  }
}

Shadow

A composite type combining dimension with a color to form a CSS box-shadow, as defined in DTCG 9.5.

{
  "shadow-md": {
    "$type": "shadow",
    "$value": {
      "offsetX": "0px",
      "offsetY": "4px",
      "blur": "8px",
      "spread": 0,
      "color": "rgb(0, 0, 0, 0.15)"
    }
  }
}

Tips & recommendations

• For smoother shadows, try layering multiple.

Gradient

A composite type combining color and number(normalized to 1) to form the stops of a CSS gradient, as defined in DTCG 9.6.

{
  "rainbow": {
    "$type": "gradient",
    "$value": [
      { "color": "red", "position": 0 },
      { "color": "orange", "position": 0.175 },
      { "color": "yellow", "position": 0.325 },
      { "color": "lawngreen", "position": 0.5 },
      { "color": "blue", "position": 0.675 },
      { "color": "indigo", "position": 0.825 },
      { "color": "violet", "position": 1 }
    ]
  }
}

Notes

• This token is currently missing information on whether this is a linear, radial, or conic gradient. In most Cobalt plugins, linear gradient is assumed.

Tips & recommendations

• Culori is the preferred library for working with color. It’s great both as an accurate, complete color science library that can parse & generate any format. But is also easy-to-use for simple color operations and is fast and lightweight (even on the client).
• Prefer the OKLCH format for declaring colors (why?). It’s not only a futureproof standard; it also allows for better color manipulation than sRGB/hex and is more perceptually-even.

Typography

A composite type combining fontFamily, dimension, and other properties to form a complete typographic style, as defined in DTCG 9.7.

{
  "bodyText": {
    "$type": "typography",
    "$value": {
      "fontFamily": ["Helvetica", "-system-ui", "sans-serif"],
      "fontSize": "1.5rem",
      "fontStyle": "normal",
      "fontWeight": 400,
      "letterSpacing": 0,
      "lineHeight": 1.5,
      "textTransform": "none"
    }
  }
}

Tips & recommendations

• Though the DTCG spec doesn’t technically allow it, declare any/all CSS typography properties on typography tokens. Without these, you couldn’t use things like variable font properties in your design system. Plugins may simply ignore properties that don’t apply for the given build target.