Design Lasagna

Schemas / v0.3

Tokens

Schema for resolved design token manifests consumed by language servers and tooling.

Minimal example

{
  "$schema": "https://designlasagna.recipes/schemas/v0.3/tokens.json",
  "schemaVersion": "0.3.0",
  "tokens": [
    {
      "id": "color.blue.500",
      "path": [
        "color",
        "blue",
        "500"
      ],
      "resolved": {
        "light": "#0b5fff",
        "dark": "#5b93ff"
      }
    }
  ]
}

Manifest fields

* Required field

Field Type Description
string Identifies the JSON Schema used to validate this file.

Use when: Include when consumers need to discover the contract from the manifest itself.

Origin: Authored metadata.

Related: schemaVersion

Example usage

{
  "$schema": "https://designlasagna.recipes/schemas/v0.3/tokens.json"
}
string States the Design Lasagna manifest format version.

Use when: Always set this so readers and tools select the correct compatibility rules.

Origin: Authored metadata.

Related: $schema

Example usage

{
  "schemaVersion": "0.3.0"
}
string Records when this resolved manifest was produced.

Use when: Use for traceability and freshness checks in generated output.

Origin: Generated metadata.

Related: source

Example usage

{
  "generatedAt": "2026-09-04T00:00:00Z"
}
array Lists manifests that should be loaded with this manifest.

Use when: Use when a system is composed from shared or inherited manifests.

Origin: Authored or generated metadata.

Related: tokens

Example usage

{
  "extends": [
    "core.tokens.json"
  ]
}
DesignSystemMeta Describes the design system that owns this manifest.

Use when: Use to attach a name, version, and documentation locations to a published manifest.

Origin: Authored metadata.

Related: source

Example usage

{
  "designSystem": {
    "name": "Acme Design System",
    "version": "2.4.0"
  }
}
object Identifies the source inputs or build context used to create the manifest.

Use when: Use when consumers need to trace resolved data back to its authoring source.

Origin: Generated metadata.

Related: generatedAt

Example usage

{
  "source": {
    "files": [
      {
        "file": "tokens.json",
        "mode": "base"
      }
    ]
  }
}
Counts Provides aggregate counts for the manifest.

Use when: Use for reporting or quick integrity checks without traversing every token.

Origin: Generated metadata.

Related: tokens

Example usage

{
  "counts": {
    "total": 248,
    "by": {
      "type": {
        "color": 96,
        "dimension": 42
      }
    }
  }
}
Conditions Declares named conditions that can affect resolved values.

Use when: Use when token values vary by environment, theme, or other named condition.

Origin: Authored metadata.

Related: tokens

Example usage

{
  "conditions": {
    "colorScheme": {
      "type": "colorScheme",
      "values": [
        "light",
        "dark"
      ],
      "default": "light"
    }
  }
}
Collections Groups tokens into named collections.

Use when: Use when consumers need stable, higher-level sets of tokens.

Origin: Authored metadata.

Related: tokens

Example usage

{
  "collections": {
    "core": {
      "name": "Core tokens"
    }
  }
}
array Declares relationships between tokens.

Use when: Use to express semantic or operational links that are not evident from a token value alone.

Origin: Authored metadata.

Related: tokens

Example usage

{
  "tokenRelations": [
    {
      "type": "paired",
      "tokens": [
        "color.text.default",
        "color.background.default"
      ]
    }
  ]
}
array Contains the resolved tokens in this manifest.

Use when: Always include the token records a consumer should read.

Origin: Generated output.

Related: schemaVersion

Example usage

{
  "tokens": [
    {
      "id": "color.blue.500",
      "resolved": {
        "base": "#0b5fff"
      }
    }
  ]
}

Token fields

Each item in tokens follows this shape.

Field Type Description
string The stable, unique identifier for this token.

Use when: Always provide it; consumers should use it as the durable token identity.

Origin: Generated from the source token identity.

Related: path, resolved

Example usage

{
  "id": "color.blue.500"
}
array The hierarchical token path as an array of name segments.

Use when: Use when tools need to group, navigate, or reconstruct a dot-separated token name.

Origin: Generated from authored naming.

Related: id, originalPath

Example usage

{
  "path": [
    "color",
    "blue",
    "500"
  ]
}
array Preserves the token path before any normalization or transformation.

Use when: Use when a build changes naming but consumers need the source path.

Origin: Generated metadata.

Related: path

Example usage

{
  "originalPath": [
    "color",
    "blue",
    "500"
  ]
}
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 metadata.

Related: id, description

Example usage

{
  "label": "Blue 500"
}
string The primary semantic category for the token.

Use when: Use to group tokens for navigation and filtering.

Origin: Authored metadata.

Related: subCategory, type

Example usage

{
  "category": "color"
}
string, null A more specific category within the primary category.

Use when: Use when category alone does not give enough grouping detail.

Origin: Authored metadata.

Related: category

Example usage

{
  "subCategory": "blue"
}
string Names the collection this token belongs to.

Use when: Use when tokens are published as named sets or packages.

Origin: Authored metadata.

Related: collections

Example usage

{
  "collection": "core"
}
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 metadata.

Related: type, usage

Example usage

{
  "tier": "primitive"
}
string, null Identifies the token value type.

Use when: Use to select appropriate editors, renderers, and validation behaviour.

Origin: Authored DTCG-compatible metadata.

Related: resolved, format

Example usage

{
  "type": "color"
}
string, null Explains the token’s meaning and intended role.

Use when: Use to give people the context that a name and value cannot convey.

Origin: Authored metadata.

Related: usage

Example usage

{
  "description": "The primary blue used for interactive elements."
}
string, null Deprecated in v0.3. A legacy CSS custom-property name for this token.

Use when: Do not add this to new manifests; use `platforms.web.reference` for CSS mappings instead.

Origin: Legacy generated or authored mapping.

Related: platforms

Example usage

{
  "cssVariable": "--color-blue-500"
}
object
values: PlatformMapping 		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: Generated or authored mapping.

Related: cssVariable

Example usage

{
  "platforms": {
    "ios": {
      "reference": "Color.Blue500"
    }
  }
}
object Contains the final value for each applicable mode.

Use when: Always provide it in a resolved manifest; consumers read this instead of evaluating source aliases.

Origin: Generated output.

Related: modes, format

Example usage

{
  "resolved": {
    "light": "#0b5fff",
    "dark": "#5b93ff"
  }
}
object Retains the authored value for each applicable mode, including unresolved aliases.

Use when: Include when consumers need alias provenance or must re-resolve the token; consumers that only need final values use `resolved` instead.

Origin: Generated from authored source.

Related: resolved

Example usage

{
  "modes": {
    "light": "{color.blue.500}",
    "dark": "{color.blue.300}"
  }
}
Format Adds information needed to interpret a typed value.

Use when: Use for values whose colour space or unit must be explicit.

Origin: Authored or generated metadata.

Related: type, resolved

Example usage

{
  "format": {
    "colorSpace": "srgb"
  }
}
Usage Documents allowed contexts and discouraged uses.

Use when: Use to guide designers and implementers toward appropriate application.

Origin: Authored metadata.

Related: description

Example usage

{
  "usage": {
    "allowedProperties": [
      "color"
    ],
    "doNot": [
      "Use for disabled text"
    ]
  }
}
A11y Provides accessibility requirements or checks associated with the token.

Use when: Use when contrast, target size, or motion guidance affects implementation.

Origin: Authored metadata.

Related: usage

Example usage

{
  "a11y": {
    "wcagContrast": {
      "ratio": 4.5,
      "against": "color.background.default",
      "level": "AA"
    }
  }
}
integer Indicates the relative importance of the token.

Use when: Use to order migrations, review, or UI presentation.

Origin: Authored metadata.

Related: deprecated

Example usage

{
  "priority": 80
}
string Records the version in which the token became available.

Use when: Use to make compatibility and migration decisions.

Origin: Authored metadata.

Related: deprecated

Example usage

{
  "since": "2.4.0"
}
array Supplies search terms for the token.

Use when: Use to improve discovery in documentation and token pickers.

Origin: Authored metadata.

Related: label, description

Example usage

{
  "keywords": [
    "blue",
    "brand",
    "action"
  ]
}
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 metadata.

Related: description

Example usage

{
  "docs": {
    "url": "https://example.com/tokens/blue-500"
  }
}
— 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 metadata.

Related: since

Example usage

{
  "deprecated": {
    "message": "Use color.action.primary instead.",
    "replacement": "color.action.primary"
  }
}
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 metadata.

Related: keywords

Example usage

{
  "tags": [
    "brand",
    "interactive"
  ]
}
array Lists source files that contributed to this token.

Use when: Use for debugging and tracing generated output back to source control.

Origin: Generated metadata.

Related: source

Example usage

{
  "sourceFiles": [
    "tokens/color/blue.json"
  ]
}
object Stores additional implementation-specific metadata.

Use when: Use only for information not represented by a defined field.

Origin: Authored or generated extension metadata.

Related: description

Example usage

{
  "metadata": {
    "figmaStyleId": "S:1234"
  }
}

Nested definitions

A11y

Accessibility guidance associated with a token. Use it to record contrast requirements, minimum target sizes, and motion safety so consumers can implement the token responsibly.

Field Type Description
— States contrast information or requirements.

Use when: Use when a colour token must meet a contrast target against another token.

Origin: Authored metadata.

Related: minTargetSize

Example usage

{
  "wcagContrast": {
    "ratio": 4.5,
    "against": "color.background.default",
    "level": "AA"
  }
}
string States the minimum target size for interactive use.

Use when: Use for tokens that influence controls or touch targets.

Origin: Authored metadata.

Related: motionSafe

Example usage

{
  "minTargetSize": "44px"
}
boolean Indicates whether the token is safe for motion-sensitive contexts.

Use when: Use when animation or motion preferences affect application.

Origin: Authored metadata.

Related: wcagContrast

Example usage

{
  "motionSafe": true
}

Collections

A map of named collections. Each collection can describe its purpose, applicable conditions, and defaults inherited by its tokens.

Each named entry has this shape:

Field Type Description
string Provides a human-friendly name for the collection.

Use when: Use when the collection key is not suitable for display.

Origin: Authored metadata.

Related: description

Example usage

{
  "name": "Acme Design System"
}
string Explains the purpose and contents of the collection.

Use when: Use to help consumers choose the correct collection.

Origin: Authored metadata.

Related: name

Example usage

{
  "description": "The primary blue used for interactive elements."
}
array Limits the collection to named condition dimensions.

Use when: Use when the collection only applies in particular variants.

Origin: Authored metadata.

Related: defaults

Example usage

{
  "conditions": [
    "colorScheme"
  ]
}
object Supplies default metadata inherited by collection members.

Use when: Use to avoid repeating shared tier, priority, usage, format, or accessibility metadata.

Origin: Authored metadata.

Related: conditions

Example usage

{
  "defaults": {
    "tier": "primitive",
    "priority": 80,
    "usage": {
      "allowedProperties": [
        "color"
      ]
    }
  }
}

Example usage

{
  "core": {
    "name": "Core tokens",
    "conditions": [
      "colorScheme"
    ],
    "defaults": {
      "tier": "primitive",
      "priority": 80
    }
  }
}

CompositeValue

An intentionally open object for structured token values such as typography, borders, or shadows. Its keys depend on the token type; consumers must interpret it together with `type`.

This definition accepts type-specific keys; the schema deliberately does not constrain the object further.

Example usage

{
  "fontFamily": "Inter",
  "fontSize": "1rem",
  "fontWeight": 600,
  "lineHeight": 1.5
}

Conditions

A map of named condition dimensions. Each key, such as `colorScheme`, describes the values a resolved token may vary by.

Each named entry has this shape:

Field Type Description
string Explains the condition dimension in reader-facing terms.

Use when: Use to clarify what changes when this condition is selected.

Origin: Authored metadata.

Related: type, values

Example usage

{
  "description": "The primary blue used for interactive elements."
}
string Classifies the condition dimension, such as colour scheme or density.

Use when: Use to help tools interpret the condition consistently.

Origin: Authored metadata.

Related: values

Example usage

{
  "type": "colorScheme"
}
array Lists the allowed values for the named condition.

Use when: Always include the selectable values for a declared condition.

Origin: Authored metadata.

Related: default

Example usage

{
  "values": [
    "light",
    "dark"
  ]
}
string Names the value used when no condition is selected.

Use when: Use when one value is the safe or expected fallback.

Origin: Authored metadata.

Related: values

Example usage

{
  "default": "light"
}

Example usage

{
  "colorScheme": {
    "type": "colorScheme",
    "values": [
      "light",
      "dark"
    ],
    "default": "light"
  }
}

ContrastInfo

A contrast requirement or result. It records the ratio, its comparison colour or token, and the relevant WCAG conformance level.

Field Type Description
number The contrast ratio achieved or required.

Use when: Use to communicate a measurable WCAG contrast result.

Origin: Authored metadata.

Related: against, level

Example usage

{
  "ratio": 4.5
}
string Identifies the colour or token used as the contrast background.

Use when: Use so the stated ratio has a clear comparison target.

Origin: Authored metadata.

Related: ratio

Example usage

{
  "against": "color.background.default"
}
string Identifies the WCAG conformance level associated with the contrast guidance.

Use when: Use when a particular accessibility threshold is required.

Origin: Authored metadata.

Related: ratio

Example usage

{
  "level": "AA"
}

Counts

A generated summary of the manifest’s token inventory. It lets reporting and validation tools inspect totals without iterating through every token.

Field Type Description
integer The total number of tokens in the manifest.

Use when: Use for quick reporting and regression checks.

Origin: Generated metadata.

Related: by

Example usage

{
  "total": 248
}
object Breaks token counts down by a named grouping.

Use when: Use to understand the composition of a token set without reading every record.

Origin: Generated metadata.

Related: total

Example usage

{
  "by": {
    "type": {
      "color": 96,
      "dimension": 42
    }
  }
}

Deprecated

Migration information for a token that should no longer be used in new work. It explains the reason, removal plan, and preferred replacement.

Field Type Description
string Explains why the token is deprecated and what consumers should do.

Use when: Use whenever a token remains available only for compatibility.

Origin: Authored metadata.

Related: replacement, removal

Example usage

{
  "message": "Use color.text.default instead."
}
string States the planned version or date for removal.

Use when: Use to let consumers schedule migration work.

Origin: Authored metadata.

Related: replacement

Example usage

{
  "removal": "4.0.0"
}
string Identifies the preferred successor token.

Use when: Use to provide a direct migration path.

Origin: Authored metadata.

Related: message

Example usage

{
  "replacement": "color.text.default"
}

DesignSystemMeta

Identity and discovery metadata for the design system that published the manifest, including its release and documentation locations.

Field Type Description
string The design system’s display name.

Use when: Use to identify the owner of a manifest to people and tooling.

Origin: Authored metadata.

Related: version

Example usage

{
  "name": "Acme Design System"
}
string The design system release version.

Use when: Use to correlate the manifest with a design-system release.

Origin: Authored metadata.

Related: name

Example usage

{
  "version": "2.4.0"
}
string Links to the design system’s general documentation.

Use when: Use to give consumers an entry point beyond individual token guidance.

Origin: Authored metadata.

Related: docsTemplates

Example usage

{
  "documentation": "https://example.com/design-system"
}
string Identifies the package that distributes the design system.

Use when: Use when consumers install or resolve the system through a package registry.

Origin: Authored metadata.

Related: version

Example usage

{
  "package": "@acme/design-tokens"
}
object Provides documentation templates or locations.

Use when: Use when generated token documentation should link into a standard structure.

Origin: Authored metadata.

Related: documentation

Example usage

{
  "docsTemplates": {
    "token": "/tokens/{id}"
  }
}

Docs

Links from a token to the places where people can understand and use it: web documentation, Figma, and Storybook.

Field Type Description
string Links to general web documentation for the token.

Use when: Use when the canonical guidance lives on a documentation site.

Origin: Authored metadata.

Related: figma, storybook

Example usage

{
  "url": "https://example.com/tokens/blue-500"
}
string Links to the corresponding Figma resource.

Use when: Use when designers need to locate the token in Figma.

Origin: Authored metadata.

Related: url

Example usage

{
  "figma": "https://figma.com/file/example"
}
string Links to the corresponding Storybook resource.

Use when: Use when implementers need to inspect the token in component examples.

Origin: Authored metadata.

Related: url

Example usage

{
  "storybook": "https://example.com/storybook"
}

Format

Type-specific information needed to interpret a resolved value correctly, such as a colour space or dimensional unit.

Field Type Description
string Names the colour space used by a colour value.

Use when: Use whenever a colour value could be interpreted in more than one colour space.

Origin: Authored or generated metadata.

Related: unit

Example usage

{
  "colorSpace": "srgb"
}
string Names the unit used by a dimensional value.

Use when: Use whenever a numeric value needs a unit to be interpreted correctly.

Origin: Authored or generated metadata.

Related: colorSpace

Example usage

{
  "unit": "px"
}

PlatformMapping

The platform-specific implementation reference developers use for a token, plus how that reference is consumed.

Field Type Description
string Gives the platform-specific identifier developers use for the token.

Use when: Use when an implementation platform uses a different identifier.

Origin: Generated or authored mapping.

Related: usage

Example usage

{
  "reference": "Color.Blue500"
}
string Records how the platform reference should actually be consumed. for example a property, a resource, or an API call.

Use when: Use when the identifier alone is ambiguous and the intended application needs to be stated.

Origin: Generated or authored mapping.

Related: reference

Example usage

{
  "usage": "UIMenuItem.titleColor"
}

TokenRelation

An explicit relationship between two or more tokens. It records the relation type as well as the participating token identifiers.

Field Type Description
string Classifies the relationship between tokens.

Use when: Use to let consumers interpret the relation consistently.

Origin: Authored metadata.

Related: tokens

Example usage

{
  "type": "color"
}
array Lists the token identifiers participating in the relationship.

Use when: Use to connect the relationship to actual token records.

Origin: Authored metadata.

Related: type

Example usage

{
  "tokens": [
    "color.text.default",
    "color.background.default"
  ]
}
string Explains why the tokens are related.

Use when: Use when the relation type alone is not sufficiently specific.

Origin: Authored metadata.

Related: type

Example usage

{
  "description": "The primary blue used for interactive elements."
}

Usage

Human guidance that defines where a token belongs, which properties it may serve, and where it should not be used.

Field Type Description
array Lists properties for which this token is appropriate.

Use when: Use to constrain implementation to intended CSS or platform properties.

Origin: Authored metadata.

Related: context

Example usage

{
  "allowedProperties": [
    "color"
  ]
}
string Describes the contexts in which the token is intended to appear.

Use when: Use to clarify semantic application beyond its raw value.

Origin: Authored metadata.

Related: doNot

Example usage

{
  "context": "Body copy"
}
array Lists discouraged or invalid uses of the token.

Use when: Use to prevent common semantic or accessibility mistakes.

Origin: Authored metadata.

Related: context

Example usage

{
  "doNot": [
    "Use for disabled text"
  ]
}

← All schemas · Schema source on GitHub ↗