Design Component Collection

Overview

Collection holding the component INSTANCING CONTEXT for the wf2des direct-assembly flow — how each Figma component is instanced (variant properties, text/image slots, default size), not the component registry itself. component_sweep writes it (deterministic Figma REST full-file walk, upsert on _id, single-flight guarded). generation-assemble reads it to instance the components pinned in a run's inputs.components set.

Table Definition

Logical Name	Physical Name	Column Name	Data Type	Primary Key	Relation	Unique	Nullable	Default Value	Remarks
Design Component	design_component	_id	string	◯	design:id				The platform design row id (type=component) = {project_id}_{figma_file_key}_{node_id}. This IS the identity — no separate surrogate; figma_file_key/node_id are DERIVED from _id via split('_', 2), NOT stored separately (no separate platform_design_id field). Context-only doc; registry lifecycle (existence/name/removal/status) lives on the platform design row (no removed_at here). node_id is derived from _id at assemble time into the spec component_node_id
		organization_id	number						Tenant owner
		project_id	number		project:id				Project scope
		component_key	string				◯		Figma publish key. NULLABLE — null for local components (instanced by node_id, no publish key)
		kind	string						published / local
		name	string						Display name
		text_slots	object[]						Text replacement slots [{ layer_path: string, default_text: string, ambiguous: boolean }] (ambiguity flagged at registration), e.g. [{"layer_path": "title", "default_text": "Page title", "ambiguous": false}]
		image_slots	object[]						Image layers the sweep discovers in the component (parallel to text_slots) [{ layer_path: string, ambiguous: boolean }] — structural placeholders recorded for instancing context; not auto-filled
		default_size	object						{ w: number, h: number }, e.g. {"w": 375, "h": 56}
		key_provenance	string						Which producer last wrote component_key — a plugin capture (plugin-observed) outranks a REST sweep, so a re-sweep cannot overwrite an authoritative key with a null
		name_provenance	string						Same rule for name
		family	object				◯		{ name, node_id, node_type } — the design system's OWN grouping, read from the SECTION the sweep found the component under (e.g. Button, Heading, Form). Recorded because it is free at sweep time and unrecoverable afterwards
		variant_defaults	object						Axis → default value, as the component set declares it
		variants	object[]						Per-variant profile [{ variant_props, size, text_slots[], nested_components[], layout_shape, appearance[], semantics[] }] — what each variant actually holds, so selection can tell siblings apart rather than trusting an axis label
		text_props	string[]						Non-variant text property names the component exposes
		semantics	object				◯		{ kind, also_kinds[], is_placeholder, function[], appearance[], model_id, prompt_version, tagged_at, facts_hash }. kind is ONE closed-vocabulary category (button / form_field / heading / media / …); is_placeholder marks a component that reserves space rather than providing content. Written by the enrichment pass (pin cs@0.3); NULL until it runs
		lineage	object						Shared lineage block on every doc { source_url, source_hash, processor_version, index_schema_version, processed_at, job_id }. source_hash ≡ the component-subtree content hash (no separate content_hash field); job_id = the producing RUN id (the component_sweep run)

Relations

• _id → the platform design row id (type=component), by value; _id IS that id (no surrogate).
• project_id → project.id
• No direct relation is enforced inside DocumentDB; relations are logical and validated by application code.

Indexes

• PRIMARY KEY (_id)
• Upsert on _id under the component_sweep single-flight guard (a sweep_marker on the project_figma_file doc); no surrogate unique key.
• Every read and write filters organization_id + project_id (tenancy scope).

Type Codes

kind:

• published: a published Figma component; carries a component_key.
• local: a local (unpublished) component; component_key is null and it is instanced by node_id.

Notes

• component_sweep owns writes to this collection — a DETERMINISTIC Figma REST full-file walk, NO LLM anywhere; every field (component_key, variant_properties, text_slots, image_slots, default_size) is a straight transform of Figma JSON.
• INSTANCING CONTEXT ONLY. Registry lifecycle (existence / name / removal / status) lives on the platform design row (type=component), which the backend UPSERTs from the sweep manifest — there is no removed_at here; component removal is recorded as the design row's status.
• _id is the sole identity: figma_file_key and node_id are recovered from it via split('_', 2), so there is no separate figma_file_key, node_id, or platform_design_id field.
• generation-assemble reads this doc for the components pinned in the result doc's inputs.components set; the candidate set is the WHOLE registry (deduped, hygiene-collapsed), identical for every section — no role or size gate; the selection LLM sifts by each candidate's full structure, size a signal not a gate (no similarity/retrieval machinery).
• At assemble the STABLE key for validator slot-constraints and the spec instance.platform_design_id is design_component._id, not the mutable Figma component_key.
• File-level local text styles and color variables are NOT stored here — they live on project_figma_file.style_captures (one per figma_file_key), the source of the derived spec style_bindings map.