Schemas / v0.4

Tokens

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

Example

This manifest declares a condition dimension and a collection, then two tokens. Each token requires an id and a resolved value per condition. The first token adds authored modes aliases, a web platform reference and contrast data. The second is marked deprecated with a status and a lifecycle deprecated record that points to its replacement.

{
  "$schema": "https://designlasagna.recipes/schemas/v0.4/tokens.json",
  "schemaVersion": "0.4.0",
  "designSystem": {
    "name": "Acme UI",
    "version": "2.3.0"
  },
  "conditions": {
    "colorScheme": {
      "type": "colorScheme",
      "values": [
        "light",
        "dark"
      ],
      "default": "light"
    }
  },
  "collections": {
    "semantic": {
      "name": "Semantic",
      "conditions": [
        "colorScheme"
      ],
      "defaults": {
        "tier": "semantic"
      }
    }
  },
  "tokens": [
    {
      "id": "color.action.primary",
      "path": [
        "color",
        "action",
        "primary"
      ],
      "collection": "semantic",
      "type": "color",
      "description": "Background for primary actions.",
      "platforms": {
        "web": {
          "reference": "var(--color-action-primary)"
        }
      },
      "resolved": {
        "light": "#0b5fff",
        "dark": "#5b93ff"
      },
      "modes": {
        "light": "{color.blue.500}",
        "dark": "{color.blue.300}"
      },
      "a11y": {
        "wcagContrast": {
          "light": {
            "ratio": 5.2,
            "against": "#ffffff",
            "level": "AA"
          }
        }
      },
      "keywords": [
        "button",
        "cta"
      ],
      "tags": [
        "interactive"
      ]
    },
    {
      "id": "color.brand.legacy",
      "collection": "semantic",
      "type": "color",
      "resolved": {
        "light": "#0b5fff",
        "dark": "#5b93ff"
      },
      "status": "deprecated",
      "deprecated": {
        "message": "Use color.action.primary instead.",
        "removal": "2027-01-01",
        "replacement": "color.action.primary"
      }
    }
  ]
}

Manifest fields

The root object is the resolved tokens manifest. Required fields are marked with *.

Field	Type	Description
`$schema`	`string`	Identifier of the schema that validates the manifest.
Use when: Always set it so editors and validators can find the contract. Origin: Contract metadata; set by authors or generators. Example usage `{ "$schema": "https://schemas.designlasagna.dev/v0.4/tokens.json" }`
`schemaVersion*`	`string`	Schema version the manifest conforms to.
Use when: Keep it in sync with the $schema document the manifest is validated against. Origin: Contract metadata; set by authors or generators. Related: `$schema` Example usage `{ "schemaVersion": "0.4.0" }`
`generatedAt`	`string`	ISO 8601 timestamp identifying the generation run that produced the manifest.
Use when: Set by generators so consumers can detect and track stale manifests. Origin: Computed by analysis or build tooling. Example usage `{ "generatedAt": "2026-01-15T08:30:00Z" }`
`extends`	`array`	Base format that the manifest extends.
Use when: Document that a manifest augments an existing standard rather than replacing it. Origin: Contract metadata; set by authors or generators. Example usage `{ "extends": "https://design-tokens.community/format" }`
`designSystem`	`DesignSystemMeta`	Identity of the design system the manifest describes.
Use when: Help tooling label, group, and switch between design systems. Origin: Authored metadata, carried through by generators. Related: `source` Example usage `{ "designSystem": { "name": "Design Lasagna", "version": "1.0.0", "package": "@designlasagna/design-system" } }`
`source`	`object`	Provenance data recording where the manifest was generated from.
Use when: Make generated files auditable by recording the source files and their state. Origin: Recorded by generators. Related: `generatedAt`, `designSystem` Example usage `{ "source": { "files": [ { "path": "tokens/colors.json", "state": "resolved" } ] } }`
`counts`	`Counts`	Summary counts for the manifest.
Use when: Give consumers quick totals without scanning every token. Origin: Computed by generators. Example usage `{ "counts": { "total": 128, "by": { "type": { "color": 72 }, "category": { "color": 72 } } } }`
`conditions`	`Conditions`	Condition set that generated the manifest, such as themes or platforms.
Use when: Document the axes a consumer can use to select resolved values. Origin: Recorded by generators. Related: `tokens` Example usage `{ "conditions": { "theme": { "description": "Color theme.", "type": "theme", "values": [ "light", "dark" ], "default": "light" } } }`
`collections`	`Collections`	Named token collections, with per-collection defaults.
Use when: Group tokens into authored collections that tooling can present. Origin: Authored metadata, carried through by generators. Related: `tokenRelations`, `tokens` Example usage `{ "collections": { "colors": { "name": "Color", "description": "Brand and semantic colors.", "conditions": [ "theme" ], "defaults": { "theme": "light" } } } }`
`tokenRelations`	`array`	Relationships between tokens, such as derived tokens.
Use when: Express how tokens are derived from one another so tools can navigate them. Origin: Authored metadata, carried through by generators. Related: `tokens` Example usage `{ "tokenRelations": [ { "type": "derived", "tokens": [ "color.surface", "color.surface-raised" ], "description": "Raised surface is derived from the base surface." } ] }`
`tokens*`	`array`	Resolved tokens in the manifest.
Use when: Provide the token data that tooling completes, documents, and consumes. Origin: Resolved by generators from authored token sources. Related: `counts`, `conditions`, `collections`, `tokenRelations` Example usage `{ "tokens": [ { "id": "color.brand", "path": "color/brand", "label": "Brand", "category": "color", "type": "color", "resolved": { "light": "#7c3aed", "dark": "#a78bfa" } } ] }`

Token fields

Each item in tokens follows this shape.

Field	Type	Description
`id*`	`string`	Stable identifier for the token.
Use when: Reference the token from tooling, manifests, and relations. Origin: Stable token identity; authored or assigned by tooling. Related: `path` Example usage `{ "id": "color.brand" }`
`path`	`array`	Path-like identifier for the token.
Use when: Locate the token within its naming hierarchy. Origin: Stable token identity; authored or assigned by tooling. Related: `originalPath` Example usage `{ "path": "color/brand" }`
`originalPath`	`array`	Path-like identifier at authoring time.
Use when: Trace the token back to its original naming. Origin: Stable token identity; preserved from authored sources. Related: `path` Example usage `{ "originalPath": "color/brand" }`
`label`	`string`	Human-readable label for the token.
Use when: Display the token in documentation and pickers. Origin: Authored metadata. Example usage `{ "label": "Brand" }`
`category`	`string`	Top-level category the token belongs to.
Use when: Group and filter tokens in documentation and tooling. Origin: Authored metadata; carried through by generators. Related: `subCategory`, `collection` Example usage `{ "category": "color" }`
`subCategory`	`string, null`	Optional subcategory within the token's category.
Use when: Add finer grouping for documentation and filters. Origin: Authored metadata; carried through by generators. Related: `category` Example usage `{ "subCategory": "brand" }`
`collection`	`string`	Collection the token belongs to.
Use when: Present tokens in their authored collection context. Origin: Authored metadata, carried through by generators. Related: `category` Example usage `{ "collection": "colors" }`
`tier`	`string`	Token tier, such as primitive or semantic.
Use when: Show how abstract or application-specific a token is. Origin: Authored metadata. Example usage `{ "tier": "semantic" }`
`type`	`string, null`	Type of the token, such as color or dimension.
Use when: Drive type-aware completion and validation in tooling. Origin: Authored metadata; carried through by generators. Related: `resolved`, `format` Example usage `{ "type": "color" }`
`description`	`string, null`	Human-readable description of the token.
Use when: Explain what the token is for in documentation and hover text. Origin: Authored metadata. Example usage `{ "description": "Primary brand color." }`
`cssVariable` Deprecated	`string, null`	Deprecated in v0.3. A legacy CSS custom-property name for this token.
Use when: Carry over existing CSS variable names during migration. Origin: Authored metadata; deprecated by the schema. Related: `platforms` Example usage `{ "cssVariable": "--color-brand" }`
`platforms`	`object` values: `PlatformMapping`	Platform-specific metadata for the token.
Use when: Map the token to concrete implementation details per platform. Origin: Authored metadata; carried through by generators. Related: `cssVariable` Example usage `{ "platforms": { "ios": { "reference": "Color.Blue500" } } }`
`resolved*`	`object`	Resolved values of the token, keyed by condition. Each value is a string, a number, an object for composite values, or (since 0.4.4) an array of strings with one entry per layer, for multi-layer shadows and gradient stops.
Use when: Provide the concrete values consumers render or consume. Origin: Computed by resolution tooling. Related: `type`, `modes` Example usage `{ "resolved": { "light": "#7c3aed", "dark": "#a78bfa" } }`
`modes`	`object`	Explicit mode names the token supports.
Use when: Tell consumers which mode variants exist. Origin: Computed by resolution tooling. Related: `resolved` Example usage `{ "modes": [ "light", "dark" ] }`
`format`	`Format`	Format metadata for the token, such as color space or unit.
Use when: Interpret and normalize token values in tooling. Origin: Authored metadata; carried through by generators. Related: `type`, `resolved` Example usage `{ "format": { "colorSpace": "srgb" } }`
`usage`	`Usage`	Usage guidance for the token.
Use when: Document allowed properties, context, and anti-patterns. Origin: Authored metadata. Example usage `{ "usage": { "context": "Use for primary actions.", "doNot": "Do not use for disabled states." } }`
`a11y`	`A11y`	Accessibility guidance for the token.
Use when: Record contrast, target size, and motion-safety guidance. Origin: Authored metadata. Related: `usage` Example usage `{ "a11y": { "wcagContrast": "AA", "motionSafe": true } }`
`priority`	`integer`	Priority or importance of the token.
Use when: Order tokens in documentation and tooling output. Origin: Authored metadata. Example usage `{ "priority": 1 }`
`since`	`string`	Version when the token was introduced.
Use when: Show when the token entered the design system. Origin: Authored metadata; maintained over time. Example usage `{ "since": "1.0.0" }`
`status`	`lifecycle.json#/definitions/Status`	Lifecycle status for the token; 'deprecated' and 'removed' are normative, other values are informational.
Use when: Declare the normative lifecycle state of the token, or carry informational states such as 'experimental'. Origin: Authored metadata. Related: `deprecated` Example usage `{ "status": "deprecated" }`
`keywords`	`array`	Keywords for search and discovery.
Use when: Improve token search in documentation and tooling. Origin: Authored metadata. Example usage `{ "keywords": [ "brand", "primary" ] }`
`docs`	`Docs`	Links to documentation and related resources.
Use when: Point consumers to deeper references and tools. Origin: Authored metadata. Example usage `{ "docs": { "url": "https://example.com/docs/color", "figma": "https://www.figma.com/file/abc/Color" } }`
`deprecated`	`lifecycle.json#/definitions/NativeDeprecation`	Deprecation record from the shared v0.4 lifecycle fragment; may be false, null, or a record with a message.
Use when: Guide consumers away from a token while it remains available, recording its replacement and removal target. Origin: Authored metadata. Related: `status` Example usage `{ "deprecated": { "message": "Use color.action.primary instead.", "replacement": "color.action.primary" } }`
`tags`	`array`	Free-form tags for filtering and classification.
Use when: Group tokens beyond categories for ad-hoc filters. Origin: Authored metadata. Related: `keywords` Example usage `{ "tags": [ "v2", "migration" ] }`
`sourceFiles`	`array`	Source files the token was derived from.
Use when: Trace resolved data back to its authored origin. Origin: Recorded by generators. Related: `source` Example usage `{ "sourceFiles": [ "tokens/colors.json" ] }`
`metadata`	`object`	Additional metadata, such as token relations.
Use when: Carry structured extras the manifest schema does not model as top-level fields. Origin: Authored metadata; carried through by generators. Related: `tokenRelations` Example usage `{ "metadata": { "aliases": [ "brand-primary" ] } }`

Nested definitions

Reusable shapes referenced by the fields above.

`A11y`

Accessibility guidance for a token, covering contrast, minimum target size, and motion safety.

Field	Type	Description
`wcagContrast`	—	WCAG contrast guidance for the token.
Use when: Record the contrast level the token must meet. Origin: Authored metadata. Related: `minTargetSize`, `motionSafe` Example usage `{ "wcagContrast": "AA" }`
`minTargetSize`	`string`	Minimum target size guidance for the token.
Use when: Record the minimum size for touch and pointer targets. Origin: Authored metadata. Related: `wcagContrast` Example usage `{ "minTargetSize": "44px" }`
`motionSafe`	`boolean`	Whether the token is safe under reduced-motion preferences.
Use when: Flag tokens whose use must respect reduced motion. Origin: Authored metadata. Related: `wcagContrast` Example usage `{ "motionSafe": true }`

`Collections`

Named token collections, keyed by collection ID, each with optional conditions and defaults.

Field	Type	Description
`name`	`string`	Display name of the collection.
Use when: Present the collection in documentation and tooling. Origin: Authored metadata. Example usage `{ "name": "Color" }`
`description`	`string`	Human-readable description of the collection.
Use when: Explain what the collection groups. Origin: Authored metadata. Example usage `{ "description": "Brand and semantic colors." }`
`conditions`	`array`	Conditions the collection varies by.
Use when: Tell consumers which condition axes apply to the collection. Origin: Authored metadata. Related: `defaults` Example usage `{ "conditions": [ "theme" ] }`
`defaults`	`object`	Default condition values for the collection.
Use when: State the values that apply when none are selected. Origin: Authored metadata. Related: `conditions` Example usage `{ "defaults": { "theme": "light" } }`

`CompositeValue`

A value composed of parts, for example a font stack or a gradient.

This definition accepts type-specific keys, described in the raw schema.

`Conditions`

The condition set that generated the manifest, keyed by condition name.

Field	Type	Description
`description`	`string`	Human-readable description of the condition.
Use when: Explain what the condition controls. Origin: Authored metadata. Example usage `{ "description": "Color theme." }`
`type`	`string`	Type of the condition, such as theme or platform.
Use when: Tell consumers how to interpret the condition. Origin: Authored metadata. Example usage `{ "type": "theme" }`
`values*`	`array`	Values the condition can take.
Use when: List the selectable values for the condition. Origin: Authored metadata. Example usage `{ "values": [ "light", "dark" ] }`
`default`	`string`	Default value of the condition.
Use when: State which value applies when none is selected. Origin: Authored metadata. Related: `values` Example usage `{ "default": "light" }`

`ContrastInfo`

A measured contrast ratio, the reference it is measured against, and the WCAG level it meets.

Field	Type	Description
`ratio*`	`number`	Measured contrast ratio for the token.
Use when: Record the numeric contrast value. Origin: Computed by analysis tooling. Related: `against`, `level` Example usage `{ "ratio": 4.5 }`
`against`	`string`	Background or reference the ratio is measured against.
Use when: State what the contrast ratio is measured against. Origin: Computed by analysis tooling. Related: `ratio` Example usage `{ "against": "#ffffff" }`
`level`	`string`	WCAG level the contrast meets.
Use when: Record which WCAG level the ratio satisfies. Origin: Computed by analysis tooling. Related: `ratio` Example usage `{ "level": "AA" }`

`Counts`

Total counts plus per-dimension breakdowns for the manifest.

Field	Type	Description
`total`	`integer`	Total number of items, such as tokens.
Use when: Give consumers the total without scanning the manifest. Origin: Computed by generators. Example usage `{ "total": 128 }`
`by`	`object`	Counts grouped by a dimension, such as type or category.
Use when: Summarize the manifest by each dimension. Origin: Computed by generators. Related: `total` Example usage `{ "by": { "type": { "color": 72 } } }`

`Deprecated`

Deprecation record for a native manifest entity; defined in the shared lifecycle fragment (lifecycle.json) and referenced from this schema, permissive of unknown properties.

lifecycle.json#/definitions/Deprecated

`DesignSystemMeta`

Identity and packaging metadata for the design system the manifest describes.

Field	Type	Description
`name`	`string`	Display name of the design system.
Use when: Identify the design system in documentation and tooling. Origin: Authored metadata. Example usage `{ "name": "Design Lasagna" }`
`version`	`string`	Version of the design system.
Use when: Track which design-system version a manifest describes. Origin: Authored metadata; maintained with releases. Example usage `{ "version": "1.0.0" }`
`documentation`	`string`	Documentation links for the design system.
Use when: Point consumers to the design system's documentation. Origin: Authored metadata. Example usage `{ "documentation": { "url": "https://example.com/docs" } }`
`package`	`string`	Package identifier of the design system.
Use when: Map the manifest to its published package. Origin: Authored metadata. Example usage `{ "package": "@designlasagna/design-system" }`
`docsTemplates`	`object`	Documentation template configuration.
Use when: Configure how documentation is generated from the design system. Origin: Authored metadata. Example usage `{ "docsTemplates": [ "tokens" ] }`

`Docs`

Documentation and design-tool links for a token.

Field	Type	Description
`url`	`string`	URL of the documentation for the token.
Use when: Link to the token's documentation. Origin: Authored metadata. Related: `figma`, `storybook` Example usage `{ "url": "https://example.com/docs/color" }`
`figma`	`string`	Figma file or node link for the token.
Use when: Point to the design source in Figma. Origin: Authored metadata. Related: `url` Example usage `{ "figma": "https://www.figma.com/file/abc/Color" }`
`storybook`	`string`	Storybook link for the token.
Use when: Point to live examples in Storybook. Origin: Authored metadata. Related: `url` Example usage `{ "storybook": "https://storybook.example.com/?path=/docs/color--primary" }`

`Format`

Format metadata for a token, such as its color space or unit.

Field	Type	Description
`colorSpace`	`string`	Color space for color tokens.
Use when: Interpret color values in tooling. Origin: Authored metadata. Related: `unit` Example usage `{ "colorSpace": "srgb" }`
`unit`	`string`	Unit for dimension-like tokens.
Use when: Interpret numeric values in tooling. Origin: Authored metadata. Related: `colorSpace` Example usage `{ "unit": "rem" }`

`PlatformMapping`

The platform-specific reference developers use for a token.

Field	Type	Description
`reference*`	`string`	Platform-specific identifier developers use for the token.
Use when: Map the token to the concrete identifier on a platform. Origin: Authored metadata; carried through by generators. Related: `cssVariable` Example usage `{ "reference": "Color.Blue500" }`

`TokenRelation`

A named relationship between tokens, such as a derived token.

Field	Type	Description
`type*`	`string`	Type of the relationship.
Use when: Classify how the related tokens are connected. Origin: Authored metadata. Related: `tokens` Example usage `{ "type": "derived" }`
`tokens*`	`array`	Tokens involved in the relationship.
Use when: Identify the tokens the relationship connects. Origin: Authored metadata. Related: `type` Example usage `{ "tokens": [ "color.surface", "color.surface-raised" ] }`
`description`	`string`	Human-readable description of the relationship.
Use when: Explain the relationship in documentation. Origin: Authored metadata. Example usage `{ "description": "Raised surface is derived from the base surface." }`

`Usage`

Usage guidance for a token: allowed properties, intended context, and anti-patterns.

Field	Type	Description
`allowedProperties`	`array`	Properties the token may be used with.
Use when: Constrain how tooling applies the token. Origin: Authored metadata. Related: `context` Example usage `{ "allowedProperties": [ "color", "background-color" ] }`
`context`	`string`	Context in which the token is intended to be used.
Use when: Guide consumers to the right usage scenario. Origin: Authored metadata. Related: `allowedProperties`, `doNot` Example usage `{ "context": "Use for primary actions." }`
`doNot`	`array`	Anti-patterns for the token.
Use when: Warn consumers about incorrect usage. Origin: Authored metadata. Related: `context` Example usage `{ "doNot": "Do not use for disabled states." }`

All schemas