Skip to content

AI Des2WF — System Workflows

How Des2WF runs, across the plugin, the backend control plane, the worker and the stores. Field-level contract: I/O Definition.

The product splits inputs by when they arrive, and the flows follow that split:

Time Input Flow
Data construction time design pages; WF components Registration
Generation time one design frame Generation

1. Registration (data construction time)

flowchart TD
    A["Designer selects the kit's component pages in the plugin<br/>(the kit lives IN the working file, like the design system)"] --> B["Plugin: scoped component sweep"]
    B --> C["Worker: derive_component_context per COMPONENT_SET<br/>(variant axes, slots, sizes, publish keys)"]
    A --> B2["Plugin: component capture<br/>(keys + variants read off live masters —<br/>the sweep alone cannot key local masters)"]
    B2 --> D
    C --> D[("DocumentDB wireframe_component<br/>keyed on componentSet PUBLISH KEY<br/>+ component_node_id, since the kit's<br/>masters are LOCAL copies")]
    A2["Design pages imported"] --> D2[("design registry (shared platform table)")]
    D --> E["Read at RUN time by assemble<br/>(per-variant selection + guards, no precomputed table)"]
    D2 --> E

The kit is designer-chosen and will change — a kit swap is this same flow re-run, never a code release. Registration must therefore stay cheap and idempotent. Because selection reads the registry at run time, a swap needs no re-mapping step and leaves nothing stale behind.

Three rules this flow exists to enforce:

  1. Key on the componentSet publish key. Not the node id — ids are per-file-copy, and the same library duplicated onto two boards yields different ids for the same master. Not the name either: measured on the available corpus, colliding names covered 56% of instances by use, and one name covered three different masters.
  2. A separate collection. The WF component library is a different library from the design system, so it does not belong in the design registry. Putting it there would also put WF2Des's candidate set — which is offered the whole registry, with the kind gate defaulted off — at the mercy of a filter being correct everywhere.
  3. Read masters with derive_component_context, never the tree extractor, which flattens the COMPONENT_SET variant partition.

A registry document describes a component set, but the unit that can actually be instanced is a variant. The run therefore expands each document per variant and votes for a unique per-variant key: every variant of a set shares the document's _id, so keying by it would hand the guards an arbitrary sibling of the variant that was shortlisted.

The kit is an existing open-source Figma Community wireframe kit whose pages are copied into the working file — the same installation the design system has on the wf2des side. Masters are therefore local: node-id resolution works directly, no library import and no instance anchor is needed, and registration requires the plugin capture path alongside the sweep (measured on wf2des: a server sweep alone keyed 106 of 279 local components; capture keyed the rest).

Whether the kit's masters carry usable variants in the working file is validated once after installation.

2. Generation (one-shot)

flowchart TD
    A["Plugin: one source frame + mode + layout=auto"] --> B["Backend: shared PG row + scoped frame snapshot"]
    B --> C["Best-effort version-pinned source PNG"]
    C --> D["Dedicated DES2WF queue"]
    D --> E["Worker: deterministic parse"]
    E --> F["Optional kit selection + contextual graphic classification"]
    F --> G["Census → apply_kit → record rendered policy → emit → score"]
    G --> H["S3 artifacts + DocumentDB wireframe/result + manifest"]
    H --> I["Terminal webhook → backend updates PG"]
    I --> J["Plugin: materialize des2wf · source name"]
    J --> K["Original source + generated output PNG pair"]
    K --> L["Scoped review validation → same DES2WF queue"]
    L --> M["Worker: validate result scope → review → merge findings"]

The backend creates the shared wf2des row before enqueueing with edge=des2wf. The transport is the dedicated DES2WF queue (SQS_DES2WF_QUEUE_URL), not the WF2Des generation queue. Generation and post-terminal review share this DES2WF queue; review messages carry kind=render_review. The worker never touches PostgreSQL.

The public API defaults to mode=primitives, layout=absolute. The plugin currently sends layout=auto without a layout selector. Both modes can classify graphics; only kit adds kit selection. Parse remains deterministic, but complete generation is not guaranteed reproducible.

Phase Processing Output
Row + snapshot Requesting user's PAT; frame-only JSON with pruned maps; same-version, absolute-bounds PNG best-effort Shared row, snapshot URL/hash, optional design_png_url
Parse Extract source identity, text, layout and typography Parsed tree and parse.json
Assemble Optional kit selection, per-appearance vision/overrides, census, guarded kit application, policy audit, emission, score Spec, score, graphic_classification
Complete Write artifacts and output/result documents before the terminal webhook Completed PG row and result refs
Materialize Source-aware layout/text and same-file glyph reproduction Canvas frame; default des2wf · {source_name}
Render review Original source and original project bound at generation start; completed job validated before upload Scoped render_review addition, previous review retained

3. Failure and retry

Condition Behavior
Invalid input: not a frame, empty or oversized snapshot Typed parse error
Source PNG missing/unusable, model failure, malformed answer or classification timeout Preserve affected artwork, record fallback reasons, continue generation
Confirmed decoration Omit paint, not a crossed placeholder; retain transparent flow slots where needed
Kit unavailable or a guard rejects the selected variant Keep primitives; do not fail the whole wireframe
A chosen kit variant cannot account for copy or independently drawn descendants Do not apply that replacement
A drawn row is unaccounted for Lineage/postcondition failure, not silent deletion; explicit ornament suppression is separately accounted
A node cannot be emitted as primitives Visible unmatched and score gate 0
Source glyph clone fails Try the actual source PNG; missing or wrong-file source yields visible fallback and diagnostics
Font fallback or necessary reflow Preserve copy, but inspect changed wrapping and geometry; do not assume pixel identity
Job ID mismatch / review before completion Backend rejects before upload/enqueue: 400 / 409
Review result belongs to another tenant/project or is unknown Worker rejects before image/model work or result mutation
Review exceeds supported render bounds Record skipped, reason and null finding count
Review provider failure Failed review, not a clean result and not a reversal of generation completion
Queue redelivery / stale result write Apply job/attempt fencing and terminal idempotency; redelivery alone does not grant permission to overwrite a newer attempt
Open-generation fence held Reject/attach to the existing run; terminal state or explicit cancel frees the key

4. The primitives-only path

primitives is a complete output vocabulary requiring no registered kit, but it still uses contextual graphic classification when evidence is available. Direction, action, state, identity, list markers and uncertainty preserve shape. Only guarded nonessential imagery becomes a placeholder; confirmed decoration becomes ornament. Explicit scoped overrides are documented in Stores.

Auto layout retains native hierarchy, one-child wrappers, item spacing and per-axis sizing. It does not infer new layout from measured gaps. The plugin preserves actual source-instance overrides and centers artwork proportionally rather than resetting to a master.

A score of 1.0 verifies structural/content constraints, not icon accuracy or correct backgrounds. The JSON-only corpus checks conservative fallback and layout; evaluate classification with source images, a real provider, and inspection of regenerated plugin output.