docs: update AGENTS.md with new guidelines

- Add ui-ux-pro-max skill reference
- Add keyboard overlay behavior rules for Flutter
- Update testing strategy to prioritize high-regression flows
- Add copy priority rules for auth and form pages
- Update minimal interface copy guidelines
This commit is contained in:
qzl
2026-03-19 18:43:23 +08:00
parent 9ddd7a0147
commit 524b91f454
3 changed files with 35 additions and 2 deletions
+20 -2
View File
@@ -55,6 +55,14 @@ This document defines **hard constraints** for Flutter mobile development. Treat
- If persistent header/footer regions exist, **MUST** center primary content within the remaining usable region.
- **MUST** prioritize *visual centering* over purely geometric centering when they differ.
## 4.1) Keyboard Overlay Behavior (MUST)
- For pages with text input, keyboard appearance **MUST** prefer overlay behavior and avoid reflowing the whole page.
- Input pages **MUST** avoid global layout jump when keyboard opens/closes (including subtle shifts caused by safe-area padding changes).
- Default strategy for full-screen pages with fixed hierarchy: `Scaffold.resizeToAvoidBottomInset = false`.
- If a page truly requires keyboard-driven scrolling to keep focused fields reachable, this must be an explicit opt-in and justified by page structure.
- When using `SafeArea` on keyboard-overlay pages, **MUST** stabilize bottom safe-area behavior (for example, maintain bottom view padding) to prevent center recalculation jitter.
## 5) Testing Strategy (MUST)
Follow lightweight testing strategy - prioritize value over coverage:
@@ -62,10 +70,16 @@ Follow lightweight testing strategy - prioritize value over coverage:
**Write tests for:**
- Model / DTO parsing (json → model)
- Service layer logic (business rules, API call handling)
- Complex custom widgets with rich interactions
- High-regression UI interaction flows only (multi-state/multi-step widgets, viewport/scroll decision logic, route return stability)
**Skip for:**
**Default skip for UI tests:**
- Simple UI pages, regular buttons, basic layouts
- Pure visual structure/snapshot-like checks without behavior risk
- Low-risk styling and static rendering changes
**UI test policy:**
- UI tests are opt-in, not default; only keep or add them when failure risk is high and there is clear regression value.
- If a UI test does not protect critical interaction behavior, remove it or avoid adding it.
## 6) UI Feedback System (MUST)
@@ -110,6 +124,10 @@ All UI/UX work **MUST** follow the visual design language defined in `apps/rules
- **MUST** achieve visual hierarchy through spacing, surface grouping, radius, depth, density, contrast, scale, and motion—not color alone.
- **MUST** prioritize compact informational delivery in top bars: when the page purpose can be clearly expressed by a concise header title, avoid repeating equivalent explanatory hints in the body.
- **MUST NOT** duplicate page identity text between header and first content block unless the repeated text introduces new decision-critical information.
- **MUST** keep interface copy minimal and action-oriented: every text node must justify its presence by either enabling a decision, reducing error risk, or satisfying compliance requirements.
- **MUST NOT** stack multiple instructional hints around the same control (for example title + subtitle + placeholder + helper text all repeating the same meaning).
- **MUST** follow copy priority for auth and form pages: `Primary action > Required input labels > Error/recovery > Compliance`. Secondary explanatory copy should be removed when users can complete the task without it.
- **MUST** ensure each form field has at most one primary hint source in normal state (prefer placeholder or label, not both with duplicated wording).
- **MUST** follow the screen-level decision rules:
1. What is the primary focus?
2. What is the surface hierarchy?