[DRAFT RFC] Component visual recipes: render components to SVG, PNG and Figma

[GarthDB]

Status: Draft — spec, schema, one pilot recipe and a prototype SVG renderer exist locally; not yet merged.

Draft spec: packages/design-data-spec/spec/component-visuals.md · Schema: packages/design-data-spec/schemas/component-visual.schema.json · Pilot: packages/design-data/visuals/action-button.json

1. Problem

Spectrum design data describes tokens, components, options, states and anatomy names. It has no geometry, so nothing can draw a component from it. Today, component visuals live in Figma files or in each platform implementation.

We want one source that renders to several outputs (SVG, PNG, Figma), and that isn't tied to Figma, React, or any other platform.

The driving use case is the Spectrum Hub website design. One component has three views fed by the same data:

• Usage: a variant × state matrix with option controls.
• Anatomy: numbered callouts on each part.
• Specs & tokens: measurement annotations labeled with the token behind each value.

2. Proposal: visual recipes

Add a renderer-neutral visual recipe per component, stored at visuals/<component>.json. A recipe is a part tree (box, text, icon, ring) with layout, shape and paint. Every value is bound to a token, so overlays can name the token behind each measurement.

Layer	Owns
Component declaration	Options, states, slots, anatomy names (existing)
Visual recipe (new)	Part tree, layout, token bindings
Render request	Component, options, states, modes, overlays (tool input)
Scene graph	Resolved rects, paths, text and measurements, each with part and token ids

A property value is a literal, a token selected by name-object fields, or a token chosen through the component's relationships. Conditional entries (when.options, states, modes) pick variants; the most specific match wins. The cascade narrows candidates by mode (colorScheme, scale). Unresolvable values produce diagnostics rather than silent fallbacks.

"container": {
  "kind": "box",
  "props": {
    "gap": { "token": { "structure": "base", "property": "gap", "size": "{size}" } },
    "fill": [
      { "token": { "colorFamily": "gray", "scaleIndex": 100, "property": "color" } },
      { "when": { "states": ["hover"] }, "token": { "colorFamily": "gray", "scaleIndex": 200, "property": "color" } }
    ]
  }
}

3. Prototype

design-data render action-button --state keyboard-focus -o out.svg resolves the pilot recipe against the corpus and writes an SVG. Each part carries data-part and data-tokens attributes. At size m on desktop the container resolves to 32px high, 12px padding and a 6px gap; the mobile scale gives 40px. Not built yet: overlays, matrices, PNG, WASM, Figma.

4. Decisions so far

• Playground (Domino): reference only. It models component instances (props, slots), with no geometry, paint, layout or token binding. Its repository is private and its node envelope has no published schema or versioning, so a public spec shouldn't depend on it. Option names align closely with ours, so an adapter between a render request and a Domino instance is possible later.
• Text: approximate metrics from Source Sans 3 (OFL). Adobe Clean can't be redistributed. SVG <text> uses the stack Adobe Clean, Source Sans 3, sans-serif.
• Layout: a minimal flex implementation first; revisit taffy when text-field is piloted.
• Icons: glyph paths keyed by icon name, as literal values.
• Figma: a backend consumes the scene graph and emits plugin node JSON bound to Variables by token id. Recipes hold no Figma-specific data.
• Location: the renderer lives in the Rust SDK (design_data_core::visual).

5. Open questions

1. Relationship bindings. Recipes currently bind to relationship context free-text strings, which break if reworded. Should relationships gain structured options and part fields everywhere, so recipes select by option and state?
2. Stored requests. Should render presets and matrices (what the Hub site shows) live in the dataset, or stay tool input?
3. Token gaps. Only a handful of tokens set name.component, so most component visuals come from generic tokens plus relationships. What is the policy for components without either?
4. Deprecated icon sizes. workflow-icon-size-* is deprecated without a replacedBy. Which tokens should icon sizing bind to?
5. Conditions. Is visibleWhen with a single condition enough, or do we need any/not composition?
6. Pilot scope. Planned pilots: action-button, button, checkbox, switch, badge, text-field, tag. Is that the right set, and what's the right order?
7. Token names. The Hub mockups label tokens like corner-radius-500 and component-height-100, while the corpus uses names like corner-radius-medium-size-medium. Which names should overlays display?

6. Feedback wanted

Design: does the recipe model cover what you'd need to draw your components? Engineering: does the scene graph work as a backend contract? Hub site: do the three views map cleanly onto recipes and render requests?