Schemas / v0.3

Components

Extensions to Custom Elements Manifest for design system lifecycle metadata.

This is not the Custom Elements Manifest (CEM) schema itself, and it defines no component format. It defines extension fields that a design system may add to CEM declarations and members to record lifecycle metadata: status, deprecation details, and migration targets.

Applying the extensions

The snippet below is a Custom Elements Manifest declaration with the extension fields applied: status on the declaration, and a deprecated attribute value with its migration path. Extension fields are additive — a valid CEM remains valid without them.

{
  "schemaVersion": "1.0.0",
  "modules": [
    {
      "kind": "javascript-module",
      "path": "src/lasagna-button.js",
      "declarations": [
        {
          "kind": "class",
          "name": "LasagnaButton",
          "tagName": "lasagna-button",
          "status": "stable",
          "attributes": [
            {
              "name": "variant",
              "enum": [
                "primary",
                "ghost"
              ],
              "deprecatedValues": [
                {
                  "value": "flat",
                  "message": "Use “ghost” instead.",
                  "replacement": "ghost",
                  "removal": "3.0.0"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Lifecycle fields

These optional fields may be added to a CEM declaration or to its members (attributes, methods, properties).

Field	Type	Description
`status`	`string`	The lifecycle status of the CEM declaration or member this field extends.
Use when: Use so tooling and readers know how much the item can be relied on. Common values are `draft`, `experimental`, `beta`, `rc`, `stable`, `deprecated`, and `removed`; any string is allowed. Origin: Authored metadata. Related: `removal`, `replacement` Example usage `{ "status": "stable" }`
`removal`	`string`	When a deprecated item is expected to be removed.
Use when: Use alongside a deprecation notice so consumers can schedule migration before the item disappears. Origin: Authored metadata. Related: `status`, `replacement` Example usage `{ "removal": "4.0.0" }`
`replacement`	`string`	The machine-readable identifier that replaces a deprecated item.
Use when: Use to point tooling and consumers at the durable identity of the successor, rather than describing it in prose alone. Origin: Authored metadata. Related: `status`, `removal` Example usage `{ "replacement": "lasagna-button-lg" }`

Extension definitions

`AttributeExtensions`

Extension fields that can be added to a CEM attribute or member entry, the allowed value set, plus deprecation and migration information for the attribute as a whole or per value.

Field	Type	Description
`enum`	`array`	The allowed values for a CEM attribute or member.
Use when: Use to advertise the value set of an attribute so autocomplete and validation tools can check it. Origin: Authored or generated metadata. Related: `deprecatedValues` Example usage `{ "enum": [ "primary", "ghost" ] }`
`removal`	`string`	When a deprecated attribute is expected to be removed.
Use when: Use alongside attribute deprecation so consumers can plan the removal. Origin: Authored metadata. Related: `replacement`, `deprecatedValues` Example usage `{ "removal": "4.0.0" }`
`replacement`	`string`	The machine-readable identifier that replaces a deprecated attribute.
Use when: Use to provide the migration target when a whole attribute is going away. Origin: Authored metadata. Related: `removal` Example usage `{ "replacement": "lasagna-button-lg" }`
`deprecatedValues`	`array`	Per-value deprecation records for a CEM attribute.
Use when: Use when only some of an attribute's values are deprecated and each one needs its own migration story. Origin: Authored metadata. Related: `enum` Example usage `{ "deprecatedValues": [ { "value": "flat", "message": "Use \"ghost\" instead.", "replacement": "ghost", "removal": "3.0.0" } ] }`

Example usage

{
  "name": "variant",
  "enum": [
    "primary",
    "ghost"
  ],
  "deprecatedValues": [
    {
      "value": "flat",
      "message": "Use \"ghost\" instead.",
      "replacement": "ghost",
      "removal": "3.0.0"
    }
  ]
}

`CssPropertyExtensions`

Extension fields that can be added to a CEM cssProperty entry to mark it deprecated and record its removal plan and replacement.

Field	Type	Description
`deprecated`	—	Marks a CEM cssProperty entry as deprecated.
Use when: Use with `true` for a plain deprecation flag, or a string explaining why the property no longer has a supported value. Origin: Authored metadata. Related: `removal`, `replacement` Example usage `{ "deprecated": "Use --lasagna-button-corner instead." }`
`removal`	`string`	When a deprecated cssProperty value is expected to be removed.
Use when: Use so consumers can stop setting the property before removal. Origin: Authored metadata. Related: `deprecated`, `replacement` Example usage `{ "removal": "4.0.0" }`
`replacement`	`string`	The cssProperty (or API) that replaces a deprecated one.
Use when: Use to give CSS consumers the direct migration target. Origin: Authored metadata. Related: `deprecated`, `removal` Example usage `{ "replacement": "--lasagna-button-corner" }`

Example usage

{
  "name": "--lasagna-border",
  "deprecated": true,
  "replacement": "--lasagna-button-border",
  "removal": "4.0.0"
}

`DeprecatedValue`

Deprecation information for one specific attribute value. It names the value, explains the deprecation, and records the removal plan and replacement.

Field	Type	Description
`value*`	`string`	The attribute value being deprecated.
Use when: Always provide it; it names the exact value this deprecation record applies to. Origin: Authored metadata. Related: `message` Example usage `{ "value": "flat" }`
`message*`	`string`	Explains why the value is deprecated and what to do instead.
Use when: Always provide it when deprecating a value; it is the reader-facing half of the record. Origin: Authored metadata. Related: `value`, `replacement` Example usage `{ "message": "Use \"ghost\" instead." }`
`removal`	`string`	When the deprecated attribute value is expected to be removed.
Use when: Use to let consumers schedule migration of that specific value. Origin: Authored metadata. Related: `replacement`, `value` Example usage `{ "removal": "3.0.0" }`
`replacement`	`string`	The value that replaces the deprecated one.
Use when: Use to give consumers the direct migration target for the value. Origin: Authored metadata. Related: `value`, `message` Example usage `{ "replacement": "ghost" }`

Example usage

{
  "value": "flat",
  "message": "Use \"ghost\" instead.",
  "replacement": "ghost",
  "removal": "3.0.0"
}

`SlotExtensions`

Extension fields that can be added to a CEM slot entry to mark the slot deprecated and record its removal plan and replacement.

Field	Type	Description
`deprecated`	—	Marks a CEM slot as deprecated.
Use when: Use with `true` for a plain deprecation flag, or a string explaining why the slot is going away and where to move content. Origin: Authored metadata. Related: `removal`, `replacement` Example usage `{ "deprecated": true }`
`removal`	`string`	When a deprecated slot is expected to be removed.
Use when: Use so consumers can migrate slot content before removal. Origin: Authored metadata. Related: `deprecated`, `replacement` Example usage `{ "removal": "4.0.0" }`
`replacement`	`string`	The slot (or API) that replaces a deprecated one.
Use when: Use to point consumers at the durable identity of the successor slot. Origin: Authored metadata. Related: `deprecated`, `removal` Example usage `{ "replacement": "icon" }`

Example usage

{
  "name": "icon",
  "deprecated": true,
  "replacement": "badge",
  "removal": "4.0.0"
}

← All schemas · Schema source on GitHub ↗