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:

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:

{
  "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

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:

"--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:

: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

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:

".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:

.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

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:

"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:

<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

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:

"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:

<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

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:

"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

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:

"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

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:

"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:

<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

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.

- [ ] 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

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.