Feature: Figma component descriptions

[m-nti]

Summary

Figma REST component and component-set metadata includes a description string, but Specs generation does not preserve it. Please add an optional component-level description field to the Specs schema and populate it from the selected Figma source record.

This would let generated specifications retain component guidance already authored in Figma without requiring consumers to maintain an out-of-schema companion artifact.

Current behavior

For a selected source node, the Figma file response exposes descriptions in one of two maps:

• A standalone COMPONENT uses file.components[nodeId].description.
• A COMPONENT_SET uses file.componentSets[nodeId].description.

Generated component output records the same node in metadata.source.nodeId and metadata.source.nodeType, but does not emit its description. The current Component schema has no description property and rejects additional root properties, so a consumer cannot add the value to api.yaml while retaining schema conformance. The configured transformer registry also provides no custom generation hook for this field.

A concrete example from our repo is Figma component-set node 3288:1275. Its REST metadata contains:

Radio Buttons allow users to select a single option from a set of multiple choices. Once selected, an option cannot be deselected without choosing another.

The generated Radio api.yaml identifies node 3288:1275 but contains no corresponding description.

Proposed schema

Add an optional string to the component definition:

export interface Component {
  title: string;
  description?: string;
  // existing fields
}

Equivalent JSON Schema shape:

{
  "description": {
    "type": "string",
    "minLength": 1
  }
}

Mapping rules

1. Use the source node selected for the generated component.
2. For COMPONENT_SET, read componentSets[nodeId].description.
3. For COMPONENT, read components[nodeId].description.
4. Trim leading and trailing whitespace.
5. Omit description when the source value is absent or whitespace-only; do not emit an empty string.
6. Preserve meaningful internal line breaks and Unicode.
7. With split concerns enabled, place description in api.yaml because it describes the component API/documentation surface rather than variants, examples, or styling.
8. With non-split output, place it on the component root.

Compatibility

The field is optional and additive. Existing documents remain valid, existing consumers can ignore it, and generators continue producing the same output for Figma components without descriptions.

Acceptance criteria

• The Component TypeScript type and JSON Schema expose description?: string.
• Figma REST generation covers both COMPONENT and COMPONENT_SET source records.
• Split-concern generation writes the field to api.yaml.
• Non-split generation writes the field to the component root.
• Empty descriptions are omitted.
• Multiline and Unicode descriptions round-trip through YAML and JSON serialization.
• Schema, transformer, split-output, and documentation tests cover the new field.
• The Component schema documentation and generate command documentation describe the behavior.

Consumer workaround

Until native support is available, our repo generates a schema-valid description.yaml beside each api.yaml, joined through metadata.source.nodeId and metadata.source.nodeType. Native support would allow that companion generator to be removed without migrating the description content itself.

[m-nti]

Some additional empirical detail on the mechanism, in case it helps scope the fix. Measured against the published packages @directededges/specs-cli 0.26.0, @directededges/specs-from-figma 0.28.0 and @directededges/specs-schema 0.29.0.

The question that prompted this was whether simply opening definitions.Component — setting additionalProperties: true — would be enough for descriptions to start appearing. It is not, and the three measurements below are why the fix has to include a generator mapping.

1. specs generate never reads component.schema.json.

I preloaded an fs interceptor logging every read whose path matches *schema*.json (readFileSync, openSync, createReadStream, promises.readFile, promises.open) and ran a real generate over a single COMPONENT_SET. Zero reads recorded. The instrument was not silently broken: a positive control immediately afterwards logged that exact file being read. This matches the CLI's shipped dist, which contains no additionalProperties, no $schema and no validator, and imports only DEFAULT_CONFIG from @directededges/specs-schema.

2. Flipping the value changes nothing in the output.

Two generate runs over the same node, identical input, differing only in the schema: in the second, every read of component.schema.json was served a variant with definitions.Component.additionalProperties: true (verified flipped by a control that printed true). The two output trees were byte-identical except for two timestamps:

api.yaml
37c37  <   lastUpdated: …T10:07:34.628Z   >   lastUpdated: …T10:08:31.306Z
88c88  <   generatedAt: …T10:07:34.629Z   >   generatedAt: …T10:08:31.307Z

Neither arm emitted a description key. This is not a missing-input case — the node's description is present and non-empty in the fetched file payload, and across the whole library 49 of the components we generate carry a non-empty source description.

3. ajv 8.20.0 against the real generated component confirms the flip is permission-only.

schema	object under test	root-level result
as published	generated, untouched	no unknown-property error
as published	generated + description	rejects unknown root property description
flipped	generated, untouched	no unknown-property error
flipped	generated + description	accepted

So additionalProperties governs only whether a description that something else already placed is allowed to survive validation. Automatic output additionally requires the generator to read file.components[nodeId].description / file.componentSets[nodeId].description and assign it.

One argument against opening the object, even as a stopgap.

A blanket additionalProperties: true would trade away a guarantee the schema is visibly paying to keep. The source property on Component carries the note:

Declared here because Subcomponent composes this closed definition via allOf and draft-07 has no unevaluatedProperties.

A subcomponent-only property was hoisted onto Component precisely because that definition is closed — so the closed contract is deliberate, and opening it would make a typo'd or drifted key indistinguishable from an intended one. A declared description: { type: "string" } on Component, populated by the generator, keeps that property.

Net: the schema property and the generator mapping are both needed, and the mapping is the half that actually produces output. Happy to test a branch against our library if that is useful — we have a payload with both components[].description and componentSets[].description populated at reasonable scale.

[nathanacurtis]

Thanks for your interest and submitting the issue!

I've not had interest in conveying the component description from subscribers and clients thus far, in part because it represents unstructured data that hasn't been useful to their pipelines (largely, serving system builders/engineers rather than product designers and product engineers). I'll put some thought into the tradeoffs.

[nathanacurtis]

I've drafted an ADR against this — ADR-082, Component.description — in #375. It's DRAFT, and I want to be clear up front: drafting it is not a commitment that it will be accepted. It exists so the tradeoffs are written down and reviewable rather than argued informally.

Thanks also for the measurements. They settled the mechanism question, and the ADR takes your reading: additionalProperties only governs whether a value is allowed to survive validation, so this declares a property rather than opening the object, and the generator mapping is the half that produces output.

What the draft proposes, as three separate decisions:

1. A first-class optional Component.description, sibling to title — essentially the shape you proposed. Rejected alternatives were metadata.source.description (provenance is not documentation, and Subcomponent drops metadata entirely), $extensions['com.figma'] (the value is platform-neutral documentation, not a Figma-only concept), and blanket additionalProperties: true, for the reason you gave.
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, which the parity tests exist to prevent.
3. Emission gated by a new spec.description setting, defaulting to false — so every existing run stays byte-identical and a library opts in.

That third point is where the open question sits, and it's worth stating the reservation plainly rather than burying it. The field is a free-text box, and libraries use it for materially different things:

• Usage guidance — when to reach for the component, when not to. This is the case that clearly earns its place.
• Anatomy or prop prose restating structure the spec already models precisely, which then drifts as the component changes.
• Process and housekeeping — status markers, deprecation notes, owning team, ticket links, changelog fragments.
• Nothing at all, across a large share of components in most libraries.

Its internal structure is just as uneven: one disciplined sentence in some libraries, a headings-and-bullets document in others. Enough implicit structure to tempt a parser, never enough to justify one. So the draft fixes the field as opaque text — carried, never interpreted, and nothing downstream may key on a convention inside it.

The other cost is readability. title is one line; a description can be several hundred words sitting directly above the props of every component, at the top of api.yaml — the file a reader opens first. Multi-line YAML block scalars also produce the noisiest possible diffs, so an editorial reword in Figma reads as a change to the component's API file. The draft's position is that this is a default problem rather than a contract problem: documentation pipelines want the value, code generators don't, and both are legitimate, so the setting decides. That mirrors how defaultSlotContent handles the same tension.

The offer to test a branch against your library is genuinely useful — a payload with both components[].description and componentSets[].description populated at scale is exactly what would validate the mapping. I'll come back to you if the ADR is accepted and implementation starts.

Review and disagreement on #375 are welcome, particularly on the default.