Skip to content

chore: keep each screen's figma frames in the screen file #1346

Description

@ovitrif

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:

  1. Add a tag to every *Screen.kt under app/src/main/java, carrying over its current row unchanged.
  2. Add the two payment request states to SendConfirmScreen.kt.
  3. 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.
  4. Delete docs/screens-map.md.
  5. 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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions