Terrazzo Documentation

Terrazzo is a monorepo containing tools for design system automation and color management. Its primary components include:

• Terrazzo CLI: A tool used to generate code from DTCG tokens (formerly known as Cobalt UI). It supports multiple output formats including CSS, Sass, JS/TS, Swift, and Tailwind.
• Terrazzo Color Picker: A specialized color picker component designed for wide gamut and high bit-depth color reproduction.
• Token Lab (Coming Soon): A tool for generating design systems from scratch or starting from existing open-source design systems.

Terrazzo provides specialized integration guides for various styling and programming environments. You can find detailed setup instructions and usage patterns for the following technologies:

• CSS: Standard CSS integration.
• JS/TS: JavaScript and TypeScript integration.
• JSON/Native: Integration for JSON-based or native environments.
• Sass: Integration for Sass preprocessors.
• Tailwind: Integration for Tailwind CSS.
• Vanilla Extract: Integration for Vanilla Extract CSS-in-JS.

The Token Listing Format is a community proposal that provides a predictable, known data structure for design tokens. It improves interoperability between design token tools by consolidating information about:

• Source tokens: The original design values.
• Modes: Variations like light/dark themes.
• Platforms: Where tokens are built (e.g., CSS, Figma, Swift).
• Name Mappings: How a single token name translates across different platforms (e.g., a Figma variable name vs. a CSS variable name).

This format is intended for use by tools such as diffing algorithms, changelog generators, documentation websites, and linting plugins.

A resolver is a DTCG standard meta-file that describes how collections of Design Tokens (DTCG tokens) relate to one another. It acts as an "entry" file for your tokens, similar to how webpack or Rollup works for JavaScript.

Resolvers are used to:

• Flatten multiple token JSON files into a single set.
• Provide contextual token values (e.g., light/dark mode, color themes, or responsive breakpoints).

Resolvers are the successor to legacy "modes" in Terrazzo/Cobalt.

A resolver is a specialized tokens file that can generate multiple sets of tokens from a single JSON source. This is primarily used for implementing design modes (e.g., light vs. dark mode) and theming.

In the Plugin API, the resolver provides a way to access all possible permutations of a token set based on specific inputs. Unlike getTransforms() or setTransforms(), the resolver is used to derive specific token sets by applying inputs to a source file.

Version 0.10.0 introduced breaking changes to align color token ranges with the CSS Color Module 4 specification. Specifically, HSL and HWB color spaces now normalize to a range of 0 - 100 instead of 0 - 1.

Example Change:

// Old (0-1 range)
{
  "colorSpace": "hsl",
  "components": [270, 0.5, 0.4]
}

// New (0-100 range)
{
  "colorSpace": "hsl",
  "components": [270, 50, 40]
}

DTCG (Design Tokens Community Group) tokens are a standard, universal design token format stored in JSON. This format allows you to centrally manage design values and generate code for various output targets like web, print, and native apps.

A token entry typically includes a $type and a $value.

{
  "rebeccapurple": {
    "$type": "color",
    "$value": {
      "colorSpace": "srgb",
      "components": [0.4, 0.2, 0.6]
    }
  }
}