docs(smartui): document the app capture half of the Figma-App CLI workflow

[chaitanyas-maker]

Problem

The Figma-App CLI page is titled "compare mobile app screenshots against Figma design frames", but every step on it uploads only the Figma side. There is no step that captures the app screenshots, no step that runs them on the grid, and no explanation of how the two halves get paired.

A reader who follows all five steps ends up with a build containing Figma frames and nothing to compare them against. The app side appears only as scattered hints inside Best Practices and Troubleshooting tabs, which assume the reader already knows the Appium setup the page never gives them.

Blocking fix

The page tells you to export PROJECT_TOKEN and FIGMA_TOKEN. The CLI also hard-fails without LT_USERNAME and LT_ACCESS_KEY:

• src/lib/config.ts throws Missing LT_USERNAME in Environment Variables and Missing LT_ACCESS_KEY in Environment Variables
• src/lib/uploadAppFigma.ts builds the request auth header as Basic from those two values

Both sibling pages document them (smartui-cli-figma.md, smartui-cli-figma-web.md). This page did not, so anyone following only this page could not get past the upload step.

What changed

New content, the missing half of the workflow

• Step 6, upload the app to the real device cloud
• Step 7, Appium capabilities including visual: true and smartUI.project, with a warning that the app side is keyed by project name and not by PROJECT_TOKEN
• Step 8, the screenshot hook shown in context, not just the .png rule in isolation
• New "How the comparison is paired" section covering the three conditions that must line up

Reference gaps

• Configuration Options table for depth, screenshot_names length and uniqueness rules, orientation, smartIgnore, exact device name matching, and the schema's rejection of unknown keys
• Documented --fetch-results [filename], which was implemented but undocumented
• Windows CMD and PowerShell env var tabs, matching the sibling pages

Structural fixes

• Replaced the two duplicate tabs both labeled "Device Names". They held byte-identical screenshot naming content and neither was about device names
• Regrouped Troubleshooting by symptom, which removed the orphaned **Symptoms**: / **Solutions**: fragments that had no body text, and the duplicate Project Type tabs
• Moved the support links footer out of the last tab, it previously only rendered when a reader clicked that specific tab
• Added the breadcrumb JSON-LD used by sibling SmartUI pages
• Updated the Figma URL example to the current /design/ form
• Added trailing slashes to internal links

One point for reviewer confirmation

I removed the "ensure both Figma and SDK uploads use the same --buildName" guidance, which appeared twice. Two reasons:

1. The Appium side has no --buildName flag, it has a smartUI.build capability, so the instruction was not actionable as written.
2. The figma-web page's working sample deliberately uses different build names on each half (FigmaBaseline2 and web-build), relying on the Figma build being the baseline instead. The two pages contradicted each other.

I replaced it with the pairing rules verifiable in the CLI source: same project, Figma build marked as baseline, exact screenshot name match. The comparison logic itself is server side and not in the CLI repo, so please confirm this against the backend behavior before merging.

Verification

• Production docusaurus build passes, no broken links. The 48 broken-anchor warnings are pre-existing on other pages, none on this one
• Dev server compiles clean, route registered in .docusaurus/routes.js
• Page renders correctly in local preview with all 9 steps in the TOC
• Every internal link target confirmed against its slug: frontmatter
• The app upload endpoint checked against existing docs pages
• Sourced from the smartui-cli source, not from the previous copy

Single file changed, no lockfile churn.

🤖 Generated with Claude Code

https://claude.ai/code/session_0183Ta7Aq3y1eqoxfi4mBBnC

[chaitanyas-maker]

Live verification run, and two corrections to this PR

I ran the whole workflow end to end against real infrastructure rather than reasoning from source: a new Figma file, a new Real Devices project (figma-app-doc-verify), the Proverbial sample app, and a real Pixel 8 / Android 14 device. Four builds were produced and the comparison actually ran. Pushed as 6a1537e.

The important one: a broken code sample

The published page's "Critical" snippet does not work, and this branch had reproduced it unchanged:

await driver.execute("smartui.takeScreenshot", {name: "homepage.png"});

On device this throws Error response status: 1. The config-object key is screenshotName, not name. Both of these were proven working in the same session:

await driver.execute("smartui.takeScreenshot=homepage.png");
await driver.execute("smartui.takeScreenshot", {screenshotName: "homepage.png"});

Anyone following the current published page gets a failing test.

I was wrong about LT_USERNAME / LT_ACCESS_KEY

My original PR description called this a blocking bug. It is not, and I have corrected the page.

Running upload-figma-app with only PROJECT_TOKEN and FIGMA_TOKEN set, exactly as the published page instructs, in a clean directory with no cached state:

✔ Authenticated with SmartUI
› {"about.png": "1:17", "homepage.png": "1:2"}
✔ App Figma images uploaded successfully to SmartUI

PROJECT_TOKEN is what authenticates that endpoint. The published Step 4 is correct as written. The two LT variables are genuinely needed, but for the Appium grid URL on the app side, so the table now records where each value is actually consumed.

The pairing rule is confirmed

This PR removed the "ensure both Figma and SDK uploads use the same --buildName" guidance. That is now proven correct:

Build	Name	Role
#1	figma-baseline	Figma frames, marked baseline
#4	smartui-e669145660	Appium run, auto-named

Different names, and the comparison still ran: Baseline = the Figma frame, Captured = the device screenshot, 89.2039% mismatch, variant Pixel 8 Android 14. Build names play no part in pairing.

Two long-standing Step 1 errors

Verified against the live Create-a-New-Project form: Approver(s) is mandatory and pre-filled, not optional, and the button is labelled Continue, not Submit. Both were wrong on the published page and both are fixed.

Also confirmed working, as documented

.png auto-append, --markBaseline placing the build under Baseline Build, smartUI.project taking the project name, smartUI.build being optional, visual: true, --fetch-results, and all four schema validation messages.

Product defects found, not doc issues

Filing separately, noting here for context:

1. The FIGMA_TOKEN / LT_USERNAME / LT_ACCESS_KEY guards compare against "". Since an unset variable is undefined, setting one to empty fails while leaving it unset passes. Suggest if (!ctx.env.X).
2. The in-product Figma App onboarding contradicts itself: Step 6 uses homepage.png, Step 7 drops the .png and silently breaks the pairing it just explained.
3. That same onboarding hardcodes "smartUI.project": "figma-rd" rather than the project the user just created.

[chaitanyas-maker]

Verification pass 2: every code sample now executed

Pushed as 1762e5f. Goal this round was a page that asserts nothing unproven. Two outcomes: one more broken snippet found and fixed, and five claims removed or narrowed because I could not execute them.

A second broken code sample

The Java tab published:

((JavaScriptExecutor) driver).executeScript("smartui.takeScreenshot=homepage.png");

JavaScriptExecutor does not exist. Selenium's interface is JavascriptExecutor, lower case s in script. Compiled both spellings against selenium-api:

• published spelling → error: cannot find symbol
• corrected spelling → compiles clean

The corrected snippet was then run against a real Pixel 8 and the screenshot confirmed in the build as java-cart.png.

The same wrong spelling appears on the Appium hooks page, so it is worth a sweep beyond this PR.

Verified and kept

Claim	Evidence
Python snippet	ran on a real Pixel 8, py-cart.png confirmed in the build
Duplicate figma_ids rejected	figma_ids must contain unique values
Multiple figma_file_token entries in one config	passes validation

New troubleshooting section: Figma API rate limits

Uploads fail during Processing App Figma when the token sits in Figma's low rate-limit bucket, which is where Viewer and Collab seats on free Starter workspaces land. Roughly five uploads exhausted it and it did not clear across ~40 minutes of retries.

Worth noting for reviewers: a direct Figma REST call can return 200 while the upload still fails, because the upload makes several calls per run. That makes the failure look inconsistent unless you know to expect it. Also documents the Invalid token case and the file_content:read scope the upload needs.

Removed or narrowed, because I could not verify them

• Deleted "Appium with SmartUI supports viewport based screenshot comparisons only". Inherited from the Appium hooks page, never exercised.
• Narrowed the device-mismatch guidance from a causal claim ("every comparison reports a mismatch") to a plain instruction to use the same device. I never ran a deliberately mismatched device.
• Narrowed figma.depth. The documented traversal semantics ("2 returns pages and all top level objects") were never exercised; only depth: 1 was run.
• Narrowed smartIgnore to what is observable: the schema accepts it and it is forwarded with the upload.
• Narrowed --fetch-results to what --help states. The flag exists, but writing results to disk is still unproven, blocked by the rate limit above.

Still outstanding

The design-matches-app comparison has not run. Every comparison so far has been a deliberate mismatch, so the page is proven to run but not yet proven to agree when design and build match. Blocked on the same Figma rate limit.

Production build passes, no broken links.