Subcomponents

Subcomponents are smaller components embedded within a parent component’s spec. They follow the same structure as a top-level Component but without metadata or nested subcomponents.

type Subcomponent = Omit<Component, 'metadata' | 'subcomponents'>;
type Subcomponents = Record<string, Subcomponent>;

Structure

A Subcomponent contains:

Property	Type	Required	Description
title	string	Yes	Subcomponent name
anatomy	Anatomy	Yes	Element map
props	Props	No	Prop definitions
default	Variant	Yes	Default variant
variants	Variant[]	No	Variant overrides
invalidVariantCombinations	PropConfigurations[]	No	Invalid prop combinations

Linking

Elements in the parent anatomy reference subcomponents via $ref:

anatomy:
  label:
    type: instance
    instanceOf:
      $ref: "#/subcomponents/formLabel"

The $ref is a JSON Pointer into the same spec document.

Detection

Subcomponent detection is controlled by config.processing.subcomponents:

Option	Type	Default	Description
scope	'NESTED' | 'PAGE'	'NESTED'	Where to search — within the component frame or across the entire page
match	string[]	['{C} / _ / {S}']	Name patterns for matching. {C} = parent component name, {S} = subcomponent name
exclude	string[]	—	Patterns to exclude from matching

Further Reading

• ADR 030 — Subcomponent $ref for instanceOf — adds SubcomponentRef for linking anatomy elements to subcomponents
• ADR 031 — Subcomponent Search Scope Config — replaces subcomponentNamePattern with structured scope, match[], exclude[]