From 639c6f7805a63dfb9ac1070a483aadd197152b72 Mon Sep 17 00:00:00 2001 From: Ovi Trif Date: Tue, 8 Sep 2026 23:26:36 +0200 Subject: [PATCH 1/2] chore: enforce figma links in relevant prs --- .agents/commands/pr.md | 10 ++++++++++ .github/pull_request_template.md | 7 +++++++ AGENTS.md | 6 ++++++ 3 files changed, 23 insertions(+) diff --git a/.agents/commands/pr.md b/.agents/commands/pr.md index 7660aef2db..6db90d2297 100644 --- a/.agents/commands/pr.md +++ b/.agents/commands/pr.md @@ -45,6 +45,7 @@ If no base branch argument provided, detect the repo's default branch: - Fetch 10 most recent PRs (open or closed) from the extracted repo for writing style reference - Run `git log $base..HEAD --oneline` for commit messages - Run `git diff $base...HEAD --stat` for understanding scope of changes +- Read `docs/screens-map.md` as the starting point for locating relevant Figma frames when the diff has user-visible UI changes - **If custom instructions provided:** - If instructions reference a specific commit SHA (pattern like `commit [a-f0-9]{7,40}`): - Read full commit message: `git log -1 --format='%B' ` @@ -157,6 +158,15 @@ When the user provides custom instructions after `--`: - Use screen names from code, formatted as separate words without the `Screen` suffix, for example `SendAmountScreen` becomes `Send Amount`. - Use short-form wording like `in-sheet` for sheet screens, `nav` for navigation, `back` for back nav, and `LN` for Lightning Network. +**Design Section:** +Always include `### Design` and apply exactly one case: +- UI changes with existing designs: link the relevant Figma frames, using `docs/screens-map.md` as the starting point. +- UI changes without an available design, including new features: write `N/A — no design available.` +- Changes without user-visible UI changes: write `N/A — no UI changes.` +- Missing or uncertain screens-map entries: report the uncertainty honestly; never invent links or require new designs. + +Reviewers may make at most one advisory request when a UI PR omits an existing-design link. Explicit `N/A` cases require no request. Missing links never block approval, CI, PR creation, or review readiness. + **For library repos (has `bindings/` directory or `Cargo.toml`):** Structure manual QA around integration validation only. Automated checks belong under `#### Automated Checks`. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 46b428a228..c02ddc9017 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,6 +6,13 @@ +### Design + + + + + + ### Preview diff --git a/AGENTS.md b/AGENTS.md index 9dead90e8b..c699155dc3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -185,6 +185,12 @@ suspend fun getData(): Result = withContext(Dispatchers.IO) { - ALWAYS remove unused code after refactors - ALWAYS follow Material3 design guidelines for UI components - When building from a Figma frame, reuse only scaffolding (sheet host, `SheetTopBar`, buttons, typography); NEVER swap a design-specific illustration/animation for a lookalike. Export the frame's assets via the Figma MCP and read animation timing/easing/direction from prototype reactions (`use_figma` → `node.reactions`) +- ALWAYS fill the PR `### Design` section: + - UI changes with existing designs: link the relevant Figma frames, using `docs/screens-map.md` as the starting point. + - UI changes without an available design, including new features: use `N/A — no design available.` + - Changes without user-visible UI changes: use `N/A — no UI changes.` + - Missing or uncertain screens-map entries: report the uncertainty honestly; never invent links or require new designs. +- Code review may make at most one advisory request when a UI PR omits an existing-design link. Explicit `N/A` cases require no request. Missing links never block approval or CI. - ALWAYS ensure proper error handling in coroutines - ALWAYS acknowledge datastore async operations run synchronously in a suspend context - NEVER use `runBlocking` in suspend functions From 0c8354a03f8433171895a4986935b888b9843d5d Mon Sep 17 00:00:00 2001 From: Ovi Trif Date: Wed, 9 Sep 2026 17:31:50 +0200 Subject: [PATCH 2/2] docs: restore broad figma coverage --- .agents/commands/pr.md | 8 ++++---- .github/pull_request_template.md | 6 +++--- AGENTS.md | 8 ++++---- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/.agents/commands/pr.md b/.agents/commands/pr.md index e2a01793c9..c8c7380bee 100644 --- a/.agents/commands/pr.md +++ b/.agents/commands/pr.md @@ -160,12 +160,12 @@ When the user provides custom instructions after `--`: **Design Section:** Always include `### Design` and apply exactly one case: -- UI changes mapped to a `Flow › Frame` in `docs/screens-map.md`: link the relevant Figma frames. -- UI changes mapped to `todo` or `n/a`, including new features without a design: write `N/A — no design available.` +- User-visible UI changes with an existing design: link the relevant Figma frames. Start with `docs/screens-map.md` for mapped screens; link known handoff frames directly for sheets, dialogs, reusable views, and other UI outside the map. +- UI changes mapped to `todo` or `n/a`, or other UI changes without an available design, including new features: write `N/A — no design available.` Creating a design is never required. - Changes without user-visible UI changes: write `N/A — no UI changes.` -- UI changes outside the map's `*Screen.kt` scope or with an uncertain match: report the uncertainty honestly; never invent links or require new designs. +- Genuinely uncertain frame matches: report the uncertainty honestly; never invent links. -Reviewers may make at most one advisory request when a UI PR omits a link for a mapped `Flow › Frame`. Valid explicit `N/A` cases require no request. Missing links never block approval, CI, PR creation, or review readiness. +Reviewers may make at most one advisory request per PR when an existing-design UI link is omitted or an out-of-map `N/A — no design available.` claim is unverified. Valid mapped `todo`/`n/a` cases and `N/A — no UI changes.` require no request. Missing links never block approval, CI, PR creation, or review readiness. **For library repos (has `bindings/` directory or `Cargo.toml`):** Structure manual QA around integration validation only. Automated checks belong under `#### Automated Checks`. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e219b5a9ac..a8c3a59701 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -8,10 +8,10 @@ ### Design - - + + - + ### Preview diff --git a/AGENTS.md b/AGENTS.md index 7cc5b76e63..8627a58714 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -187,11 +187,11 @@ suspend fun getData(): Result = withContext(Dispatchers.IO) { - When building from a Figma frame, reuse only scaffolding (sheet host, `SheetTopBar`, buttons, typography); NEVER swap a design-specific illustration/animation for a lookalike. Export the frame's assets via the Figma MCP and read animation timing/easing/direction from prototype reactions (`use_figma` → `node.reactions`) - ALWAYS resolve a changed `*Screen.kt` to its Figma frame through `docs/screens-map.md` (`Flow › Frame` on the latest `Bitkit - Handoff vNN` page). When adding or removing a `*Screen.kt`, add or drop its row there (`todo` when the design does not exist yet); `ScreensMapTest` fails otherwise - ALWAYS fill the PR `### Design` section: - - UI changes mapped to a `Flow › Frame`: link the relevant Figma frames. - - UI changes mapped to `todo` or `n/a`, including new features without a design: use `N/A — no design available.` + - User-visible UI changes with an existing design: link the relevant Figma frames. Start with `docs/screens-map.md` for mapped screens; link known handoff frames directly for sheets, dialogs, reusable views, and other UI outside the map. + - UI changes mapped to `todo` or `n/a`, or other UI changes without an available design, including new features: use `N/A — no design available.`; creating a design is never required. - Changes without user-visible UI changes: use `N/A — no UI changes.` - - UI changes outside the map's `*Screen.kt` scope or with an uncertain match: report the uncertainty honestly; never invent links or require new designs. -- Code review may make at most one advisory request when a UI PR omits a link for a mapped `Flow › Frame`. Valid explicit `N/A` cases require no request. Missing links never block approval or CI. + - Genuinely uncertain frame matches: report the uncertainty honestly; never invent links. +- Code review may make at most one advisory request per PR when an existing-design UI link is omitted or an out-of-map `N/A — no design available.` claim is unverified. Valid mapped `todo`/`n/a` cases and `N/A — no UI changes.` require no request. Missing links never block approval or CI. - ALWAYS ensure proper error handling in coroutines - ALWAYS acknowledge datastore async operations run synchronously in a suspend context - NEVER use `runBlocking` in suspend functions