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