Schemas / v0.3

DTCG token
extensions.

Design Lasagna governance metadata carried inside DTCG `$extensions` under the reverse-domain key `recipes.designlasagna`. This is the authoring-side counterpart to v0.3/tokens.json: everything here is human-authored and cannot be derived by a build tool. Resolver output (id, path, resolved, modes) is NOT represented here.

This schema validates optional Design Lasagna metadata authored inside a DTCG token file. It does not replace the DTCG format or describe the generated resolved token manifest.

Minimal example

{
  "$extensions": {
    "recipes.designlasagna": {
      "tier": "semantic",
      "docs": { "url": "https://example.com/tokens/color" }
    }
  }
}

Token extension fields

Use these fields on an individual DTCG token’s $extensions["recipes.designlasagna"] object.

Field	Type	Description
`tier`	`string`	Expresses the token’s abstraction level or intended layer.
Use when: Use to distinguish foundational values from semantic or component-level tokens. Origin: Authored source metadata. Example usage `{ "tier": "primitive" }`
`collection`	`string`	Names the collection this token belongs to.
Use when: Use when tokens are published as named sets or packages. Origin: Authored source metadata. Example usage `{ "collection": "core" }`
`type`	`string`	Identifies the token value type.
Use when: Use to select appropriate editors, renderers, and validation behaviour. Origin: Authored source metadata. Example usage `{ "type": "color" }`
`label`	`string`	A human-friendly display name for the token.
Use when: Use in interfaces, documentation, and pickers where the identifier is too technical. Origin: Authored source metadata. Example usage `{ "label": "Blue 500" }`
`category`	`string`	The primary semantic category for the token.
Use when: Use to group tokens for navigation and filtering. Origin: Authored source metadata. Example usage `{ "category": "color" }`
`subCategory`	`string, null`	A more specific category within the primary category.
Use when: Use when category alone does not give enough grouping detail. Origin: Authored source metadata. Example usage `{ "subCategory": "blue" }`
`priority`	`integer`	Indicates the relative importance of the token.
Use when: Use to order migrations, review, or UI presentation. Origin: Authored source metadata. Example usage `{ "priority": 80 }`
`since`	`string`	Records the version in which the token became available.
Use when: Use to make compatibility and migration decisions. Origin: Authored source metadata. Example usage `{ "since": "2.4.0" }`
`keywords`	`array`	Supplies search terms for the token.
Use when: Use to improve discovery in documentation and token pickers. Origin: Authored source metadata. Example usage `{ "keywords": [ "blue", "brand", "action" ] }`
`tags`	`array`	Adds free-form labels for filtering and organisation.
Use when: Use for lightweight grouping that does not merit a first-class category. Origin: Authored source metadata. Example usage `{ "tags": [ "brand", "interactive" ] }`
`usage`	`Usage`	Documents allowed contexts and discouraged uses.
Use when: Use to guide designers and implementers toward appropriate application. Origin: Authored source metadata. Example usage `{ "usage": { "allowedProperties": [ "color" ], "doNot": [ "Use for disabled text" ] } }`
`docs`	`Docs`	Links the token to its supporting documentation.
Use when: Use when readers need to continue to design-system guidance outside the manifest. Origin: Authored source metadata. Example usage `{ "docs": { "url": "https://example.com/tokens/blue-500" } }`
`a11y`	`A11y`	Provides accessibility requirements or checks associated with the token.
Use when: Use when contrast, target size, or motion guidance affects implementation. Origin: Authored source metadata. Example usage `{ "a11y": { "wcagContrast": { "ratio": 4.5, "against": "color.background.default", "level": "AA" } } }`
`format`	`Format`	Adds information needed to interpret a typed value.
Use when: Use for values whose colour space or unit must be explicit. Origin: Authored source metadata. Example usage `{ "format": { "colorSpace": "srgb" } }`
`deprecated`	`Deprecated`	Marks a token as deprecated and explains its replacement plan.
Use when: Use when retaining a token temporarily while guiding consumers to a successor. Origin: Authored source metadata. Example usage `{ "deprecated": { "message": "Use color.action.primary instead.", "replacement": "color.action.primary" } }`
`platforms`	`object`	Maps each platform name to that platform’s implementation reference.
Use when: Use when a token has a different implementation identifier on a platform. Origin: Authored source metadata. Values: `PlatformMapping` Example usage `{ "platforms": { "ios": { "reference": "Color.Blue500" } } }`
`relations`	`array`	Relations declared from this token's perspective. The emitter hoists these into the manifest's top-level `tokenRelations` (RFC B7).
Origin: Authored source metadata. Example usage `{ "relations": [ { "type": "pairs-with", "tokens": [ "color.background.default" ] } ] }`
`metadata`	`object`	Stores additional implementation-specific metadata.
Use when: Use only for information not represented by a defined field. Origin: Authored source metadata. Example usage `{ "metadata": { "figmaStyleId": "S:1234" } }`

Group extension fields

Use these inheritable fields on a DTCG group. Descendant tokens may override them where the schema permits.

Field	Type	Description
`tier`	`string`	Expresses the token’s abstraction level or intended layer.
Use when: Use to distinguish foundational values from semantic or component-level tokens. Origin: Authored source metadata. Example usage `{ "tier": "primitive" }`
`collection`	`string`	Names the collection this token belongs to.
Use when: Use when tokens are published as named sets or packages. Origin: Authored source metadata. Example usage `{ "collection": "core" }`
`label`	`string`	A human-friendly display name for the token.
Use when: Use in interfaces, documentation, and pickers where the identifier is too technical. Origin: Authored source metadata. Example usage `{ "label": "Blue 500" }`
`category`	`string`	The primary semantic category for the token.
Use when: Use to group tokens for navigation and filtering. Origin: Authored source metadata. Example usage `{ "category": "color" }`
`subCategory`	`string, null`	A more specific category within the primary category.
Use when: Use when category alone does not give enough grouping detail. Origin: Authored source metadata. Example usage `{ "subCategory": "blue" }`
`type`	`string`	Identifies the token value type.
Use when: Use to select appropriate editors, renderers, and validation behaviour. Origin: Authored source metadata. Example usage `{ "type": "color" }`
`priority`	`integer`	Indicates the relative importance of the token.
Use when: Use to order migrations, review, or UI presentation. Origin: Authored source metadata. Example usage `{ "priority": 80 }`
`keywords`	`array`	Supplies search terms for the token.
Use when: Use to improve discovery in documentation and token pickers. Origin: Authored source metadata. Example usage `{ "keywords": [ "blue", "brand", "action" ] }`
`tags`	`array`	Adds free-form labels for filtering and organisation.
Use when: Use for lightweight grouping that does not merit a first-class category. Origin: Authored source metadata. Example usage `{ "tags": [ "brand", "interactive" ] }`
`usage`	`Usage`	Documents allowed contexts and discouraged uses.
Use when: Use to guide designers and implementers toward appropriate application. Origin: Authored source metadata. Example usage `{ "usage": { "allowedProperties": [ "color" ], "doNot": [ "Use for disabled text" ] } }`
`docs`	`Docs`	Links the token to its supporting documentation.
Use when: Use when readers need to continue to design-system guidance outside the manifest. Origin: Authored source metadata. Example usage `{ "docs": { "url": "https://example.com/tokens/blue-500" } }`
`a11y`	`A11y`	Provides accessibility requirements or checks associated with the token.
Use when: Use when contrast, target size, or motion guidance affects implementation. Origin: Authored source metadata. Example usage `{ "a11y": { "wcagContrast": { "ratio": 4.5, "against": "color.background.default", "level": "AA" } } }`
`format`	`Format`	Adds information needed to interpret a typed value.
Use when: Use for values whose colour space or unit must be explicit. Origin: Authored source metadata. Example usage `{ "format": { "colorSpace": "srgb" } }`
`deprecated`	`Deprecated`	Marks a token as deprecated and explains its replacement plan.
Use when: Use when retaining a token temporarily while guiding consumers to a successor. Origin: Authored source metadata. Example usage `{ "deprecated": { "message": "Use color.action.primary instead.", "replacement": "color.action.primary" } }`

Supporting definitions

`A11y`

Accessibility context for a token, including its measured contrast or interaction requirements.

Field	Type	Description
`wcagContrast`	—	Either a single ContrastInfo, or a map keyed by condition key (see docs/condition-keys.md) when contrast differs per mode. Resolves RFC open question 6. Emitters SHOULD compute this rather than require authoring.
`minTargetSize`	`string`	—
`motionSafe`	`boolean`	—

Example usage

{
  "wcagContrast": {
    "ratio": 4.8,
    "against": "color.background.default",
    "level": "AA"
  },
  "minTargetSize": "44px",
  "motionSafe": true
}

`ContrastInfo`

A contrast measurement and the token it was measured against.

Field	Type	Description
`ratio`	`number`	—
`against`	`string`	Token id this ratio was measured against.
`level`	`string`	—

Example usage

{
  "ratio": 4.8,
  "against": "color.background.default",
  "level": "AA"
}

`Deprecated`

Lifecycle metadata with the reader-facing migration message, the planned removal, and a machine-readable replacement token.

Field	Type	Description
`message*`	`string`	Human-readable reason plus migration guidance.
`removal`	`string`	When it will be removed. ISO date (2026-07-30), semver (3.0.0), or quarter (2026-Q3). ISO dates drive language-server severity escalation.
`replacement`	`string`	Machine-readable replacement token id. MUST resolve to an existing token.

Example usage

{
  "message": "Use color.action.primary instead.",
  "replacement": "color.action.primary",
  "removal": "3.0.0"
}

`Docs`

Links to the places where people can learn more about the token.

Field	Type	Description
`url`	`string`	—
`figma`	`string`	—
`storybook`	`string`	—

Example usage

{
  "url": "https://example.com/tokens/brand",
  "figma": "https://figma.com/file/example",
  "storybook": "https://storybook.example.com/?path=/docs/tokens"
}

`Format`

Output preferences for consumers, distinct from the authored DTCG token value.

Field	Type	Description
`colorSpace`	`string`	Preferred output color space. Distinct from DTCG `$value.colorSpace`, which describes the authored value.
`unit`	`string`	—

Example usage

{
  "colorSpace": "srgb",
  "unit": "rem"
}

`PlatformMapping`

A platform-specific implementation reference, optionally with usage guidance.

Field	Type	Description
`reference*`	`string`	—
`usage`	`string`	—

Example usage

{
  "reference": "Color.Brand.Primary",
  "usage": "Use on primary actions."
}

`TokenRelationRef`

A relationship declared from one token to one or more other token identifiers.

Field	Type	Description
`type*`	`string`	—
`tokens*`	`array`	Other token ids in the relation. The declaring token is implicit and is prepended by the emitter.
`description`	`string`	—

Example usage

{
  "type": "pairs-with",
  "tokens": [
    "color.background.default"
  ],
  "description": "Pair this foreground with the default background."
}

`Usage`

Guidance that tells consumers where a token is appropriate and where it should not be used.

Field	Type	Description
`allowedProperties`	`array`	CSS properties (or platform-equivalent) this token may be applied to.
`context`	`string`	—
`doNot`	`array`	Anti-patterns, surfaced as language-server diagnostics.

Example usage

{
  "allowedProperties": [
    "color",
    "background-color"
  ],
  "context": "Interactive controls",
  "doNot": [
    "Use for body copy"
  ]
}

← All schemas · About Schemas · Schema source on GitHub ↗

DTCG tokenextensions.

Minimal example

Token extension fields

Group extension fields

Supporting definitions

A11y

ContrastInfo

Deprecated

Docs

Format

PlatformMapping

TokenRelationRef

Usage

DTCG token
extensions.

`A11y`

`ContrastInfo`

`Deprecated`

`Docs`

`Format`

`PlatformMapping`

`TokenRelationRef`

`Usage`