### Install Dependencies and Run Local Development Server

Source: https://github.com/design-tokens/community-group/blob/main/CONTRIBUTING.md

Install project dependencies, browser dependencies, and start the local development server for previewing designtokens.org. Node.js and pnpm are required.

```sh
pnpm i
pnpm run install-browsers
pnpm run dev
```

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

### Project Commands

Source: https://github.com/design-tokens/community-group/blob/main/www/README.md

This table lists the essential commands for managing the Astro project, including dependency installation, starting the development server, building for production, and previewing the build.

```bash
pnpm install
```

```bash
pnpm dev
```

```bash
pnpm build
```

```bash
pnpm preview
```

```bash
pnpm astro ...
```

```bash
pnpm astro -- --help
```

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

### Border Composite Token Examples

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/composite-types.md

Provides examples of border composite tokens, demonstrating different configurations for heavy and focusring borders. Includes color, width, and style properties.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "border": {
    "heavy": {
      "$type": "border",
      "$value": {
        "color": {
          "colorSpace": "srgb",
          "components": [0.218, 0.218, 0.218]
        },
        "width": {
          "value": 3,
          "unit": "px"
        },
        "style": "solid"
      }
    },
    "focusring": {
      "$type": "border",
      "$value": {
        "color": "{color.focusring}",
        "width": {
          "value": 1,
          "unit": "px"
        },
        "style": {
          "dashArray": [
            { "value": 0.5, "unit": "rem" },
            { "value": 0.25, "unit": "rem" }
          ],
          "lineCap": "round"
        }
      }
    }
  }
}
```

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

### Run Build Command

Source: https://github.com/design-tokens/community-group/blob/main/CONTRIBUTING.md

Execute this command to build the project. Ensure all dependencies are installed via pnpm.

```bash
pnpm run build
```

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

### Basic Composite Token Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/composite-types.md

A simple example of a composite token defining a shadow style with explicit sub-values.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "shadow-token": {
    "$type": "shadow",
    "$value": {
      "color": {
        "colorSpace": "srgb",
        "components": [0, 0, 0],
        "alpha": 0.5,
        "hex": "#000000"
      },
      "offsetX": { "value": 0.5, "unit": "rem" },
      "offsetY": { "value": 0.5, "unit": "rem" },
      "blur": { "value": 1.5, "unit": "rem" },
      "spread": { "value": 0, "unit": "rem" }
    }
  }
}
```

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

### Typography Composite Token Examples

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/composite-types.md

Demonstrates how to define typography styles using the 'typography' composite type. Includes examples for headings and microcopy, showcasing direct values and token references.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "type styles": {
    "heading-level-1": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Roboto",
        "fontSize": {
          "value": 42,
          "unit": "px"
        },
        "fontWeight": 700,
        "letterSpacing": {
          "value": 0.1,
          "unit": "px"
        },
        "lineHeight": 1.2
      }
    },
    "microcopy": {
      "$type": "typography",
      "$value": {
        "fontFamily": "{font.serif}",
        "fontSize": "{font.size.smallest}",
        "fontWeight": "{font.weight.normal}",
        "letterSpacing": {
          "value": 0,
          "unit": "px"
        },
        "lineHeight": 1
      }
    }
  }
}
```

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

### Basic Composite Shadow Token Example

Source: https://github.com/design-tokens/community-group/blob/main/www/src/pages/TR/2025.10/format/index.html

An example of a basic composite token defining a shadow with explicit color, offset, blur, and spread properties.

```json
{
  "shadow-token": {
    "$type": "shadow",
    "$value": {
      "color": {
        "colorSpace": "srgb",
        "components": [0, 0, 0],
        "alpha": 0.5,
        "hex": "#000000"
      },
      "offsetX": { "value": 0.5, "unit": "rem" },
      "offsetY": { "value": 0.5, "unit": "rem" },
      "blur": { "value": 1.5, "unit": "rem" },
      "spread": { "value": 0, "unit": "rem" }
    }
  }
}
```

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

### Transition Composite Token Examples

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/composite-types.md

Shows examples of transition composite tokens, defining duration, delay, and timing function for animations. The timing function is represented as a cubic Bézier curve.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "transition": {
    "emphasis": {
      "$type": "transition",
      "$value": {
        "duration": { "value": 200, "unit": "ms" },
        "delay": { "value": 0, "unit": "ms" },
        "timingFunction": [0.5, 0, 1, 1]
      }
    }
  }
}
```

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

### Shadow Token Examples

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/composite-types.md

Demonstrates various shadow token configurations, including single shadows, layered shadows, mixed references, and inner shadows.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "shadow-token": {
    "$type": "shadow",
    "$value": {
      "color": {
        "colorSpace": "srgb",
        "components": [0, 0, 0],
        "alpha": 0.5
      },
      "offsetX": { "value": 0.5, "unit": "rem" },
      "offsetY": { "value": 0.5, "unit": "rem" },
      "blur": { "value": 1.5, "unit": "rem" },
      "spread": { "value": 0, "unit": "rem" }
    }
  },
  "layered-shadow": {
    "$type": "shadow",
    "$value": [
      {
        "color": {
          "colorSpace": "srgb",
          "components": [0, 0, 0],
          "alpha": 0.1
        },
        "offsetX": { "value": 0, "unit": "px" },
        "offsetY": { "value": 24, "unit": "px" },
        "blur": { "value": 22, "unit": "px" },
        "spread": { "value": 0, "unit": "px" }
      },
      {
        "color": {
          "colorSpace": "srgb",
          "components": [0, 0, 0],
          "alpha": 0.2
        },
        "offsetX": { "value": 0, "unit": "px" },
        "offsetY": { "value": 42.9, "unit": "px" },
        "blur": { "value": 44, "unit": "px" },
        "spread": { "value": 0, "unit": "px" }
      },
      {
        "color": {
          "colorSpace": "srgb",
          "components": [0, 0, 0],
          "alpha": 0.3
        },
        "offsetX": { "value": 0, "unit": "px" },
        "offsetY": { "value": 64, "unit": "px" },
        "blur": { "value": 64, "unit": "px" },
        "spread": { "value": 0, "unit": "px" }
      }
    ]
  },

  "mixed-reference-shadow": {
    "$type": "shadow",
    "$value": [
      "{base.shadow}",
      {
        "color": "{brand.accent}",
        "offsetX": { "value": 2, "unit": "px" },
        "offsetY": { "value": 2, "unit": "px" },
        "blur": { "value": 4, "unit": "px" },
        "spread": { "value": 1, "unit": "px" }
      },
      "{highlight.shadow}"
    ]
  },
  "inner-shadow": {
    "$type": "shadow",
    "$value": {
      "color": {
        "colorSpace": "srgb",
        "components": [0, 0, 0],
        "alpha": 0.5
      },
      "offsetX": { "value": 2, "unit": "px" },
      "offsetY": { "value": 2, "unit": "px" },
      "blur": { "value": 4, "unit": "px" },
      "spread": { "value": 0, "unit": "px" },
      "inset": true
    }
  }
}
```

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

### Dimension Token Example

Source: https://github.com/design-tokens/community-group/blob/main/www/src/pages/TR/2025.10/format/index.html

Illustrates how to define dimension tokens with explicit values and units.

```json
{
  "spacing-stack-0": {
    "$value": {
      "value": 0,
      "unit": "px"
    },
    "$type": "dimension"
  },
  "spacing-stack-1": {
    "$value": {
      "value": 0.5,
      "unit": "rem"
    },
    "$type": "dimension"
  }
}
```

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

### Component Color Token Examples

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/color/token-naming.md

Shows component-specific color tokens, such as 'button.primary' and 'banner.background', referencing other tokens.

```json
{
  "color": {
    "button": {
      "primary": {
        "$value": "{color.brand.primary}"
      }
    },
    "banner": {
      "background": {
        "$value": "{color.palette.black}"
      }
    }
  }
}
```

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

### Basic Group with Root Token Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/groups.md

A fundamental example of a design token group defining spacing properties, including a root token and several scaled variants.

```json
{
  "spacing": {
    "$type": "dimension",
    "$description": "Base spacing scale",
    "$root": { "$value": { "value": 16, "unit": "px" } },
    "small": { "$value": { "value": 8, "unit": "px" } },
    "large": { "$value": { "value": 32, "unit": "px" } }
  }
}
```

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

### Dimension Token Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/types.md

Demonstrates the structure for a 'dimension' type token, requiring a 'value' and 'unit' (px or rem).

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "spacing-stack-0": {
    "$value": {
      "value": 0,
      "unit": "px"
    },
    "$type": "dimension"
  },
  "spacing-stack-1": {
    "$value": {
      "value": 0.5,
      "unit": "rem"
    },
    "$type": "dimension"
  }
}
```

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

### Valid Input Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/resolver/inputs.md

A valid input object for the preceding resolver, matching modifier names and providing valid context values.

```json
{
  "theme": "light",
  "size": "large",
  "beta": "true"
}
```

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

### Alias Color Token Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/color/token-naming.md

Illustrates an alias token where 'text.base' references the 'color.palette.black' token.

```json
{
  "color": {
    "palette": {
      "black": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0, 0, 0]
        }
      }
    },
    "text": {
      "base": {
        "$value": "{color.palette.black}"
      }
    }
  }
}
```

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

### String Stroke Style Example

Source: https://github.com/design-tokens/community-group/blob/main/www/src/pages/TR/2025.10/format/index.html

Demonstrates how to define a stroke style using a predefined string value. Ensure the '$type' is set to 'strokeStyle'.

```json
{
  "focus-ring-style": {
    "$type": "strokeStyle",
    "$value": "dashed"
  }
}
```

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

### Set with $extensions

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/resolver/syntax.md

An example of a set containing arbitrary metadata for the 'figma.com' vendor using the '$extensions' object.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/resolver.json",
  "sets": {
    "color": {
      "sources": [
        { "$ref": "colors/ramps.json" },
        { "$ref": "colors/semantic.json" }
      ],
      "$extensions": {
        "figma.com": {
          "sourceFile": "https://figma.com/file/xxxxxx",
          "updatedAt": "2025-11-01"
        }
      }
    }
  }
}
```

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

### Valid Reference Objects

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/resolver/syntax.md

Examples of valid reference objects, including same-document, relative path, partial file, and remote URL references.

```json
{ "$ref": "#/sets/MySet" }
```

```json
{ "$ref": "path/to/example.json" }
```

```json
{ "$ref": "example.json#sets/MySet" }
```

```json
{ "$ref": "https://my-server.com/tokens.json" }
```

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

### Resolver Resolution Stages Example

Source: https://context7.com/design-tokens/community-group/llms.txt

Illustrates the 'last-wins' conflict resolution during the ordering stage of the resolver process, where later declarations override earlier ones.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/resolver.json",
  "version": "2025.10",
  "sets": {
    "foundation": {
      "sources": [
        {
          "color": {
            "text": {
              "default": {
                "$value": { "colorSpace": "srgb", "components": [0, 0, 0] },
                "$type": "color"
              }
            }
          }
        },
        {
          "color": {
            "text": {
              "default": {
                "$value": { "colorSpace": "srgb", "components": [0.1, 0.1, 0.1] },
                "$type": "color"
              }
            }
          }
        }
      ]
    }
  },
  "resolutionOrder": [{ "$ref": "#/sets/foundation" }]
}
```

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

### Gradient Token Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/composite-types.md

Defines a simple gradient from blue to red. Ensure the $type is set to 'gradient' and $value is an array of stop objects.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "blue-to-red": {
    "$type": "gradient",
    "$value": [
      {
        "color": {
          "colorSpace": "srgb",
          "components": [0, 0, 1]
        },
        "position": 0
      },
      {
        "color": {
          "colorSpace": "srgb",
          "components": [1, 0, 0]
        },
        "position": 1
      }
    ]
  }
}
```

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

### Group Extension Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/groups.md

Demonstrates how to use the $extends property to inherit properties from a base group and override specific values.

```json
{
  "button": {
    "$type": "color",
    "background": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0, 0.4, 0.8],
        "hex": "#0066cc"
      }
    },
    "text": {
      "$value": {
        "colorSpace": "srgb",
        "components": [1, 1, 1],
        "hex": "#ffffff"
      }
    }
  },
  "button-primary": {
    "$extends": "{button}",
    "background": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0.8, 0, 0.4],
        "hex": "#cc0066"
      }
    }
  }
}
```

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

### Font Family Token Examples

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/types.md

Illustrates how to define 'fontFamily' tokens, supporting single font names as strings or arrays of preferred font names.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "Primary font": {
    "$value": "Comic Sans MS",
    "$type": "fontFamily"
  },
  "Body font": {
    "$value": ["Helvetica", "Arial", "sans-serif"],
    "$type": "fontFamily"
  }
}
```

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

### Group Extension with Override Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/groups.md

Demonstrates extending a base group ('input') to create a new group ('input-amount') that overrides specific tokens while inheriting others.

```json
{
  "input": {
    "$type": "dimension",
    "field": {
      "width": { "$value": { "value": 100, "unit": "%" } },
      "background": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [1, 1, 1],
          "hex": "#ffffff"
        }
      }
    }
  },
  "input-amount": {
    "$extends": "{input}",
    "field": {
      "width": { "$value": { "value": 100, "unit": "px" } }
    }
  }
}
```

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

### Example of Conflict Resolution in Design Tokens

Source: https://github.com/design-tokens/community-group/blob/main/www/src/pages/TR/2025.10/resolver/index.html

Demonstrates how the last declaration of a token wins in case of conflicts when multiple sources are combined based on the resolution order.

```json
{
  "sets": {
    "foundation": {
      "sources": [
        {
          "color": {
            "text": {
              "default": {
                "$value": { "colorSpace": "srgb", "components": [0, 0, 0] },
                "$type": "color"
              }
            }
          }
        },
        {
          "color": {
            "text": {
              "default": {
                "$value": {
                  "colorSpace": "srgb",
                  "components": [0.1, 0.1, 0.1]
                },
                "$type": "color"
              }
            }
          }
        }
      ]
    }
  },
  "resolutionOrder": [{ "$ref": "#/sets/foundation" }]
}
```

```json
{
  "color": {
    "text": {
      "default": {
        "$value": { "colorSpace": "srgb", "components": [0.1, 0.1, 0.1] },
        "$type": "color"
      }
    }
  }
}
```

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

### Conflict Resolution Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/resolver/resolution-logic.md

Demonstrates how the last declaration of a token in the `resolutionOrder` takes precedence in case of conflicts. This applies when multiple sources define the same token.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/resolver.json",
  "sets": {
    "foundation": {
      "sources": [
        {
          "color": {
            "text": {
              "default": {
                "$value": { "colorSpace": "srgb", "components": [0, 0, 0] },
                "$type": "color"
              }
            }
          }
        },
        {
          "color": {
            "text": {
              "default": {
                "$value": {
                  "colorSpace": "srgb",
                  "components": [0.1, 0.1, 0.1]
                },
                "$type": "color"
              }
            }
          }
        }
      ]
    }
  },
  "resolutionOrder": [{ "$ref": "#/sets/foundation" }]
}
```

```json
{
  "color": {
    "text": {
      "default": {
        "$value": { "colorSpace": "srgb", "components": [0.1, 0.1, 0.1] },
        "$type": "color"
      }
    }
  }
}
```

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

### Define a Gradient Token with Omitted Start Stop

Source: https://github.com/design-tokens/community-group/blob/main/www/src/pages/TR/2025.10/format/index.html

This example shows a gradient where the initial color is solid for a portion before transitioning. The color from the closest stop is extended to the start if no stop is present at position 0.

```json
{
  "mostly-yellow": {
    "$type": "gradient",
    "$value": [
      {
        "color": {
          "colorSpace": "srgb",
          "components": [1, 1, 0]
        },
        "position": 0.666
      },
      {
        "color": {
          "colorSpace": "srgb",
          "components": [1, 0, 0]
        },
        "position": 1
      }
    ]
  }
}
```

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

### Setup Panel Event Listeners

Source: https://github.com/design-tokens/community-group/blob/main/www/src/pages/TR/2025.10/resolver/index.html

Attaches keydown and click event listeners to the document body to manage panel interactions. Ensures setupPanel is called after the document is ready.

```javascript
document.addEventListener("readystatechange", () => {
  if (document.readyState === "interactive" || document.readyState === "complete") {
    ready.then(setupPanel);
  } else {
    setupPanel();
  }
});

function setupPanel() {
  const listener = panelListener();
  document.body.addEventListener("keydown", listener);
  document.body.addEventListener("click", listener);
}
```

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

### Run Local Previews

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/README.md

Execute this command at the repository root to start a local server for live previews of technical report edits. Access the previews at http://localhost:8080/TR/drafts/.

```bash
pnpm run dev
```

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

### Design Token Path Examples

Source: https://github.com/design-tokens/community-group/blob/main/www/src/pages/TR/2025.10/format/index.html

Illustrates different ways to reference design tokens using JSON Pointer and curly brace syntax. Curly braces do not support array indices directly.

```json
#/primary
{primary}
```

```json
#/colors/blue
{colors.blue}
```

```json
#/brand colors/primary
{brand colors.primary}
```

```json
#/my~1group/token
{my/group.token}
```

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

### Gradient Token with Omitted Start Stop

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/composite-types.md

Illustrates a gradient that is solid yellow for the first two-thirds and then fades to red. The color of the first stop is extended to the start of the gradient axis.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "mostly-yellow": {
    "$type": "gradient",
    "$value": [
      {
        "color": {
          "colorSpace": "srgb",
          "components": [1, 1, 0]
        },
        "position": 0.666
      },
      {
        "color": {
          "colorSpace": "srgb",
          "components": [1, 0, 0]
        },
        "position": 1
      }
    ]
  }
}
```

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

### Another Invalid Circular Reference Example

Source: https://github.com/design-tokens/community-group/blob/main/www/src/pages/TR/2025.10/format/index.html

This example demonstrates a circular reference between 'groupA' and 'groupB', where each group attempts to extend the other. Avoid such reciprocal extensions to maintain a clear inheritance hierarchy.

```json
{
  "groupA": {
    "$extends": "{groupB}",
    "token": {
      // …
    },
  },
  "groupB": {
    "$extends": "{groupA}", 
    "token": {
      // …
    },
  },
}
```

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

### Bounded Color Scale Example (HSL)

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/color/token-naming.md

Demonstrates a bounded scale for gray tokens, where numerical names correspond to HSL lightness values, allowing for precise shade control.

```json
{
  "color": {
    "gray": {
      "22": {
        "$type": "color",
        "$value": {
          "colorSpace": "hsl",
          "components": [0, 0, 22]
        }
      },
      "49": {
        "$type": "color",
        "$value": {
          "colorSpace": "hsl",
          "components": [0, 0, 49]
        }
      },
      "73": {
        "$type": "color",
        "$value": {
          "colorSpace": "hsl",
          "components": [0, 0, 73]
        }
      },
      "99": {
        "$type": "color",
        "$value": {
          "colorSpace": "hsl",
          "components": [0, 0, 99]
        }
      }
    }
  }
}
```

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

### Current Reference Syntax for Aliasing

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/groups.md

This example demonstrates the recommended current reference syntax for creating aliases to existing token values. It uses curly braces to reference the 'base' token.

```json
{
  "base": {
    "$value": {
      "colorSpace": "srgb",
      "components": [0, 0.4, 0.8],
      "hex": "#0066cc"
    }
  },
  "alias": { "$value": "{base}" }
}
```

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

### Define Gradient Token Using References

Source: https://github.com/design-tokens/community-group/blob/main/www/src/pages/TR/2025.10/format/index.html

This example demonstrates how to use references to other tokens (color, number, and gradient) within a gradient definition. Ensure referenced tokens are defined elsewhere.

```json
{
  "brand-primary": {
    "$type": "color",
    "$value": {
      "colorSpace": "srgb",
      "components": [0, 1, 0.4]
    }
  },

  "position-end": {
    "$type": "number",
    "$value": 1
  },

  "brand-in-the-middle": {
    "$type": "gradient",
    "$value": [
      {
        "color": {
          "colorSpace": "srgb",
          "components": [0, 0, 0]
        },
        "position": 0
      },
      {
        "color": "{brand-primary}",
        "position": 0.5
      },
      {
        "color": {
          "colorSpace": "srgb",
          "components": [0, 0, 0]
        },
        "position": "{position-end}"
      }
    ]
  },

  "gradient-with-references": {
    "$type": "gradient",
    "$value": [
      "{gradient.start-stop}",
      {
        "color": "{brand.secondary}",
        "position": 0.333
      },
      "{gradient.end-stop}"
    ]
  },

  "gradient": {
    "start-stop": {
      "$type": "gradient",
      "$value": [
        {
          "color": { "colorSpace": "srgb", "components": [1, 1, 1] },
          "position": 0
        }
      ]
    },
    "end-stop": {
      "$type": "gradient",
      "$value": [
        {
          "color": { "colorSpace": "srgb", "components": [0, 0, 0] },
          "position": 1
        }
      ]
    }
  }
}
```

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

### Common Project Commands

Source: https://github.com/design-tokens/community-group/blob/main/CONTRIBUTING.md

A list of common commands for managing the project, including development, linting, spellchecking, and building.

```markdown
| Command               | Description                                       |
| :-------------------- | :------------------------------------------------ |
| `pnpm run dev`        | Run designtokens.org locally in development mode. |
| `pnpm run lint`       | Lint the project.                                 |
| `pnpm run spellcheck` | Run [spellcheck](#spellcheck).                    |
| `pnpm run build`      | Make a static build of the website.               |
```

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

### JSON Pointer Path Examples

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/aliases.md

Illustrates various JSON Pointer paths for accessing design tokens, including root references, nested properties, array elements, and properties with special characters.

```json
#/colors/blue/$value
```

```json
#/colors/blue/$value/hex
```

```json
#/colors/blue/$value/components/0
```

```json
#/colors/blue/$type
```

```json
#/primary
```

```json
#/colors/blue
```

```json
#/color/components/0
```

```json
#/brand colors/primary
```

```json
#/my~1group/token
```

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

### Gradient Token Using References

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/composite-types.md

Demonstrates a gradient using references for color and position tokens. This allows for modularity and reuse of defined design tokens.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "brand-primary": {
    "$type": "color",
    "$value": {
      "colorSpace": "srgb",
      "components": [0, 1, 0.4]
    }
  },

  "position-end": {
    "$type": "number",
    "$value": 1
  },

  "brand-in-the-middle": {
    "$type": "gradient",
    "$value": [
      {
        "color": {
          "colorSpace": "srgb",
          "components": [0, 0, 0]
        },
        "position": 0
      },
      {
        "color": "{brand-primary}",
        "position": 0.5
      },
      {
        "color": {
          "colorSpace": "srgb",
          "components": [0, 0, 0]
        },
        "position": "{position-end}"
      }
    ]
  },

  "gradient-with-references": {
    "$type": "gradient",
    "$value": [
      "{gradient.start-stop}",
      {
        "color": "{brand.secondary}",
        "position": 0.333
      },
      "{gradient.end-stop}"
    ]
  },

  "gradient": {
    "start-stop": {
      "$type": "gradient",
      "$value": [
        {
          "color": {"colorSpace": "srgb", "components": [1, 1, 1]},
          "position": 0
        }
      ]
    },
    "end-stop": {
      "$type": "gradient",
      "$value": [
        {
          "color": {"colorSpace": "srgb", "components": [0, 0, 0]},
          "position": 1
        }
      ]
    }
  }
}
```

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

### JSON Pointer Reference Syntax

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/groups.md

This example shows how to use JSON Pointer notation with the $ref property to create aliases. This is an alternative to the current reference syntax and is useful for advanced use cases.

```json
{
  "base": {
    "$value": {
      "colorSpace": "srgb",
      "components": [0, 0.4, 0.8],
      "hex": "#0066cc"
    }
  },
  "alias": { "$ref": "#/base" }
}
```

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

### Ordered Color Scale Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/color/token-naming.md

Defines a color scale for green with increments of 100, suitable for consistent progression of shades.

```json
{
  "color": {
    "green": {
      "400": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0.42, 0.73, 0.63]
        }
      },
      "500": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0.15, 0.56, 0.42]
        }
      },
      "600": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0.07, 0.5, 0.36]
        }
      }
    }
  }
}
```

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

### Example Resolver Modifiers

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/resolver/inputs.md

This JSON defines modifiers for a design token resolver, specifying contexts for 'theme', 'size', and 'beta'.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/resolver.json",
  "resolutionOrder": [
    {
      "type": "modifier",
      "name": "theme",
      "contexts": {
        "light": [{ "$ref": "light.json" }],
        "dark": [{ "$ref": "dark.json" }]
      }
    },
    {
      "type": "modifier",
      "name": "size",
      "context": {
        "default": [{ "$ref": "size/default.json" }],
        "large": [{ "$ref": "size/large.json" }]
      }
    },
    {
      "type": "modifier",
      "name": "beta",
      "context": {
        "false": [],
        "true": [{ "$ref": "beta.json" }]
      },
      "default": "false"
    }
  ]
}
```

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

### Invalid Reference Objects (Circular)

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/resolver/syntax.md

Examples of invalid reference objects due to circular references, which prevent a final value from being determined.

```json
{
  "foo": {
    "bar": { "$ref": "#/baz/bat" }
  },
  "baz": {
    "bat": { "$ref": "#/foo/bar" }
  }
}
```

```json
{
  "foo": {
    "bar": {
      "baz": { "$ref": "#/foo/bar" }
    }
  }
}
```

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

### Composite Type with Array Aliasing Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/composite-types.md

Demonstrates a composite token with an array value that mixes references to other tokens and explicit values.

```json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "layered-shadow": {
    "$type": "shadow",
    "$value": [
      "{base.shadow}",
      {
        "color": "{brand.accent}",
        "offsetX": { "value": 4, "unit": "px" },
        "offsetY": { "value": 4, "unit": "px" },
        "blur": { "value": 8, "unit": "px" },
        "spread": { "value": 0, "unit": "px" }
      }
    ]
  }
}
```

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

### Prepare Local Repository for Publishing

Source: https://github.com/design-tokens/community-group/blob/main/CONTRIBUTING.md

Steps to clean and update your local repository to ensure a clean state before publishing a new report version. This includes pulling the latest changes, cleaning untracked files, and reinstalling dependencies.

```sh
git pull
git clean -dfx
pnpm i
```

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

### Deprecated Token with URL Link (JS)

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/design-token.md

Example of a JSDoc comment for a deprecated token, linking to external documentation via a URL.

```javascript
/**
 * @deprecated Please use {@link https://docs.ds/tokens/#button-activeborder button.activeBorder} instead.
 */
```

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

### Deprecated Token with String Explanation (JS)

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/design-token.md

Example of a JSDoc comment for a deprecated token, linking to a specific token or external documentation.

```javascript
/**
 * @deprecated Please use {@link file://./my-tokens.js:85 button.activeBorder} instead.
 */
```

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

### Invalid Input Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/resolver/inputs.md

An invalid input object demonstrating unknown keys and invalid context values, which would cause errors.

```json
{
  "theme": "blue",
  "foo": "bar"
}
```

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

### Extending with $ref

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/resolver/syntax.md

Demonstrates how to extend a reference object by including other keys alongside '$ref'. Local keys override referenced values and new properties are appended.

```json
{
  "animal": {
    "color": "brown",
    "legs": 4
  },
  "lizard": {
    "color": "green",
    "$ref": "#/animal",
    "size": "small"
  }
}
```

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

### Circular Reference Detection Example

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/format/groups.md

Illustrates a scenario where circular references are created through `$extends` properties, which tools must detect and report as an error.

```jsonc
{
  "a": { "$extends": "{b}" },
  "b": { "$extends": "{c}" },
  "c": { "$extends": "{a}" } // Creates circular reference: a → b → c → a
}
```

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

### Foundation Token Definition

Source: https://github.com/design-tokens/community-group/blob/main/technical-reports/resolver/resolution-logic.md

Example of a token defined in a foundation source file. This token is a color named 'primary' within the 'brand' category.

```json
- `color.brand.primary` (color)
```