Problem or use case
docs/screens-map.md maps each *Screen.kt to one frame on the latest Bitkit - Handoff vNN page. That shape misses two cases we now hit:
A single index file also collects edits from every PR that touches a screen. The journeys README index showed how that turns into merge conflicts once several PRs are open.
Proposed solution
Move the mapping into each screen file, as tag lines in the KDoc of the screen's public composable, and delete the central map.
/**
* Figma: Send (Paste) (On-chain) › Confirm Send Onchain
* Figma (payment request): Bitkit - Refactor v63 › Send (Pay Payment Request) › Payment Request
* Figma (payment request details): Bitkit - Refactor v63 › Send (Pay Payment Request) › Confirm Details
*/
@Composable
fun SendConfirmScreen(
Figma: <Section> › <Frame> is a frame on the latest Bitkit - Handoff vNN page. Leaving the page implicit means a new Handoff version doesn't touch every screen file.
Figma: <Page> › <Section> › <Frame> is a frame on another page, for a spec that arrived later. It moves back to the two-part form once a Handoff page absorbs it.
Figma (<state>): … gives the frame for one state when a screen renders several designs, one line per state.
Figma: todo and Figma: n/a keep their current meaning.
- One live frame per state. When a newer spec lands, its line replaces the old one.
The work, in one PR that changes only this concern:
- Add a tag to every
*Screen.kt under app/src/main/java, carrying over its current row unchanged.
- Add the two payment request states to
SendConfirmScreen.kt.
- Replace
ScreensMapTest with a test that reads each *Screen.kt and fails when it has no tag or a tag doesn't match the grammar.
- Delete
docs/screens-map.md.
- Point the instructions at the tags, with
git grep -n "Figma" -- '*Screen.kt' for an overview: AGENTS.md, .agents/commands/pr.md, .github/pull_request_template.md, .cursor/rules/rules.main.mdc.
Acceptance
- Every
*Screen.kt (158 today, 14 of them todo or n/a) carries at least one valid Figma tag, matching its former row.
SendConfirmScreen.kt names the Refactor v63 Payment Request and Confirm Details frames for its payment request states.
- No committed file lists every screen.
- The test fails for a
*Screen.kt without a valid tag.
AGENTS.md, pr.md, the PR template and the Cursor rules resolve a screen's design through its tags.
- The PR changes only tags, the test and those instructions, with no UI or behaviour change.
Alternatives considered
- Central table with Page and State columns: fixes the mapping but keeps the shared file every screen PR edits, and so the conflicts.
- One YAML file per screen: avoids conflicts, but the mapping lives apart from the code it describes and needs its own sync test.
- A
@FigmaFrame(...) annotation: typed and compiler-checked, but SwiftUI has no equivalent, and a doc-comment format reads the same on both platforms.
- Splitting
SendConfirmScreen into per-flow screens: a worthwhile refactor on its own, with its own regression cost on the send path. The tags work before and after it.
Additional context
Problem or use case
docs/screens-map.mdmaps each*Screen.ktto one frame on the latestBitkit - Handoff vNNpage. That shape misses two cases we now hit:Send (Pay Payment Request)section onBitkit - Refactor v63. The map still sendsSendConfirmScreen.ktto Handoff v62'sConfirm Send Onchain, and a review of fix: surface payment request details in sheet bitkit-ios#791 compared the PR against the superseded frames.SendConfirmScreen.ktalone renders on-chain and Lightning send, LNURL pay, subscription and payment request states. One row can't say which frame belongs to which state.A single index file also collects edits from every PR that touches a screen. The journeys README index showed how that turns into merge conflicts once several PRs are open.
Proposed solution
Move the mapping into each screen file, as tag lines in the KDoc of the screen's public composable, and delete the central map.
Figma: <Section> › <Frame>is a frame on the latestBitkit - Handoff vNNpage. Leaving the page implicit means a new Handoff version doesn't touch every screen file.Figma: <Page> › <Section> › <Frame>is a frame on another page, for a spec that arrived later. It moves back to the two-part form once a Handoff page absorbs it.Figma (<state>): …gives the frame for one state when a screen renders several designs, one line per state.Figma: todoandFigma: n/akeep their current meaning.The work, in one PR that changes only this concern:
*Screen.ktunderapp/src/main/java, carrying over its current row unchanged.SendConfirmScreen.kt.ScreensMapTestwith a test that reads each*Screen.ktand fails when it has no tag or a tag doesn't match the grammar.docs/screens-map.md.git grep -n "Figma" -- '*Screen.kt'for an overview:AGENTS.md,.agents/commands/pr.md,.github/pull_request_template.md,.cursor/rules/rules.main.mdc.Acceptance
*Screen.kt(158 today, 14 of themtodoorn/a) carries at least one validFigmatag, matching its former row.SendConfirmScreen.ktnames the Refactor v63 Payment Request and Confirm Details frames for its payment request states.*Screen.ktwithout a valid tag.AGENTS.md,pr.md, the PR template and the Cursor rules resolve a screen's design through its tags.Alternatives considered
@FigmaFrame(...)annotation: typed and compiler-checked, but SwiftUI has no equivalent, and a doc-comment format reads the same on both platforms.SendConfirmScreeninto per-flow screens: a worthwhile refactor on its own, with its own regression cost on the send path. The tags work before and after it.Additional context