chore: enforce figma links in relevant prs

[ovitrif]

Closes #1234

This PR adds a Design section to the pull request workflow so applicable UI changes reference their Figma frames and all other changes use an explicit N/A case.

Description

• Adds the Design section to the pull request template.
• Ties the agent and /pr guidance to the tested screens map, including its todo and n/a cases.
• Adds the no-UI Design case to version-bump release PR generation.
• Maps the payment-request and subscription screens merged alongside the screens-map test to their Figma frames.

Design

N/A — no UI changes.

Preview

N/A — no user-visible changes.

QA Notes

Manual Tests

N/A

Automated Checks

• Local verification: just test file "to.bitkit.docs.ScreensMapTest" and git diff --check; verified mapped designs, valid no-design markers, non-UI changes, uncertain matches, and omitted applicable links.

[greptile-apps]

Confidence Score: 5/5

The documentation-only policy changes appear safe to merge.

Summary

• Directs UI changes with existing designs to relevant Figma frames, starting from the screen map.
• Defines explicit N/A cases for changes without designs or user-visible UI.
• Keeps missing design links advisory and non-blocking.

[jvsena42]

Non-blocking — nothing in CI reads the PR body (both repos' claude-code-review.yml are workflow_dispatch-only with a required pr_number, and no workflow greps for figma, ### Design, or the body at all), so this is advisory, which the text correctly says.

#1237 merged to master at 10:17 today and this branch now conflicts in AGENTS.md. Master added, at the same insertion point this PR targets:

- ALWAYS resolve a changed *Screen.kt to its Figma frame through docs/screens-map.md ... (todo when the design does not exist yet); ScreensMapTest fails otherwise

Worth reconciling on rebase rather than landing both, because the merge also changes what the guidance here should say. docs/screens-map.md on master is no longer the RN↔Compose filename table — it now carries 37 Figma references across 155 screen rows, 141 of them pointing at a real Flow › Frame, with todo/n/a for the rest, and the header names both the file key and the Bitkit - Handoff vNN page. ScreensMapTest guarantees every screen has a row.

Two knock-ons for the wording:

• N/A — no design available. (pr.md:164, AGENTS.md:190, template:12) is currently a self-declared opt-out with nothing to check it against. Post-merge it can be tied to the map: the row is marked todo. That turns it from an assertion into something a reviewer can verify, and it matters because AGENTS.md:193 explicitly exempts N/A cases from the one advisory request — so today the zero-effort branch is the one shielded from review. Scoping the exemption to N/A — no UI changes. and pointing the design case at the map's todo marker closes it in one line.
• "missing or uncertain screens-map entries" (pr.md:166) now describes a state ScreensMapTest makes impossible on Android.

Separately, and outside this diff: .agents/commands/release.md:116-131 hardcodes a PR body with Description / Preview / QA Notes and no ### Design, so release PRs bypass the new section. Line 111 does say to read the template first, so it's a mixed signal rather than a flat contradiction. greptile raised the same gap on the iOS twin (synonymdev/bitkit-ios#734) but not here.

[jvsena42]

All four points from my last pass are closed — thanks.

• The #1237 conflict is reconciled cleanly: master's rule survives verbatim at AGENTS.md:188 and the new bullets hang off it, so the rule is stated once rather than duplicated.
• N/A is now anchored to the map: :191 scopes it to todo/n/a rows and :194 gates the exemption on Valid. That closes the loophole — validity is checkable against a row now.
• The impossible "missing screens-map entries" wording is gone, replaced by a state that is actually reachable given docs/screens-map.md:10.
• release.md:124-126 emits ### Design, in template order.

One thing the follow-up narrowed further than I think you intended — inline.

Cross-repo: the iOS twin went the opposite way (synonymdev/bitkit-ios#734). It kept the broad scope but left the N/A exemption unqualified. Between the two of you the end state each wants is the other's half, and both are one-liners.

[jvsena42]

One LOW inline. These are instruction documents — nobody executes them, but agents and humans follow them, so a wrong rule gets executed many times. That's the lens I used.

Verified sound:

• docs/screens-map.md vs ScreensMapTest — the test matches Regex("""\b[A-Z]\w*Screen\.kt\b""") against the file text and compares that set with *Screen.kt filenames under app/src/main/java. Both edited rows keep their filename cell unchanged and no row was added or removed, so the Figma column is outside what the test reads. Not at risk.
• Both new frame references are real. I checked them against Figma file ltqvnKiejWj0JQiqtDf2JJ, page Bitkit - Handoff v62 (the only handoff page): Payment Request Details (46920:240340) and Subscriptions overview (46920:239663) are both top-level frames under the Subscriptions SectionTitle (46920:239660). So :74 and :124 are correct in the map's Flow › Frame convention — including the cross-package case where IncomingPaymentRequestDetailsScreen.kt lives in ui/screens/paymentrequests but resolves to a frame in the Subscriptions flow.
• No conflict with the existing rule at AGENTS.md:188. The new :190 says "Start with docs/screens-map.md for mapped screens" and :191 reuses the same todo/n/a markers the map already defines at docs/screens-map.md:8 — the rule is extended, not duplicated. That was the thing most likely to go wrong here.
• No unbacked enforcement claim. AGENTS.md:194 and pr.md:168 both say missing links never block approval or CI, and that matches reality — none of the nine files in .github/workflows references the template, ### Design, or figma.
• Literal strings are byte-identical across every surface that emits or consumes them, em dash and trailing period included: template :12/:13, AGENTS.md:191/:192/:194, pr.md:164/:165/:168, release.md:126. release.md's body order matches the template (Description → Design → Preview → QA Notes).
• All agent surfaces receive the rule — CLAUDE.md and GEMINI.md are symlinks to AGENTS.md, .cursor/commands/pr.md symlinks to .agents/commands/pr.md, and .cursor/rules/*.mdc carry code-style rules only, so nothing there needs a parallel edit.

Drift vs synonymdev/bitkit-ios#734: mostly justified rather than accidental. Android points at docs/screens-map.md first and adds the mapped-todo/n/a → N/A — no design available. rule; iOS has no such map, so it points only at the handoff page and omits that rule. Android deliberately drops "missing" from the uncertain-frame clause (the map makes a missing frame unreachable) where iOS says "Missing or uncertain". Two genuine inconsistencies worth a look: android's pr.md:168 says links never block "approval, CI, PR creation, or review readiness" where every other surface on both repos says just "approval or CI"; and android scopes the advisory request "per PR" where iOS doesn't scope it at all.

[jvsena42]

Fix confirmed at 69a750a1, and the cross-repo drift closed with it.

.agents/commands/pr.md:162 now reads "Include ### Design when the PR template contains a ### Design heading, and apply exactly one case:" — which matches the file's own conditional-section pattern at :204/:205, so the travelling case at :170 (library repos, and bitkit-android-bark's own copy against a template with no ### Design) is handled.

AGENTS.md:189 still says "ALWAYS fill the PR ### Design section", and that's correct rather than a half-applied fix: AGENTS.md is repo-local and this repo's template does carry the heading, so both layers resolve identically. iOS has the same two-layer shape.

On the second change — I was going to query it, and I was wrong to. You propagated the longer "approval, CI, PR creation, or review readiness" wording into AGENTS.md:194, and I'd flagged that phrasing as the odd one out. Checking the twin at synonymdev/bitkit-ios#734, ovitrif adopted the same long form on both iOS surfaces. git grep "approval or CI" now returns zero hits in both repos — four surfaces, one wording. So this converged the two repos rather than widening the gap, which is the better outcome and the opposite of what I assumed.

The other inconsistency I raised is closed too: iOS adopted "per PR" scoping for the advisory request.

The one remaining difference is deliberate and I'm not asking you to match it — this repo drops "missing" from the uncertain-frame clause because docs/screens-map.md makes a missing frame unreachable, while iOS keeps "Missing or uncertain" since it has no map. Correct on both sides.

Both my findings are resolved. Clean from my side.