Design Lasagna

Schemas / v0.4

DTCG token extensions

A reference for Design Lasagna metadata on DTCG tokens and groups.

This schema validates only the recipes.designlasagna metadata stored in the DTCG $extensions hook; the linked official DTCG Format specification defines the host format. It is the authoring-side counterpart to the resolved v0.4 tokens format.

Minimal example

A standalone DTCG token node — only the recipes.designlasagna payload inside $extensions validates against this schema.

{
  "$type": "color",
  "$value": "#0b5fff",
  "$extensions": {
    "recipes.designlasagna": {
      "tier": "primitive"
    }
  }
}

Token extension fields

The TokenExtensions definition is the value of $extensions["recipes.designlasagna"] on a DTCG token. Required fields are marked with *.

Field Type Description
string Token tier, commonly primitive, semantic, or component.

Use when: Set the tier on a token, or omit it to inherit from the nearest ancestor group.

Origin: Authored DTCG extension metadata; not derivable by a build tool.

Related: collection, category

Example usage

{
  "tier": "semantic"
}
string Collection key the token belongs to; must match a key in the manifest collections object.

Use when: Assign the token to a collection so generated manifests can group and filter it.

Origin: Authored DTCG extension metadata; inheritable.

Example usage

{
  "collection": "brand"
}
string Granular Lasagna type override for preview rendering; narrows the coarse DTCG $type, e.g. dimension becomes borderRadius.

Use when: Use when the DTCG $type is too coarse for previews and the emitter should not fall back to it.

Origin: Authored DTCG extension metadata.

Example usage

{
  "type": "borderRadius"
}
string Human-facing display label for docs, e.g. "Color" or "Layout"; unrelated to DTCG group nesting, which is carried by path and id.

Use when: Give readers a display name that does not come from the token's path.

Origin: Authored DTCG extension metadata; inheritable.

Related: category, subCategory

Example usage

{
  "label": "Primary action"
}
string Category label for grouping tokens in documentation and tooling.

Use when: Classify a token at the level above its subcategory, or omit it to inherit from a group.

Origin: Authored DTCG extension metadata; inheritable.

Related: label, subCategory

Example usage

{
  "category": "color"
}
string, null Optional finer-grained category below category; null clears an inherited value.

Use when: Split a category into subgroups, or null it out to stop inheriting.

Origin: Authored DTCG extension metadata; inheritable.

Related: category

Example usage

{
  "subCategory": "shadows"
}
integer Autocomplete sort weight from 0 to 100; higher values sort first.

Use when: Order tokens in autocomplete and pickers, or omit it to inherit the group weight.

Origin: Authored DTCG extension metadata; inheritable.

Example usage

{
  "priority": 80
}
string Version or date the token was introduced.

Use when: Record introduction so consumers can gauge how established a token is.

Origin: Authored DTCG extension metadata.

Related: deprecated

Example usage

{
  "since": "2.1.0"
}
lifecycle.json#/definitions/Status Lifecycle status from the shared v0.4 lifecycle fragment; only deprecated and removed are normative, any other value is informational.

Use when: Declare the normative lifecycle state of the token alongside a deprecated record.

Origin: Authored metadata; defined in the shared v0.4 lifecycle fragment.

Related: deprecated, since

Example usage

{
  "status": "deprecated"
}
array Semantic search synonyms: other words someone might search for, like "navy" for a blue token. Search only; nothing selects on them.

Use when: Improve findability of a token without changing its classification.

Origin: Authored DTCG extension metadata.

Related: tags

Example usage

{
  "keywords": [
    "navy",
    "corporate blue"
  ]
}
array Arbitrary classification labels that are selectable: a lint rule can target { "tag": ["off-limits"] }. Meaning is the project's, not the schema's.

Use when: Tag tokens for team-specific rules and workflows beyond built-in categories.

Origin: Authored DTCG extension metadata.

Related: keywords

Example usage

{
  "tags": [
    "off-limits"
  ]
}
Usage Usage guidance: where the token may be applied, the context it fits, and the anti-patterns to avoid.

Use when: Tell consumers where a token is appropriate and where it should not be used.

Origin: Authored DTCG extension metadata; see the Usage definition.

Related: docs

Example usage

{
  "usage": {
    "allowedProperties": [
      "background-color"
    ],
    "context": "Interactive controls",
    "doNot": [
      "Use for body copy"
    ]
  }
}
Docs Links to the places where people can learn more about the token.

Use when: Point documentation, Figma, and Storybook surfaces at the token.

Origin: Authored DTCG extension metadata; see the Docs definition.

Related: usage

Example usage

{
  "docs": {
    "url": "https://example.com/tokens/color"
  }
}
A11y Accessibility context: measured contrast, minimum target size, and motion-safety notes.

Use when: Record measured or required accessibility data next to the token.

Origin: Authored DTCG extension metadata; emitters SHOULD compute contrast rather than require it.

Related: format

Example usage

{
  "a11y": {
    "wcagContrast": {
      "ratio": 4.8,
      "against": "color.background.default",
      "level": "AA"
    },
    "motionSafe": true
  }
}
Format Output preferences for consumers, distinct from the authored DTCG value.

Use when: Tell emitters which color space or unit to emit, without changing the source value.

Origin: Authored DTCG extension metadata; see the Format definition.

Example usage

{
  "format": {
    "unit": "rem"
  }
}
Deprecated Closed deprecation record (the lifecycle fragment's StrictDeprecated): the required message plus optional removal and replacement. At the same node it wins over a standard $deprecated: false.

Use when: Phase out a token and give consumers the migration story; the nearest declaration replaces the whole inherited record, and fields are never merged from older ancestors.

Origin: Authored DTCG extension metadata; defined in the shared v0.4 lifecycle fragment.

Related: status, since

Example usage

{
  "deprecated": {
    "message": "Use color.action.primary instead.",
    "replacement": "color.action.primary",
    "removal": "3.0.0"
  }
}
object
values: PlatformMapping 		Per-platform reference overrides, one PlatformMapping per platform; omit to let the emitter derive references from the naming transform.

Use when: Correct the generated reference for a platform whose implementation name does not follow the transform.

Origin: Authored DTCG extension metadata; see the PlatformMapping definition.

Example usage

{
  "platforms": {
    "android": {
      "reference": "Color/Brand/Primary"
    }
  }
}
array Relations declared from this token's perspective; the emitter hoists them into the manifest's top-level tokenRelations.

Use when: Declare pairs, contrast pairs, scale siblings, or replacement links between tokens.

Origin: Authored DTCG extension metadata; see the TokenRelationRef definition.

Example usage

{
  "relations": [
    {
      "type": "pairs-with",
      "tokens": [
        "color.background.default"
      ]
    }
  ]
}
object Freeform passthrough, copied verbatim to the manifest token's metadata.

Use when: Carry project-specific data the schema does not model, without a schema change.

Origin: Authored DTCG extension metadata.

Example usage

{
  "metadata": {
    "owner": "Design Platform"
  }
}

Group extension fields

The GroupExtensions definition is the value of the same key on a DTCG group (DTCG 6.3.2). Only inheritable fields are permitted here, and they cascade to every descendant token unless a nearer node overrides them.

Field Type Description
string Inherited tier for every descendant token; common values are primitive, semantic, and component.

Use when: Set the tier once on a group instead of repeating it on each token.

Origin: Authored DTCG group extension metadata; inherited by descendants.

Example usage

{
  "tier": "primitive"
}
string Inherited collection key for every descendant token; must match a key in the manifest collections object.

Use when: Put an entire group of tokens in one collection.

Origin: Authored DTCG group extension metadata; inherited by descendants.

Example usage

{
  "collection": "brand"
}
string Inherited display label for the group's descendant tokens.

Use when: Name a group for documentation without touching each token.

Origin: Authored DTCG group extension metadata; inherited by descendants.

Example usage

{
  "label": "Brand color"
}
string Inherited category label for every descendant token.

Use when: Classify a whole group at once.

Origin: Authored DTCG group extension metadata; inherited by descendants.

Example usage

{
  "category": "color"
}
string, null Inherited subcategory below category; null clears the value.

Use when: Split a group's category into subgroups for all descendants.

Origin: Authored DTCG group extension metadata; inherited by descendants.

Example usage

{
  "subCategory": "shadows"
}
string Granular Lasagna type for every descendant; the common case is a radius group whose DTCG $type is dimension but whose Lasagna type is borderRadius.

Use when: Narrow a group's coarse DTCG $type for preview rendering without repeating it per token.

Origin: Authored DTCG group extension metadata; inherited by descendants.

Example usage

{
  "type": "borderRadius"
}
integer Inherited autocomplete sort weight from 0 to 100; higher values sort first.

Use when: Give a whole group of tokens a shared autocomplete ranking.

Origin: Authored DTCG group extension metadata; inherited by descendants.

Example usage

{
  "priority": 80
}
lifecycle.json#/definitions/Status Lifecycle status from the shared v0.4 lifecycle fragment; only deprecated and removed are normative, any other value is informational.

Use when: Declare a lifecycle state that applies to every descendant of the group.

Origin: Authored metadata; defined in the shared v0.4 lifecycle fragment.

Related: deprecated

Example usage

{
  "status": "deprecated"
}
array Inherited semantic search synonyms applied to every descendant token.

Use when: Boost findability for a whole family of tokens with shared vocabulary.

Origin: Authored DTCG group extension metadata; inherited by descendants.

Example usage

{
  "keywords": [
    "brand palette"
  ]
}
array Inherited arbitrary classification labels, selectable by lint rules, applied to every descendant token.

Use when: Apply a team-specific tag to an entire group at once.

Origin: Authored DTCG group extension metadata; inherited by descendants.

Example usage

{
  "tags": [
    "legacy"
  ]
}
Usage Inherited usage guidance: allowed properties, context, and anti-patterns for every descendant token.

Use when: State where a family of tokens may be used without repeating it per token.

Origin: Authored DTCG group extension metadata; see the Usage definition.

Example usage

{
  "usage": {
    "context": "Chromatic scales"
  }
}
Docs Inherited documentation links for the group's descendant tokens.

Use when: Point every token in a group at the same reference material.

Origin: Authored DTCG group extension metadata; see the Docs definition.

Example usage

{
  "docs": {
    "url": "https://example.com/tokens/brand"
  }
}
A11y Inherited accessibility context for every descendant token.

Use when: Attach shared accessibility notes to a group of related tokens.

Origin: Authored DTCG group extension metadata; see the A11y definition.

Example usage

{
  "a11y": {
    "minTargetSize": "44px"
  }
}
Format Inherited output preferences for every descendant token.

Use when: Set one emit format (color space or unit) for a whole group.

Origin: Authored DTCG group extension metadata; see the Format definition.

Example usage

{
  "format": {
    "colorSpace": "srgb"
  }
}
Deprecated Deprecates every descendant token unless a nearer node declares lifecycle state; a descendant's standard $deprecated: false clears the inherited deprecation.

Use when: Phase out a whole group of tokens with one migration story.

Origin: Authored DTCG group extension metadata; see the Deprecated definition.

Related: status

Example usage

{
  "deprecated": {
    "message": "Use the v2 palette tokens instead.",
    "removal": "3.0.0"
  }
}

Supporting definitions

Reusable shapes referenced by the fields above.

A11y

Accessibility context for a token: measured contrast (single or per-condition), minimum target size, and motion-safety. The record is closed.

Field Type Description
— Measured contrast: either a single ContrastInfo, or a map keyed by condition key when contrast differs per mode.

Use when: Record measured contrast so consumers can trust the token for text; emitters SHOULD compute this rather than require authoring.

Origin: Authored or computed accessibility metadata; see the ContrastInfo definition.

Related: minTargetSize

Example usage

{
  "wcagContrast": {
    "ratio": 4.8,
    "against": "color.background.default",
    "level": "AA"
  }
}
string Minimum interactive target size the token's UI must meet.

Use when: State the smallest touch target where the token's contrast still works.

Origin: Authored accessibility metadata.

Example usage

{
  "minTargetSize": "44px"
}
boolean Whether the token's intended use is safe for users with motion sensitivity.

Use when: Flag motion-related tokens so consumers can honor reduced-motion preferences.

Origin: Authored accessibility metadata.

Example usage

{
  "motionSafe": true
}

ContrastInfo

A contrast measurement: the ratio, the token id it was measured against, and the WCAG level it satisfies. The record is closed.

Field Type Description
number The measured contrast ratio.

Use when: Record the number a contrast tool produced for the token.

Origin: Authored or computed accessibility metadata.

Related: against, level

Example usage

{
  "ratio": 4.8
}
string Token id the ratio was measured against.

Use when: Anchor the ratio to a concrete counter token so it is reproducible.

Origin: Authored or computed accessibility metadata.

Related: ratio

Example usage

{
  "against": "color.background.default"
}
string WCAG level the measurement satisfies, e.g. AA, AAA, AA-large, or fail.

Use when: State which standard the measurement meets so consumers can pick the right token.

Origin: Authored or computed accessibility metadata.

Related: ratio

Example usage

{
  "level": "AA"
}

Deprecated

Closed deprecation record for the DTCG extension namespace: the required message plus optional removal and replacement. It reuses the shared lifecycle fragment's StrictDeprecated.

Reference to lifecycle.json#/definitions/StrictDeprecated in the shared v0.4 lifecycle fragment.

Docs

Documentation links for a token: canonical URL, Figma, and Storybook, plus any additional URI-valued links.

Field Type Description
string Canonical documentation URL for the token.

Use when: Point tooling and readers at the token's documentation page.

Origin: Authored DTCG extension metadata.

Related: figma, storybook

Example usage

{
  "url": "https://example.com/tokens/color"
}
string Figma link where the token is designed or documented.

Use when: Bridge code and design surfaces for the token.

Origin: Authored DTCG extension metadata.

Example usage

{
  "figma": "https://figma.com/file/example"
}
string Storybook link showing the token in use.

Use when: Give consumers a live example of the token rendered.

Origin: Authored DTCG extension metadata.

Example usage

{
  "storybook": "https://storybook.example.com/?path=/docs/tokens"
}

Format

Output preferences for a token: preferred emit color space and unit, distinct from how the value was authored. The record is closed.

Field Type Description
string Preferred output color space; distinct from DTCG $value.colorSpace, which describes the authored value.

Use when: Tell the emitter which color space to emit, independent of how the value was authored.

Origin: Authored DTCG extension metadata.

Related: unit

Example usage

{
  "colorSpace": "srgb"
}
string Preferred output unit, e.g. rem or px.

Use when: Normalize how dimension and spacing tokens are emitted.

Origin: Authored DTCG extension metadata.

Example usage

{
  "unit": "rem"
}

PlatformMapping

One platform's implementation reference, keyed per platform under platforms; reference is required and the record is closed.

Field Type Description
string The platform-specific implementation reference, e.g. a resource or API name.

Use when: Map the token to where it actually lives on a platform that does not follow the naming transform.

Origin: Authored DTCG extension metadata; reference is the only (required) field.

Example usage

{
  "reference": "Color/Brand/Primary"
}

TokenRelationRef

A relation from the declaring token to one or more other token ids, with the relation type and an optional description; type and tokens are required and the record is closed.

Field Type Description
string Kind of relation, e.g. pairs-with, contrast-pair, scale-sibling, or replaces.

Use when: Name the relationship so consumers can act on it (pairing, contrast, scale, migration).

Origin: Authored DTCG extension metadata.

Related: tokens

Example usage

{
  "type": "pairs-with"
}
array Other token ids in the relation; the declaring token is implicit and is prepended by the emitter.

Use when: List the counterpart tokens without repeating the declaring token's own id.

Origin: Authored DTCG extension metadata.

Related: type

Example usage

{
  "tokens": [
    "color.background.default"
  ]
}
string Optional human-readable explanation of the relation.

Use when: Explain why the tokens are related when the type alone is not enough.

Origin: Authored DTCG extension metadata.

Related: type, tokens

Example usage

{
  "description": "Pair this foreground with the default background."
}

Usage

Usage guidance for a token: the properties it may be applied to, the context it fits, and the anti-patterns surfaced as diagnostics. The record is closed.

Field Type Description
array CSS properties (or platform-equivalents) the token may be applied to.

Use when: Restrict where a token is valid so tooling can flag misuse.

Origin: Authored DTCG extension metadata.

Related: doNot

Example usage

{
  "allowedProperties": [
    "color",
    "background-color"
  ]
}
string The situation in which the token fits, in plain language.

Use when: Describe the intended use so readers know when to reach for the token.

Origin: Authored DTCG extension metadata.

Example usage

{
  "context": "Interactive controls"
}
array Anti-patterns, surfaced as language-server diagnostics.

Use when: Call out misuse the team keeps making, with wording the diagnostics will show verbatim.

Origin: Authored DTCG extension metadata.

Related: allowedProperties

Example usage

{
  "doNot": [
    "Use for body copy"
  ]
}

All schemas