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), 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/"
}

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)."
        }
      ]
    }
  ]
}