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

Auth Pages Redesign Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Redesign the Flutter auth pages and feedback system so login, register, reset-password, segmented code input, and toast/inline feedback all match the project visual design language while preserving existing logic.

Architecture: Keep auth business logic, cubits, navigation, and repository behavior unchanged. Move the redesign into shared design tokens and shared widgets first, then rebuild each auth screen on top of those primitives so the result is reusable and consistent.

Tech Stack: Flutter, flutter_bloc, go_router, existing design tokens and shared widgets under apps/lib/

---

Task 1: Audit reusable auth and feedback primitives

Files:

• Modify: apps/lib/core/theme/design_tokens.dart
• Modify: apps/lib/shared/widgets/app_button.dart
• Modify: apps/lib/shared/widgets/fixed_length_code_input.dart
• Modify: apps/lib/shared/widgets/toast/toast.dart
• Modify: apps/lib/shared/widgets/banner/app_banner.dart
• Test: apps/test/ relevant existing widget or feature tests if impacted

Step 1: Identify missing token semantics before UI changes

Review current colors, spacing, radius, and surface semantics. List any missing token roles needed for:

• atmospheric auth background
• floating card border/shadow layering
• premium CTA surface states
• segmented input states
• toast and inline message states

Step 2: Add only the minimal new tokens needed

Update apps/lib/core/theme/design_tokens.dart with shared semantic tokens rather than page-local constants.

Expected areas:

• auth background surface tones
• auth card border/highlight tones
• stronger button tonal roles
• inline message backgrounds/borders/text roles
• toast surface roles if existing status tokens are insufficient

Step 3: Run a quick compile-oriented check mentally against all planned components

Confirm the new tokens are generic enough for shared reuse and not named after individual screens.

Step 4: Commit checkpoint note

Do not create a git commit unless explicitly requested by the user.

Task 2: Redesign shared CTA and link interaction surfaces

Files:

• Modify: apps/lib/shared/widgets/app_button.dart
• Modify: apps/lib/shared/widgets/link_button.dart
• Test: existing auth tests if button usage affects behavior

Step 1: Write the failing test if widget behavior changes materially

If the redesign introduces new behavior beyond styling, add a targeted widget test. If changes remain visual-only, document that no new test is added per lightweight UI testing policy.

Step 2: Refactor AppButton into a stronger material hierarchy

Implement:

• calmer premium CTA surface
• better disabled state separation
• consistent capsule-like shape
• optional secondary/outlined appearance if already used

Keep public API stable unless a small safe extension is clearly needed.

Step 3: Refine LinkButton hit area and visual tone

Implement:

• clearer touch target
• lighter emphasis than CTA
• better pressed and disabled feel

Step 4: Run impacted checks

Run: flutter analyze

Expected: no new analyzer issues from button or link widget changes.

Task 3: Redesign segmented input as a premium grouped control

Files:

• Modify: apps/lib/shared/widgets/fixed_length_code_input.dart
• Test: add or update a widget test only if interaction logic changes materially

Step 1: Write the failing test for any changed interaction behavior

If focus progression, formatting, or semantic behavior changes, add a widget test that captures the intended interaction. If only visuals change, document why no new test is added.

Step 2: Rebuild the visual structure of the segmented input

Implement:

• clearer grouped container feel
• balanced cell rhythm
• group-level focus cue plus active-cell cue
• stronger filled state
• polished error and disabled states

Step 3: Preserve existing logical behavior

Keep:

• fixed length handling
• allowed character filtering
• uppercase support
• autofill compatibility

Step 4: Run focused verification

Run: flutter analyze

Expected: no new issues from segmented input refactor.

Task 4: Rebuild global toast and inline message visuals

Files:

• Modify: apps/lib/shared/widgets/toast/toast.dart
• Modify: apps/lib/shared/widgets/banner/app_banner.dart
• Modify: apps/lib/shared/widgets/toast/toast_type.dart if needed
• Modify: apps/lib/shared/widgets/toast/toast_type_config.dart
• Test: add widget tests only if feedback behavior semantics change

Step 1: Inspect current toast config implementation

Review toast_type_config.dart and align the redesign with shared semantic tokens.

Step 2: Redesign global toast as a floating product card

Implement:

• safe-area aware floating card
• refined tint, border, icon, and text hierarchy
• restrained shadow and motion
• stable dismissal behavior

Step 3: Redesign inline message presentation

Implement:

• lighter component-level message styling
• consistent relationship to current form group
• clear differentiation from toast while sharing status semantics

Step 4: Preserve system rules

Keep:

• Toast.show(...) for transient global feedback
• AppBanner for persistent inline feedback
• no raw ScaffoldMessenger

Step 5: Run focused verification

Run: flutter analyze

Expected: no analyzer issues.

Task 5: Add a reusable auth surface composition primitive

Files:

• Modify: apps/lib/features/auth/ui/widgets/auth_page_scaffold.dart
• Create or Modify: apps/lib/features/auth/ui/widgets/ shared auth surface widgets as needed

Step 1: Evaluate whether the existing scaffold can express the new surface hierarchy

Check whether AuthPageScaffold can support:

• atmospheric background treatment
• safe-area balanced centering
• top brand anchor spacing
• floating card composition

Step 2: Implement the minimal reusable auth layout primitives

Possible additions:

• auth hero header
• auth floating card shell
• grouped section wrapper

Only create what is reused by at least two auth screens.

Step 3: Keep layout semantics explicit

Ensure every Row and Column has explicit crossAxisAlignment and layout intent remains traceable.

Task 6: Rebuild the login page UI on top of the shared primitives

Files:

• Modify: apps/lib/features/auth/ui/screens/login_screen.dart

Step 1: Preserve all existing logic paths

Do not change:

• cubit usage
• submit flow
• auth bloc event dispatch
• navigation targets

Step 2: Replace the existing layout with the new design

Implement:

• brand anchor header
• compact floating login card
• refined email and password groups
• CTA-first hierarchy
• lightweight forgot-password action
• low-emphasis register switch

Step 3: Reconnect inline feedback to the new grouping

Place validation and error banners where they support the form rhythm rather than interrupt it.

Step 4: Run impacted checks

Run: flutter analyze

Expected: login screen compiles cleanly.

Task 7: Rebuild the register page UI with grouped invite code treatment

Files:

• Modify: apps/lib/features/auth/ui/screens/register_screen.dart

Step 1: Preserve all existing logic paths

Do not change:

• cubit usage
• invite code normalization
• validation behavior
• route transition to verification page
• silent code send behavior

Step 2: Rebuild required and optional sections

Implement:

• shared brand anchor header
• taller floating card
• grouped account info section
• separate optional invite code section
• refined progress indicator treatment
• improved footer switch action

Step 3: Keep segmented invite code input

Use the redesigned shared segmented input without changing its fixed-length semantics.

Step 4: Run impacted checks

Run: flutter analyze

Expected: register screen compiles cleanly.

Task 8: Rebuild the reset-password page as a guided two-stage flow

Files:

• Modify: apps/lib/features/auth/ui/screens/reset_password_screen.dart

Step 1: Preserve all existing logic and feedback semantics

Do not change:

• cubit interactions
• send code and resend behavior
• submit behavior
• success redirect
• toast semantics

Step 2: Recompose the screen into staged groups

Implement:

• task-focused header
• stage one email + send code group
• stage two reveal for code and password reset controls after send success
• separate resend action from the code row while preserving usability

Step 3: Reconnect segmented verification code input and inline messaging

Make the code group feel premium and central without overcrowding the card.

Step 4: Run impacted checks

Run: flutter analyze

Expected: reset-password screen compiles cleanly.

Task 9: Run verification and inspect affected tests

Files:

• Test: impacted auth tests and any new widget tests added

Step 1: Run analyzer

Run: flutter analyze

Expected: PASS with no new issues.

Step 2: Run impacted auth tests

Run an auth-focused test subset appropriate to the changed files, for example:

flutter test apps/test/features/auth

Adjust the exact command to the repository's Flutter test layout if needed.

Expected: existing auth tests remain green; any new targeted widget tests pass.

Step 3: Manual visual review checklist

Verify:

• login looks calm and premium
• register invite code section feels optional but intentional
• reset-password stage flow is clear
• segmented code input feels grouped and polished
• toast feels like a product surface
• inline messages feel local and non-intrusive

Task 10: Final review and handoff

Files:

• Modify: any touched files from previous tasks if final polish is needed

Step 1: Check for consistency drift

Ensure the three auth pages, toast, inline messages, buttons, and segmented input all feel like one system.

Step 2: Confirm no scope creep changed logic unexpectedly

Re-check that routing, auth behavior, and validation rules remain intact.

Step 3: Prepare concise handoff summary

Include:

• files changed
• verification commands run
• test results
• any follow-up visual refinements still worth considering