feat: 添加视觉设计语言系统并重构认证页面UI
- 新增 visual_design_language.md 设计规范文档 - 新增 auth 设计 tokens (authBackground, authCard, authInput, feedback 系列等) - 重构登录/注册/验证码/重置密码页面为新设计系统 - 新增 AuthHeroHeader, AuthSurfaceCard, AuthSection, AuthField, PasswordField 组件 - 重构 AppBanner 和 Toast 支持多类型配置 (info/success/warning/error) - 后端 AgentScope: 重整 schemas/prompts/tools 作用域, 新增协议文档 - 更新 AGENTS.md 集成视觉设计语言约束
This commit is contained in:
qzl
@@ -0,0 +1,640 @@
|
||||
# Visual Design Language for Flutter Mobile App
|
||||
|
||||
This document defines the **visual design language** for the mobile app.
|
||||
It is intended to guide AI agents, designers, and developers toward a **consistent, premium, mobile-native product experience**.
|
||||
|
||||
This file focuses on **visual style, surface hierarchy, interaction feel, motion tone, and design intent**.
|
||||
Implementation constraints such as token usage, component reuse, testing, and protocol requirements remain defined elsewhere.
|
||||
|
||||
---
|
||||
|
||||
## 0) Scope and Role (MUST)
|
||||
|
||||
- This file applies to all mobile UI work under `apps/**`.
|
||||
- This file defines the **design intent** and **visual system**.
|
||||
- This file does **not** replace implementation constraints; it complements them.
|
||||
- If implementation and visual intent conflict, prefer the stricter rule while preserving as much visual intent as possible.
|
||||
- The agent **MUST** treat this file as the source of truth for:
|
||||
- visual tone
|
||||
- aesthetic direction
|
||||
- surface hierarchy
|
||||
- perceived product quality
|
||||
- motion feel
|
||||
- assistant-product identity
|
||||
|
||||
---
|
||||
|
||||
## 1) Product Design Goal (MUST)
|
||||
|
||||
The app is a **personal assistant mobile app**.
|
||||
Its UI must feel like a **premium consumer product**, not a wireframe, dashboard, admin console, or document page.
|
||||
|
||||
The overall product impression must be:
|
||||
|
||||
- calm
|
||||
- intelligent
|
||||
- trustworthy
|
||||
- soft
|
||||
- polished
|
||||
- mobile-native
|
||||
- slightly futuristic
|
||||
- assistant-oriented
|
||||
|
||||
The UI must communicate:
|
||||
|
||||
- clarity without coldness
|
||||
- capability without heaviness
|
||||
- elegance without visual noise
|
||||
- structure without rigidity
|
||||
|
||||
The visual result must feel closer to a refined consumer app than to a productivity back office tool.
|
||||
|
||||
---
|
||||
|
||||
## 2) Core Style Direction (MUST)
|
||||
|
||||
The app’s visual design language is based on the following style blend:
|
||||
|
||||
- **soft blue brand atmosphere**
|
||||
- **layered card-based interface**
|
||||
- **subtle depth and hierarchy**
|
||||
- **selective soft neumorphic influence**
|
||||
- **light glassmorphism accents where appropriate**
|
||||
- **modern iOS-inspired spacing and composition**
|
||||
- **premium startup-product polish**
|
||||
|
||||
The UI should feel:
|
||||
|
||||
- soft, not blunt
|
||||
- layered, not flat
|
||||
- tactile, not decorative
|
||||
- modern, not trendy for its own sake
|
||||
- structured, not mechanical
|
||||
|
||||
The visual system must avoid extremes:
|
||||
- not overly flat
|
||||
- not heavily skeuomorphic
|
||||
- not toy-like
|
||||
- not enterprise-heavy
|
||||
- not overly ornamental
|
||||
|
||||
---
|
||||
|
||||
## 3) Brand Mood (MUST)
|
||||
|
||||
The brand mood is:
|
||||
|
||||
- soft blue
|
||||
- airy
|
||||
- supportive
|
||||
- composed
|
||||
- focused
|
||||
- warm-tech
|
||||
- light but capable
|
||||
|
||||
The assistant should feel like:
|
||||
|
||||
- a calm expert
|
||||
- a thoughtful companion
|
||||
- a reliable digital helper
|
||||
|
||||
The assistant should **not** feel like:
|
||||
|
||||
- a chatbot demo
|
||||
- a mechanical enterprise workflow engine
|
||||
- a gaming interface
|
||||
- a childish mascot product
|
||||
- a harsh cyberpunk system
|
||||
|
||||
Avoid visual moods that are:
|
||||
- overly playful
|
||||
- overly sharp
|
||||
- overly dark and oppressive
|
||||
- sterile and lifeless
|
||||
- loud or attention-seeking
|
||||
|
||||
---
|
||||
|
||||
## 4) Visual Hierarchy Principles (MUST)
|
||||
|
||||
Every screen must present a clear and intentional visual hierarchy.
|
||||
|
||||
The hierarchy should generally be readable as:
|
||||
|
||||
1. page background / spatial field
|
||||
2. primary surfaces
|
||||
3. grouped secondary surfaces
|
||||
4. highlighted interactive elements
|
||||
5. text and status accents
|
||||
6. transient states and feedback
|
||||
|
||||
The UI must always help the user understand:
|
||||
|
||||
- what is primary
|
||||
- what is grouped
|
||||
- what is interactive
|
||||
- what is informational
|
||||
- what is temporary
|
||||
- what is currently changing
|
||||
|
||||
Hierarchy must not rely on color alone.
|
||||
It should also be expressed through:
|
||||
|
||||
- spacing
|
||||
- surface grouping
|
||||
- radius
|
||||
- depth
|
||||
- density
|
||||
- contrast
|
||||
- scale
|
||||
- motion
|
||||
|
||||
---
|
||||
|
||||
## 5) Surface Model (MUST)
|
||||
|
||||
The app must be designed as a **surface-based system**, not as a collection of raw containers.
|
||||
|
||||
Every major screen should define at least these conceptual surface layers:
|
||||
|
||||
- **Background Surface**
|
||||
The calm spatial field behind all content.
|
||||
|
||||
- **Primary Content Surface**
|
||||
The main assistant response area, key card, major module, or central interaction container.
|
||||
|
||||
- **Secondary Grouped Surfaces**
|
||||
Supporting cards, grouped actions, metadata blocks, previews, summaries, or widgets.
|
||||
|
||||
- **Interactive Emphasis Surface**
|
||||
Elements that deserve stronger presence, such as quick actions, active cards, selected states, or focused modules.
|
||||
|
||||
Surfaces must feel intentional and product-grade.
|
||||
A surface should never read as “just another box”.
|
||||
|
||||
Surfaces should feel:
|
||||
- softly separated
|
||||
- visually organized
|
||||
- breathable
|
||||
- cohesive with surrounding layers
|
||||
|
||||
---
|
||||
|
||||
## 6) Depth and Elevation Language (MUST)
|
||||
|
||||
The UI must use depth carefully and consistently.
|
||||
|
||||
Depth should be expressed through:
|
||||
- layered surfaces
|
||||
- subtle shadows
|
||||
- gentle highlights
|
||||
- tonal contrast
|
||||
- grouped spacing
|
||||
- controlled overlap when appropriate
|
||||
|
||||
Depth is used to:
|
||||
- separate surfaces from background
|
||||
- indicate focus
|
||||
- elevate important actions
|
||||
- support tactile feel
|
||||
- avoid paper-flat layouts
|
||||
|
||||
Depth must **not** be used as random decoration.
|
||||
|
||||
The app must avoid:
|
||||
- harsh shadow stacks
|
||||
- muddy over-layering
|
||||
- fake 3D gimmicks
|
||||
- heavy embossed skeuomorphism
|
||||
- noisy glow effects
|
||||
|
||||
The preferred depth quality is:
|
||||
- soft
|
||||
- understated
|
||||
- calm
|
||||
- premium
|
||||
- readable
|
||||
|
||||
---
|
||||
|
||||
## 7) Shape Language (MUST)
|
||||
|
||||
The shape language should feel soft, modern, and coherent.
|
||||
|
||||
Shapes should communicate:
|
||||
- friendliness
|
||||
- calmness
|
||||
- safety
|
||||
- clarity
|
||||
|
||||
Preferred characteristics:
|
||||
- rounded corners
|
||||
- smooth modules
|
||||
- softened containers
|
||||
- pill-like or capsule-like actions where appropriate
|
||||
- continuous visual flow across adjacent surfaces
|
||||
|
||||
Avoid:
|
||||
- sharp aggressive geometry as default
|
||||
- inconsistent corner treatments
|
||||
- randomly mixing square and rounded systems
|
||||
- highly ornamental silhouettes
|
||||
|
||||
Shape consistency is important to product polish.
|
||||
If a screen mixes too many shape styles, it will feel unrefined.
|
||||
|
||||
---
|
||||
|
||||
## 8) Composition Style (MUST)
|
||||
|
||||
The app must use **layered modular composition** rather than flat linear stacking wherever reasonable.
|
||||
|
||||
Preferred composition patterns:
|
||||
- grouped cards
|
||||
- floating modules
|
||||
- segmented content blocks
|
||||
- clearly separated information zones
|
||||
- visually anchored action regions
|
||||
- progressive disclosure sections
|
||||
|
||||
The screen should feel like a composed product surface, not a long sheet of stacked rectangles.
|
||||
|
||||
The design should avoid:
|
||||
- full-screen blank white slabs
|
||||
- ungrouped content dumps
|
||||
- evenly weighted sections with no focal point
|
||||
- spreadsheet-like layouts
|
||||
- dashboard density unless explicitly needed
|
||||
|
||||
Content layout should guide the eye through the screen in a deliberate way.
|
||||
|
||||
---
|
||||
|
||||
## 9) Spacing Rhythm (MUST)
|
||||
|
||||
Spacing must create visual rhythm, hierarchy, and calmness.
|
||||
|
||||
Spacing should:
|
||||
- separate conceptual groups clearly
|
||||
- keep related content close enough to feel connected
|
||||
- create a breathable reading experience
|
||||
- support scanning within a few seconds
|
||||
|
||||
The app should feel:
|
||||
- compact enough to be useful
|
||||
- spacious enough to feel premium
|
||||
|
||||
Avoid both:
|
||||
- cramped layouts
|
||||
- excessively empty layouts
|
||||
|
||||
Spacing rhythm should create a sense of:
|
||||
- confidence
|
||||
- order
|
||||
- softness
|
||||
- ease of use
|
||||
|
||||
---
|
||||
|
||||
## 10) Color Usage Philosophy (MUST)
|
||||
|
||||
The app uses a **soft blue-centered palette**, but blue must be used strategically.
|
||||
|
||||
Blue is a brand signal, not a paint bucket.
|
||||
|
||||
Use brand color to:
|
||||
- anchor important actions
|
||||
- signal focus
|
||||
- support assistant identity
|
||||
- reinforce important states
|
||||
- create premium calmness
|
||||
|
||||
Do not use blue by flooding all surfaces equally.
|
||||
|
||||
Color distribution must preserve:
|
||||
- hierarchy
|
||||
- readability
|
||||
- tonal balance
|
||||
- calmness
|
||||
|
||||
Preferred color impression:
|
||||
- light
|
||||
- trustworthy
|
||||
- airy
|
||||
- intelligent
|
||||
- non-aggressive
|
||||
|
||||
Avoid:
|
||||
- oversaturated color blocks
|
||||
- excessive accent competition
|
||||
- flat monochrome sameness
|
||||
- harsh enterprise-blue overuse
|
||||
|
||||
---
|
||||
|
||||
## 11) Typography Feel (MUST)
|
||||
|
||||
Typography should feel:
|
||||
|
||||
- clean
|
||||
- modern
|
||||
- readable
|
||||
- calm
|
||||
- product-grade
|
||||
|
||||
Text hierarchy must be immediately understandable.
|
||||
|
||||
The text system should communicate:
|
||||
- primary focus
|
||||
- supportive explanation
|
||||
- metadata
|
||||
- actionability
|
||||
- transient status
|
||||
|
||||
Avoid:
|
||||
- text-heavy document appearance
|
||||
- dense paragraph dumps
|
||||
- weak heading contrast
|
||||
- decorative typography
|
||||
- oversized headline drama unless intentionally needed
|
||||
|
||||
Typography should support assistant use cases:
|
||||
- fast scanning
|
||||
- digestible summaries
|
||||
- calm reading
|
||||
- structured conversation
|
||||
- confidence in results
|
||||
|
||||
---
|
||||
|
||||
## 12) Information Density (MUST)
|
||||
|
||||
The product is a personal assistant, so information density must be carefully balanced.
|
||||
|
||||
The UI must avoid:
|
||||
- toy-like under-information
|
||||
- enterprise-dashboard over-information
|
||||
|
||||
The ideal density is:
|
||||
- compact but breathable
|
||||
- rich but organized
|
||||
- helpful without overwhelming
|
||||
|
||||
Assistant outputs should be:
|
||||
- quickly scannable
|
||||
- clearly grouped
|
||||
- progressively explorable
|
||||
- structured for decision support
|
||||
|
||||
When complexity increases, use:
|
||||
- grouping
|
||||
- folding
|
||||
- summarization
|
||||
- layered detail reveal
|
||||
|
||||
Do not dump all content at the same visual weight.
|
||||
|
||||
---
|
||||
|
||||
## 13) Interaction Feel (MUST)
|
||||
|
||||
Interactions must feel:
|
||||
- responsive
|
||||
- soft
|
||||
- clear
|
||||
- premium
|
||||
- mobile-native
|
||||
|
||||
The UI should feel alive, but not noisy.
|
||||
|
||||
Interaction feedback should reinforce:
|
||||
- user action
|
||||
- state transition
|
||||
- focus shift
|
||||
- hierarchy change
|
||||
- successful completion
|
||||
- temporary waiting
|
||||
|
||||
The product should feel smooth and intentional under touch.
|
||||
|
||||
Avoid interaction feel that is:
|
||||
- abrupt
|
||||
- dead
|
||||
- jittery
|
||||
- overly animated
|
||||
- flashy for its own sake
|
||||
|
||||
---
|
||||
|
||||
## 14) Motion Language (MUST)
|
||||
|
||||
Motion is part of the product language and must be treated as meaningful.
|
||||
|
||||
Motion should communicate:
|
||||
- causality
|
||||
- continuity
|
||||
- spatial relationship
|
||||
- emphasis
|
||||
- system responsiveness
|
||||
|
||||
Preferred motion patterns:
|
||||
- soft press feedback
|
||||
- gentle surface transition
|
||||
- smooth card expand/collapse
|
||||
- subtle content entrance
|
||||
- assistant response reveal continuity
|
||||
- calm loading transitions
|
||||
- state changes that feel connected rather than replaced
|
||||
|
||||
Motion must not feel:
|
||||
- bouncy in a toy-like way
|
||||
- abrupt and mechanical
|
||||
- dramatic and distracting
|
||||
- overloaded with simultaneous effects
|
||||
|
||||
The best motion is:
|
||||
- noticeable enough to feel polished
|
||||
- restrained enough to remain calm
|
||||
|
||||
---
|
||||
|
||||
## 15) Assistant-Specific UI Tone (MUST)
|
||||
|
||||
This is not a generic CRUD app.
|
||||
It is an assistant product.
|
||||
|
||||
Therefore, the UI must visually support:
|
||||
- conversation
|
||||
- guidance
|
||||
- summaries
|
||||
- suggestions
|
||||
- action handoff
|
||||
- confidence-building
|
||||
- clarity of next steps
|
||||
|
||||
Assistant screens should feel:
|
||||
- structured but conversational
|
||||
- intelligent but approachable
|
||||
- helpful rather than commanding
|
||||
|
||||
Key assistant outputs should feel like:
|
||||
- curated result modules
|
||||
- decision-support surfaces
|
||||
- intelligent summaries
|
||||
- actionable insight cards
|
||||
|
||||
They should not feel like:
|
||||
- raw logs
|
||||
- plain transcript dumps
|
||||
- developer console output
|
||||
- generic list rows only
|
||||
|
||||
---
|
||||
|
||||
## 16) Visual Anti-Patterns (MUST NOT)
|
||||
|
||||
The UI must not look like any of the following:
|
||||
|
||||
- a plain document page
|
||||
- a white sheet with blue buttons
|
||||
- a spreadsheet-like admin panel
|
||||
- a low-fidelity wireframe
|
||||
- a default Flutter demo app
|
||||
- an over-glowing concept shot that is not implementable
|
||||
- a generic template marketplace screen
|
||||
- a visually noisy Dribbble-style mockup without product discipline
|
||||
|
||||
Specifically avoid:
|
||||
- full-screen flat white blocks with little hierarchy
|
||||
- arbitrary shadow usage
|
||||
- inconsistent card treatments
|
||||
- too many competing accent colors
|
||||
- overly dense content without grouping
|
||||
- equally weighted sections with no focus
|
||||
- raw container stacking with no surface semantics
|
||||
- excessive decorative gradients
|
||||
- empty “pretty” layouts with weak usability
|
||||
|
||||
---
|
||||
|
||||
## 17) Preferred Inspirations (SHOULD)
|
||||
|
||||
The product should loosely evoke qualities found in:
|
||||
|
||||
- modern iOS app composition
|
||||
- premium startup productivity apps
|
||||
- calm AI-native product interfaces
|
||||
- refined card-based mobile layouts
|
||||
- soft glass / soft depth surface systems
|
||||
|
||||
Useful inspiration qualities include:
|
||||
- compositional discipline
|
||||
- strong spacing rhythm
|
||||
- excellent hierarchy
|
||||
- restrained polish
|
||||
- tactile clarity
|
||||
- premium consumer feel
|
||||
|
||||
Inspiration must be translated into this product’s identity, not copied literally.
|
||||
|
||||
---
|
||||
|
||||
## 18) Screen-Level Decision Rules (MUST)
|
||||
|
||||
When generating or refining a screen, the agent must decide in this order:
|
||||
|
||||
1. What is the primary focus of the screen?
|
||||
2. What is the surface hierarchy?
|
||||
3. What needs strongest emphasis?
|
||||
4. What should be grouped together?
|
||||
5. What should remain lightweight or secondary?
|
||||
6. Where should motion reinforce understanding?
|
||||
7. How can the result feel more like a premium assistant app and less like a document page?
|
||||
|
||||
When multiple valid layouts exist, prefer the one that:
|
||||
- has clearer hierarchy
|
||||
- feels more mobile-native
|
||||
- has stronger surface semantics
|
||||
- feels calmer and more polished
|
||||
- better supports future micro-interactions
|
||||
- better matches the assistant-product identity
|
||||
|
||||
---
|
||||
|
||||
## 19) AI Generation Guidance (MUST)
|
||||
|
||||
When an AI agent generates UI, it must think in terms of:
|
||||
|
||||
- visual hierarchy
|
||||
- surface system
|
||||
- product polish
|
||||
- interaction states
|
||||
- motion readiness
|
||||
- assistant identity
|
||||
- premium mobile composition
|
||||
|
||||
It must not think in terms of:
|
||||
|
||||
- raw widget stacking only
|
||||
- “just make it functional”
|
||||
- generic default mobile layouts
|
||||
- admin or dashboard templates
|
||||
- flat page sections without depth
|
||||
- a document-first visual model
|
||||
|
||||
Before finalizing a UI, the agent should mentally verify:
|
||||
|
||||
- Does this feel like a product, not a page?
|
||||
- Is there clear hierarchy?
|
||||
- Do surfaces feel intentional?
|
||||
- Does the screen feel calm and premium?
|
||||
- Is the assistant identity visually present?
|
||||
- Would this look plausible in a polished shipping app?
|
||||
|
||||
If the answer is no, the UI is not finished.
|
||||
|
||||
---
|
||||
|
||||
## 20) Relationship with Design Tokens (MUST)
|
||||
|
||||
This document defines **what the UI should feel like**.
|
||||
Implementation files define **how those values are encoded**.
|
||||
|
||||
Therefore:
|
||||
|
||||
- the visual language must be realized through the project’s design token system
|
||||
- any missing visual semantics should be added to tokens or shared theme primitives
|
||||
- the agent must not bypass the design system to approximate the visual intent locally
|
||||
|
||||
The correct workflow is:
|
||||
|
||||
1. understand desired visual effect
|
||||
2. map it into shared tokens / shared components
|
||||
3. implement consistently
|
||||
4. preserve future reusability
|
||||
|
||||
---
|
||||
|
||||
## 21) Final Design Standard (MUST)
|
||||
|
||||
Every shipped screen should aim to satisfy all of the following:
|
||||
|
||||
- visually coherent
|
||||
- recognizably premium
|
||||
- mobile-native
|
||||
- calm and intelligent
|
||||
- structurally clear
|
||||
- not flat
|
||||
- not noisy
|
||||
- clearly assistant-oriented
|
||||
- implementation-realistic
|
||||
- design-system-compatible
|
||||
|
||||
The final bar is not merely:
|
||||
- “works”
|
||||
- “renders”
|
||||
- “uses tokens”
|
||||
- “passes lint”
|
||||
|
||||
The final bar is:
|
||||
- **feels like a polished personal assistant product**
|
||||
Reference in New Issue
Block a user