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:
+20
-2
@@ -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?
|
||||
|
||||
Reference in New Issue
Block a user