# Portal UI Cleanup Design

## Problem

The portal account pages have accumulated visual inconsistencies: different card styles, spacing, button variants, badge implementations, and header structures across pages. The sidebar color feels disconnected from the landing page brand. Logo visibility is poor on the dark sidebar. Subscriptions navigation is over-complicated. Breadcrumbs conflict with page titles. Detail pages lack consistent structure.

## Decisions

### 1. Sidebar & Brand Consistency

**Sidebar background:** Shift from `oklch(0.18 0.03 250)` to `oklch(0.20 0.06 234.4)` — same hue as primary blue, slightly more saturated, still dark. Creates brand harmony with landing page.

**Sidebar border:** Adjust to match new tone.

**Logo:** White variant for dark sidebar. SVG fallback colors change from `#60A5FA`/`#1E40AF` to `#ffffff`/`rgba(255,255,255,0.6)`. Remove the `bg-white/10` container — let logo sit directly.

**Subscriptions nav:** Change from expandable with child links to a direct link to `/account/subscriptions` (like Dashboard or Services). Remove `computeNavigation` dynamic children.

### 2. Unified List Page Pattern

All list pages (Subscriptions, Orders, Invoices, Support) follow one pattern:

```
PageLayout (bg-muted/40 header built-in, icon + title + action buttons, NO description)
  Metric cards row (grid-cols-2 lg:grid-cols-4 gap-3) — where applicable
  Content card (bg-card rounded-xl border border-border shadow-[var(--cp-shadow-1)])
    Search/filter bar (px-5 py-3.5 border-b border-border/40)
    Content area (p-5)
      Grid: grid-cols-1 sm:grid-cols-2 xl:grid-cols-3 gap-3
      or Table: DataTable
```

**List header:** Handled by PageLayout. Icon + title on left, action buttons right-aligned. No description text.

**Card borders:** `border border-border` everywhere — drop `/60` opacity variants on outer cards.

**List item hover:** `hover:border-border hover:shadow-[var(--cp-shadow-2)] hover:-translate-y-0.5` — consistent across all.

**Status badges:** Always use `StatusPill` atom — no inline badge classes.

**Affected pages:** SubscriptionsList, OrdersList, InvoicesList, SupportCasesView.

### 3. Unified Detail Page Pattern

```
PageLayout (bg-muted/40 header, backLink + title + status pill + right-aligned action buttons)
  Stats/summary row (bg-card rounded-xl border border-border shadow-[var(--cp-shadow-1)])
    Grid: grid-cols-2 md:grid-cols-4 gap-6, px-6 py-5
  Stacked section cards (space-y-6)
```

**Back navigation:** PageLayout `backLink` prop renders `← Back to {parent}` link above the header. Detail pages only. No breadcrumbs.

**Action buttons:** Always in PageLayout `actions` prop, right-aligned. Use `<Button>` component variants (not inline-styled).

**Affected pages:** SubscriptionDetail, OrderDetail, InvoiceDetail, SupportCaseDetailView.

### 4. PageLayout Template Changes

PageLayout becomes the single source of truth for page header styling. Changes:

- **Header area:** Always renders with `bg-muted/40 border-b border-border/40` background. No more plain/transparent headers.
- **Remove description:** Drop the `description` prop usage — title is enough, description was redundant with sidebar context.
- **New `backLink` prop:** `{ label: string; href: string }` — renders `← Back to {parent}` above the header on detail pages. List pages don't pass this.
- **Remove breadcrumbs:** Drop breadcrumb rendering entirely — replaced by `backLink` on detail pages, sidebar on list pages.
- **Header layout:** `flex items-center justify-between` — icon + title on left, actions on right. Status pills sit next to the title.
- **Consistent spacing:** Header padding `px-6 py-4`, content area spacing `space-y-6`.

This means every account page automatically gets the same header treatment by using PageLayout. No per-page header styling needed.

### 5. Section Card Pattern

Every content section in detail pages uses this structure:

```
bg-card rounded-xl border border-border shadow-[var(--cp-shadow-1)] overflow-hidden
  Header (bg-muted/40 px-6 py-4 border-b border-border/40)
    flex items-center justify-between
      Left: flex items-center gap-3
        Icon circle (h-9 w-9 rounded-lg bg-{tone}/10 text-{tone})
        Title: text-sm font-semibold text-foreground
        Subtitle: text-xs text-muted-foreground
      Right: action button(s) or link
  Content (px-6 py-5)
```

Each section gets a semantic tone for its icon circle:

- Billing: `primary`
- SIM Management: `info`
- Order Items: `success`
- Support: `warning`

### 6. Subscriptions-Specific Fixes

- **Active/inactive dimming:** Active subscriptions render normally. Completed/Cancelled/Terminated get `opacity-60` on the grid card + muted status indicator.
- **Cancel button:** Move from inline-styled to `<Button variant="destructive" size="sm">` via PageLayout actions.
- **Domain imports:** Fix `@customer-portal/domain/subscriptions` module resolution (run `pnpm domain:build`).
- **Grid card borders:** Standardize from `border-border/60` to `border-border`.

### 7. Cross-Page Consistency

**Typography:**

- Page titles: PageLayout handles it (`text-xl sm:text-2xl md:text-3xl font-bold`). Remove custom title sizes in views.
- Section headings: `text-sm font-semibold text-foreground` inside section cards.
- Stat values: `font-heading` for numbers.

**Buttons — always use `<Button>` component:**

- Primary actions: `variant="default"` (Browse Services, New Case)
- Secondary: `variant="outline"` (Back, Retry, View All)
- Destructive: `variant="destructive"` (Cancel Service)
- Links: `variant="link"` or `ghost` for in-section navigation

**Status display:**

- Always `<StatusPill>` — no inline badge classes
- `size="sm"` in list views, `size="md"` in detail headers

**Borders:**

- Outer cards: `border border-border`
- Internal dividers only: `border-b border-border/40`

**Spacing:**

- Card padding: `p-4` for list item cards, `p-5` for container sections
- Gap between items: `gap-3`
- Section spacing: `space-y-6`

### 8. Navigation Changes

- **List pages:** No back link — sidebar handles navigation.
- **Detail pages:** `← Back to {parent}` link above title.
- **Breadcrumbs:** Removed — redundant with page title.
- **Sidebar subscriptions:** Direct link, no expandable children.

## Out of Scope

- Landing page color token migration (separate effort)
- New component creation beyond what's needed for the patterns above
- Mobile-specific layout changes
