ctms/docs/plans/2026-03-04-ctms-enterprise-ui-implementation.md

# CTMS Enterprise UI Refresh Implementation Plan

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

**Goal:** Deliver a management-grade, visually unified CTMS UI across 10 core pages in 1-2 weeks, without changing business logic.

**Architecture:** Use a dual-track rollout: (A) minimal design-system hardening (tokens + shell + shared states), then (B) apply the same UI contract across prioritized pages. All page work must consume centralized CSS variables and shared shell patterns; page-local visual forks are disallowed.

**Tech Stack:** Vue 3, TypeScript, Vite, Element Plus, CSS variables

---

Skills to apply during execution: `@test-driven-development`, `@frontend-design`, `@verification-before-completion`, `@requesting-code-review`.

### Task 1: Add UI Contract Guardrails (Automated Checks)

**Files:**
- Create: `frontend/scripts/verify-ui-contract.mjs`
- Modify: `frontend/package.json`
- Test: `frontend/scripts/verify-ui-contract.mjs`

**Step 1: Write the failing test**

Create `frontend/scripts/verify-ui-contract.mjs`:

```js
import { readFileSync } from "node:fs";

const main = readFileSync("src/styles/main.css", "utf8");
const unified = readFileSync("src/styles/unified-page.css", "utf8");

const requiredMainTokens = [
  "--ctms-primary",
  "--ctms-text-main",
  "--ctms-bg-base",
  "--ctms-radius",
  "--ctms-shadow"
];

const requiredUnifiedTokens = [
  "--unified-shell-bg",
  "--unified-shell-radius",
  ".unified-action-bar",
  ".unified-section"
];

const missing = [
  ...requiredMainTokens.filter((t) => !main.includes(t)),
  ...requiredUnifiedTokens.filter((t) => !unified.includes(t))
];

if (missing.length) {
  console.error("UI contract check failed. Missing:", missing.join(", "));
  process.exit(1);
}

console.log("UI contract check passed");
```

**Step 2: Run test to verify it fails**

Run: `cd frontend && node scripts/verify-ui-contract.mjs`
Expected: FAIL (`ENOENT` for script file before creation, then missing-token failures until Task 2/3 done)

**Step 3: Write minimal implementation**

Update `frontend/package.json` scripts:

```json
{
  "scripts": {
    "ui:contract": "node scripts/verify-ui-contract.mjs"
  }
}
```

**Step 4: Run test to verify it passes**

Run: `cd frontend && npm run ui:contract`
Expected: PASS with `UI contract check passed` after Tasks 2/3 complete.

**Step 5: Commit**

```bash
git add frontend/scripts/verify-ui-contract.mjs frontend/package.json
git commit -m "chore(ui): add enterprise ui contract checks"
```

### Task 2: Harden Global Design Tokens (Single Source of Truth)

**Files:**
- Modify: `frontend/src/styles/main.css`
- Test: `frontend/scripts/verify-ui-contract.mjs`

**Step 1: Write the failing test**

Add new required tokens into `requiredMainTokens` in `verify-ui-contract.mjs`:

```js
"--ctms-brand-900",
"--ctms-brand-700",
"--ctms-neutral-100",
"--ctms-neutral-300",
"--ctms-focus-ring"
```

**Step 2: Run test to verify it fails**

Run: `cd frontend && npm run ui:contract`
Expected: FAIL listing the newly required tokens as missing.

**Step 3: Write minimal implementation**

In `frontend/src/styles/main.css`, define enterprise tokens in `:root`:

```css
:root {
  --ctms-brand-900: #13243a;
  --ctms-brand-700: #24496f;
  --ctms-neutral-100: #f5f7fa;
  --ctms-neutral-300: #d5dce5;
  --ctms-focus-ring: 0 0 0 3px rgba(36, 73, 111, 0.2);
}
```

**Step 4: Run test to verify it passes**

Run: `cd frontend && npm run ui:contract`
Expected: PASS for these tokens.

**Step 5: Commit**

```bash
git add frontend/src/styles/main.css frontend/scripts/verify-ui-contract.mjs
git commit -m "feat(ui): add enterprise token baseline"
```

### Task 3: Standardize Shell Layout & Page Container Contract

**Files:**
- Modify: `frontend/src/styles/unified-page.css`
- Modify: `frontend/src/components/Layout.vue`
- Test: `frontend/scripts/verify-ui-contract.mjs`

**Step 1: Write the failing test**

Extend `requiredUnifiedTokens` with:

```js
".ctms-page-shell",
".ctms-page-header-row",
".ctms-page-content-grid"
```

**Step 2: Run test to verify it fails**

Run: `cd frontend && npm run ui:contract`
Expected: FAIL showing missing shell classes.

**Step 3: Write minimal implementation**

Add shell classes in `unified-page.css`:

```css
.ctms-page-shell { padding: 16px 20px 20px; }
.ctms-page-header-row { display: flex; justify-content: space-between; align-items: center; gap: 12px; }
.ctms-page-content-grid { display: grid; gap: 12px; }
```

In `Layout.vue`, ensure routed views are wrapped by a stable shell root class.

**Step 4: Run test to verify it passes**

Run: `cd frontend && npm run ui:contract && npm run type-check`
Expected: PASS.

**Step 5: Commit**

```bash
git add frontend/src/styles/unified-page.css frontend/src/components/Layout.vue frontend/scripts/verify-ui-contract.mjs
git commit -m "feat(ui): enforce shared page shell contract"
```

### Task 4: Create Shared List-Page Visual Pattern

**Files:**
- Modify: `frontend/src/views/ia/ProjectMilestones.vue`
- Modify: `frontend/src/views/ia/SubjectManagement.vue`
- Modify: `frontend/src/views/ia/RiskIssueSae.vue`
- Modify: `frontend/src/views/ia/RiskIssuePd.vue`
- Modify: `frontend/src/views/ia/RiskIssueMonitoringVisits.vue`
- Test: `frontend/src/views/ia/*.vue`

**Step 1: Write the failing test**

In `verify-ui-contract.mjs`, add per-page checks that each target file includes:

```js
"ctms-page-shell",
"unified-action-bar",
"ctms-table-card"
```

**Step 2: Run test to verify it fails**

Run: `cd frontend && npm run ui:contract`
Expected: FAIL on one or more target views.

**Step 3: Write minimal implementation**

Refactor each page template to the same structure:

```vue
<div class="ctms-page-shell">
  <section class="unified-action-bar">...</section>
  <section class="unified-shell ctms-table-card">...</section>
</div>
```

**Step 4: Run test to verify it passes**

Run: `cd frontend && npm run ui:contract && npm run type-check`
Expected: PASS.

**Step 5: Commit**

```bash
git add frontend/src/views/ia/ProjectMilestones.vue frontend/src/views/ia/SubjectManagement.vue frontend/src/views/ia/RiskIssueSae.vue frontend/src/views/ia/RiskIssuePd.vue frontend/src/views/ia/RiskIssueMonitoringVisits.vue frontend/scripts/verify-ui-contract.mjs
git commit -m "feat(ui): unify list-page enterprise visual pattern"
```

### Task 5: Upgrade Executive Dashboard Surfaces

**Files:**
- Modify: `frontend/src/views/ia/ProjectOverview.vue`
- Modify: `frontend/src/components/KpiCard.vue`
- Modify: `frontend/src/styles/unified-page.css`
- Test: `frontend/src/views/ia/ProjectOverview.vue`

**Step 1: Write the failing test**

Add checks requiring overview page contains:

```js
"ctms-page-shell",
"kpi",
"unified-section"
```

**Step 2: Run test to verify it fails**

Run: `cd frontend && npm run ui:contract`
Expected: FAIL until overview/kpi structure is aligned.

**Step 3: Write minimal implementation**

- Ensure KPI cards use unified spacing, title scale, value prominence.
- Add deterministic class contract to KPI root:

```vue
<article class="kpi-card kpi-enterprise">...</article>
```

- Add style rules in `unified-page.css` for KPI rhythm and hierarchy.

**Step 4: Run test to verify it passes**

Run: `cd frontend && npm run ui:contract && npm run type-check`
Expected: PASS.

**Step 5: Commit**

```bash
git add frontend/src/views/ia/ProjectOverview.vue frontend/src/components/KpiCard.vue frontend/src/styles/unified-page.css frontend/scripts/verify-ui-contract.mjs
git commit -m "feat(ui): elevate project overview for executive readout"
```

### Task 6: Standardize Finance & File Management Pages

**Files:**
- Modify: `frontend/src/views/fees/ContractFees.vue`
- Modify: `frontend/src/views/fees/SpecialExpenses.vue`
- Modify: `frontend/src/views/ia/FileVersionManagement.vue`
- Test: `frontend/src/views/fees/*.vue`, `frontend/src/views/ia/FileVersionManagement.vue`

**Step 1: Write the failing test**

Require common classes in target pages:

```js
"ctms-page-shell",
"unified-action-bar",
"unified-shell"
```

**Step 2: Run test to verify it fails**

Run: `cd frontend && npm run ui:contract`
Expected: FAIL for non-conforming pages.

**Step 3: Write minimal implementation**

Refactor templates to shared contract and align action hierarchy:
- Primary action right-aligned.
- Secondary actions grouped.
- Filter and table blocks separated by unified sections.

**Step 4: Run test to verify it passes**

Run: `cd frontend && npm run ui:contract && npm run type-check`
Expected: PASS.

**Step 5: Commit**

```bash
git add frontend/src/views/fees/ContractFees.vue frontend/src/views/fees/SpecialExpenses.vue frontend/src/views/ia/FileVersionManagement.vue frontend/scripts/verify-ui-contract.mjs
git commit -m "feat(ui): unify finance and file management surfaces"
```

### Task 7: Standardize Admin High-Visibility Project Page

**Files:**
- Modify: `frontend/src/views/admin/ProjectDetail.vue`
- Modify: `frontend/src/styles/unified-page.css`
- Test: `frontend/src/views/admin/ProjectDetail.vue`

**Step 1: Write the failing test**

Add contract checks for `ProjectDetail.vue` requiring:

```js
"ctms-page-shell",
"unified-action-bar",
"unified-section"
```

**Step 2: Run test to verify it fails**

Run: `cd frontend && npm run ui:contract`
Expected: FAIL until shell contract is applied.

**Step 3: Write minimal implementation**

- Normalize section titles, spacing, card treatment.
- Remove page-specific visual overrides that conflict with token system.
- Keep business fields and logic unchanged.

**Step 4: Run test to verify it passes**

Run: `cd frontend && npm run ui:contract && npm run type-check`
Expected: PASS.

**Step 5: Commit**

```bash
git add frontend/src/views/admin/ProjectDetail.vue frontend/src/styles/unified-page.css frontend/scripts/verify-ui-contract.mjs
git commit -m "feat(ui): align admin project detail with enterprise system"
```

### Task 8: Unify Loading / Empty / Error States

**Files:**
- Modify: `frontend/src/components/StateLoading.vue`
- Modify: `frontend/src/components/StateEmpty.vue`
- Modify: `frontend/src/components/StateError.vue`
- Modify: `frontend/src/styles/main.css`
- Test: `frontend/src/components/State*.vue`

**Step 1: Write the failing test**

Add checks requiring all three state components include:

```js
"ctms-state",
"ctms-state-title",
"ctms-state-desc"
```

**Step 2: Run test to verify it fails**

Run: `cd frontend && npm run ui:contract`
Expected: FAIL for missing class contract.

**Step 3: Write minimal implementation**

Refactor each component to common structure:

```vue
<section class="ctms-state">
  <h3 class="ctms-state-title">...</h3>
  <p class="ctms-state-desc">...</p>
</section>
```

Add shared state styles in `main.css`.

**Step 4: Run test to verify it passes**

Run: `cd frontend && npm run ui:contract && npm run type-check`
Expected: PASS.

**Step 5: Commit**

```bash
git add frontend/src/components/StateLoading.vue frontend/src/components/StateEmpty.vue frontend/src/components/StateError.vue frontend/src/styles/main.css frontend/scripts/verify-ui-contract.mjs
git commit -m "feat(ui): unify loading empty error states"
```

### Task 9: Verification, Demo Path, and Release Gate

**Files:**
- Create: `docs/audits/enterprise-ui-acceptance-checklist.md`
- Modify: `docs/guides/release-checklist.md`
- Test: manual smoke + build checks

**Step 1: Write the failing test**

Create acceptance checklist with explicit pass/fail items. Mark all as pending initially.

```md
- [ ] Overview and milestones visual consistency
- [ ] Risk pages visual consistency
- [ ] Finance pages visual consistency
- [ ] File/admin detail visual consistency
- [ ] Desktop and iPad width checks
- [ ] Management path continuity
```

**Step 2: Run test to verify it fails**

Run: `cd frontend && npm run type-check && npm run build`
Expected: PASS technically, but acceptance checklist remains FAIL/PENDING.

**Step 3: Write minimal implementation**

- Execute manual smoke on target routes.
- Update checklist to PASS with reviewer/date notes.
- Add release gating notes to `docs/guides/release-checklist.md`.

**Step 4: Run test to verify it passes**

Run: `cd frontend && npm run ui:contract && npm run type-check && npm run build`
Expected: PASS for all commands and checklist completed.

**Step 5: Commit**

```bash
git add docs/audits/enterprise-ui-acceptance-checklist.md docs/guides/release-checklist.md
git commit -m "docs(ui): add enterprise refresh acceptance and release gates"
```

## Milestone Mapping

1. **M1 (Day 1-3):** Tasks 1-3 + page alignment.
2. **M2 (Day 4-7):** Tasks 4-5 (first 6 core pages).
3. **M3 (Day 8-10):** Tasks 6-8 (remaining 4 pages + states).
4. **M4 (Day 11-14):** Task 9 + release rehearsal + release gate.

## Definition of Done

1. `npm run ui:contract` passes.
2. `npm run type-check` passes.
3. `npm run build` passes.
4. Acceptance checklist fully marked PASS with reviewer/date.
5. No business logic behavior regressions in smoke path.