Props

Props define the configurable inputs of a component. Each prop has a type, a default value, and optional extensions.

type Props = Record<string, AnyProp>;
type AnyProp = BooleanProp | StringProp | EnumProp | NumberProp | SlotProp | ImageProp;

Prop Kinds

BooleanProp

Property	Type	Required	Description
`type`	`'boolean'`	Yes
`default`	`boolean`	Yes	Default value
`$extensions`	`PropExtensions`	No	Vendor extensions

EnumProp

Property	Type	Required	Description
`type`	`'string'`	Yes
`default`	`string`	Yes	Default value (must be in `enum`)
`enum`	`string[]`	Yes	Allowed values
`nullable`	`boolean`	No	Whether `null` is a valid value — absent means `false`
`$extensions`	`PropExtensions`	No	Vendor extensions

StringProp

Property	Type	Required	Description
`type`	`'string'`	Yes
`default`	`string \| null`	No	Deprecated — use `examples`
`nullable`	`boolean`	No	Whether `null` is a valid value — absent means `true`
`examples`	`string[]`	No	Example values
`$extensions`	`PropExtensions`	No	Vendor extensions

A StringProp is distinguished from an EnumProp by the absence of enum.

NumberProp

Property	Type	Required	Description
`type`	`'number'`	Yes
`default`	`number`	No	Default value
`enum`	`number[]`	No	Closed set of allowed values, recorded when the prop was inferred from a VARIANT prop’s finite value set (ADR-072)
`nullable`	`boolean`	No	Whether `null` is a valid value — absent means `true` (since 0.29.0)
`examples`	`number[]`	No	Example values

Inferred from Figma variant values when conventions.platforms.figma.inferNumberProps is enabled; a prop inferred from a VARIANT source carries the variant’s values as enum.

SlotProp

Property	Type	Required	Description
`type`	`'slot'`	Yes
`default`	`string \| null`	No	Default slot content
`nullable`	`boolean`	No	Whether `null` is a valid value — absent means `true`
`minChildren`	`number`	No	Minimum number of children the slot accepts (since 0.25.0)
`maxChildren`	`number`	No	Maximum number of children the slot accepts (since 0.25.0)
`anyOf`	`string[]`	No	Permitted component type names (since 0.14.0)
`$extensions`	`PropExtensions`	No	Vendor extensions

Slot constraint properties (minChildren, maxChildren, anyOf) are emitted when conventions.platforms.figma.slotConstraints is declared.

ImageProp

Property	Type	Required	Description
`type`	`'image'`	Yes
`default`	`string \| null`	No	Default image — an `images` registry reference, or null
`nullable`	`boolean`	No	Whether `null` is a valid value — absent means `true`
`examples`	`ImageValue[]`	No	Authoring-default images the component was authored with (since 0.33.0)
`$extensions`	`PropExtensions`	No	Vendor extensions

An image-valued property (e.g. a dsImage source prop). Emitted for code-only props named in figma.images.sourceProps (since 0.28.0).

An authoring-default image sits in one of two places, and they describe different things:

Location	Describes
`ImageBinding.examples`	The image at that binding site — how one consumer placed it
`ImageProp.examples`	The image the component itself was authored with

Where both apply to one rendered instance, the binding is the more specific statement. A designated image component is the origin of an image rather than a consumer of one, so it has no binding site in its own spec — examples on the prop is its only home for this.

examples is non-contractual reference material, parallel to StringProp.examples, and is distinct from default: a default states what the prop resolves to when a consumer omits it, while examples only demonstrate typical content.

props:
  imageSource:
    type: image
    examples:
      - $image: "#/components/dsImage/images/dsImage__image"

Nullability

nullable is optional on every prop kind that carries it. Its absence is meaningful, and what it means depends on whether the prop’s value set is open or closed:

Prop kind	Absent `nullable` means	Why
`StringProp`	`true`	Open value set — nothing enumerates it
`NumberProp`	`true`	Open value set
`SlotProp`	`true`	Open content set; a slot may be empty
`ImageProp`	`true`	Open value set
`EnumProp`	`false`	`enum` lists every accepted value, and `null` is not one of them
`BooleanProp`	(no field)	Booleans are never nullable

An explicit nullable: false on an open-valued prop asserts that a value always exists — useful when a code-only prop was authored with a non-empty default:

props:
  # No nullable key — accepts null
  label:
    type: string
  # Explicitly asserts a value is always present
  headingLevel:
    type: number
    default: 2
    nullable: false

Extensions

The $extensions object holds vendor-specific metadata. Currently only the com.figma extension is defined.

FigmaPropExtension

Property	Type	Description
`type`	`string`	Figma property type (e.g. `BOOLEAN`, `TEXT`, `INSTANCE_SWAP`, `VARIANT`)
`source`	`FigmaCodeOnlySource`	Present when the prop originates from a code-only prop layer
`name`	`string`	The Figma property name, present only when the prop key cannot reconstruct it — see Key Formatting

FigmaCodeOnlySource

Property	Type	Description
`kind`	`'codeOnlyProp'`	Always `'codeOnlyProp'`
`layer`	`string`	Sub-layer name in the code-only container
`instanceOf`	`string`	Component name, for enum code-only props