figma-survey

name	figma-survey
description	Survey a Figma design against what a Vaadin app already builds, interview the user in rounds on every divergence, and write the project's design spec. Ends in the spec plus a delta in the conversation — never in code, theme CSS, or a ticket.
disable-model-invocation	true
argument-hint	[theme | view or component name] [figma url]

Figma survey

A survey reads two things — the design, and whatever the app already builds for it — and writes two:

• The design spec, the durable half: what the design asks for, with a decision recorded wherever the design and the app disagree. A later run looks a value up here instead of deciding it again, which is the whole point — an agent with no memory of the last session invents a plausible value rather than reaching for the settled one, and by the fifth view the app reads as several products.
• The delta, the transient half: what the design shows that the app does not yet do, written checkable so each item can become a ticket's acceptance-criteria line.

It writes no application code, no theme CSS, and no ticket. Applying the spec belongs to figma-theme (the global theme) or to implementation (a view). Filing the delta belongs to a separate ticketing pass, run on this conversation once the user has read the delta. The survey ends in the conversation, and that pause is what lets the expensive judgement calls be reviewed before a ticket is worded or a diff is started.

Applies to Vaadin Flow (Java) on the Aura theme.

Two rules that shape every step

Facts are yours; decisions are the user's. Anything readable from the design, the code or the existing spec, you look up. Anything that picks one side over the other, you put to the user in rounds, each question carrying your recommendation — the method is interview.md. The spec is written only once the interview's frontier is empty.

A survey never boots the app. Its three inputs — the design, the code, the existing spec — are all readable without one, and a running app can only show the scale you are about to replace. A figure only a browser produces (a contrast ratio, a rendered pixel size, a resolved token) is left marked unverified for whoever applies the spec. An unverified row said to be unverified costs the next run five minutes; the same row presented as settled costs it a wrong decision.

Scope

$ARGUMENTS fixes one of three scopes. The scope decides which branch file supplies the reading and the writing in steps 2, 5 and 6:

Scope	Target	Writes	Branch
theme	the design's global variables, across every mode	foundations/, and the inputs in tokens/	theme-scope.md
view	one frame — a screen or a dialog	components/ for the components on it, plus the delta	view-scope.md
component	one component, wherever it appears	that component's file in components/	view-scope.md

Do the theme scope first, and once. It decides the font family and base size, which reflow every screen; per-view spacing settled against the old scale is work thrown away.

Steps

1. Resolve the target and find the spec's home

$ARGUMENTS names a scope, or a view or component in whatever words came to hand — "Add Expense", LineEditorDialog, report detail — and may include a Figma URL.

Fix the design file first: take fileKey and nodeId from a URL of the form figma.com/design/:fileKey/:name?node-id=1-2. Absent a URL, check whether the project records a design file (its agent instructions are the usual home) before asking for one.

Resolve the target on the design side with get_metadata on the page to list frame names; the branch file says how to pick the frame. Name the resolution back to the user, and ask only when two candidates are genuinely indistinguishable.

The spec's home is the directory the project's agent instructions name. Read what is already there — it is the baseline this run revises, not a blank page. No spec at all means nothing has been settled yet, which makes every divergence in step 4 open by default; say so, because it bounds what this survey can conclude.

Done when the scope is fixed, one Figma node id is fixed, and the existing spec is either read or its absence noted.

2. Read both ends

Follow the branch file's reading sections: theme reads the design's variables through their bindings; view and component find what the code already builds, read the frame, and map every component instance to a Vaadin component.

Everything in this step is fact-finding. Where a branch file marks a row as judgement — an override or invented mapping, a value inferred from a drawing — carry it forward as a question for step 4 rather than settling it here.

Done when the branch file's reading criteria are met and every judgement call it surfaced is on the list for step 4.

3. Establish the app's values — from files

Take the formulas from the spec's token reference — round(baseRadius * 2px + 3px, 1px) and its siblings. They are what the framework derives each scale with, they are stable across a theme change, and they go stale only on a framework upgrade, which is why the spec caches them. Then list every property the app's own theme file sets, so step 4 knows what is a deliberate app choice rather than a default.

Compute the resolved values; do not measure them. Given the formulas this is arithmetic, and it is the only correct way round — step 4 is about to change an input, so the numbers you need are the ones at the decided inputs, not the ones the app renders today. Scored against the outgoing base, the wrong base can look better: a type scale whose small step is a clamped fraction of the medium step lands a design's most-used size exactly on a token at one base and between two tokens at another.

Where the spec has no formulas — a first run, or a framework upgrade since the last one — say so and stop short of asserting any resolved number or off-scale verdict. Those rows stay unresolved for a measurement pass to fill; obtaining formulas belongs to whoever applies the theme and is already in a browser.

Done when the formulas are in hand or their absence is recorded, the resolved values at the decided inputs are computed rather than measured, the version they hold for is noted, and every property the app's theme sets is listed.

4. Interview: turn every judgement into a decision

Build the design tree of everything steps 2 and 3 left to judgement, and work it in rounds per interview.md. Its material, across every scope:

• Divergences — one per property where the design and the app disagree. Properties that already agree need no row and no question.
• Off-scale values — solve the formulas backwards and the design's raw pixel values disagree with each other: a 9 px field radius asks for one base radius and a 12 px card radius for another, at which the field renders 6 px. Each such value sits between two steps of the scale or beyond its end, and each is a global decision with four options: correct the design back to the scale, override the derived property globally, define one project-level property used everywhere that value appears, or accept the nearest token and record the difference. Recommend a property only for a value several pixels off and recurring; within a pixel or two, the nearest token — a property shadowing the scale for one pixel is where drift starts. Where the framework has a real property for exactly that value, override it rather than inventing a twin.
• Judgement calls the branch file surfaced — mappings, accepted infidelities, domain gaps.

Two constraints are facts to report, never questions:

• The accessibility floor. Contrast, touch-target size and focus visibility are constraints. A design value that breaks one is a design defect; the app keeps the accessible value, recorded as a settled divergence.
• A value the design contradicts itself on. Where a variable and the drawn value disagree, the variable wins, and the drawn value is a design defect to report.

Done when the frontier is empty and the user has confirmed the tree: every property is either identical on both sides or carries a decision with a status — settled or open — that the user chose.

5. Write the spec

Write into the project's spec directory, following any template its own README defines — where it does, that is binding and overrides the branch file. The branch file says which files and what each covers.

Every decision row carries settled or open. A divergence resolved in the app's favour is settled, not absent — that row is what stops the next survey reporting the app's own font as a mismatch. A concern with no divergence still gets its file or its section saying so; absence recorded is what stops the next survey re-deriving it. A figure only a browser can produce stays unverified.

Done when every file the scope calls for exists, every decision row carries a status, and no measured figure is asserted without a measurement.

6. Hand over in the conversation

Write the hand-over as your final message, under the headings the branch file gives. It is the input to a ticketing pass, so it must stand without this conversation: a reader lifting it into a ticket should never need to re-read the frame.

Global theming differences do not go in a view's delta. They were decided in step 4 and written in step 5, which is what stops the next survey re-litigating the same radius.

The survey stops here. Name the ticketing pass as the next step and leave it to the user; the delta is theirs to read before it becomes anyone's work.

Done when every heading is filled or explicitly marked empty, the spec files are listed, and the message ends with the next step named.