Terrazzo Token Tools

https://terrazzo.app/docs
Admin
Terrazzo Token Tools is a work-in-progress suite of tools for design tokens, comprising a CLI to use...
Tokens:13,712
Snippets:112
Trust Score:6.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Tailwind Terrazzo Plugin (bun)

Source: https://terrazzo.app/docs/cli/integrations/tailwind

Installs the necessary Terrazzo CLI and Tailwind plugin using bun. This is another alternative installation method.

```bash
bun i -D @terrazzo/cli @terrazzo/plugin-tailwind
```

--------------------------------

### Install Tailwind Terrazzo Plugin (pnpm)

Source: https://terrazzo.app/docs/cli/integrations/tailwind

Installs the necessary Terrazzo CLI and Tailwind plugin using pnpm. This is an alternative installation method.

```bash
pnpm i -D @terrazzo/cli @terrazzo/plugin-tailwind
```

--------------------------------

### Install Terrazzo CLI using pnpm

Source: https://terrazzo.app/docs/cli

Installs the Terrazzo CLI as a development dependency using pnpm. This command is an alternative for projects managed with pnpm.

```bash
pnpm i -D @terrazzo/cli
```

--------------------------------

### Install Terrazzo CLI using npm

Source: https://terrazzo.app/docs/cli

Installs the Terrazzo CLI as a development dependency using npm. This command is essential for setting up the CLI in your project.

```bash
npm i -D @terrazzo/cli
```

--------------------------------

### Install Terrazzo CLI using bun

Source: https://terrazzo.app/docs/cli

Installs the Terrazzo CLI as a development dependency using bun. This command is suitable for projects utilizing the bun runtime.

```bash
bun i -D @terrazzo/cli
```

--------------------------------

### Install Terrazzo CSS Plugin

Source: https://terrazzo.app/docs/cli/integrations/css

Instructions for installing the Terrazzo CSS plugin and its CLI using npm, pnpm, or bun. This is a prerequisite for using the plugin in your project.

```bash
npm i -D @terrazzo/cli @terrazzo/plugin-css
```

```bash
pnpm i -D @terrazzo/cli @terrazzo/plugin-css
```

```bash
bun i -D @terrazzo/cli @terrazzo/plugin-css
```

--------------------------------

### Install Tailwind Terrazzo Plugin (npm)

Source: https://terrazzo.app/docs/cli/integrations/tailwind

Installs the necessary Terrazzo CLI and Tailwind plugin using npm. This is a prerequisite for using the plugin.

```bash
npm i -D @terrazzo/cli @terrazzo/plugin-tailwind
```

--------------------------------

### Install Terrazzo Parser

Source: https://terrazzo.app/docs/cli/api/js

Installs the Terrazzo parser package as a development dependency. This is a prerequisite for using the Terrazzo JS API for parsing design tokens.

```bash
npm i -D @terrazzo/parser
```

```bash
pnpm i -D @terrazzo/parser
```

```bash
bun i -D @terrazzo/parser
```

--------------------------------

### Install Terrazzo Swift Plugin (npm)

Source: https://terrazzo.app/docs/cli/integrations/swift

Installs the necessary Terrazzo CLI and Swift plugin packages as development dependencies. Requires Node.js 20 or later.

```bash
npm i -D @terrazzo/cli @terrazzo/plugin-swift
```

--------------------------------

### Initialize Terrazzo Project

Source: https://terrazzo.app/docs/cli

Initializes a new Terrazzo project by creating a starter configuration file (`terrazzo.config.js`) and potentially setting up tokens from a popular design system. This command streamlines the initial project setup.

```bash
npx tz init
```

--------------------------------

### Install Sass Plugin with bun

Source: https://terrazzo.app/docs/cli/integrations/sass

Installs the necessary Terrazzo CSS and Sass plugins using bun. These plugins are required for converting tokens to Sass.

```bash
bun i -D @terrazzo/plugin-css @terrazzo/plugin-sass
```

--------------------------------

### Install Terrazzo CLI and Plugins for Package Managers

Source: https://terrazzo.app/docs/cli/integrations/vanilla-extract

Installs the necessary Terrazzo CLI packages for different package managers (npm, pnpm, bun). Requires Node.js 20 or later.

```bash
npm i -D @terrazzo/cli @terrazzo/plugin-css @terrazzo/plugin-vanilla-extract
```

```bash
pnpm i -D @terrazzo/cli @terrazzo/plugin-css @terrazzo/plugin-vanilla-extract
```

```bash
bun i -D @terrazzo/cli @terrazzo/plugin-css @terrazzo/plugin-vanilla-extract
```

--------------------------------

### Terrazzo Sass Plugin Configuration Example

Source: https://terrazzo.app/docs/cli/integrations/sass

An example configuration for the Terrazzo Sass plugin within `terrazzo.config.js`. It shows how to specify the output filename and exclude specific token IDs.

```javascript
import { defineConfig } from "@terrazzo/cli";
import css from "@terrazzo/plugin-css";
import sass from "@terrazzo/plugin-sass";

export default defineConfg({
  plugins: [
    css(),
    sass({
      filename: "index.scss",
      exclude: [],
    }),
  ],
});
```

--------------------------------

### Install @terrazzo/plugin-js with npm, pnpm, or bun

Source: https://terrazzo.app/docs/cli/integrations/js

This snippet shows how to install the Terrazzo JS plugin using different package managers: npm, pnpm, and bun. It is a development dependency.

```bash
npm i -D @terrazzo/plugin-js
```

```bash
pnpm i -D @terrazzo/plugin-js
```

```bash
bun i -D @terrazzo/plugin-js
```

--------------------------------

### Install Sass Plugin with npm

Source: https://terrazzo.app/docs/cli/integrations/sass

Installs the necessary Terrazzo CSS and Sass plugins using npm. These plugins are required for converting tokens to Sass.

```bash
npm i -D @terrazzo/plugin-css @terrazzo/plugin-sass
```

--------------------------------

### Install YAML-to-Momoa for Terrazzo

Source: https://terrazzo.app/docs/cli/api/js

Installs the `yaml-to-momoa` package, which is necessary for enabling YAML support within the Terrazzo JS API. This package is not included by default to minimize the parser's package size.

```bash
npm i -D yaml-to-momoa
```

```bash
pnpm i -D yaml-to-momoa
```

```bash
bun i -D yaml-to-momoa
```

--------------------------------

### Install Sass Plugin with pnpm

Source: https://terrazzo.app/docs/cli/integrations/sass

Installs the necessary Terrazzo CSS and Sass plugins using pnpm. These plugins are required for converting tokens to Sass.

```bash
pnpm i -D @terrazzo/plugin-css @terrazzo/plugin-sass
```

--------------------------------

### Usage Example for Terrazzo JS Plugin Output

Source: https://terrazzo.app/docs/cli/integrations/js

This JavaScript code demonstrates how to import and use the generated token file. It shows a typical pattern for accessing design tokens programmatically after they have been processed by the Terrazzo JS plugin.

```javascript
import token from "./tokens/index.js";

token("color.blue.500");
```

--------------------------------

### Configure Terrazzo CSS Plugin

Source: https://terrazzo.app/docs/cli/integrations/css

Example configuration for the Terrazzo CSS plugin in `terrazzo.config.js`. This shows how to define the output filename, customize variable names, and specify base selectors and color schemes.

```javascript
import { defineConfig } from "@terrazzo/cli";
import pluginCSS from "@terrazzo/plugin-css";

export default defineConfig({
  plugins: [
    pluginCSS({
      filename: "tokens.css",
      variableName: (id) => id.replace(/\./g, "-"),
      baseSelector: ":root",
      baseScheme: "light dark", // Optional: support both light and dark themes
    }),
  ],
});
```

--------------------------------

### DTCG Color Token Example (JSON)

Source: https://terrazzo.app/docs/guides/dtcg

An example of a DTCG token representing a color. DTCG tokens are stored in JSON format and include a type and value, enabling centralized management and code generation for various output targets.

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

--------------------------------

### Configure core/colorspace Lint Rule (JavaScript)

Source: https://terrazzo.app/docs/cli/lint

This example shows how to configure the 'core/colorspace' lint rule in Terrazzo. It specifies the required color space (e.g., 'oklab') and provides an option to ignore certain tokens using globs.

```javascript
import { defineConfig } from "@terrazzo/cli";

export default defineConfig({
  lint: {
    rules: {
      "core/colorspace": ["error", { colorSpace: "oklab" }],
    },
  },
});
```

--------------------------------

### JSON Token with Rec2020 Color

Source: https://terrazzo.app/docs/cli/integrations/css

A JSON example defining a color token using the `Rec2020` color space. This showcases the input format for advanced color values handled by the plugin.

```json
{
  "color": {
    "blue": {
      "600": {
        "$type": "color",
        "$value": {
          "colorSpace": "oklch",
          "components": [0.5618, 0.227, 252.19] // Rec2020 color
        }
      }
    }
  }
}
```

--------------------------------

### Set Plugin Name - JavaScript

Source: https://terrazzo.app/docs/cli/api/plugin-development

The 'name' option provides a unique identifier for the plugin, which is useful for debugging and error reporting. This example shows how to set the name property within the plugin function.

```javascript
export default function myPlugin() {
  return {
    name: "my-plugin",
  };
}
```

--------------------------------

### Access Configuration in config() Hook - JavaScript

Source: https://terrazzo.app/docs/cli/api/plugin-development

The 'config()' hook allows plugins to access the resolved user configuration after all plugins are registered. This hook is read-only and useful for retrieving settings like 'outDir'.

```javascript
export default function myPlugin() {
  let outDir;

  return {
    name: "my-plugin",
    config(userConfig) {
      outDir = userConfig.outDir;
    },
  };
}
```

--------------------------------

### Configure Sass Plugin in terrazzo.config.js

Source: https://terrazzo.app/docs/cli/integrations/sass

Configures the Terrazzo build process to include the CSS and Sass plugins. This example demonstrates setting filenames and mode selectors for the CSS output and the filename for the Sass output.

```javascript
import { defineConfig } from "@terrazzo/cli";
import css from "@terrazzo/plugin-css";
import sass from "@terrazzo/plugin-sass";

export default defineConfig({
  plugins: [
    css({
      filename: "tokens.css",
      modeSelectors: [
        { mode: "light", selectors: ["@media (prefers-color-scheme: light)"] },
        { mode: "dark", selectors: ["@media (prefers-color-scheme: dark)"] },
      ],
    }),
    sass({
      filename: "index.scss",
    }),
  ],
});
```

--------------------------------

### Implement a CSS Token Transformer in JavaScript

Source: https://terrazzo.app/docs/cli/api/plugin-development

This JavaScript snippet demonstrates how to create a Terrazzo plugin to transform color tokens into CSS variables. It utilizes `culori` for color formatting and `scule` for kebab-case conversion. The `transform` function processes tokens, and the `build` function generates a CSS file with CSS variables.

```javascript
import { formatCss } from "culori";
import { kebabCase } from "scule";

export default function clampColor(userOptions) {
  return {
    name: "my-css-plugin",
    async transform({ tokens, setTransform }) {
      for (const [id, token] of Object.entries(tokens)) {
        switch (token.$type) {
          case "color": {
            setTransform(id, {
              format: "css",
              localID: `--${kebabCase(id)}`,
              value: formatCss(token.$value), // convert original format into CSS-friendly value
            });
            break;
          }

          // … other $types here
        }
      }
    },
    async build({ getTransforms, outputFile }) {
      const output = [];
      output.push(":root {");
      for (const token of getTransforms({ format: "css", id: "*" })) {
        // renders "--my-token-id: color(srgb 0.6 0 0.3);"
        output.push(`  ${token.localID ?? token.token.id}: ${token.value};`);
      }
      output.push("}", "");
      outputFile("my-file.css", output.join("\n"));
    },
  };
}
```

--------------------------------

### Generated CSS with Color Gamut Support

Source: https://terrazzo.app/docs/cli/integrations/css

Example of CSS output generated by the Terrazzo plugin for a Rec2020 color token. It includes media queries to ensure the color is displayed correctly across different color gamuts (sRGB, P3, Rec2020).

```css
:root {
  --color-blue-600: oklch(0.5618 0.1686 252.19); /* srgb safe color */
}

@media (color-gamut: p3) {
  :root {
    --color-blue-600: oklch(0.5618 0.2171 252.19); /* p3 safe color */
  }
}

@media (color-gamut: rec2020) {
  :root {
    --color-blue-600: oklch(0.5618 0.227 252.19);
  }
}
```

--------------------------------

### Configure core/duplicate-values Lint Rule (JavaScript)

Source: https://terrazzo.app/docs/cli/lint

This example demonstrates how to configure the 'core/duplicate-values' lint rule in Terrazzo. It shows how to enable the rule with an 'error' severity and optionally ignore specific tokens.

```javascript
import { defineConfig } from "@terrazzo/cli";

export default defineConfig({
  lint: {
    rules: {
      "core/duplicate-values": "error",
    },
  },
});
```

--------------------------------

### Use CSS Variables in Button Component

Source: https://terrazzo.app/docs/cli/integrations/css

Example of how to use the generated CSS variables within a CSS file to style a button component. Demonstrates applying colors and typography tokens.

```css
.button {
  color: var(--color-action-primary);
  font-family: var(--typography-family-default);
  font-size: var(--typography-font-size-200);
}
```

--------------------------------

### Build Token Values into CSS File with JavaScript Plugin

Source: https://terrazzo.app/docs/cli/api/plugin-development

This JavaScript code snippet demonstrates a Terrazzo plugin's build step. It accesses color tokens, transforms them, and then writes them into a 'tokens.css' file. It utilizes the `tokens`, `getTransforms`, and `outputFile` options provided to the build function. The output is a string representing CSS variables.

```javascript
export default function myPlugin() {
  return {
    name: "my-plugin",
    async build({ tokens, getTransforms, outputFile }) {
      const output = [];

      output.push("const tokens = {");

      const colorTokens = getTransforms({
        format: "js",
        id: "color.*",
        mode: ".",
      });
      for (const token of colorTokens) {
        output.push(`  ${token.localID ?? token.token.id}: ${token.value},`);
      }
      output.push("};", "", "export default tokens;", "");

      outputFile("tokens.css", output.join("\n"));
    },
  };
}
```

--------------------------------

### Set Plugin Enforcement Order - JavaScript

Source: https://terrazzo.app/docs/cli/api/plugin-development

The 'enforce' option controls when a plugin runs in the build process. Options include 'pre' (run first), 'post' (run last), or undefined (run in array order). This is useful for managing plugin dependencies.

```javascript
export default function myPlugin() {
  return {
    name: "my-plugin",
    enforce: "pre", // run before all other plugins
  };
}
```

--------------------------------

### Configure Terrazzo to Use a Custom Plugin in JavaScript

Source: https://terrazzo.app/docs/cli/api/plugin-development

This JavaScript code shows how to configure Terrazzo to use a custom plugin. It imports the `defineConfig` function from `@terrazzo/cli` and the custom plugin, then includes the plugin in the `plugins` array within the configuration object.

```javascript
import { defineConfig } from "@terrazzo/cli";
import myCssPlugin from "./my-css-plugin.js";

export default defineConfig({
  plugins: [myCssPlugin()],
});
```

--------------------------------

### Configure core/max-gamut Lint Rule (JavaScript)

Source: https://terrazzo.app/docs/cli/lint

This example configures the 'core/max-gamut' lint rule in Terrazzo to enforce color gamut compliance. It allows specifying the target gamut (e.g., 'srgb') and ignoring certain tokens.

```javascript
import { defineConfig } from "@terrazzo/cli";

export default defineConfig({
  lint: {
    rules: {
      "core/max-gamut": ["error", { format: "srgb" }],
    },
  },
});
```

--------------------------------

### Define Font Family Tokens (JSON)

Source: https://terrazzo.app/docs/reference/tokens

Provides examples of defining font family tokens in JSON for Terrazzo. It shows how to specify a single font name or an array of font names with fallbacks.

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

--------------------------------

### Define Font Weight Tokens (JSON)

Source: https://terrazzo.app/docs/reference/tokens

Shows how to define font weight tokens using JSON in Terrazzo. This includes examples of using numeric values and predefined string aliases for font weights.

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

--------------------------------

### Configure Terrazzo to Use Custom Lint Rule

Source: https://terrazzo.app/docs/cli/api/plugin-development

This JavaScript configuration file shows how to enable a custom lint rule defined in a Terrazzo plugin. It imports the plugin and specifies the 'primary' rule to be treated as an 'error' within the `lint.rules` configuration.

```javascript
import { defineConfig } from "@terrazzo/cli";
import myPlugin from "./my-plugin/index.js";

export default defineConfig({
  plugin: [myPlugin()],
  lint: {
    rules: {
      primary: "error", // error on the "primary" rule violation
    },
  },
});

```

--------------------------------

### Configure Color Depth in Terrazzo CSS

Source: https://terrazzo.app/docs/cli/integrations/css

Configuration option to set the color depth for generated CSS variables. This example shows how to specify `colorDepth` in `terrazzo.config.js` to control the precision of color values.

```javascript
export default defineConfig({
  plugins: [
    css({
      colorDepth: 30, // 24, 30, 36, 48, or "unlimited"
    }),
  ],
};
```

--------------------------------

### Define ESLint-like Lint Rule for Design Tokens

Source: https://terrazzo.app/docs/cli/api/plugin-development

This JavaScript code defines a custom lint rule for Terrazzo that checks for the disallowed use of 'primary' or 'secondary' in token names. It mimics the structure of ESLint rules, accepting a context object and reporting violations using `context.report()`.

```javascript
export default {
  meta: {
    docs: {
      description: "Don’t use the words “primary” or “secondary” in names.",
      url: "https://my-docs.com/rule-primary",
    },
  },
  defaultOptions: [],
  create(context) {
    for (const [id, token] of Object.entries(context.tokens)) {
      if (["primary", "secondary"].includes(id.toLowerCase())) {
        context.report({
          message: `Invalid token name: "${id}"`, // Error message to display to the user
          node: token.source.node, // this will point to the precise token in source code
        });
      }
    }
  },
};

```

--------------------------------

### Register Custom Lint Rule in Terrazzo Plugin

Source: https://terrazzo.app/docs/cli/api/plugin-development

This JavaScript code demonstrates how to create a Terrazzo plugin that exposes a custom lint rule. The plugin function returns an object with a `lint()` method, which in turn returns an object containing the registered lint rules.

```javascript
import primary from "./rule-primary.js";

export default function myPlugin() {
  return {
    name: "my-plugin",
    lint() {
      return {
        primary,
      };
    },
  };
}

```

--------------------------------

### Transform API for Token Manipulation in Terrazzo

Source: https://terrazzo.app/docs/cli/api/js

Illustrates the use of the Transform API in Terrazzo JS API to dynamically modify token data during the parsing process. It shows examples of injecting new token values and transforming existing color token values using AST visitors.

```javascript
import { parse } from "@terrazzo/parser";
import culori from "culori";
import fs from "node:fs/promises";

const filename = new URL("./tokens/my-tokens.json", import.meta.url);
const config = defineConfig({}, { cwd: new URL(import.meta.url) });
const { sources } = await parse(
  [{ filename, src: await fs.readFile(filename) }],
  {
    config,
    transform: {
      // Dynamically inject some colors
      group(json, path, ast) {
        if (path.startsWith("color.base.slate")) {
          return {
            ...json,
            "1000": { $value: "#242424" }, // dynamically inject color.base.slate.1000
          };
        }
      },

      // Transform color tokens, converting them from CSS strings into color objects
      color(json, path, ast) {
        const color = culori.parse(json.$value);
        if (!color) return;

        const { mode: colorSpace, alpha, ...components } = color;

        return {
          ...json,
          $value: { colorSpace, components, alpha },
        };
      },
    },
  }
);
```

--------------------------------

### Define CSS Variables for Colors (CSS)

Source: https://terrazzo.app/docs/guides/modes

This CSS defines root variables for various color tokens, including accessibility variations. This is part of the manual setup required when not leveraging color modes effectively.

```css
:root {
  --color-green-light: #2da44e;
  --color-green-light-high-contrast: #117f32;
  --color-green-light-protanopia-deuteranopia: #0088ff;
  --color-green-light-tritanopia: #0088ff;
  --color-green-dark: #2ea043;
  --color-green-dark-high-contrast: #09b43a;
  --color-green-dark-protanopia-deuteranopia: #1585fd;
  --color-green-dark-tritanopia: #1585fd;
}
```

--------------------------------

### Transform Tokens for CSS and TypeScript Formats

Source: https://terrazzo.app/docs/cli/api/plugin-development

This JavaScript code defines a Terrazzo plugin that transforms color tokens. It uses the `setTransform` function to convert a blue color token's value into both a JavaScript object using `rgb()` and a TypeScript type definition.

```javascript
import { rgb } from "culori";

export default function myPlugin() {
  name: "my-plugin",
  return {
    async transform({ tokens, setTransform }) {
      setTransform("color.base.blue.500", {
        format: "js",
        localID: "color.base.blue.500",
        value: rgb(tokens["color.base.blue.500"].$value),
        mode: ".",
      });
      setTransform("color.base.blue.500", {
        format: "ts",
        localID: "color.base.blue.500",
        value: "ReturnType<typeof rgb>",
        mode: ".",
      });
    }
  };
}

```

--------------------------------

### Basic Usage of Terrazzo JS API

Source: https://terrazzo.app/docs/cli/api/js

Demonstrates the fundamental steps of using the Terrazzo JS API: configuring the parser, parsing token files, and building the tokens. It reads tokens from a JSON file and writes the built output to new files.

```javascript
import { defineConfig, parse, build } from "@terrazzo/parser";
import fs from "node:fs/promises";

const config = defineConfig(
  {
    // config options
  },
  { cwd: new URL(import.meta.url) }
);

const filename = new URL("./tokens/my-tokens.json", import.meta.url);
const { tokens, sources } = await parse(
  [{ filename, src: await fs.readFile(filename) }],
  { config }
);
const buildResult = await build(tokens, { sources, config });

for (const { filename, contents } of buildResult) {
  await fs.writeFile(filename, contents);
}
```

--------------------------------

### Build Swift Asset Catalog with Terrazzo (bash)

Source: https://terrazzo.app/docs/cli/integrations/swift

Executes the Terrazzo build command to generate the Swift asset catalog based on the project's configuration. This command creates a `./tokens/Tokens.xcassets` file.

```bash
npx tz build
```

--------------------------------

### Debug All Terrazzo Scopes

Source: https://terrazzo.app/docs/cli

Builds Terrazzo tokens while enabling debugging for all scopes. This is useful for comprehensive troubleshooting of the build process.

```bash
DEBUG=* tz build
```

--------------------------------

### Configure Terrazzo for Swift Asset Catalog Generation (JavaScript)

Source: https://terrazzo.app/docs/cli/integrations/swift

Sets up the Terrazzo configuration file (`terrazzo.config.js`) to use the Swift plugin for generating asset catalogs. Specifies the output directory and the Swift plugin with a custom catalog name.

```javascript
import { defineConfig } from "@terrazzo/cli";
import swift from "@terrazzo/plugin-swift";

export default defineConfig({
  outDir: "./tokens/",
  plugins: [
    swift({
      catalogName: "Tokens",
    }),
  ],
});
```

--------------------------------

### Configure Utility CSS Generation with Terrazzo CLI

Source: https://terrazzo.app/docs/cli/integrations/css

This configuration sets up the Terrazzo CLI to generate utility CSS classes. It uses the `@terrazzo/plugin-css` with a `utility` option to map token groups (like `bg`, `border`, `font`) to specific token patterns, enabling fine-grained control over the generated CSS.

```javascript
import { defineConfig } from "@terrazzo/cli";
import css from "@terrazzo/plugin-css";
import { kebabCase } from "scule";

export default defineConfig({
  plugins: [
    css({
      utility: {
        bg: ["color.*-bg", "gradient.*"],
        border: ["border.*"],
        font: ["typography.*"],
        layout: ["space.*"],
        shadow: ["shadow.*"],
        text: ["color.*-text", "gradient.*"],
      },
    }),
  ],
});
```

--------------------------------

### Configure Terrazzo for Vanilla Extract Themes

Source: https://terrazzo.app/docs/cli/integrations/vanilla-extract

Sets up the `terrazzo.config.js` file to use the CSS and Vanilla Extract plugins. This includes defining theme configurations for scoped or global themes.

```javascript
import { defineConfig } from "@terrazzo/cli";
import css from "@terrazzo/plugin-css";
import vanillaExtract from "@terrazzo/plugin-vanilla-extract";

export default defineConfig({
  plugins: [
    css({
      // Optional: control the final CSS variable names
      variableName: (id) => id.replace(/\./g, "-"),
      // Optional: pass `skipBuild: true` to not generate a .css file if only using Vanilla Extract.
      skipBuild: false,
    }),

    vanillaExtract({
      filename: "themes.css.ts",
      // Use global CSS vars (recommended). Your Vanilla Extract CSS is still scoped.
      globalThemeContract: true,

      // Option 1: scoped themes
      themes: {
        light: { mode: [".", "light"] },
        dark: { mode: [".", "dark"] },
      },

      // Option 2: global themes (in case you have code outside Vanilla Extract)
      globalThemes: {
        globalLight: { selector: "[data-color-mode=light]", mode: [".", "light"] },
        globalDark: { selector: "[data-color-mode=dark]", mode: [".", "dark"] },
      },
    }),
  ],
});
```

--------------------------------

### Configure Minimum Color Contrast (JavaScript)

Source: https://terrazzo.app/docs/cli/lint

Enforces that color tokens meet WCAG 2 minimum contrast ratios. This rule requires defining pairs of foreground and background tokens to test, with an option to specify if it's for large text.

```javascript
import { defineConfig } from "@terrazzo/cli";

export default defineConfig({
  lint: {
    rules: {
      "a11y/min-contrast": [
        "error",
        {
          level: "AA",
          pairs: [
            {
              foreground: "color.text-primary",
              background: "color.bg-primary",
            },
            {
              foreground: "color.error-text",
              background: "color.error-bg",
            },
            {
              foreground: "color.action-text",
              background: "color.action-bg",
            },
          ],
        },
      ],
    },
  },
});
```

--------------------------------

### Terrazzo CSS Plugin Basic Light/Dark Mode Selectors

Source: https://terrazzo.app/docs/cli/integrations/css

This JavaScript configuration demonstrates a common pattern for setting up light and dark modes using the Terrazzo CSS plugin. It defines selectors for `@media (prefers-color-scheme)` and `[data-mode]` attributes, also specifying the `color-scheme` property for each mode.

```javascript
import { defineConfig } from "@terrazzo/cli";
import css from "@terrazzo/plugin-css";

export default defineConfig({
  plugins: [
    css({
      modeSelectors: [
        {
          mode: "light",
          selectors: [
            "@media (prefers-color-scheme: light)",
            '[data-mode="light"]',
          ],
          scheme: "light", // Optional: set color-scheme for light mode
        },
        {
          mode: "dark",
          selectors: [
            "@media (prefers-color-scheme: dark)",
            '[data-mode="dark"]',
          ],
          scheme: "dark", // Optional: set color-scheme for dark mode
        },
      ],
    }),
  ],
});
```

--------------------------------

### Configure Terrazzo for Tailwind CSS

Source: https://terrazzo.app/docs/cli/integrations/tailwind

Configures the Terrazzo CLI to use the Tailwind plugin, specifying output directory, plugins, and theme mappings for Tailwind CSS.

```javascript
import { defineConfig } from "@terrazzo/cli";
import css from "@terrazzo/plugin-css";
import tailwind from "@terrazzo/plugin-tailwind";

export default defineConfig({
  outDir: "./tokens/",
  plugins: [
    css(),
    tailwind({
      filename: "tailwind.js",

      theme: {
        /** @see https://tailwindcss.com/docs/configuration#theme */
        colors: ["color.*"],
        font: {
          sans: "typography.family.base",
        },
        spacing: ["spacing.*"],
        radius: ["borderRadius.*"],
      },
    }),
  ],
});
```

--------------------------------

### Default Terrazzo CLI Configuration (JavaScript)

Source: https://terrazzo.app/docs/cli/config

This snippet shows a default configuration file for the Terrazzo CLI. It specifies token sources, the output directory, and includes a CSS plugin. It assumes an ES module environment or a .mjs file extension.

```javascript
import { defineConfig } from "@terrazzo/cli";
import css from "@terrazzo/plugin-css";

export default defineConfig({
  tokens: ["./tokens.json"],
  outDir: "./tokens/",

  plugins: [
    css(), // generate .css files
  ],

  lint: {
    rules: {
      // my lint rules
    },
  },
});
```

--------------------------------

### Dynamic Mode Handling in CSS

Source: https://terrazzo.app/docs/cli/integrations/css

Illustrates how Terrazzo handles dynamic mode switching in CSS. When upstream values change, aliases are redeclared to maintain consistency between light and dark themes.

```css
  :root {
    --neutral-3: #e6eaef;
    --color-bg-alt: var(--neutral-3);
  }

  [data-theme='dark'] {
    --neutral-3: #212830;
+   --color-bg-alt: var(--neutral-3);
  }
```

--------------------------------

### Debug Terrazzo Plugin Scope

Source: https://terrazzo.app/docs/cli

Builds Terrazzo tokens with debugging enabled for plugin-related scopes. This is helpful for identifying problems within Terrazzo plugins.

```bash
DEBUG=plugin:* tz build
```

--------------------------------

### Configure Terrazzo Linting Rules (JavaScript)

Source: https://terrazzo.app/docs/cli/lint

This snippet demonstrates how to configure various linting rules for Terrazzo tokens in the terrazzo.config.js file. It shows how to set severity levels and provide options for rules like 'core/consistent-naming'.

```javascript
import { defineConfig } from "@terrazzo/cli";

export default defineConfig({
  lint: {
    rules: {
      "core/colorspace": "warn",
      "core/consistent-naming": ["error", { format: "kebab-case" }],
      "core/duplicate-values": "off",
    },
  },
});
```

--------------------------------

### Update package.json dependencies

Source: https://terrazzo.app/docs/cli/migrating

Replace Cobalt UI package scopes with Terrazzo scopes in your package.json file and reinstall dependencies. This ensures you are using the latest versions and features of Terrazzo.

```json
    "devDependencies": {
-     "@cobalt-ui/cli": "^1.x",
-     "@cobalt-ui/plugin-css": "^1.x",
-     "@cobalt-ui/plugin-js": "^1.x",
-     "@cobalt-ui/plugin-sass": "^1.x",
+     "@terrazzo/cli": "^2.x"
+     "@terrazzo/plugin-css": "^2.x"
+     "@terrazzo/plugin-js": "^2.x"
+     "@terrazzo/plugin-sass": "^2.x"
    }
```

--------------------------------

### CSS Output for Multiple Variable Transformation

Source: https://terrazzo.app/docs/cli/integrations/css

Demonstrates the CSS output when the `transform` function returns an object. This generates multiple CSS variables based on the token and the keys provided in the returned object.

```css
:root {
  --typography-base-font-family: Inter;
  --typography-base-font-size: 1rem;
}
```

--------------------------------

### Recommended Font Stack (Text)

Source: https://terrazzo.app/docs/reference/tokens

Presents a recommended universal fallback font stack for base typography tokens. This stack prioritizes system fonts and includes fallbacks for emojis.

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

--------------------------------

### CSS for Themed Button Backgrounds (CSS)

Source: https://terrazzo.app/docs/guides/modes

This CSS demonstrates the complexity of applying theme-aware styles for a button's background without using color modes. Each color mode requires a separate class and CSS variable.

```css
/* button must have theme-aware styles */
.button {
  background: var(--button-bg-light);
}
.color-mode-light-high-contrast .button {
  background: var(--button-bg-light-high-contrast);
}
.color-mode-light-protanopia-deuteranopia .button {
  background: var(--button-bg-light-protanopia-deuteranopia);
}
.color-mode-light-tritanopia .button {
  background: var(--button-bg-light-tritanopia);
}
.color-mode-dark .button {
  background: var(--button-bg-dark);
}
.color-mode-dark-high-contrast .button {
  background: var(--button-bg-dark-high-contrast);
}
.color-mode-dark-protanopia-deuteranopia .button {
  background: var(--button-bg-dark-protanopia-deuteranopia);
}
.color-mode-dark-tritanopia .button {
  background: var(--button-bg-dark-tritanopia);
}
```

--------------------------------

### Debug Terrazzo Parser Scope

Source: https://terrazzo.app/docs/cli

Builds Terrazzo tokens with debugging enabled specifically for the `@terrazzo/parser` scope. This helps in diagnosing issues related to token parsing.

```bash
DEBUG=parser:* tz build
```

--------------------------------

### Map All Color Tokens Using Array (Terser)

Source: https://terrazzo.app/docs/cli/integrations/tailwind

The most concise method for mapping all color tokens to Tailwind CSS theme properties using a single array glob.

```javascript
tailwind({
  theme: {
    color: ["color.*"],
  },
});
```

--------------------------------

### Configure core/consistent-naming Lint Rule (JavaScript)

Source: https://terrazzo.app/docs/cli/lint

This snippet illustrates the configuration for the 'core/consistent-naming' lint rule in Terrazzo. It allows setting the naming format (e.g., 'kebab-case') and ignoring specific tokens.

```javascript
import { defineConfig } from "@terrazzo/cli";

export default defineConfig({
  lint: {
    rules: {
      "core/consistent-naming": ["error", { format: "kebab-case" }],
    },
  },
});
```

--------------------------------

### Configure Terrazzo CSS Plugin with Mode Selectors

Source: https://terrazzo.app/docs/cli/integrations/css

This configuration sets up the Terrazzo CSS plugin to generate a 'tokens.css' file. It includes defining mode selectors for light and dark color schemes, which translate into CSS media queries and attribute selectors.

```javascript
import { defineConfig } from "@terrazzo/cli";
import css from "@terrazzo/plugin-css";
import { kebabCase } from "scule";

export default defineConfig({
  plugins: [
    css({
      filename: "tokens.css",
      exclude: [], // ex: ["beta.*"] will exclude all tokens in the "beta" top-level group
      baseScheme: "light dark", // Optional: set base color-scheme
      modeSelectors: [
        {
          mode: "light",
          selectors: [
            "@media (prefers-color-scheme: light)",
            '[data-mode="light"]',
          ],
          scheme: "light", // Optional: set color-scheme for this mode
        },
        {
          mode: "dark",
          selectors: [
            "@media (prefers-color-scheme: dark)",
            '[data-mode="dark"]',
          ],
          scheme: "dark", // Optional: set color-scheme for this mode
        },
        { mode: "mobile", selectors: ["@media (width < 600px)"] },
        { mode: "desktop", selectors: ["@media (width >= 600px)"] },
        {
          mode: "reduced-motion",
          selectors: ["@media (prefers-reduced-motion)"],
        },
      ],
      variableName: (id) => kebabCase(id),
    }),
  ],
});
```

--------------------------------

### Map Color Tokens to Tailwind Theme

Source: https://terrazzo.app/docs/cli/integrations/tailwind

Demonstrates how to explicitly map individual color tokens to Tailwind CSS theme properties. This provides fine-grained control over color mappings.

```javascript
tailwind({
  theme: {
    color: {
      blue: {
        0: "color.blue.0",
        1: "color.blue.1",
        // …
        9: "color.blue.9",
      },
    },
  },
});
```

--------------------------------

### Configure Terrazzo JS Plugin in terrazzo.config.js

Source: https://terrazzo.app/docs/cli/integrations/js

This JavaScript configuration sets up the Terrazzo CLI with the JS plugin. It specifies output filenames for JavaScript and TypeScript, and optionally for JSON. The plugin processes design tokens into usable code formats.

```javascript
import { defineConfig } from "@terrazzo/cli";
import pluginJS from "@terrazzo/plugin-js";

export default defineConfig({
  plugins: [
    pluginJS({
      js: "index.js",
      ts: "index.d.ts",
      json: false, // set to a filename to generate JSON
    }),
  ],
});
```

--------------------------------

### Update Terrazzo configuration file

Source: https://terrazzo.app/docs/cli/migrating

Rename `tokens.config.js` to `terrazzo.config.js` and use the `defineConfig` wrapper from `@terrazzo/cli` for type safety and validation.

```javascript
+ import { defineConfig } from "@terrazzo/cli";

- export default {
+ export default defineConfig({
    // plugins, settings
- };
+ });
```

--------------------------------

### JSON Typography Token Definition with Modes

Source: https://terrazzo.app/docs/guides/modes

A JSON object defining typography token sizes, including variations for different modes (e.g., xSmall, Small, Medium). This structure allows for flexible theming and accessibility adjustments.

```json
{
  "typography": {
    "size": {
      "$type": "dimension",
      "title1": {
        "$value": "28px",
        "$extensions": {
          "mode": {
            "xSmall": "25px",
            "Small": "26px",
            "Medium": "27px",
            "Large": "28px",
            "xLarge": "30px",
            "xxLarge": "32px",
            "xxxLarge": "32px"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Configure core/descriptions Lint Rule (JavaScript)

Source: https://terrazzo.app/docs/cli/lint

This snippet shows the configuration for the 'core/descriptions' lint rule in Terrazzo, ensuring tokens have descriptions. It can be set to 'error' and allows ignoring specific tokens.

```javascript
import { defineConfig } from "@terrazzo/cli";

export default defineConfig({
  lint: {
    rules: {
      "core/descriptions": "error",
    },
  },
});
```

--------------------------------

### Reference Color Token in Button (JSON)

Source: https://terrazzo.app/docs/guides/modes

This JSON snippet shows how a semantic token like 'button-bg' can reference a basic color token. This approach becomes problematic when multiple color modes need to be supported.

```json
{
  "button-bg": { "$value": "{color.green-light}" }
}
```

--------------------------------

### CSS Color Tokens with Modes

Source: https://terrazzo.app/docs/guides/modes

This CSS defines a button background using a CSS variable that is dynamically set based on color modes. It demonstrates how modes can manage different color themes for a single token.

```css
.button {
  background: var(--button-bg);
}

```

--------------------------------

### Update npm scripts

Source: https://terrazzo.app/docs/cli/migrating

Change CLI commands from 'cobalt' or 'co' to 'terrazzo' or 'tz' in your package.json scripts. This reflects the renaming of the command-line interface.

```json
    "scripts": {
-     "build": "co build",
-     "dev": "co build --watch"
+     "build": "tz build",
+     "dev": "tz build --watch"
    }
```

--------------------------------

### CSS Typography Styles Without Modes

Source: https://terrazzo.app/docs/guides/modes

This CSS demonstrates typography styles for a heading element, showing numerous classes to apply different font sizes based on specific type modes (e.g., xsmall, small, large). This highlights the complexity without using modes.

```css
/* heading must have theme-aware styles */
.heading {
  font-size: var(--typography-size-title1-large);
}
.type-mode-xsmall .heading {
  font-size: var(--typography-size-title1-xsmall);
}
.type-mode-small .heading {
  font-size: var(--typography-size-title1-small);
}
.type-mode-medium .heading {
  font-size: var(--typography-size-title1-medium);
}
.type-mode-large .heading {
  font-size: var(--typography-size-title1-large);
}
.type-mode-xlarge .heading {
  font-size: var(--typography-size-title1-xlarge);
}
.type-mode-xxlarge .heading {
  font-size: var(--typography-size-title1-xxlarge);
}
.type-mode-xxxlarge .heading {
  font-size: var(--typography-size-title1-xxxlarge);
}

```

--------------------------------

### Configure Required Token Modes (JavaScript)

Source: https://terrazzo.app/docs/cli/lint

Ensures that specified tokens have the required modes. This rule matches tokens using glob patterns and defines the list of acceptable mode names.

```javascript
import { defineConfig } from "@terrazzo/cli";

export default defineConfig({
  lint: {
    rules: {
      "core/required-modes": [
        "error",
        {
          matches: [
            {
              match: ["color.*"],
              modes: ["light", "dark"],
            },
          ],
        },
      ],
    },
  },
});
```

--------------------------------

### Map Color Tokens Using Array (Explicit)

Source: https://terrazzo.app/docs/cli/integrations/tailwind

A more concise way to map color tokens to Tailwind CSS theme properties using an array, suitable for 1:1 token declarations.

```javascript
tailwind({
  theme: {
    color: {
      blue: ["color.blue.*"],
    },
  },
});
```

--------------------------------

### Terrazzo JS Plugin Configuration Options

Source: https://terrazzo.app/docs/cli/integrations/js

This JavaScript configuration snippet illustrates where to define options for the Terrazzo JS plugin within the `terrazzo.config.js` file. The available options control the generation of JavaScript, TypeScript, and JSON output files.

```javascript
import { defineConfig } from "@terrazzo/cli";
import pluginJS from "@terrazzo/plugin-js";

export default defineConfig({
  plugins: [
    pluginJS({
      /* options */
    }),
  ],
});
```

--------------------------------

### Configure Per-Mode Color Schemes with CSS Plugin

Source: https://terrazzo.app/docs/cli/integrations/css

Defines specific color schemes for different modes (e.g., light and dark) using media queries or data attributes. This allows for more granular control over theme appearance.

```javascript
import { defineConfig } from "@terrazzo/cli";
import css from "@terrazzo/plugin-css";

export default defineConfig({
  plugins: [
    css({
      baseScheme: "light dark",
      modeSelectors: [
        {
          mode: "light",
          selectors: [
            "@media (prefers-color-scheme: light)",
            '[data-theme="light"]',
          ],
          scheme: "light", // Forces light color scheme
        },
        {
          mode: "dark",
          selectors: [
            "@media (prefers-color-scheme: dark)",
            '[data-theme="dark"]',
          ],
          scheme: "dark", // Forces dark color scheme
        },
      ],
    }),
  ],
});
```

--------------------------------

### Define Color Tokens (YAML)

Source: https://terrazzo.app/docs/reference/tokens

Shows the YAML representation for defining color tokens in Terrazzo. This format is more concise, specifying the color value directly using the 'oklch' format.

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

--------------------------------

### Configure Minimum Font Size (JavaScript)

Source: https://terrazzo.app/docs/cli/lint

Enforces that font sizes do not fall below a specified minimum value, either in pixels or rem units. It also allows for ignoring certain token patterns.

```javascript
import { defineConfig } from "@terrazzo/cli";

export default defineConfig({
  lint: {
    rules: {
      "a11y/min-font-size": ["error", { minSizeRem: 1 }],
    },
  },
});
```

--------------------------------

### Terrazzo CLI Ignore Configuration (JavaScript)

Source: https://terrazzo.app/docs/cli/config

This configuration snippet demonstrates how to ignore specific tokens or deprecated tokens within the Terrazzo CLI. It allows for global exclusion of tokens based on globs or by marking them as deprecated.

```javascript
export default defineConfig({
  ignore: {
    tokens: ["legacy-tokens.*"],
    deprecated: true,
  },
});
```

--------------------------------

### Define Button Background Tokens for Modes (JSON)

Source: https://terrazzo.app/docs/guides/modes

This JSON defines specific button background tokens for various color modes. This approach leads to a significant increase in token definitions for each component and property.

```json
{
  "button-bg-light": { "$value": "{color.green-light}" },
  "button-bg-light-high-contrast": {
    "$value": "{color.green-light-high-contrast}"
  },
  "button-bg-light-protanopia-deuteranopia": {
    "$value": "{color.green-light-protanopia-deuteranopia}"
  },
  "button-bg-light-tritanopia": { "$value": "{color.green-light-tritanopia}" },
  "button-bg-dark": { "$value": "{color.green-dark}" },
  "button-bg-dark-high-contrast": { "$value": "{color.green-high-contrast}" },
  "button-bg-dark-protanopia-deuteranopia": {
    "$value": "{color.green-dark-protanopia-deuteranopia}"
  },
  "button-bg-dark-trianopia": { "$value": "{color.green-dark-tritanopia}" }
}
```

--------------------------------

### JSON Color Tokens with Modes

Source: https://terrazzo.app/docs/guides/modes

This JSON object defines color tokens, specifically for 'green', with multiple mode-specific values. The 'button-bg' token references the 'color.green' token, showcasing a simplified mapping.

```json
{
  "color": {
    "$type": "color",
    "green": {
      "$value": "#2da44e",
      "$extensions": {
        "mode": {
          "light": "#2da44e",
          "light-high-contrast": "#117f32",
          "light-protanopia-deuteronopia": "#0088ff",
          "light-tritanopia": "#0088ff",
          "dark": "#2ea043",
          "dark-high-contrast": "#09b43a",
          "light-protanopia-deuteronopia": "#1585fd",
          "light-tritanopia": "#1585fd"
        }
      }
    }
  },
  "button-bg": { "$value": "{color.green}" }
}

```

--------------------------------

### Define Basic Color Tokens (JSON)

Source: https://terrazzo.app/docs/guides/modes

This JSON snippet defines a basic set of green color tokens. These tokens are intended for direct use in design systems or applications.

```json
{
  "color": {
    "$type": "color",
    "green-light": { "$value": "#2da44e" },
    "green-light-high-contrast": { "$value": "#117f32" },
    "green-light-protanopia-deuteronopia": { "$value": "#0088ff" },
    "green-light-tritanopia": { "$value": "#0088ff" },
    "green-dark": { "$value": "#2ea043" },
    "green-dark-high-contrast": { "$value": "#09b43a" },
    "green-dark-protanopia-deuteranopia": { "$value": "#1585fd" },
    "green-dark-tritanopia": { "$value": "#1585fd" }
  }
}
```
Tokens:
Raw