Component format

Spec version: 1.0.0-draft (see Overview)

This document defines the normative component declaration object: identity ($id, name, displayName), component metadata (meta), platform implementations (implementations), API options (options), named content slots (slots), anatomy parts (anatomy), state model (states), and lifecycle metadata.

Component declarations close the structural gap between the token name-object's component, variant, anatomy, and state fields and the declared surface of each component. Before this chapter, a token referencing component: "button" with variant: "foo" was undetectable as invalid because no machine-readable component contract existed in the same spec. After this chapter, validators enforce cross-reference rules (see SPEC rules).

Scoped under RFC-A — Component Contract in Design Data Spec. See also rfc-coordination.md.

Document shape

A component declaration is a single JSON object in a .json file. One file per component. Files live under a components/ directory within a design-data package.

NORMATIVE: Each component declaration file MUST validate against the Layer 1 schema component.schema.json (canonical $id: https://opensource.adobe.com/spectrum-design-data/schemas/v0/component.schema.json). Layer 1 and Layer 2 validation are defined in the validation layers section of the overview.

Component object

Required fields

A component declaration MUST contain:

Optional fields

NORMATIVE: No properties beyond those listed above are permitted at the top level of a component declaration. Additional fields MUST cause a Layer 1 schema error.

$id

NORMATIVE: The $id MUST be a valid URI identifying this component declaration document. The recommended pattern is:

https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/{name}.json

where {name} matches the component's name field.

name

NORMATIVE: name MUST match the pattern ^[a-z][a-z0-9-]*$ — lower-case kebab-case, non-empty.

NORMATIVE: name MUST be unique within a dataset. No two component declarations in the same design-data package may share a name value.

NORMATIVE: Token name-object component field values MUST match the name of a declared component in the dataset (rule SPEC-018). An undeclared component value is a validation error.

Meta

NORMATIVE: meta MUST contain:

"meta": {
  "category": "actions",
  "documentationUrl": "https://spectrum.adobe.com/page/button/"
}

Implementations

implementations declares the published platform implementations corresponding to this design-system component. It is foundation-owned canonical data so consumers, including Code Connect generators, can resolve an implementation without platform-specific configuration.

Each entry MUST contain platform and componentName, plus exactly one implementation reference: package for a published package or importPath for an importable module/source path. notes is optional context for consumers. Multiple entries MAY use the same platform when their packages distinguish different implementations for that platform.

"implementations": [
  {
    "platform": "web",
    "componentName": "Button",
    "package": "@spectrum-web-components/button"
  }
]

Platform manifests do not override implementations in this version. A future extension may add platform-owned overrides after consumers need them; until then, component declarations remain the canonical source of implementation names and references.

Options

The options block declares the component's API surface — the configurable properties that affect its appearance or behavior. It mirrors the shape of @adobe/spectrum-component-api-schemas for backward compatibility.

NORMATIVE: options MUST be a JSON object. Each key is an option name; each value is an option descriptor.

Option descriptor

An option descriptor is a JSON object with the following fields:

optionValue

Each entry in values is an object:

NORMATIVE: Each key in options MUST be camelCase.

NORMATIVE: Boolean option names MUST begin with is or has (e.g. isDisabled, hasIcon).

NORMATIVE: When values is present, token name-object variant field values referencing this component MUST be drawn from the declared variant option values list (rule SPEC-019, Error). Token name-object keys matching any other declared option's values list SHOULD be drawn from that list (rule SPEC-040, Warning). Both rules are silent when no values array is declared for the option.

ADVISORY: When a value in values carries a lifecycle.deprecated string and a non-deprecated token references that value via its name object field, SPEC-037 fires an advisory warning prompting migration or token deprecation.

Example with a deprecated option value:

"variant": {
  "type": "string",
  "values": [
    { "value": "primary" },
    { "value": "secondary" },
    {
      "value": "cta",
      "lifecycle": {
        "deprecated": "1.0.0-draft",
        "deprecatedComment": "Use primary instead."
      }
    }
  ]
}

"options": {
  "variant": {
    "type": "string",
    "values": [
      { "value": "accent" },
      { "value": "negative" },
      { "value": "primary" },
      { "value": "secondary" }
    ],
    "default": "accent",
    "description": "Visual emphasis level."
  },
  "size": {
    "type": "string",
    "values": [
      { "value": "s" },
      { "value": "m" },
      { "value": "l" },
      { "value": "xl" }
    ],
    "default": "m"
  },
  "isDisabled": {
    "type": "boolean",
    "default": false
  },
  "icon": {
    "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/workflow-icon.json",
    "description": "Icon placed at the start of the button. Required when hideLabel is true."
  }
}

Slots

The slots block declares the component's named content injection points — the positions where consumers place child content. Slot declarations are derived from the cross-platform audit in audits/slots.audit.md.

NORMATIVE: slots MUST be a JSON array. Each element is a slot declaration.

Slot declaration

Canonical slot vocabulary

The following slot names are defined by the cross-platform audit and SHOULD be used in preference to custom names:

NORMATIVE: Custom slot names are permitted but SHOULD be documented in the slot's description field (rule SPEC-021 fires a warning for undocumented custom names).

RECOMMENDED: Components SHOULD declare a default slot when they accept primary child content.

"slots": [
  {
    "name": "default",
    "description": "Text label of the button.",
    "required": false
  },
  {
    "name": "icon",
    "description": "Icon placed at the start of the button. Required when isLabelHidden is true."
  }
]

Anatomy (stub)

The anatomy block declares the component's named visual parts — the anatomy terms used in token name-object anatomy fields. Full normative definition is in spec/anatomy-format.md (Phase 6.2).

NORMATIVE: anatomy MUST be a JSON array. Each element is an anatomy part object.

NORMATIVE: Token name-object anatomy field values referencing this component MUST match the name of a declared anatomy part (rule SPEC-020).

Each anatomy part carries at minimum:

See spec/anatomy-format.md for constraints, cross-field validation, and the full anatomy part schema.

"anatomy": [
  { "name": "icon", "description": "Leading icon." },
  { "name": "label", "description": "Button text.", "required": true }
]

States (stub)

The states block declares the component's interactive and semantic states — the state terms used in token name-object state fields. Full normative definition is in spec/state-model.md (Phase 6.3).

NORMATIVE: states MUST be a JSON array. Each element is a state declaration object.

Each state carries at minimum:

See spec/state-model.md for the full state resolution algorithm, trigger semantics, and precedence rules.

"states": [
  { "name": "hover",    "trigger": "interaction", "precedence": 50 },
  { "name": "focus",    "trigger": "interaction", "precedence": 60, "layered": true },
  { "name": "disabled", "trigger": "prop",        "precedence": 100 }
]

Lifecycle

The lifecycle block tracks a component declaration's version history. It mirrors the per-token lifecycle pattern from spec/token-format.md.

"lifecycle": {
  "introduced": "1.0.0-draft"
}

Token bindings

The optional tokenBindings array declares which tokens a component uses, including foundation and structure tokens that do not carry the component name in their name-object. This is the component-declares-usage direction; the token-declares-scope direction is expressed via name-object component/anatomy/state fields and validated by SPEC-018–022.

"tokenBindings": [
  { "token": "component-height-100",         "context": "Minimum height" },
  { "token": "corner-radius-full",           "context": "Rounding" },
  { "token": "button-background-color-accent", "context": "Fill background" }
]

Each entry contains:

NORMATIVE: When the dataset includes token declarations, each tokenBindings[].token value MUST match the name of a declared token (rule SPEC-027). A missing token reference is a validation error.

The context field is informative. It is used by describe_component (Phase 8 agent surface) to present token usage in grouped, human-readable form.

SPEC rules

The following rules are added to the Layer 2 rule catalog (rules/rules.yaml) by this chapter. New component cross-reference rules start at SPEC-018 to avoid collision with existing token rules (SPEC-001–SPEC-017).

Full example

A complete button component declaration:

{
  "$schema": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/component.schema.json",
  "$id": "https://opensource.adobe.com/spectrum-design-data/schemas/v0/components/button.json",
  "specVersion": "1.0.0-draft",
  "name": "button",
  "displayName": "Button",
  "description": "Buttons allow users to perform an action or to navigate to another page.",
  "meta": {
    "category": "actions",
    "documentationUrl": "https://spectrum.adobe.com/page/button/"
  },
  "options": {
    "variant": {
      "type": "string",
      "values": [
        { "value": "accent" },
        { "value": "negative" },
        { "value": "primary" },
        { "value": "secondary" }
      ],
      "default": "accent",
      "description": "Visual emphasis level."
    },
    "style": {
      "type": "string",
      "values": [{ "value": "fill" }, { "value": "outline" }],
      "default": "fill"
    },
    "size": {
      "type": "string",
      "values": [
        { "value": "s" },
        { "value": "m" },
        { "value": "l" },
        { "value": "xl" }
      ],
      "default": "m"
    },
    "isDisabled": { "type": "boolean", "default": false },
    "isPending": { "type": "boolean", "default": false },
    "isLabelHidden": { "type": "boolean", "default": false },
    "icon": {
      "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/workflow-icon.json",
      "description": "Icon placed at the start of the button. Required when isLabelHidden is true."
    },
    "staticColor": {
      "type": "string",
      "values": [{ "value": "white" }, { "value": "black" }],
      "description": "Static color for use on colored backgrounds. Must not be set for the default variant."
    }
  },
  "slots": [
    {
      "name": "default",
      "description": "Text label of the button.",
      "required": false
    },
    {
      "name": "icon",
      "description": "Icon placed at the start of the button."
    }
  ],
  "anatomy": [
    { "name": "icon",  "description": "Leading icon." },
    { "name": "label", "description": "Button text.", "required": true }
  ],
  "states": [
    { "name": "hover",    "trigger": "interaction", "precedence": 50 },
    { "name": "focus",    "trigger": "interaction", "precedence": 60, "layered": true },
    { "name": "disabled", "trigger": "prop",        "precedence": 100 }
  ],
  "lifecycle": {
    "introduced": "1.0.0-draft"
  }
}

Accessibility

Phase 7. Component declarations MAY carry an accessibility object at the top level. State declarations MAY carry announce, communicates, and blocksInteraction fields. See spec/accessibility.md for the full vocabulary, SPEC rules, and examples.

{
  "name": "button",
  "displayName": "Button",
  "meta": { "category": "actions", "documentationUrl": "https://spectrum.adobe.com/page/button/" },
  "accessibility": {
    "role": "button",
    "intents": ["trigger"],
    "focusable": true,
    "keyboardIntents": ["activate"],
    "wcag": [
      { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
    ]
  },
  "states": [
    {
      "name": "disabled",
      "trigger": "prop",
      "precedence": 100,
      "announce": "Button disabled",
      "communicates": "disabled",
      "blocksInteraction": true
    }
  ]
}

Document blocks

Phase 9. Component declarations MAY carry a documentBlocks array at the top level, and individual anatomy parts MAY carry their own documentBlocks arrays. See spec/document-blocks.md for the full block schema, type vocabulary, and SPEC rules.

{
  "name": "button",
  "displayName": "Button",
  "meta": { "category": "actions", "documentationUrl": "https://spectrum.adobe.com/page/button/" },
  "documentBlocks": [
    {
      "type": "purpose",
      "content": "Buttons trigger a discrete action or event.",
      "agents": "Use Button when the user must trigger an action. For navigation, use Link."
    }
  ],
  "anatomy": [
    {
      "name": "label",
      "required": true,
      "documentBlocks": [
        {
          "type": "guideline",
          "content": "Button labels should be action verbs (Save, Delete, Submit)."
        }
      ]
    }
  ]
}