### Install Dependencies

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/plugin-vanilla-extract/README.md

Install the necessary Terrazzo CLI and plugins for CSS and Vanilla Extract. This is a required setup step.

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

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

### Install Token Listing Plugin

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/plugin-token-listing/README.md

Install the @terrazzo/plugin-token-listing as a development dependency.

```sh
npm i -D @terrazzo/plugin-token-listing
```

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

### Install Token Lab

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/token-lab/README.md

Install the Token Lab package using pnpm.

```sh
pnpm i
```

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

### Install Token Listing Plugin

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/token-listing.md

Install the Token Listing plugin and CLI as development dependencies.

```sh
npm i -D @terrazzo/cli @terrazzo/plugin-token-listing
```

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

### Install React Color Picker

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/react-color-picker/README.md

Install the react-color-picker and tiles packages using pnpm.

```sh
pnpm i @terrazzo/react-color-picker @terrazzo/tiles
```

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

### Install @terrazzo/tiles

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/tiles/README.md

Install the @terrazzo/tiles package using npm.

```sh
npm i @terrazzo/tiles
```

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

### Install Dependencies

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/plugin-css-in-js/README.md

Install the necessary Terrazzo CLI and plugins as development dependencies.

```sh
npm i -D @terrazzo/cli @terrazzo/plugin-css @terrazzo/plugin-css-in-js
```

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

### Install Sass Plugin

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/plugin-sass/README.md

Install the CSS and Sass plugins as development dependencies.

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

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

### Install Terrazzo CLI and Swift Plugin

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/plugin-swift/README.md

Install the necessary packages as development dependencies using npm.

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

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

### Install Terrazzo Parser

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/parser/README.md

Install the Terrazzo parser as a development dependency.

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

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

### Install CSS Plugin

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/plugin-css/README.md

Install the CSS plugin as a development dependency using npm.

```sh
npm i -D @terrazzo/plugin-css
```

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

### Install CSS Plugin

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/css.md

Install the Terrazzo CLI and the CSS plugin as development dependencies.

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

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

### Install Terrazzo Fonts

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/fonts/README.md

Install the Terrazzo Fonts package using pnpm.

```sh
pnpm i @terrazzo/fonts
```

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

### Install Terrazzo CLI

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/cli/README.md

Install the Terrazzo CLI as a development dependency using npm.

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

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

### Install Dependencies

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/plugin-tailwind/README.md

Install the necessary Terrazzo CLI and plugins, including the Tailwind plugin, as development dependencies.

```sh
npm i -D @terrazzo/cli @terrazzo/plugin-css @terrazzo/plugin-tailwind
```

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

### Install Tailwind Plugin

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/tailwind.md

Install the necessary Terrazzo CLI and Tailwind plugin packages using npm.

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

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

### Token Source Information Example

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/token-listing.md

Example of source information for a design token, indicating the resource file and its location within that file. This is automatically generated and used for linking documentation to token editors.

```jsonc
{
  "resource": "file://<root>/tokens.json",
  "loc": {
    "start": { "line": 21, "column": 14, "offset": 556 },
    "end": { "line": 28, "column": 8, "offset": 770 },
  },
}
```

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

### Usage Example

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/js.md

Import the resolver from the generated JS file and use it to apply token configurations. Demonstrates accessing token properties and invalid input handling.

```ts
import { resolver } from "./tokens/my-ds.js";

const lightMd = resolver.apply({ theme: "light", size: "sm" });
lightMd["color.bg"].$type; // "color"
lightMd["color.bg"].$value; // { "colorSpace": "srgb", "components": [1, 1, 1] }

resolver.apply({ foo: "bar" }); // ❌ Invalid input { "foo": "bar" }
```

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

### Example Token Listing JSON Content

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/token-listing.md

An example of the generated Token Listing JSON file, showing metadata and token data including names, types, values, and extensions.

```json
{
  "meta": {
    "version": 1,
    "authoringTool": "Terrazzo",
    "modes": [
      {
        "name": "color-scheme",
        "values": ["light", "dark"],
        "description": "Color theme matching user device preferences",
      },
    ],
    "platforms": {
      "figma": {
        "description": "Figma variables (color, spacing) and local styles (typography)",
      },
      "css": {
        "description": "Tokens built as CSS variables for the developers",
      },
    },
    "sourceOfTruth": "figma",
  },
  "data": [
    {
      "$name": "color.black.100",
      "$type": "color",
      "description": "Darkest grayscale color, use sparingly.",
      "$value": "rgba(12, 12, 13, 0.05)",
      "$extensions": {
        "app.terrazzo.listing": {
          "names": {
            "figma": "color/black/100",
            "css": "--color-black-100",
          },
          "originalValue": {
            "colorSpace": "srgb",
            "components": [
              0.047058823529411764, 0.047058823529411764, 0.050980392156862744,
            ],
            "alpha": 0.050980392156862744,
            "hex": "#0c0c0d",
          },
          "previewValue": "#0c0c0d0d",
          "source": {
            "resource": "file:///path/to/tokens.json",
            "loc": {
              "start": {
                /* ... */
              },
              "end": {
                /* ... */
              },
            },
          },
        },
      },
    },
    // Etc.
  ],
}
```

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

### Build Token File with Plugin

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/plugin-api.md

Example of a plugin's build function that retrieves color tokens using `getTransforms` and writes them to a CSS file named 'tokens.css'.

```js
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.*",
      });
      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"));
    },
  };
}
```

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

### Configure CSS Plugin

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/css.md

Example of configuring the CSS plugin in terrazzo.config.ts. This setup defines custom permutations for generating CSS variables based on different inputs like theme and screen size.

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

export default defineConfig({
  plugins: [
    css({
      filename: "tokens.css",
      permutations: [
        {
          prepare: (contents) => ":root {\n  ${contents}\n}",
          input: { size: "mobile" },
        },
        {
          prepare: (contents) => `[data-theme="light"] {\n  ${contents}\n}`,
          input: { theme: "light" },
        },
        {
          prepare: (contents) =>
            `@media (prefers-color-scheme: dark) {\n  :root {\n    ${contents}\n  }\n}`,
          input: { theme: "dark" },
        },
        {
          prepare: (contents) => `[data-theme="dark"] {\n  ${contents}\n}`,
          input: { theme: "dark" },
        },
        {
          prepare: (contents) =>
            `@media (width >= 600px) {\n  :root {\n    ${contents}\n  }\n}`,
          input: { size: "desktop" },
        },
        {
          prepare: (contents) =>
            `@media (prefers-reduced-motion) {\n  :root {\n    ${contents}\n  }\n}`,
          input: { motion: "reduced-motion" },
        },
      ],
      variableName: (token) => kebabCase(token.id),
    }),
  ],
});
```

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

### Tailwind CSS Configuration with Custom Variants and @tz

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/tailwind.md

Example of a full Tailwind CSS setup using Terrazzo's @tz function to manage multiple themes and custom variants like 'dark', 'light-hc', 'dark-hc', and 'reduced-motion'. Requires registering custom variants with @custom-variant.

```css
@import "tailwindcss";

/* Default theme */
@theme {
  @tz (theme: "light");
}

/* Uncomment to change conditions for dark mode */
/* @custom-variant dark ([data-theme="dark"] &); */

/* Dark mode (@see https://tailwindcss.com/docs/dark-mode) */
@variant dark {
  @tz (theme: "dark");
}

/* Custom variant: light-high-contrast (shortened to "light-hc" in Tailwind) */
@custom-variant light-hc ([data-theme="light-hc"] &);

@variant light-hc {
  @tz (theme: "light-high-contrast");
}

/* Custom variant: dark-high-contrast (shortened to "dark-hc" in Tailwind) */
@custom-variant dark-hc ([data-theme="dark-hc"] &);

@variant dark-hc {
  @tz (theme: "dark-high-contrast");
}

/* Custom variant for reduced motion */
@custom-variant reduced-motion (@media (prefers-reduced-motion: reduce));

@variant reduced-motion {
  @tz (motion: "reduced");
}

/* Custom CSS is allowed */
.my-custom-util {
  color: red;
}
```

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

### CSS Plugin Example

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/plugin-api.md

A simplified CSS plugin demonstrating token transformation and CSS variable generation. It iterates through token permutations, transforms color tokens to CSS format, and builds a CSS output file.

```ts
import { serialize } from "colorjs.io/fn";
import { kebabCase } from "scule";

export default function clampColor(userOptions) {
  return {
    name: "my-css-plugin",
    async transform({ resolver, setTransform }) {
      const permutations = [
        { colorMode: "light", size: "mobile" },
        { colorMode: "dark", size: "mobile" },
        { colorMode: "light", size: "desktop" },
        { colorMode: "light", size: "desktop" },
      ];
      for (const input of permutations) {
        const tokens = resolver.apply(input);
        for (const [id, token] of Object.entries(tokens)) {
          switch (token.$type) {
            case "color": {
              setTransform(id, {
                format: "css",
                localID: `--${kebabCase(id)}`,
                value: serialize(
                  {
                    spaceId: "srgb",
                    coords: token.$value.components,
                    alpha: token.$value.alpha,
                  },
                  { format: "hex" },
                ),
                input,
              });
              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"));
    },
  };
}
```

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

### Install @terrazzo/use-color

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/use-color/README.md

Install the use-color package using npm. This is the first step before using the hook in your React application.

```sh
npm i @terrazzo/use-color
```

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

### Example CSS Preview Value

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/token-listing.md

An example of a CSS preview value computed by the Token Listing plugin for a typography token. This value is generated based on the token's properties and is intended for machine consumption.

```jsonc
{
  "$name": "typography.code.medium",
  "$type": "typography",
  "$value": {
    "fontFamily": ["roboto mono", "monospace"],
    "fontSize": { "value": 1, "unit": "rem" },
    "fontWeight": 400,
  },
  "$extensions": {
    "app.terrazzo.listing": {
      // ...
      "previewValue": "400 1rem \"roboto mono\", monospace",
      // ...
    },
  },
}

```

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

### Install YAML Support

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/js-api.md

Install the `yaml-to-momoa` package to enable YAML parsing within the Terrazzo JS API.

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

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

### Install JS Plugin

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/js.md

Install the Terrazzo JS plugin as a development dependency using npm.

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

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

### Stroke Style Token Examples

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/tokens.md

Examples of stroke style tokens, demonstrating both string keyword and object value types.

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

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

### Install Terrazzo CLI and JS Plugin

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/plugin-js/README.md

Install the necessary Terrazzo CLI and JS plugin as development dependencies.

```sh
npm i -D @terrazzo/cli @terrazzo/plugin-js
```

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

### Configure Terrazzo for Vanilla Extract

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/plugin-vanilla-extract/README.md

Configure the Terrazzo CLI with the CSS and Vanilla Extract plugins. This example shows how to set up CSS variable names, theme generation, and global theme contracts.

```ts
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: (token) => token.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",

      // generate createTheme()
      themes: [
        { name: "light", input: { theme: "light" } },
        { name: "dark", input: { theme: "dark" } },
      ],

      // generate createGlobalTheme()
      globalThemes: [
        {
          selector: "@media (prefers-color-scheme: light)",
          input: { theme: "light" },
        },
        {
          selector: "@media (prefers-color-scheme: dark)",
          input: { theme: "dark" },
        },
      ],
    }),
  ],
});
```

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

### Transition Token Example

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/tokens.md

Defines a CSS transition using duration, delay, and timing function. The timing function can be a cubic bezier array.

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

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

### Generated CSS Output with Permutations

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/css.md

Example of the combined CSS output from multiple permutations, showing how different contexts are mapped to CSS selectors and media queries.

```css
/* { mode: "light", size: "mobile" } */
:root {
  --color-blue-600: #0588f0;
  --font-size: 0.875rem;
  color-scheme: light;
}

/* { mode: "light" } */
[data-mode="light"] {
  color-scheme: light;
  --color-blue-600: #0588f0;
}

/* { mode: "dark" } */
@media (prefers-color-scheme: dark) {
  :root {
    color-scheme: dark;
    --color-blue-600: #3b9eff;
  }
}

/* { mode: "dark" } */
[data-mode="dark"] {
  color-scheme: dark;
  --color-blue-600: #3b9eff;
}

/* { size: "desktop" } */
@media (width >= 600px) {
  --font-size: 1rem;
}
```

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

### Create a Custom Terrazzo Plugin

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/plugin-api.md

This example shows how to create a custom Terrazzo plugin that iterates through all permutations of modifiers, applies them to tokens, and writes the resulting JSON to files. Use this as a template for building your own plugins.

```typescript
import type { Plugin } from "@terrazzo/parser";

export function MyPlugin(): Plugin {
  return {
    name: "my-plugin",
    build({ resolver, outputFile }) {
      // ⚠️ Warning! May be expensive for extremely large systems
      const permutations = resolver.listPermutations();
      for (const permutation of permutations) {
        const filename = `${Object.entries(permutation)
          .map(([k, v]) => `${k}-${v}`)
          .join("-")}.json`; // e.g. theme-dark-size-md.json

        const tokens = resolver.apply(permutation);
        const contents = JSON.stringify(tokens, null, 2);

        outputFile(filename, contents);
      }
    },
  };
}
```

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

### Configure Terrazzo for Vanilla Extract

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/vanilla-extract.md

Set up the terrazzo.config.ts file to use the CSS and Vanilla Extract plugins. This example configures both scoped and global themes.

```ts
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: (token) => token.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 Token Listing Platforms

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/token-listing.md

Define platforms for token listing, including descriptions, associated plugins, and custom naming functions. This example shows CSS, Sass with a custom filter, and Figma with a custom name function.

```typescript
export default defineConfig({
  plugins: [
    listing({
      platforms: {
        css: 'css',
        sass: {
          description: 'Design tokens as SASS variables (modes are not supported)',
          name: 'sass',
          filter: ({ mode }) => mode === '.',
        },
        figma: {
          description: 'Figma Variables curated by the design system team',
          name: ({ token }) => token.id.replace(/\./g, '/'),
        },
      },
    }),
  ],
};
```

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

### Border Token Example

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/tokens.md

A composite border token combining color, width, and style.

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

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

### Access User Configuration in Config Hook

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/plugin-api.md

The config() hook allows plugins to read the user's final configuration after all plugins are registered. This example shows how to access and store the 'outDir' from the user config.

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

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

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

### Initialize Terrazzo Configuration

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/cli/README.md

Initialize the Terrazzo CLI, creating a starter configuration file and setting up a design system.

```sh
npx tz init
```

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

### build() Options

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/plugin-api.md

The build() function accepts an options object for configuring the build process. Key options include tokens, getTransforms, outputFile, resolver, and sources.

```javascript
build({
  tokens: { /* ... */ },
  getTransforms: ({ format, id, $type }) => { /* ... */ },
  outputFile: (name, contents) => { /* ... */ },
  resolver: new Resolver(),
  sources: [{ src: "./tokens.json" }]
});
```

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

### Run Project Linting

Source: https://github.com/terrazzoapp/terrazzo/blob/main/CONTRIBUTING.md

Execute this command from the project root to lint all packages using Biome.

```sh
pnpm run lint
```

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

### Basic Resolver Usage

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/js-api.md

Demonstrates how to parse sources and create a resolver for applying tokens with specific inputs. The `apply` method can be used with or without input arguments to retrieve token sets.

```typescript
import { createResolver, parse } from "@terrazzo/parser";

const sources = [
  {
    filename: new URL("file:///my-resolver.resolver.json"),
    src: {
      /* contents */
    },
  },
];

const { resolver } = await parse(sources, { config });
const r = createResolver(resolver);

r.apply(); // get base set ⚠️ only possible if resolver declared 0 modifiers
r.apply({ theme: "light", size: "desktop" }); // tokens for theme: light; size: desktop
r.apply({ theme: "dark", size: "mobile" }); // tokens for theme: dark; size: mobile
```

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

### Run All Tests

Source: https://github.com/terrazzoapp/terrazzo/blob/main/CONTRIBUTING.md

Execute all tests in the project using Vitest. Ensure all packages are built first.

```sh
pnpm run build
pnpm exec playwright install
pnpm test
```

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

### Boolean Token Example

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/tokens.md

A boolean token used for simple true/false logic within Terrazzo.

```json
{
  "isDisabled": {
    "$type": "boolean",
    "$value": false
  }
}
```

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

### Import Default Styles

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/react-color-picker/README.md

Import the default CSS styles for the color picker and tiles components. Alternatively, copy the CSS files manually for customization.

```diff
+ import "@terrazzo/tiles/all-components.css";
+ import "@terrazzo/react-color-picker/styles.css";
```

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

### Gradient Token Example

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/tokens.md

Defines the stops for a CSS gradient. Each stop includes a color and an optional position. Linear gradients are typically assumed.

```json
{
  "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 }
    ]
  }
}
```

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

### Shadow Token Example

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/tokens.md

Defines a CSS box-shadow using offset, blur, spread, and color. Color is the only required property for the shadow value.

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

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

### String Token Example

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/tokens.md

An undefined string token in Terrazzo, intended for custom plugin use. Not recommended for user-readable content due to internationalization limitations.

```json
{
  "myCustomValue": {
    "$type": "boolean",
    "$value": ""
  }
}
```

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

### Show Help Message

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/cli.md

A global flag to display the help message for the CLI, outlining all available commands and their options. The command will exit after showing help.

```sh
--help
```

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

### Number Token Example

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/tokens.md

Represents a simple number token, often used for values like line height. It requires a type and a numeric value.

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

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

### buildEnd() Options

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/plugin-api.md

The buildEnd() function provides introspection into the final build. Options include tokens, outputFiles, getTransforms, and ast.

```javascript
buildEnd({
  tokens: { /* ... */ },
  outputFiles: [
    { name: "file.css", contents: ".token { color: red; }", plugin: "css", time: 100 }
  ],
  getTransforms: ({ format, id, $type, mode }) => { /* ... */ },
  ast: { /* ... */ }
});
```

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

### Set Plugin Enforcement Order

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/plugin-api.md

Specifies when the plugin should run in the build process. Use 'pre' to run before all other plugins, 'post' to run after, or leave undefined for default order.

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

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

### Example DTCG Color Token

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/guides/dtcg.md

This snippet shows a basic DTCG token for a color named 'rebeccapurple' with its value defined in sRGB color space.

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

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

### Configure Plugin in Terrazzo

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/plugin-api.md

Example of how to add a custom plugin to the Terrazzo configuration file. Ensure the plugin is imported and then included in the 'plugins' array of the defineConfig function.

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

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

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

### Configure Terrazzo with Token Listing

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/plugin-token-listing/README.md

Configure `terrazzo.config.ts` to include the token listing plugin, specifying output filename, modes, and platforms.

```typescript
import { defineConfig } from "@terrazzo/cli";
import css from "@terrazzo/plugin-css";
import listing from "@terrazzo/plugin-token-listing";

export default defineConfig({
  outDir: "./tokens/",
  plugins: [
    // Include at least one plugin to build tokens
    css({
      filename: "tokens.css",
    }),

    // Configure the token listing
    listing({
      filename: "terrazzo.listing.json",
      // Pass mode information so documentation tools can generate mode selectors
      modes: [
        {
          name: "color-scheme",
          values: ["light", "dark"],
          description: "Color theme matching user device preferences",
        },
      ],
      // Define platforms included in the Terrazzo build
      platforms: {
        css: {
          description: "Tokens built as CSS variables for the developers",
          filter: "@terrazzo/plugin-css",
          name: "@terrazzo/plugin-css",
        },
      },
    }),
  ],
});
```

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

### Basic Color Picker Usage

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/react-color-picker/README.md

Demonstrates how to use the ColorPicker component with state management for color selection. Supports multiple color spaces.

```tsx
import ColorPicker from "@terrazzo/react-color-picker";
import { useState } from "react";

const [color, setColor] = useState("color(display-p3 0 0.3 1)");

<ColorPicker
  color={color}
  setColor={setColor}
  colorSpaces={["srgb", "oklch", "oklab"]}
/>;
```

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

### Array Declaration for Tailwind Color Tokens

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/tailwind.md

Use array syntax for 1:1 token declarations to save typing. This example maps 'color.blue.**' to Tailwind's color theme.

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

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

### Configuring Custom Lint Rules

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/plugin-api.md

Configures Terrazzo to use a custom plugin and specifies the severity for a registered lint rule. This example enables the 'primary' rule and sets its severity to 'error'.

```typescript
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
    },
  },
});

```

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

### Replace Modes with Contexts and Modifiers in Plugin API

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/guides/migrating-v2.md

Update plugin transforms to use 'context' and 'modifier' instead of 'mode'. This example shows how to identify and set a specific light modifier.

```diff
  transform({ setTransform, resolver }) {
+   const lightModifier = resolver.source.resolutionOrder.filter((m) => m.type === "modifier" && "light" in m.contexts)?.name || "tzMode";
    setTransform(id, {
      // …
-     mode: "light",
+     context: "light",
+     modifier: lightModifier,
    });
  }
```

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

### Resolver Name, Version, and Description

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/guides/resolvers.md

The initial structure of a resolver file includes its name, the specification version (always '2025.10'), and an optional description.

```json
{
  "name": "My DS",
  "description": "v2.1 of the design system",
  "version": "2025.10"
}
```

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

### Update getTransforms in Plugin API for Explicit Contexts and Modifiers

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/guides/migrating-v2.md

Modify getTransforms calls to explicitly request modifiers and contexts. This example demonstrates querying for legacy modes as 'tzMode' and specific contexts.

```diff
  build({ getTransforms, resolver }) {
+   const modifiers = [
+     ...resolver.source.resolutionOrder.filter((m) => m.type === "modifier"),
+     { "type": "modifier", "name": "tzMode" }, // query for legacy modes, if any
+   ];
-   getTransforms({
-     // …
-     mode: "light",
-   });
+   for (mod of modifiers) {
+     getTransforms({
+       // …
+       context: "light", // note: if context doesn’t exist, this will return empty array
+       modifier: mod.name,
+     });
+   }
  });
```

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

### Basic Usage of use-color Hook

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/use-color/README.md

Demonstrates initializing the hook with a CSS color string, reading its properties (CSS, original, P3), formatting a P3 color, and updating the color using both string and object formats. It also shows relative color adjustment using Oklab.

```tsx
import useColor, { formatCSS } from "@terrazzo/use-color";

const [color, setColor] = useColor("color(srgb 0.0 0.3 1.0)");

// Reading

color.css; // color(srgb 0.0 0.3 1.0)
color.original; // { mode: "srgb", r: 0, g: 0.3, b: 1.0, alpha: 1 }
color.p3; // { mode: "p3", r: 0.1184, g: 0.2956, b: 0.9611 }
formatCSS(color.p3); // color(display-p3 0.1184 0.2956 0.9611)

// Setting color

setColor("color(display-p3 0.12 0.3 0.98)");
setColor({ mode: "p3", r: 0.12, g: 0.3, b: 0.98 });

// Adjusting color relatively (lighten by 10% via Oklab)

setColor({ ...color.original.oklab, l: color.oklab.l + 0.1 });
```

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

### Import Figma Variables and Styles

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/cli.md

Exports Figma Variables and Styles to a resolver JSON file. Requires a Figma account and a valid authentication token.

```sh
tz import https://figma.com/[file] -o my-ds.resolver.json
```

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

### Resolver Configuration for Themes

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/guides/resolver-contexts.md

Configures the resolver to use foundation tokens and theme contexts (light/dark).

```jsonc
{
  "name": "My Design System",
  "version": "2025.10",
  "resolutionOrder": [
    { "$ref": "#/sets/foundation" },
    { "$ref": "#/modifiers/theme" },
  ],
  "sets": {
    "foundation": {
      "sources": [
        { "$ref": "foundation/colors.tokens.json" },
        { "$ref": "foundation/layout.tokens.json" },
      ],
    },
  },
  "modifiers": {
    "theme": {
      "contexts": {
        "light": [{ "$ref": "theme/light.tokens.json" }],
        "dark": [{ "$ref": "theme/dark.tokens.json" }],
      },
    },
  },
}
```

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

### Import All CSS Variables with Glob

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/css-in-js.md

Alternatively, import all generated variables using a glob import for convenience.

```ts
import * as myDS from "./tokens/vars.js";
```

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

### Transforming Token Values for Different Formats

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/plugin-api.md

Implements the `transform` hook in a Terrazzo plugin to set transformed token values for specific formats. This example shows how to set a value for 'js' format and a different representation for 'ts' format.

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

```

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

### Basic Terrazzo JS API Usage

Source: https://github.com/terrazzoapp/terrazzo/blob/main/packages/parser/README.md

Demonstrates the core steps of configuring, parsing raw token data, and building the final token output using the Terrazzo JS API. The `cwd` option in `defineConfig` is crucial for resolving files, and the AST from `parse` must be passed to `build` for accurate error reporting.

```js
import { defineConfig, parse, build } from "@terrazzo/parser";

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

const rawTokens = "(any JSON or YAML)";
const { tokens, sources } = await parse(
  [{ filename: new URL("file:///tokens.json"), src: rawTokens }],
  { config }
);
const buildResult = await build(tokens, { sources, config });
```

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

### Custom Preview Value Function

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/token-listing.md

Provide a custom function to control the preview values for design tokens. If the function returns undefined, the computed CSS value is used. This example forces the use of sRGB for color token previews.

```typescript
export default defineConfig({
  plugins: [
    listing({
      previewValue: ({ token }) => {
        if (token.$type === 'color') {
          const color = new Color({ space: token.$value.colorSpace, coords: token.$value.components, alpha: token.$value.alpha });
          return color.to("srgb").toString();
        }
    }),
  ],
};

```

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

### Resolver Sets Configuration

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/guides/resolvers.md

Defines how token files are grouped into meaningful sets, such as colors, typography, and sizing. The order of sources within a set matters for precedence.

```jsonc
{
  "name": "My DS",
  "version": "2025.10",
  "sets": {
    "colors": {
      "description": "Color ramps and gradients",
      "sources": [
        { "$ref": "colors/ramps.tokens.json" },
        { "$ref": "colors/semantic.tokens.json" },
      ],
    },
    "typography": {
      "sources": [{ "$ref": "typography/fonts.tokens.json" }],
    },
    "sizing": {
      "description": "Margin, padding, and layout values",
      "sources": [
        { "$ref": "sizing/layout.tokens.json" },
        { "$ref": "sizing/breakpoints.tokens.json" },
        { "$ref": "sizing/padding.tokens.json" },
      ],
    },
  },
}
```

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

### Customizing CSS Tokens with transform()

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/css.md

Use the transform function in the CSS plugin to override specific token values based on token ID and permutation mode. This example shows how to return a custom string value for a specific token.

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

export default defineConfig({
  plugins: [
    css({
      transform(token, { permutation }) {
        if (token.id === "token.i.want" && permutation.tzMode === ".") {
          return "my-custom-value"; // generates `--token-i-want: my-custom-value;`
        }
      },
    }),
  ],
});
```

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

### Configure Utility CSS Generation

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/css.md

Specify output groups for utility CSS generation in your Terrazzo configuration. This example defines groups for background, border, font, layout, shadow, and text utilities, mapping them to specific token patterns.

```typescript
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.*"],
      },
    }),
  ],
});
```

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

### Update Configuration File and Use defineConfig

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/guides/migrating-v2.md

Rename your configuration file from 'tokens.config.js' to 'terrazzo.config.ts'. Use the 'defineConfig' wrapper from '@terrazzo/cli' for full typing and validation of your configuration.

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

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

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

### Basic JS API Usage

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/reference/js-api.md

Demonstrates the core steps of configuring, parsing, and building design tokens using the Terrazzo JS API. The build step produces in-memory output files that need to be written to disk manually.

```js
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);
}
```

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

### Tailwind Color Token Unpacking with Wildcards

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/tailwind.md

Demonstrates how wildcard expansion in array declarations can lead to unexpected naming conventions if not carefully managed. The '*' in 'color.*' results in names like '--color-blue-blue-0'.

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

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

### Configure CSS Plugin with Permutations

Source: https://github.com/terrazzoapp/terrazzo/blob/main/www/src/pages/docs/integrations/css.md

Add permutations to the CSS plugin configuration to map input contexts to CSS selectors. The `prepare` function generates the CSS wrapper for each permutation.

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

export default defineConfig({
  plugins: [
    css({
      permutations: [
        {
          input: {} // default
          prepare: (contents) => `:root {
  color-scheme: light dark;
  ${contents}
}`,
        },
        {
          input: { mode: "light" },
          prepare: (contents) => `[data-theme="light"] {
  color-scheme: light;
  ${contents}}`,
        },
        {
          input: { mode: "dark" },
          prepare: (contents) => `@media (prefers-color-scheme: "dark") {
  :root {
    color-scheme: dark;
    ${contents}
  }
}

[data-theme="dark"] {
  color-scheme: dark;
  ${contents}
}`,
        },
        {
          input: { size: "desktop" },
          prepare: (contents) => `@media (width >= 600px) {
  :root {
    ${contents}
  }
}`,
        },
      ],
    }),
  ],
});
```