Feature: Component.description

[nathanacurtis]

Draft ADR responding to #374 — carrying a Figma component's authored description into the spec.

Status is DRAFT. This records a proposal and the reasoning behind it; it is not a commitment to accept.

What it decides

Three separate decisions, each with its own options section:

1. Where the value lives — a first-class optional Component.description, sibling to title. Rejected metadata.source.description (provenance is not documentation, and Subcomponent drops metadata), $extensions['com.figma'] (the value is platform-neutral documentation, not a Figma-only concept), and additionalProperties: true (surrenders the closed Component definition that Subcomponent's draft-07 allOf composition depends on).
2. Plain text, not markdown — the Plugin API exposes both description and descriptionMarkdown; the REST file response exposes only the plain form. A markdown field would make the CLI and the plugin emit different output for the same component.
3. Emission gated by a new spec.description setting, default false — every existing run stays byte-identical, and a library opts in knowingly. Same shape as defaultSlotContent (ADR-050). A length cap or truncation was rejected as lossy and arbitrary.

The field is fixed as opaque text — carried, never interpreted. No consumer may parse structure out of it.

Why the gate

The Context section works through what libraries actually put in that box:

• Usage guidance — the high-value case
• Anatomy or prop prose that restates what the spec already models, and drifts from it
• Process and housekeeping — status, ownership, deprecation notes, ticket links
• Nothing at all, for a large share of components

There is enough implicit structure to tempt a parser and never enough to justify one. And the readability cost is real: an unbounded block scalar at the top of every api.yaml, where an editorial reword in Figma reads as a change to the component's API. That is a default problem, not a contract problem — hence declare the property, make the run ask for it.

Change inventory

Artifact	Change
types/Component.ts	description?: string
types/Settings.ts	spec.description?: boolean, required on ResolvedSettings, false in DEFAULT_SETTINGS
schema/component.schema.json	description under #/definitions/Component/properties; definition stays closed
schema/settings.schema.json	spec.description boolean, default false

Subcomponent needs no change — it inherits the field through Omit<Component, …>.

Semver: 0.31.0, MINOR — additive optional fields only.

Refs #374

[nathanacurtis]

Draft ADR responding to #374 — carrying a Figma component's authored description into the spec.

Status is DRAFT. This records a proposal and the reasoning behind it; it is not a commitment to accept.

What it decides

Three separate decisions, each with its own options section:

1. Where the value lives — a first-class optional Component.description, sibling to title. Rejected metadata.source.description (provenance is not documentation, and Subcomponent drops metadata), $extensions['com.figma'] (the value is platform-neutral documentation, not a Figma-only concept), and additionalProperties: true (surrenders the closed Component definition that Subcomponent's draft-07 allOf composition depends on).
2. Plain text, not markdown — the Plugin API exposes both description and descriptionMarkdown; the REST file response exposes only the plain form. A markdown field would make the CLI and the plugin emit different output for the same component.
3. Emission gated by a new spec.description setting, default false — every existing run stays byte-identical, and a library opts in knowingly. Same shape as defaultSlotContent (ADR-050). A length cap or truncation was rejected as lossy and arbitrary.

The field is fixed as opaque text — carried, never interpreted. No consumer may parse structure out of it.

Why the gate

The Context section works through what libraries actually put in that box:

• Usage guidance — the high-value case
• Anatomy or prop prose that restates what the spec already models, and drifts from it
• Process and housekeeping — status, ownership, deprecation notes, ticket links
• Nothing at all, for a large share of components

There is enough implicit structure to tempt a parser and never enough to justify one. And the readability cost is real: an unbounded block scalar at the top of every api.yaml, where an editorial reword in Figma reads as a change to the component's API. That is a default problem, not a contract problem — hence declare the property, make the run ask for it.

Change inventory

Artifact	Change
types/Component.ts	description?: string
types/Settings.ts	spec.description?: boolean, required on ResolvedSettings, false in DEFAULT_SETTINGS
schema/component.schema.json	description under #/definitions/Component/properties; definition stays closed
schema/settings.schema.json	spec.description boolean, default false

Subcomponent needs no change — it inherits the field through Omit<Component, …>.

Semver: 0.31.0, MINOR — additive optional fields only.

Refs #374

[nathanacurtis]

Draft ADR responding to #374 — carrying a Figma component's authored description into the spec.

Status is DRAFT. This records a proposal and the reasoning behind it; it is not a commitment to accept.

What it decides

Three separate decisions, each with its own options section:

1. Where the value lives — a first-class optional Component.description, sibling to title. Rejected metadata.source.description (provenance is not documentation, and Subcomponent drops metadata), $extensions['com.figma'] (the value is platform-neutral documentation, not a Figma-only concept), and additionalProperties: true (surrenders the closed Component definition that Subcomponent's draft-07 allOf composition depends on).
2. Plain text, not markdown — the Plugin API exposes both description and descriptionMarkdown; the REST file response exposes only the plain form. A markdown field would make the CLI and the plugin emit different output for the same component.
3. Emission gated by a new spec.description setting, default false — every existing run stays byte-identical, and a library opts in knowingly. Same shape as defaultSlotContent (ADR-050). A length cap or truncation was rejected as lossy and arbitrary.

The field is fixed as opaque text — carried, never interpreted. No consumer may parse structure out of it.

Why the gate

The Context section works through what libraries actually put in that box:

• Usage guidance — the high-value case
• Anatomy or prop prose that restates what the spec already models, and drifts from it
• Process and housekeeping — status, ownership, deprecation notes, ticket links
• Nothing at all, for a large share of components

There is enough implicit structure to tempt a parser and never enough to justify one. And the readability cost is real: an unbounded block scalar at the top of every api.yaml, where an editorial reword in Figma reads as a change to the component's API. That is a default problem, not a contract problem — hence declare the property, make the run ask for it.

Change inventory

Artifact	Change
types/Component.ts	description?: string
types/Settings.ts	spec.description?: boolean, required on ResolvedSettings, false in DEFAULT_SETTINGS
schema/component.schema.json	description under #/definitions/Component/properties; definition stays closed
schema/settings.schema.json	spec.description boolean, default false

Subcomponent needs no change — it inherits the field through Omit<Component, …>.

Semver: 0.31.0, MINOR — additive optional fields only.

Refs #374

[nathanacurtis]

Draft ADR responding to #374 — carrying a Figma component's authored description into the spec.

Status is DRAFT. This records a proposal and the reasoning behind it; it is not a commitment to accept.

What it decides

Three separate decisions, each with its own options section:

1. Where the value lives — a first-class optional Component.description, sibling to title. Rejected metadata.source.description (provenance is not documentation, and Subcomponent drops metadata), $extensions['com.figma'] (the value is platform-neutral documentation, not a Figma-only concept), and additionalProperties: true (surrenders the closed Component definition that Subcomponent's draft-07 allOf composition depends on).
2. Plain text, not markdown — the Plugin API exposes both description and descriptionMarkdown; the REST file response exposes only the plain form. A markdown field would make the CLI and the plugin emit different output for the same component.
3. Emission gated by a new spec.description setting, default false — every existing run stays byte-identical, and a library opts in knowingly. Same shape as defaultSlotContent (ADR-050). A length cap or truncation was rejected as lossy and arbitrary.

The field is fixed as opaque text — carried, never interpreted. No consumer may parse structure out of it.

Why the gate

The Context section works through what libraries actually put in that box:

• Usage guidance — the high-value case
• Anatomy or prop prose that restates what the spec already models, and drifts from it
• Process and housekeeping — status, ownership, deprecation notes, ticket links
• Nothing at all, for a large share of components

There is enough implicit structure to tempt a parser and never enough to justify one. And the readability cost is real: an unbounded block scalar at the top of every api.yaml, where an editorial reword in Figma reads as a change to the component's API. That is a default problem, not a contract problem — hence declare the property, make the run ask for it.

Change inventory

Artifact	Change
types/Component.ts	description?: string
types/Settings.ts	spec.description?: boolean, required on ResolvedSettings, false in DEFAULT_SETTINGS
schema/component.schema.json	description under #/definitions/Component/properties; definition stays closed
schema/settings.schema.json	spec.description boolean, default false

Subcomponent needs no change — it inherits the field through Omit<Component, …>.

Semver: 0.31.0, MINOR — additive optional fields only.

Refs #374

[nathanacurtis]

Draft ADR responding to #374 — carrying a Figma component's authored description into the spec.

Status is DRAFT. This records a proposal and the reasoning behind it; it is not a commitment to accept.

What it decides

Three separate decisions, each with its own options section:

1. Where the value lives — a first-class optional Component.description, sibling to title. Rejected metadata.source.description (provenance is not documentation, and Subcomponent drops metadata), $extensions['com.figma'] (the value is platform-neutral documentation, not a Figma-only concept), and additionalProperties: true (surrenders the closed Component definition that Subcomponent's draft-07 allOf composition depends on).
2. Plain text, not markdown — the Plugin API exposes both description and descriptionMarkdown; the REST file response exposes only the plain form. A markdown field would make the CLI and the plugin emit different output for the same component.
3. Emission gated by a new spec.description setting, default false — every existing run stays byte-identical, and a library opts in knowingly. Same shape as defaultSlotContent (ADR-050). A length cap or truncation was rejected as lossy and arbitrary.

The field is fixed as opaque text — carried, never interpreted. No consumer may parse structure out of it.

Why the gate

The Context section works through what libraries actually put in that box:

• Usage guidance — the high-value case
• Anatomy or prop prose that restates what the spec already models, and drifts from it
• Process and housekeeping — status, ownership, deprecation notes, ticket links
• Nothing at all, for a large share of components

There is enough implicit structure to tempt a parser and never enough to justify one. And the readability cost is real: an unbounded block scalar at the top of every api.yaml, where an editorial reword in Figma reads as a change to the component's API. That is a default problem, not a contract problem — hence declare the property, make the run ask for it.

Change inventory

Artifact	Change
types/Component.ts	description?: string
types/Settings.ts	spec.description?: boolean, required on ResolvedSettings, false in DEFAULT_SETTINGS
schema/component.schema.json	description under #/definitions/Component/properties; definition stays closed
schema/settings.schema.json	spec.description boolean, default false

Subcomponent needs no change — it inherits the field through Omit<Component, …>.

Semver: 0.31.0, MINOR — additive optional fields only.

Refs #374

[nathanacurtis]

Draft ADR responding to #374 — carrying a Figma component's authored description into the spec.

Status is DRAFT. This records a proposal and the reasoning behind it; it is not a commitment to accept.

What it decides

Three separate decisions, each with its own options section:

1. Where the value lives — a first-class optional Component.description, sibling to title. Rejected metadata.source.description (provenance is not documentation, and Subcomponent drops metadata), $extensions['com.figma'] (the value is platform-neutral documentation, not a Figma-only concept), and additionalProperties: true (surrenders the closed Component definition that Subcomponent's draft-07 allOf composition depends on).
2. Plain text, not markdown — the Plugin API exposes both description and descriptionMarkdown; the REST file response exposes only the plain form. A markdown field would make the CLI and the plugin emit different output for the same component.
3. Emission gated by a new spec.description setting, default false — every existing run stays byte-identical, and a library opts in knowingly. Same shape as defaultSlotContent (ADR-050). A length cap or truncation was rejected as lossy and arbitrary.

The field is fixed as opaque text — carried, never interpreted. No consumer may parse structure out of it.

Why the gate

The Context section works through what libraries actually put in that box:

• Usage guidance — the high-value case
• Anatomy or prop prose that restates what the spec already models, and drifts from it
• Process and housekeeping — status, ownership, deprecation notes, ticket links
• Nothing at all, for a large share of components

There is enough implicit structure to tempt a parser and never enough to justify one. And the readability cost is real: an unbounded block scalar at the top of every api.yaml, where an editorial reword in Figma reads as a change to the component's API. That is a default problem, not a contract problem — hence declare the property, make the run ask for it.

Change inventory

Artifact	Change
types/Component.ts	description?: string
types/Settings.ts	spec.description?: boolean, required on ResolvedSettings, false in DEFAULT_SETTINGS
schema/component.schema.json	description under #/definitions/Component/properties; definition stays closed
schema/settings.schema.json	spec.description boolean, default false

Subcomponent needs no change — it inherits the field through Omit<Component, …>.

Semver: 0.31.0, MINOR — additive optional fields only.

Refs #374

[nathanacurtis]

Draft ADR responding to #374 — carrying a Figma component's authored description into the spec.

Status is DRAFT. This records a proposal and the reasoning behind it; it is not a commitment to accept.

What it decides

Three separate decisions, each with its own options section:

1. Where the value lives — a first-class optional Component.description, sibling to title. Rejected metadata.source.description (provenance is not documentation, and Subcomponent drops metadata), $extensions['com.figma'] (the value is platform-neutral documentation, not a Figma-only concept), and additionalProperties: true (surrenders the closed Component definition that Subcomponent's draft-07 allOf composition depends on).
2. Plain text, not markdown — the Plugin API exposes both description and descriptionMarkdown; the REST file response exposes only the plain form. A markdown field would make the CLI and the plugin emit different output for the same component.
3. Emission gated by a new spec.description setting, default false — every existing run stays byte-identical, and a library opts in knowingly. Same shape as defaultSlotContent (ADR-050). A length cap or truncation was rejected as lossy and arbitrary.

The field is fixed as opaque text — carried, never interpreted. No consumer may parse structure out of it.

Why the gate

The Context section works through what libraries actually put in that box:

• Usage guidance — the high-value case
• Anatomy or prop prose that restates what the spec already models, and drifts from it
• Process and housekeeping — status, ownership, deprecation notes, ticket links
• Nothing at all, for a large share of components

There is enough implicit structure to tempt a parser and never enough to justify one. And the readability cost is real: an unbounded block scalar at the top of every api.yaml, where an editorial reword in Figma reads as a change to the component's API. That is a default problem, not a contract problem — hence declare the property, make the run ask for it.

Change inventory

Artifact	Change
types/Component.ts	description?: string
types/Settings.ts	spec.description?: boolean, required on ResolvedSettings, false in DEFAULT_SETTINGS
schema/component.schema.json	description under #/definitions/Component/properties; definition stays closed
schema/settings.schema.json	spec.description boolean, default false

Subcomponent needs no change — it inherits the field through Omit<Component, …>.

Semver: 0.31.0, MINOR — additive optional fields only.

Refs #374

[nathanacurtis]

Draft ADR responding to #374 — carrying a Figma component's authored description into the spec.

Status is DRAFT. This records a proposal and the reasoning behind it; it is not a commitment to accept.

What it decides

Three separate decisions, each with its own options section:

1. Where the value lives — a first-class optional Component.description, sibling to title. Rejected metadata.source.description (provenance is not documentation, and Subcomponent drops metadata), $extensions['com.figma'] (the value is platform-neutral documentation, not a Figma-only concept), and additionalProperties: true (surrenders the closed Component definition that Subcomponent's draft-07 allOf composition depends on).
2. Plain text, not markdown — the Plugin API exposes both description and descriptionMarkdown; the REST file response exposes only the plain form. A markdown field would make the CLI and the plugin emit different output for the same component.
3. Emission gated by a new spec.description setting, default false — every existing run stays byte-identical, and a library opts in knowingly. Same shape as defaultSlotContent (ADR-050). A length cap or truncation was rejected as lossy and arbitrary.

The field is fixed as opaque text — carried, never interpreted. No consumer may parse structure out of it.

Why the gate

The Context section works through what libraries actually put in that box:

• Usage guidance — the high-value case
• Anatomy or prop prose that restates what the spec already models, and drifts from it
• Process and housekeeping — status, ownership, deprecation notes, ticket links
• Nothing at all, for a large share of components

There is enough implicit structure to tempt a parser and never enough to justify one. And the readability cost is real: an unbounded block scalar at the top of every api.yaml, where an editorial reword in Figma reads as a change to the component's API. That is a default problem, not a contract problem — hence declare the property, make the run ask for it.

Change inventory

Artifact	Change
types/Component.ts	description?: string
types/Settings.ts	spec.description?: boolean, required on ResolvedSettings, false in DEFAULT_SETTINGS
schema/component.schema.json	description under #/definitions/Component/properties; definition stays closed
schema/settings.schema.json	spec.description boolean, default false

Subcomponent needs no change — it inherits the field through Omit<Component, …>.

Semver: 0.31.0, MINOR — additive optional fields only.

Refs #374