Design Lasagna

Schemas / v0.3

Utilities

Schema for resolved utility manifests consumed by language servers and tooling.

Minimal example

This manifest declares a flat utilities list. The schema also allows a categories manifest, in which each category groups its utilities — every utility class follows the same shape either way.

{
  "$schema": "https://designlasagna.recipes/schemas/v0.3/utilities.json",
  "schemaVersion": "0.3.0",
  "utilities": [
    {
      "name": "layout:grid",
      "description": "Arrange content on a CSS grid.",
      "status": "stable"
    }
  ]
}

Manifest fields

* Required field. A manifest declares categories or utilities (one of the two), alongside schemaVersion.

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/utilities.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 utilities manifest was produced.

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

Origin: Generated metadata.

Related: designSystem

Example usage

{
  "generatedAt": "2026-09-04T00:00:00Z"
}
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: generatedAt

Example usage

{
  "designSystem": {
    "name": "Acme Design System",
    "version": "2.4.0"
  }
}
VariantPatterns Declares the state and responsive variant names available to utilities.

Use when: Use when utilities expose variant forms that tools should recognise, such as `hover:` or breakpoint prefixes.

Origin: Generated from the utility definition.

Related: utilities

Example usage

{
  "variantPatterns": {
    "states": {
      "hover": {
        "format": "hover:{utility}",
        "description": "Applies while the element is hovered."
      }
    },
    "responsive": {
      "breakpoints": [
        "sm",
        "md"
      ],
      "format": "sm:{utility}"
    }
  }
}
array Groups utilities into named categories.

Use when: Use to organise utilities for browsing and autocomplete grouping.

Origin: Generated from authored definitions.

Related: utilities

Example usage

{
  "categories": [
    {
      "name": "Layout",
      "description": "Utilities that control layout.",
      "prefix": "layout",
      "utilities": [
        {
          "name": "layout:grid"
        }
      ]
    }
  ]
}
array Contains the utility class records in this manifest.

Use when: Always include the utilities a consumer should discover or apply.

Origin: Generated from authored utility definitions.

Related: categories, variantPatterns

Example usage

{
  "utilities": [
    {
      "name": "flex",
      "status": "stable",
      "variants": {
        "responsive": true
      }
    }
  ]
}

Utility class fields

Each item in utilities follows this shape.

Field Type Description
string The stable utility identifier, such as a utility name.

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

Origin: Authored metadata.

Related: description, keywords

Example usage

{
  "name": "flex"
}
string Explains what the utility does and when to apply it.

Use when: Use to give implementers the intent that a name cannot convey.

Origin: Authored metadata.

Related: name, keywords

Example usage

{
  "description": "Lay out children in a flex row."
}
string Describes the lifecycle status of the utility.

Use when: Use so consumers know how much they can rely on the utility, such as stable versus experimental.

Origin: Authored metadata.

Related: since, deprecated

Example usage

{
  "status": "stable"
}
string Names the group of mutually exclusive utilities.

Use when: Use when only one utility in a set should be applied at a time, such as display modes.

Origin: Authored metadata.

Related: name

Example usage

{
  "exclusiveGroup": "display"
}
UtilityVariants Controls which variant kinds a specific utility supports.

Use when: Use to advertise the state and responsive variants of this utility in autocomplete.

Origin: Authored metadata.

Related: status

Example usage

{
  "variants": {
    "responsive": true
  }
}
integer Influences the order utilities appear in suggestion lists.

Use when: Use to surface the most common utilities first in tooling.

Origin: Authored metadata.

Related: keywords

Example usage

{
  "priority": 80
}
array Supplies natural-language synonyms and search terms.

Use when: Use to improve discovery in autocomplete and documentation search.

Origin: Authored metadata.

Related: description, name

Example usage

{
  "keywords": [
    "layout",
    "flex"
  ]
}
string Records the version in which the utility became available.

Use when: Use to make compatibility and migration decisions.

Origin: Authored metadata.

Related: status, deprecated

Example usage

{
  "since": "2.4.0"
}
Docs Links the utility 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/docs/utilities/flex"
  }
}
object
values: PlatformUtility 		Maps each platform name to that platform’s utility expression.

Use when: Use when a utility is realised differently per platform, such as a class name and CSS properties on the web.

Origin: Generated or authored mapping.

Related: properties

Example usage

{
  "platforms": {
    "web": {
      "className": "flex",
      "properties": {
        "display": "flex"
      }
    }
  }
}
object DEPRECATED in v0.3. Maps CSS property names to utility values; new manifests should use `platforms.web.properties` instead.

Use when: Read it for legacy manifests only; do not add it to new ones.

Origin: Legacy authored mapping.

Related: platforms

Example usage

{
  "properties": {
    "display": "flex"
  }
}
array Lists the token identifiers this utility references.

Use when: Use to connect a utility back to the design tokens it consumes.

Origin: Generated from utility evaluation.

Related: name

Example usage

{
  "tokens": [
    "spacing.400",
    "color.blue.500"
  ]
}
— Marks the utility as deprecated and explains its replacement.

Use when: Use when the utility remains available temporarily while guiding consumers to a successor.

Origin: Authored metadata.

Related: status, since

Example usage

{
  "deprecated": {
    "message": "Use layout:grid instead.",
    "replacement": "layout:grid"
  }
}

Nested definitions

Category

A named grouping of utilities. It carries a display name, an optional prefix, and the utility records that belong to the group.

Field Type Description
string The human-readable name of the utility category.

Use when: Always provide it; it names the group in documentation and UI.

Origin: Authored metadata.

Related: description, prefix

Example usage

{
  "name": "Layout"
}
string Explains what the category covers.

Use when: Use to help readers choose the right category at a glance.

Origin: Authored metadata.

Related: name

Example usage

{
  "description": "Utilities that control layout."
}
string The common utility name prefix shared by this category.

Use when: Use when tools should recognise related utilities by naming.

Origin: Authored metadata.

Related: name, utilities

Example usage

{
  "prefix": "layout"
}
array The utility classes belonging to this category.

Use when: Always list the utilities so category browsing stays complete.

Origin: Generated from authored definitions.

Related: name

Example usage

{
  "utilities": [
    {
      "name": "layout:grid",
      "status": "stable"
    }
  ]
}

Deprecated

Migration information for a utility 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 utility is deprecated and what to do instead.

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

Origin: Authored metadata.

Related: replacement, removal

Example usage

{
  "message": "Use layout:grid 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 machine-readable successor utility.

Use when: Use to provide a direct migration path.

Origin: Authored metadata.

Related: message

Example usage

{
  "replacement": "layout:grid"
}

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 utility 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-system"
}
object Provides URL templates for constructing documentation links.

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

Origin: Authored metadata.

Related: documentation

Example usage

{
  "docsTemplates": {
    "url": "/docs/utilities/{name}"
  }
}

Docs

Links from a utility 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 utility.

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

Origin: Authored metadata.

Related: figma, storybook

Example usage

{
  "url": "https://example.com/docs/utilities/flex"
}
string Links to the corresponding Figma resource.

Use when: Use when designers need to locate the utility 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 utility in component examples.

Origin: Authored metadata.

Related: url

Example usage

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

PlatformUtility

The platform-specific ways a utility is expressed, such as a class name on the web or style properties, so tooling can apply it faithfully per platform.

Field Type Description
string The class name that expresses the utility on this platform.

Use when: Use when the platform applies the utility through a class.

Origin: Generated or authored mapping.

Related: modifier, properties

Example usage

{
  "className": "flex"
}
string The modifier token the platform combines with a base class to express the utility.

Use when: Use when the platform names utilities as a base class plus a modifier, rather than a single class name.

Origin: Generated or authored mapping.

Related: className

Example usage

{
  "modifier": "flex"
}
string A style fragment the platform attaches to express the utility.

Use when: Use when the platform realises the utility through inline or embedded style text.

Origin: Generated or authored mapping.

Related: properties

Example usage

{
  "style": "display: flex;"
}
object The property map the platform uses to implement the utility.

Use when: Use when the utility is realised directly as style properties.

Origin: Generated from utility evaluation.

Related: className

Example usage

{
  "properties": {
    "display": "flex"
  }
}

UtilityVariants

Per-utility variant support flags. It records whether a state and a responsive variant apply to this utility, keeping variant data distinct from the shared variant vocabulary.

Field Type Description
— Indicates which state variants this utility supports.

Use when: Use to advertise state variants such as `hover:` for one specific utility.

Origin: Authored metadata.

Related: responsive

Example usage

{
  "states": [
    "hover",
    "focus"
  ]
}
boolean Indicates whether this utility supports responsive breakpoint variants.

Use when: Use when the utility is offered under breakpoint prefixes such as `sm:` and `md:`.

Origin: Authored metadata.

Related: states

Example usage

{
  "responsive": true
}

VariantPatterns

The declared state and responsive variant naming patterns a manifest supports. It lets tooling generate and recognise variant names such as `hover:flex` or `sm:flex`.

Field Type Description
object Declares the pseudo-state variants available to utilities.

Use when: Use when utilities support state forms such as `hover:` or `focus:` and tools should generate them.

Origin: Generated from variant configuration.

Related: responsive

Example usage

{
  "states": {
    "hover": {
      "format": "hover:{utility}",
      "description": "Applies while the element is hovered."
    }
  }
}
object Declares the responsive breakpoints and naming form for utility variants.

Use when: Use when utilities support breakpoint variants like `sm:`.

Origin: Generated from breakpoint configuration.

Related: states

Example usage

{
  "responsive": {
    "breakpoints": [
      "sm",
      "md"
    ],
    "format": "sm:{utility}"
  }
}

← All schemas · Schema source on GitHub ↗