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:

```bash
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