Publish per-variant figma-SVGs so the Figma file can carry the full state x theme x size x locale matrix

[yschimke]

Follow-up to #258 / #260. The Figma file is now structured one page per screen,
each major state a bordered section of captioned variant cells — but most cells
can't be filled, because the artifacts branch doesn't publish the renders.

The constraint

scripts/design-artifacts/figma-svg-emit.mjs in compose-ai-tools emits one
figma-SVG per component function, deliberately preferring the light variant:

Map componentFunction -> { id, svg } for each preview that carried a
compose/figma-svg. Prefer the light variant so a single deterministic
sticker is emitted per component.

So figma/<slug>.svg is always light, compact, default locale. Everything else
on the branch is raster (images/<slug>/…png). Current coverage in the Figma file:

Axis	Coverage	Cell type
State	Full — every state has its own section	vector
Theme	light vector + dark PNG for the 6 Device states; no dark render at all for cached device, the 3 chat screens, settings	mixed
Locale	device-cached de/ja/ar, settings-ready de. Nothing else	PNG
Size	compact (412 dp) only	—

PNG cells are reference imagery, not a design source — they aren't editable in
Figma, which is the whole point of the design-led direction.

Three workstreams

1. Per-variant figma-SVG export (upstream, compose-ai-tools)

Emit one SVG per preview variant rather than per component function, keyed by
the same ideal__<state>[__theme][__size][__k-v…] scheme catalog-variants.mjs
already uses for PNGs. Needs a delivery-branch layout that doesn't collide —
e.g. figma/<slug>/<variant>.svg — and a matching update to
rewriteRasterHrefs for the hybrid sticker crops.

Blocks everything below: without it, extra breakpoints and locales only produce
more PNGs.

2. Breakpoints (this repo) — PARKED until the app has adaptive layout

Two corrections to the original framing here.

First, the breakpoints field in catalog.spec.json is inert. Nothing reads it —
no consumer in design-parity's catalog-export, none in compose-ai-tools'
generate-design-catalog.mjs. Editing it changes nothing. A component's size comes
from the preview's own @Preview(widthDp = …), normalized through sizeForWidth() in
design-parity packages/core/src/size.ts:

compact < 600dp     medium 600-839dp     expanded >= 840dp

Devices.PIXEL_7 is 411dp, which is why everything lands in compact. So adding size
coverage means authoring wide @Preview functions, the same shape of work as the
locale variants below — not a config edit.

Second, the app has no adaptive layout to render at those widths: no
BoxWithConstraints in app/src/main or meshcore-components/src, no
material3-adaptive or window-size-class dependency in gradle/libs.versions.toml,
and every parity preview pinned to Devices.PIXEL_7. Wide previews today would render
the single-column layout stretched, and publish a Figma "design" for a form factor the
code never adapts to — a reference that either gets ignored or fails forever.

Parked by decision. Revisit when the app gains window-size-class branching, at
which point the previews should use the widths the code actually switches on.

3. Locale previews (this repo)

Locale variants are hand-written @Preview functions — device-cached has
de/ja/ar and settings-ready has de, via the spec's variants array:

"variants": [
  { "props": { "locale": "de" }, "preview": "CachedDeviceBodyGermanPreview" }
]

Authoring en/ar/ja/de for the remaining screens is ~30 new preview functions.
Worth confirming the set of "blessed" locales first — ar earns its place as the
RTL check, ja for CJK line-breaking; de mainly stresses string length.

Why it matters beyond the sticker sheet

Seven design-map.json entries still resolve to committed HTML because they have
no Figma node — DeviceBodyPreview and every *DarkPreview. Dark figma-SVGs
from workstream 1 would close most of that gap and let .design-parity.json move
to design-led.

Related

• Status-bar mismatch: the seeded renders carry the synthetic OS status bar that
  the HTML references deliberately omit (see "Render path" in
  docs/design-parity.md). That needs settling before the direction flips, and
  may resolve itself via compose-ai-tools#1930.
• docs/design-parity.md -> "Variant coverage (and why it's uneven)".

[yschimke]

Finding: the dark vectors already exist — they're discarded at the last step

Traced the capture path before starting. The figma-svg export is not gated on
theme anywhere upstream:

• DaemonSemanticsFetcher.Outcome.Ok.figmaSvgById — "holds the matching
  compose-figma.svg … for each preview that produced drawing layers", keyed by
  preview id, which already carries the _Light / _Dark suffix.
• injectFigmaSvgIntoBundle writes previews/<id>.figma.svg per preview id, and
  injectFigmaRasterIntoBundle does the same for the hybrid crops.

So the bundle carries a figma-svg for every rendered variant. The loss happens in
one place — figmaSvgByFunction in scripts/design-artifacts/figma-svg-emit.mjs
collapses the map to one entry per function, preferring light.

Consequence: workstream 1 is a JS-only change in figma-svg-emit.mjs +
generate-design-catalog.mjs. No renderer or Kotlin work. Dark comes essentially
free; size and locale still need workstreams 2 and 3 to produce the variants,
but once produced their vectors will flow through automatically.

Proposed delivery layout

Mirror the existing raster layout exactly, so the two are 1:1 and the naming is
already-solved:

images/<slug>/ideal__default__dark__compact.png
figma/<slug>/ideal__default__dark__compact.svg     <-- new

Driving the emit from each component's images[] (which already carry previewId,
theme, size and props) guarantees a vector never disappears silently: if a PNG has
no matching figma-svg, that's a reportable gap rather than an invisible one.

Keep figma/<slug>.svg as-is, pointing at the light variant, so existing consumers
don't break — index.html, compare.html, design-parity's FIGMA_IMPORT.md
playbook, and the meshcore-mobile seeding runbook all reference that path today.

Hybrid raster crops need a per-variant dir (<slug>__<variant>.figma-raster/) since
rewriteRasterHrefs currently assumes one per slug and two variants would collide
on <node>.png.

[yschimke]

Workstream 2 (breakpoints): should not be done as specified

Checked what the app actually branches on before adding widths. It doesn't branch:

• No BoxWithConstraints anywhere in app/src/main or meshcore-components/src.
• No material3-adaptive and no window-size-class dependency in
  gradle/libs.versions.toml.
• Every parity preview is pinned to Devices.PIXEL_7. The only widthDp uses in the
  tree are per-preview render widths for the component sticker sheet.

So adding a "large phone" and "small tablet landscape" breakpoint today would render
the same single-column layout stretched to a wider viewport. That is worse than
useless for parity: it would publish a Figma "design" for a form factor the code has
no adaptation for, so the reference either gets ignored or fails forever, and in a
design-led direction it asserts an intent nothing implements.

Recommendation: drop workstream 2 from this issue. Reinstate it if and when the
app grows adaptive layout, at which point the breakpoints should match the size
classes the code actually switches on. If a tablet layout is wanted, that is a
design exploration to run in Figma first and then implement -- worth its own issue,
and explicitly not a parity subject until the code adapts.

Workstream 3 (locales): smaller and better targeted than "~30 previews"

Localizable string counts per screen:

Screen	stringResource calls
DeviceBody	31
DeviceSettingsBody	10
ChatBody	3

ChatBody is almost entirely literal sample data, so de/ja variants of the three
chat screens would render nearly identically to English -- catalog noise, not signal.

Proposed set, on the same locale = "xx" pattern as the existing
CachedDeviceBodyGermanPreview:

• ar for every screen. RTL mirrors the whole layout -- back-arrow direction,
  row alignment, chat bubble sides -- so it earns its place regardless of string count.
  This is the highest-value locale in the set and currently only exists for device-cached.
• de + ja for DeviceBody and DeviceSettingsBody only. de stresses string
  length against the section headers and chips; ja stresses CJK glyphs and line breaking.

That's roughly 10 new previews rather than 30, and each one tests something the
others don't.

[yschimke]

Status

Workstream	State
1. Per-variant figma-SVG export	Merged — compose-ai-tools#2653 (308d917da)
2. Breakpoints	Parked — no adaptive layout to render at those widths; the breakpoints field is inert, size comes from @Preview(widthDp)
3. Locale previews	In review — #265

Plus one bug found along the way, not in the original scope:

• compose-ai-tools#2656 — the live-preview bridge can't key on theme, so every
  theme-only dark sticker takes the light preview's previewId. Live here since
  feat(catalog): pair split light/dark screen renders so night mode stays baked #263 adopted theme variants; with #2653 merged it would publish the light vector at
  each …__dark.svg path.

Blocking the payoff

Do not dispatch design-artifacts.yml until #2656 lands. Once it does, dispatch it
so the delivery branch regenerates — that is what actually puts the per-variant vectors
(dark + locale, editable) on design-artifacts/meshcore-mobile, which is what the whole
chain exists to produce. Until then the branch still carries one light vector per slug.

After that regeneration, the remaining #258 follow-up becomes possible: seed the dark
and locale vectors into the Figma file's variant cells (currently PNG placeholders), and
give DeviceBodyPreview / the *DarkPreview subjects real Figma nodes so the last seven
design-map.json entries can move off their committed HTML references.