social-app/apps/rules/visual_design_language.md

# 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

For top navigation and title areas:
- prefer concise, high-signal header titles to communicate page identity
- avoid repeating equivalent helper text in the first body section when it does not add new actionable meaning
- use body copy only for new context, constraints, or decision guidance

---

## 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**