Schemas / v0.4

Utilities

Schema for resolved utility manifests consumed by language servers and tooling. A manifest must use exactly one root representation: flat utilities or grouped categories. Neither representation is preferred.

Minimal example

This manifest declares the 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.4/utilities.json",
  "schemaVersion": "0.4.0",
  "utilities": [
    {
      "name": "layout:grid"
    }
  ]
}

Manifest fields

The root object is the resolved utilities manifest. Required fields are marked with *. A manifest declares categories or utilities (exactly one of the two), alongside schemaVersion.

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://designlasagna.recipes/schemas/v0.4/utilities.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" }`
`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: `generatedAt` Example usage `{ "designSystem": { "name": "Design Lasagna", "version": "1.0.0", "package": "@designlasagna/design-system" } }`
`variantPatterns`	`VariantPatterns`	Declared state and responsive variant patterns available to utilities.
Use when: Let tooling generate and recognise variant names such as `hover:grid` or `sm:grid`. Origin: Generated from variant configuration. Related: `utilities`, `categories` Example usage `{ "variantPatterns": { "states": { "hover": { "format": "hover:{utility}", "description": "Applies while the element is hovered." } }, "responsive": { "breakpoints": [ "sm", "md" ], "format": "sm:{utility}" } } }`
`categories`	`array`	Category-grouped manifest branch; the alternative to the flat utilities list.
Use when: Use when utilities are organised into named categories for browsing and autocomplete grouping. Origin: Generated from authored definitions. Related: `utilities` Example usage `{ "categories": [ { "name": "Layout", "prefix": "layout", "utilities": [ { "name": "layout:grid" } ] } ] }`
`utilities`	`array`	Flat manifest branch listing utility classes; the alternative to the categories list.
Use when: Use when the manifest declares utility classes without category grouping. Origin: Generated from authored utility definitions. Related: `categories`, `variantPatterns` Example usage `{ "utilities": [ { "name": "layout:grid" } ] }`

Utility fields

Each item in utilities — or in a category's utilities list — follows this shape.

Field	Type	Description
`name*`	`string`	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": "layout:grid" }`
`description`	`string`	Human-readable description of what the utility does.
Use when: Use to give implementers the intent that a name cannot convey. Origin: Authored metadata. Related: `name`, `keywords` Example usage `{ "description": "Arrange content on a CSS grid." }`
`status`	`lifecycle.json#/definitions/Status`	Lifecycle status from the shared v0.4 lifecycle fragment; 'deprecated' and 'removed' are normative, other values are informational.
Use when: Declare the normative lifecycle state of the utility, or carry informational states such as 'stable' or 'experimental'. Origin: Authored metadata. Related: `deprecated` Example usage `{ "status": "stable" }`
`exclusiveGroup`	`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" }`
`variants`	`UtilityVariants`	Variant support for this utility: state and responsive flags.
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 } }`
`priority`	`integer`	Sort weight for autocomplete, from 0 (lowest) to 100 (highest).
Use when: Use to surface the most common utilities first in tooling. Origin: Authored metadata. Related: `keywords` Example usage `{ "priority": 80 }`
`keywords`	`array`	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", "grid" ] }`
`since`	`string`	Version or date when the utility was introduced.
Use when: Use to make compatibility and migration decisions. Origin: Authored metadata. Related: `status`, `deprecated` Example usage `{ "since": "1.2.0" }`
`docs`	`Docs`	Links to the utility's 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://designlasagna.recipes/docs/utilities/layout-grid" } }`
`platforms`	`object` values: `PlatformUtility`	Platform-specific implementations, keyed by platform identifier.
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": "layout:grid", "properties": { "display": "grid" } } } }`
`properties` Deprecated	`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": "grid" } }`
`tokens`	`array`	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" ] }`
`deprecated`	`lifecycle.json#/definitions/NativeDeprecation`	Native deprecation record from the shared v0.4 lifecycle fragment; may be false, null, or a record with a required message.
Use when: Guide consumers away from a utility while it remains available, recording its replacement and removal target. Origin: Authored metadata. Related: `status`, `since` Example usage `{ "deprecated": { "message": "Use layout:grid instead.", "replacement": "layout:grid" } }`

Nested definitions

Reusable shapes referenced by the fields above.

`Category`

A named grouping of utilities, carrying display metadata and the utility records that belong to the group.

Field	Type	Description
`name*`	`string`	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" }`
`description`	`string`	Description of 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." }`
`prefix`	`string`	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" }`
`utilities*`	`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`

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 discovery metadata for the design system that produced the manifest.

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": "https://designlasagna.recipes/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`	URL templates for generating documentation links.
Use when: Configure how tooling builds documentation links for utilities. Origin: Authored metadata. Example usage `{ "docsTemplates": { "url": "/docs/utilities/{name}" } }`

`Docs`

Documentation and design-tool links for a utility.

Field	Type	Description
`url`	`string`	Primary documentation page for this item.
Use when: Provide it as the canonical destination for detailed guidance. Origin: Authored metadata. Related: `figma`, `storybook` Example usage `{ "url": "https://designlasagna.recipes/docs/utilities/layout-grid" }`
`figma`	`string`	Figma reference for the design or component.
Use when: Use when implementers need to compare the rendered result with the design source. Origin: Authored metadata. Related: `url` Example usage `{ "figma": "https://figma.com/file/designlasagna/utilities" }`
`storybook`	`string`	Storybook reference for live component states.
Use when: Use when readers benefit from interactive examples. Origin: Authored metadata. Related: `url` Example usage `{ "storybook": "https://storybook.designlasagna.recipes/?path=/story/utilities--grid" }`

`PlatformUtility`

How one utility is realised on a specific platform, such as a class name or style properties on the web.

Field	Type	Description
`className`	`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": "layout:grid" }`
`modifier`	`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": "grid" }`
`style`	`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: grid; grid-template-columns: repeat(4, 1fr);" }`
`properties`	`object`	CSS properties and values that realise the utility on this platform.
Use when: Use when tooling needs the underlying declarations to apply or preview the utility. Origin: Generated from utility evaluation. Related: `className` Example usage `{ "properties": { "display": "grid" } }`

`UtilityVariants`

Per-utility variant support flags, recording which states and whether responsive variants apply to this utility.

Field	Type	Description
`states`	—	State variant support: true for all declared states, or a subset of state names.
Use when: Use to advertise state variants such as `hover:` for one specific utility. Origin: Authored metadata. Related: `responsive` Example usage `{ "states": [ "hover", "focus" ] }`
`responsive`	`boolean`	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, letting tools generate and recognise names like `hover:grid` or `sm:grid`.

Field	Type	Description
`states`	`object`	Declared pseudo-state variants, keyed by state name.
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." } } }`
`responsive`	`object`	Declared 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