# Provider Portal Visual Alignment Implementation Plan

> **For Codex:** Execute this plan inline with TDD checkpoints. Preserve every
> provider route, form field, `id`, `name`, `data-*` attribute and JavaScript
> selector.

**Goal:** Align every provider account and private portal screen with the
approved MyCode visual system, using a persistent desktop sidebar and mobile
bottom navigation without changing application behavior.

**Architecture:** Blade remains a thin presentation layer over the existing
provider ViewModel. A shared token sheet supplies MyCode typography, color,
radius and shadow primitives to both the homepage and provider portal. Provider
styles are split by responsibility and loaded in deterministic order.

**Tech Stack:** Laravel Blade, PHPUnit feature tests, CSS, existing vanilla
JavaScript provider bundle.

---

### Task 1: Add failing visual contracts

**Files:**
- Create: `tests/Feature/ProviderPortalVisualContractTest.php`
- Modify: `tests/Feature/ProviderPortalArchitectureTest.php`

1. Assert provider pages load the shared tokens, MyCode fonts, Material Symbols
   and the six ordered provider stylesheets.
2. Assert the old monolithic `css/provider/portal.css` reference is absent.
3. Assert private markup exposes one semantic provider navigation with the four
   existing `data-provider-nav` values and icon labels.
4. Assert the shared token file defines blue primary, coral accent, danger and
   completion roles, while provider CSS consumes those roles.
5. Run:

   ```bash
   php artisan test --filter=ProviderPortalVisualContractTest
   php artisan test --filter=ProviderPortalArchitectureTest
   ```

   Expected: fail because the new assets and markup do not exist yet.

### Task 2: Introduce the shared MyCode design tokens

**Files:**
- Create: `public/css/mycode-design-tokens.css`
- Modify: `public/css/welcome-base/01.css`
- Modify: `resources/views/welcome.blade.php`
- Modify: `resources/views/provider/portal.blade.php`

1. Move the existing homepage visual primitives into the shared token sheet,
   retaining backwards-compatible aliases used by the homepage.
2. Add provider-facing semantic aliases for primary, accent, danger, success,
   text, surface, line, radii, shadows and transitions.
3. Load tokens before page-specific styles on the homepage and provider portal.
4. Load Plus Jakarta Sans, Bricolage Grotesque and Material Symbols Rounded in
   the provider portal.
5. Run homepage and provider visual contract tests.

### Task 3: Rebuild account and private portal structure

**Files:**
- Modify: `resources/views/provider/partials/account.blade.php`
- Modify: `resources/views/provider/partials/app-shell.blade.php`

1. Add presentational wrappers, icon treatments and supporting copy to account
   screens while retaining every existing form contract.
2. Convert the private shell into a two-column layout containing a branded
   sidebar, semantic navigation and main workspace.
3. Use one navigation DOM that reflows into the approved mobile bottom bar.
4. Add icons and visually hidden labels where needed; retain `aria-current`
   ownership in the existing router.
5. Run provider JavaScript selector and markup security tests.

### Task 4: Split and implement provider styles

**Files:**
- Delete: `public/css/provider/portal.css`
- Create: `public/css/provider/portal/01-base.css`
- Create: `public/css/provider/portal/02-account.css`
- Create: `public/css/provider/portal/03-shell.css`
- Create: `public/css/provider/portal/04-components.css`
- Create: `public/css/provider/portal/05-forms.css`
- Create: `public/css/provider/portal/06-responsive.css`

1. Implement the approved MyCode productive visual direction.
2. Keep account screens navigation-free and center the active account form.
3. Keep the desktop sidebar persistent and reserve content space for it.
4. At mobile breakpoints, transform navigation into a fixed bottom bar,
   account for `safe-area-inset-bottom`, and preserve 44px touch targets.
5. Keep coral limited to brand/progress/attention; use red for errors and
   destructive actions, green for completion.
6. Keep every new stylesheet under 150 lines.
7. Run the two visual contracts and all provider feature tests.

### Task 5: Version, visual QA and full verification

**Files:**
- Modify: `VERSION`

1. Run the local application and inspect login/register on desktop and mobile.
2. Verify private shell structure through authenticated feature renders and
   check responsive CSS contracts.
3. Set the visual release version to `1.4.0`.
4. Run:

   ```bash
   php artisan architecture:audit --strict
   php artisan test
   ```

5. Review `git diff --check`, inspect the final diff with the code review graph
   and confirm unrelated user assets remain untouched and unstaged.