social-app/docs/plans/2026-03-13-auth-pages-redesign-design.md

Auth Pages And Feedback System Redesign

Goal

Redesign the mobile authentication experience so the login, register, and reset-password flows feel like a polished assistant product instead of a flat form flow, while preserving existing business logic, routing, validation, and feedback behavior semantics.

Scope

• Rebuild the UI for login, register, and reset-password
• Preserve existing auth logic, cubits, navigation, and API calls
• Redesign the fixed-length code input experience for verification code and invite code
• Redesign the feedback system into two coordinated layers:
  • global floating toast messages
  • in-component contextual messages
• Keep all work inside the existing Flutter design system and shared widget architecture

Constraints

• Must follow apps/AGENTS.md
• Must follow apps/rules/visual_design_language.md
• Must use tokens from apps/lib/core/theme/design_tokens.dart
• Must not introduce a parallel feedback system outside the approved Toast and inline message architecture
• Must not change auth protocols, routing semantics, or submission logic

Current Problems

Visual Problems

• The screens read as flat white pages with blue buttons, which matches a prohibited anti-pattern in the visual design language.
• The main CTA button uses color as its only emphasis mechanism, so it feels plastic and low-fidelity.
• The three auth screens share only superficial consistency, not a strong surface system.
• The reset-password screen presents all steps at once, causing poor rhythm and weak hierarchy.
• The verification code layout feels cramped and improvised because the code cells and send button compete on the same row.

Feedback Problems

• Global toast messages are visually generic and lack product identity.
• Component-level messaging is under-specified and inconsistently expressed.
• Result messages and contextual validation messages are not clearly separated in responsibility.

Design Direction

The approved direction is a floating-card auth system with a soft blue atmospheric background, a clear brand anchor, and a calm layered surface hierarchy.

The target feeling is:

• premium
• calm
• trustworthy
• assistant-oriented
• softly tactile
• mobile-native

The redesign should feel like a cohesive product surface, not a stack of form containers.

Surface Model

Each auth screen uses the same four-layer structure.

1. Background Surface

The screen background is not a plain blank fill. It should feel like a soft spatial field with subtle blue-gray atmosphere. This establishes the assistant mood before the user interacts with any form element.

2. Brand Anchor Surface

The top area contains the logo and brand title. On login and register, this remains the visual identity anchor. On reset password, the title becomes more task-driven, but the page still inherits the same spatial language and product mood.

3. Primary Floating Card

The form lives in a single, elevated primary card with softened corners, restrained shadows, and calm separation from the background. This card should feel intentional and product-grade rather than like a white panel.

4. Secondary Assistive Layer

Links, helper text, step hints, resend actions, and supplemental explanations belong to a lower-emphasis support layer. These elements should feel connected to the primary card without visually competing with it.

Shared Auth Composition

All three auth screens should use a unified composition pattern.

• Top brand or task heading area
• Main floating card for the active task
• Internal grouped sections inside the card
• Lightweight transition area for secondary actions

This creates cross-screen consistency while allowing each flow to have different emphasis.

Screen Designs

Login Screen

The login screen should be the most restrained and focused of the three.

Structure:

• logo and brand title at top
• one compact floating form card
• email field
• password field
• primary login CTA
• low-emphasis forgot-password action inside the card
• lightweight bottom switch action to register

Intent:

• reduce visual noise
• make the login action feel confident and central
• keep account switching and recovery available without stealing focus

Register Screen

The register screen should feel richer than login, but still composed.

Structure:

• same brand anchor as login
• taller primary card
• grouped section for core account information
• grouped section for invite code as an optional enhancement
• subtle progress indicator treated as part of the card rhythm, not as a crude progress bar
• primary CTA for moving to verification
• lightweight switch action to login

Invite code treatment:

• remains a fixed-length segmented input
• visually grouped as an optional section, not mixed into the main required inputs
• supported by a nearby low-emphasis explanation block

Reset Password Screen

The reset-password screen should shift from a flat all-fields form into a guided two-stage flow.

Structure:

• task heading at top
• primary floating card
• stage one: email input plus send-code action
• after successful code send, reveal stage two inside the same card
• stage two: segmented verification code input, resend action, new password, confirm password, submit CTA
• lightweight return-to-login switch action below

Intent:

• create procedural clarity
• avoid forcing all fields onto the screen at once
• make the verification code area feel deliberate and product-grade

Fixed-Length Segmented Input Design

The user explicitly prefers fixed-length segmented input for both verification code and invite code. This input pattern will be preserved.

However, it will be redesigned to feel like a premium grouped input rather than a row of raw boxes.

Design principles:

• the individual cells must read as one continuous input group
• current focus should be visible at both cell level and group level
• spacing should be balanced and calm
• filled state should feel confident and readable
• disabled and error states should be obvious without becoming harsh

Required states:

• default
• focused group
• active cell
• filled
• error
• disabled

Usage rules:

• verification code remains segmented
• invite code remains segmented
• resend action is no longer visually fused to the segmented input row

Button Design

The CTA button must stop reading as a flat blue block.

New button intent:

• deeper and calmer brand blue
• stronger tactile weight
• premium capsule shape
• light depth through tonal layering and restrained shadow
• pressed and disabled states that clearly change material weight

Button hierarchy:

• primary button: for submission and key forward progress
• secondary button: for bounded alternative actions
• text-link action: for lightweight transitions and low-risk actions

Color strategy:

• blue remains the anchor, but is used with restraint
• the strongest emphasis goes to the main CTA only
• supporting actions should not look equally loud

Input Field Design

Text fields should move from generic bordered rectangles to soft embedded surfaces.

Desired qualities:

• calmer default appearance
• stronger focus clarity
• reduced raw border noise
• consistent radius and spacing rhythm
• visually integrated label, input, and helper message states

Feedback System Redesign

The feedback system is split into two coordinated layers.

1. Global Floating Toast

Global toast is a lightweight floating feedback card presented in the safe area near the top of the screen.

Use global toast for:

• cross-component success feedback
• async result notifications
• cross-step flow results
• errors that are not tied to a single visible field

Do not use global toast for:

• simple inline validation
• field-level format guidance
• contextual explanations that belong near the active input area

Visual direction:

• floating product card, not a system notification strip
• soft surface and rounded shape
• restrained state tinting
• icon plus title/message hierarchy if needed
• gentle slide/fade motion

2. In-Component Contextual Message

Contextual messages live inside the component or form group they explain.

Use contextual messages for:

• validation near fields
• warnings tied to current form state
• helper guidance for invite code or verification flow
• inline explanation of what the user should fix next

Visual direction:

• integrated into the card hierarchy
• lighter than a toast
• close to the related field or group
• consistent state styling across info, warning, and error

Responsibility Boundary

• global toast = result-oriented, temporary, cross-context feedback
• inline message = contextual, explanatory, local feedback

This separation prevents toast overuse and makes forms feel calmer.

Motion Language

Motion should be soft and minimal.

Use motion for:

• toast entrance and dismissal
• reset-password stage reveal
• button press feedback
• segmented input focus continuity

Avoid:

• springy or playful motion
• overlapping dramatic transitions
• flashy state animations

Shared Component Impact

The redesign likely requires updates or additions to shared widgets rather than one-off page styling.

Expected shared component work:

• refine AppButton
• refine or replace current toast visuals
• refine AppBanner or introduce a shared inline message presentation built on the same semantics
• redesign FixedLengthCodeInput
• add a reusable auth surface wrapper if needed

Verification Strategy

Because this work is UI-heavy, verification should focus on correctness, consistency, and safe reuse.

Primary verification targets:

• flutter analyze
• impacted auth tests
• targeted widget tests only where reusable interactive widgets become materially more complex
• manual visual review of the three auth screens and feedback states

Success Criteria

The redesign is successful when all of the following are true:

• the three auth screens feel like one coherent product system
• the UI no longer resembles a plain white form page with blue buttons
• the main CTA has better perceived material quality
• reset password has a clearer and more attractive two-stage flow
• segmented code input remains intact but feels premium
• global toasts and inline messages have clear responsibility boundaries
• the feedback system feels native to the product rather than bolted on
• the result plausibly matches the visual language standard for a polished assistant app